# How the generated bindings in generated.flan are shaped. One directive per # line, `#` comments, blank lines ignored. A line that is neither directive is # an error rather than a line quietly skipped. # # exclude do not generate a binding for this # name call it this instead of the kebab rule's # # `*` in an exclude pattern stands for any run of characters, and nothing else # does anything. # # Why this file exists. generated.flan is committed, so it is not a build # artefact anybody can hand-correct: the next `flan generate-c vendor/raylib` # overwrites it, and an edit made there is destroyed without anybody being # told. This file is read *while* those lines are made, so it is the edit that # survives regeneration. A postprocessing pass over the generated text was the # alternative and was rejected — a second program to understand, applied to # output the generator had already committed to. # # What does NOT belong here. Anything neither directive can express is a # hand-written `declare-c` in raylib.flan, which wins over the generated file # and is left alone by the importer. That is the escape hatch for a signature # the importer gets wrong and for a Flan face the header cannot describe — # load-font-ex-raw and load-image-from-memory-raw are both that, each wrapped # by a Flan defn of the same name without the suffix. # ── raylib's allocator ────────────────────────────────────────────── # # raylib exports malloc, realloc and free under its own names. Flan's memory # model is explicit — plan.org's rule is that an operation never falls back to # a hidden allocator — so binding these would put a second, untracked heap # behind three innocuous-looking Flan names, and a pointer from one freed by # the other is the kind of bug that does not point at itself. Nothing in the # package needs them: raylib's own Load*/Unload* pairs own everything raylib # allocates. exclude MemAlloc exclude MemRealloc exclude MemFree # ── Predicates read as questions ──────────────────────────────────── # # The kebab rule gives `is-window-ready`, which is C's phrasing wearing Flan's # punctuation. The hand-written bindings in raylib.flan settled the convention # years of Lisp settled first — a predicate ends in `?` and does not begin with # `is` — and these are the generated half of the same set, so they follow it. # key-pressed? and window-ready? being spelled differently would be the split # this whole change exists to remove. # # The C symbol is kept verbatim in the declaration either way, so nothing here # is lost: the name is the Flan face and `IsWindowReady` is still what is # called and still what the check compares against. name IsWindowReady window-ready? name IsWindowFullscreen window-fullscreen? name IsWindowHidden window-hidden? name IsWindowMinimized window-minimized? name IsWindowMaximized window-maximized? name IsWindowFocused window-focused? name IsWindowResized window-resized? name IsWindowState window-state? name IsCursorOnScreen cursor-on-screen? name IsKeyUp key-up? name IsKeyPressedRepeat key-pressed-repeat? name IsMouseButtonUp mouse-button-up? name IsFileDropped file-dropped? name IsFileExtension file-extension? name IsFileNameValid file-name-valid? name IsPathFile path-file? name IsAudioStreamValid audio-stream-valid? name IsAudioStreamPlaying audio-stream-playing? name IsAudioStreamProcessed audio-stream-processed? # Hand-written in raylib.flan, so excluded here: a second declare-c for one C # symbol is refused for the whole program. These three are on a game's # per-frame path (PORTING.md), and a hand-written line is what the signature # check has to compare against -- generated output agrees with the header by # construction, so it can only check the hand-written half. exclude DrawTexturePro exclude ImageFromImage exclude IsWindowReady # The scissor pair and the 3D surface the ported examples in examples/ draw # through, excluded here for the same two reasons in different proportions. # # - BeginScissorMode/EndScissorMode, BeginMode3D/EndMode3D, DrawCube, # DrawCubeWires, DrawGrid are inside a frame. The rule above is about the # per-frame path, and a begin/end pair is taken together: hand-writing one # half and generating the other is the asymmetry that reads as a mistake. # - SetExitKey, UpdateCamera and GetWorldToScreen are excluded because their # Flan face is not the C signature. SetExitKey takes a Key and not an int, # UpdateCamera takes a CameraMode, and both of those refuse a typo the # generated i32 would take. GetWorldToScreen goes with BeginMode3D # because they read the same camera. # # What this line splits, and deliberately: draw-cube is here and draw-cube-v # is generated, get-world-to-screen is here and get-world-to-screen-ex is # generated, update-camera is here and update-camera-pro is generated. Every # other family in raylib.flan — the texture draws, the circle draws — sits # together, so the split is worth naming: what is hand-written is what the # ported examples call, and hand-writing the variants as well would widen the # half that has to be maintained by hand for nothing the examples ask for. # # What is deliberately NOT here: the window-state family (IsWindowState, # SetWindowState, ClearWindowState, ToggleFullscreen, Minimize/Maximize/ # RestoreWindow), GetMouseX/GetMouseY and GetRandomValue. Those are called # per frame by the examples too, but their Flan face IS the C one — plain # scalars, nothing an enum or a pointer improves — and generated.flan is # committed, so the default build has them with no header set either way. exclude BeginScissorMode exclude EndScissorMode exclude BeginMode3D exclude EndMode3D exclude DrawCube exclude DrawCubeWires exclude DrawGrid exclude SetExitKey exclude UpdateCamera exclude GetWorldToScreen