X_eTaL documentation

Files

• macro library lib/Ffi.xtlm: Ffi.xtlm -- the binding macro: a facade function written from the signature of a native function (docs/ffi-macro.md). Import: "ffi:" u_se< "Ffi" (xetal-x puts this directory on XETAL_PATH)
• library extensions/audio/lib/Audio.xtl: Audio.xtl -- the facade of the audio extension: decode Ogg Vorbis, MP3 and WAV, play them on the sound device, read what is playing as arrays, and play arrays. Import: "au:" u_se< "Audio" Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). With XETAL_HEADLESS=1 (or XETAL_AUDIO=off) nothing sounds and playback advances a 60th of a second per au:w_indow (or au:p_layed) -- for tests. Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• library extensions/audio/demos/Instruments.xtl: Instruments.xtl -- the instruments of the synthesizer demos (synth.xtl, scope.xtl): music as arrays. An ordinary X_eTaL library beside them. Import: "in:" u_se< "Instruments"
• program extensions/audio/demos/scope.xtl: A live oscilloscope: the synthesizer's music (Instruments.xtl) plays while a window draws the samples under the playhead -- the left channel above, the right below -- each frame, triggered on the left channel's rising zero crossing so a steady chord stands still. Run: just demo audio scope (q or close: quit)
• library extensions/canvas/lib/Canvas.xtl: Canvas.xtl -- the facade of the canvas extension: a native window showing X_eTaL arrays as pixels, with keys, clicks and frame ticks back. Import: "cv:" u_se< "Canvas" Run with xetal-x, which links canvas and serves its windows on the main thread (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• program extensions/audio/demos/spectrum.xtl: The music visualizer: an Ogg Vorbis (or MP3, WAV) file plays while X_eTaL turns what is playing into a spectrum and the spectrum into 16 spokes in a 3D window -- Rust decodes, plays and draws; the analysis and the picture's geometry are X_eTaL arrays. Run: just demo audio spectrum (Space: pause, j/k: back/on 5 s, q: quit) Another file: change the path below (Ogg Vorbis, MP3 or WAV).
• library extensions/scene/lib/Scene.xtl: Scene.xtl -- the facade of the scene extension: retained 3D line and point scenes in a native window, patched by id, the mouse orbiting. Import: "sc:" u_se< "Scene" Run with xetal-x, which links scene and serves its windows on the main thread (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• library std/Stats.xtl: Stats: a small statistics library (a standard library, built into xetal). Import it with an alias of your choice: "s:" u_se< "Stats". It is a demo library, loaded only by that import: a small subset of X_eTaL-libraries' Statistics, which has much more (a program may use either). Names with l: are exported; names with h: are private to this file.
• program extensions/audio/demos/synth.xtl: A synthesizer made of arrays: X_eTaL computes every sample of a little piece -- notes from equal temperament, harmonics, envelopes, chords, stereo (the instruments are in Instruments.xtl, beside this file) -- and the audio extension plays them as they are made. Run: just demo audio synth
• program extensions/canvas/demos/life.xtl: Conway's Life in a native window: the board is an X_eTaL array, each generation one array expression, drawn by Rust with every frame. Run: just demo canvas life (Space: a new board; q or close: quit)
• library extensions/clock/lib/Clock.xtl: Clock.xtl -- the facade of the clock extension: wall-clock and monotonic time, which X_eTaL does not have, for timestamps and timing. Import: "ck:" u_se< "Clock" Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• program extensions/clock/demos/bridge-cost.xtl: What the text bridge costs (docs/bridge.md): calls per second, and Floats per second carried out and back (it uses hello too). Run: just demo clock bridge-cost
• library extensions/hello/lib/Hello.xtl: Hello.xtl -- the facade of the hello extension, the smallest X_eTaL native extension: each function proves one thing about the boundary. Import: "hx:" u_se< "Hello" Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). Each line below is a native function's signature; the binding macro (lib/Ffi.xtlm, docs/ffi-macro.md) writes the facade function from it.
• library extensions/digest/lib/Digest.xtl: Digest.xtl -- the facade of the digest extension: SHA-256 and CRC-32 of text and of files, to check that content is what it should be. Import: "dg:" u_se< "Digest" Files are named by paths under the working directory (or XETAL_DIGEST_ROOT), relative, with no .. Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• program extensions/hello/demos/tour.xtl: A tour of the hello extension: X_eTaL arrays handed to Rust and back. Run: just demo hello tour (or: xetal-x --ext extensions/hello run demos/tour.xtl)
• library extensions/http/lib/Http.xtl: Http.xtl -- the facade of the http extension: bounded HTTP GET, text from the web within size, time and redirect limits. Import: "ht:" u_se< "Http" Limits: XETAL_HTTP_MAX bytes (16 MiB), XETAL_HTTP_TIMEOUT seconds (30), 5 redirects; only http:// and https:// URLs. Downloads go under the working directory (or XETAL_HTTP_ROOT). Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• program extensions/http/demos/quakes-live.xtl: Earthquakes of the past week, live: the USGS feed of magnitude 2.5 and up, fetched now (the network: run it only when you mean to), its SHA-256 shown, then the same report as quakes.xtl. Run: just live-quakes (from the repository root; pictures go to work/draw/)
• library extensions/http/demos/Seismic.xtl: Seismic.xtl -- the earthquake report (quakes.xtl, quakes-live.xtl): a USGS feed CSV into SQLite, SQL to select and group, X_eTaL arrays to compute, pictures to see it. An ordinary X_eTaL library beside them (not Quakes.xtl: on a case-insensitive file system that is quakes.xtl). Import: "se:" u_se< "Seismic"
• library extensions/sqlite/lib/Sqlite.xtl: Sqlite.xtl -- the facade of the sqlite extension: SQLite databases for X_eTaL (rusqlite, SQLite compiled in). Import: "sq:" u_se< "Sqlite" A database is named by its path, relative to the working directory (or XETAL_SQLITE_ROOT), or ":memory:" for one call's scratch database; each call opens it and closes it. Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• program extensions/http/demos/quakes.xtl: Earthquakes of a week: the USGS feed of magnitude 2.5 and up, saved 2026-10-06 (demos/data/PROVENANCE.txt), checked against its SHA-256, into SQLite; SQL selects and groups, X_eTaL computes (the magnitude-frequency law), pictures show it. Run: just demo http quakes (pictures go to work/draw/; the live feed: just live-quakes)
• library extensions/image/lib/Image.xtl: Image.xtl -- the facade of the image extension: PNG and JPEG files as Float arrays from 0 to 1, and back. Gray is h by w, color h by w by 3 (red, green, blue); alpha is dropped. Import: "im:" u_se< "Image" Files are named by paths under the working directory (or XETAL_IMAGE_ROOT), relative, with no .. Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• program extensions/image/demos/photo-lab.xtl: The photo lab: a photo is an array. Buzz Aldrin on the Moon (Apollo 11, NASA, public domain: demos/data/PROVENANCE.txt) read as numbers; filters and edges by rotating the array (the Life idiom), a color toning by an inner product, and the SVD compressing it at several ranks -- the native code reads, writes and decomposes, X_eTaL does the rest. Pictures go to work/photo-lab/. Run: just demo image photo-lab
• library extensions/linalg/lib/Linalg.xtl: Linalg.xtl -- the facade of the linalg extension: numerical linear algebra through nalgebra. Matrices are Float arrays (row by column); a right-hand side may be a vector or a matrix of columns. Import: "la:" u_se< "Linalg" Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• program extensions/scene/demos/cube.xtl: A wireframe cube turning in a native 3D window: its corners and edges are X_eTaL arrays; Rust draws them. Run: just demo scene cube (drag to turn it; q or close: quit)
• library extensions/scene/demos/Endless.xtl: Endless.xtl -- the endless world and its player, shared by the voxel demos that walk or fly in it (voxels-endless, voxels-fly, and those after): columns of 16 by 16 blocks made around the player and dropped behind it, each made over three frames so no frame waits long, and the player -- walking, swimming, flying -- moving against them. Import: "en:" u_se< "Endless"
• library extensions/scene/demos/Voxels.xtl: Voxels.xtl -- voxel chunks as arrays, shared by the voxels-* demos (docs/voxels.md). A chunk is a 16 by 16 by 16 array of block numbers, indexed x (east), y (up), z (south); 0 is air. Import: "vx:" u_se< "Voxels" (Not voxels.xtl: on a case-insensitive file system a demo of that name would be this file -- ask E8.)
• library extensions/scene/demos/Rubik.xtl: Rubik.xtl -- a Rubik's cube as arrays, for the voxel cube demos (voxels-rubik and after). The cube is its 54 stickers; each sticker is where it is -- its cubie's position x y z, each -1 0 or 1 -- and which way it faces, a unit normal. A turn rotates the stickers of one layer by a quarter turn; matching the rotated stickers against the stickers gives where each one goes, a permutation of 54, and turning the cube is selecting its colors by that permutation. Every position reached by turns is a real cube's. Import: "rb:" u_se< "Rubik"
• program extensions/scene/demos/voxels-chunk.xtl: Voxels, 1: a chunk is an array. 16 by 16 by 16 block numbers built from a height field in a few array expressions -- grass, dirt, stone, water below a level, sand at its shore, one tree -- then counted, cut and seen from above. (docs/voxels.md; the next demos draw it.) Run: just demo scene voxels-chunk (pictures go to work/draw/)
• program extensions/scene/demos/voxels-endless.xtl: Voxels, 6: an endless world. Walk in any direction and it never ends: the land comes from value noise hashed from the coordinates (vx:h_eightsAt), so any column of 16 by 16 blocks can be made by itself and fits its neighbors; columns are made around the player as it walks -- the nearest missing one each frame -- and dropped behind it; fog hides the edge of what is made, and a curved horizon (scene lowers the world by d^2 / 2R) makes it look like a small planet. Collision asks the columns themselves. The world and the player are the library Endless.xtl, shared with voxels-fly: each column is made over three frames, so no frame waits long. Run: just demo scene voxels-endless W A S D walk, Shift run, Space jump (in water: swim up; at the surface: climb out onto a bank one block high), drag the mouse or the arrows to look, H: back to the start, q or close: quit
• program extensions/scene/demos/voxels-faces.xtl: Voxels, 2: which faces to draw. A face shows where a solid block's neighbor is not solid: six rotations of the solid mask, each compared with the mask itself (the idiom of Life), give every exposed face of the chunk at once; the faces become a list, one row each: x y z direction block. Checked on shapes with known answers, then the chunk's faces drawn as outlines in a 3D window, turning. Run: just demo scene voxels-faces (drag to turn it; q or close: quit)
• program extensions/scene/demos/voxels-fly.xtl: Voxels, 7: flying. The endless world of voxels-endless, now from the air: F switches between walking and flying. Flying moves level whatever you look at -- W forward, S back, A and D sideways -- Space rises and Shift sinks, with no gravity, the blocks still stopping you; so you can look down at the land as you cross it. F again drops you back to walking wherever you are. The columns are made ahead, one a frame, and dropped behind, under fog and a curved horizon. Run: just demo scene voxels-fly F fly or walk; flying: W A S D level, Space up, Shift down; walking: Space jump or swim up, Shift run; drag the mouse or the arrows to look, H: back to the start, q quit
• program extensions/scene/demos/voxels-rubik.xtl: Voxels, 8: a Rubik's cube. 26 dark cubies with their colored stickers, drawn as voxels; the cube itself is arrays (Rubik.xtl): its 54 stickers, each where it is and which way it faces, and each of the twelve quarter turns a permutation of them, computed from the cube's geometry. This demo checks the turns -- each a permutation, four of one solved, a turn and its undoing solved, R U R' U' of order 6, R U of order 105, and U and R turning the right way -- and shows the solved cube, turning slowly; keys turn its faces. Run: just demo scene voxels-rubik u d r l f b turn a face clockwise (as you look at it), Shift with the letter counterclockwise, z undo (back to solved), Space a scramble (25 random turns), 0 reset, drag to look around, q quit
• program extensions/scene/demos/voxels-solid.xtl: Voxels, 3: the chunk drawn solid. The same faces as voxels-faces, each now a filled quad -- its four corners from a 6 by 4 table by direction -- one object per kind of block; scene shades each by how it faces the light and hides the farther ones behind the nearer (a depth buffer), with a little fog. All the array work is X_eTaL's; Rust only draws. Run: just demo scene voxels-solid (drag to turn it; q or close: quit)
• program extensions/scene/demos/voxels-walk.xtl: Voxels, 5: walking. The island of voxels-world, seen from inside it. The player is nine numbers -- x y z (feet), vx vy vz, yaw, pitch, on the ground -- and every frame X_eTaL reads the keys and the mouse, turns, falls, jumps, and moves one axis at a time against the solid blocks the player's box would overlap, stopping at the face of the block it hits (a swept box per axis, as the APL game collides); then it sets scene's first-person camera. It also tests the 32 chunks against the planes of the view, as the APL game culls (key c). Run: just demo scene voxels-walk (a new island each run; --seed 1) W A S D walk, Shift run, Space jump (in water: swim up; at the surface: climb out onto a bank one block high), drag the mouse or the arrows to look, c: the chunks in view, H: back to the start, q or close: quit
• program extensions/scene/demos/voxels-world.xtl: Voxels, 4: a world of chunks. An island 64 by 32 by 64 -- 32 chunks of 16 cubed -- from value noise made by linear algebra (random heights on grids every 16, 8 and 4 blocks, each interpolated as M G M'), shaped by the chunk's rules over the whole world at once, with trees planted by folding one tree over a list of places. Its faces are found over the whole array (so faces between chunks hide each other), then sent to scene chunk by chunk, each chunk's kinds of block under their own ids -- the ids a later demo patches when a block changes. Run: just demo scene voxels-world (drag to turn it; q or close: quit)
• program extensions/sqlite/demos/notebook.xtl: The data notebook: a CSV in SQLite, SQL to select and group, X_eTaL arrays to compute, pictures to see it. Atmospheric CO2 at Mauna Loa, 1959-2025 (NOAA GML and Scripps; demos/data/PROVENANCE.txt). Run: just demo sqlite notebook (pictures go to work/draw/)
• library extensions/web/lib/Web.xtl: Web.xtl -- the facade of the web extension: HTTP serving, where the program is the request loop. axum serves on 127.0.0.1 in the background and queues each request; the program takes the next one, reads its parts, and replies. Import: "wb:" u_se< "Web" Run with xetal-x (xetal-x --ext DIR puts this directory on XETAL_PATH). Each signature line is written out by the binding macro (lib/Ffi.xtlm).
• program extensions/web/demos/life.xtl: A live page: Conway's Life kept by an X_eTaL program and drawn as SVG, one generation per request. The program is the server's request loop. Run: just demo web life, then open http://127.0.0.1:8470/ (New board, Glider; Quit ends the program)
• program extensions/web/demos/todomvc.xtl: TodoMVC on the web: the todos live in SQLite, the X_eTaL program is the server -- it routes each request, keeps the filter, counts what is left, and writes the page; forms post and are redirected back. Run: just demo web todomvc, then open http://127.0.0.1:8470/ (the list is kept in work/todos.db; Quit ends the program)

Items