Write in Arabic. Run here.

What you will learn

You will change a greeting, predict its exact output, and use a reported source location to repair an error. You will also tell printed text apart from the program's status.

Before you begin

No programming experience or installation is required. First program in the browser explains the playground controls. Source is the text of your program. Checking asks whether that source obeys the language rules. Run checks it and, if checking succeeds, executes its instructions.

Opening any complete example below creates a new Home draft with its original source. Your earlier drafts and edits remain available. Opening checks the source but does not run it. Choose Run yourself. Documentation language and source vocabulary are separate. The example selector offers supplied Arabic and English keywords; it does not translate the greeting inside quotes or your draft.

Read a complete program

ASPL needs a reserved entry function, named ابدأ_الرئيسية or its exact English alias start_main. Execution starts there. fn / دالة introduces a function. The empty () means this entry takes no arguments. -> i64 / -> ص64 means it returns an integer status. Keep this entry signature as supplied while you learn the instructions inside it.

The opening and closing braces mark the function's body. Instructions run in order inside that body. print / اطبع writes a string, which is text between double quotes. The parentheses pass that string to print. print adds no newline. The two source characters \n inside the string request one newline, so the next output starts on a new line. English statements end with ;, and Arabic statements may end with .. Neither terminator becomes output.

return 0 / أرجع 0 ends the entry normally with process status 0. It does not print the digit zero. You will use this same ending in each independent lesson. Defining other functions comes later.

After Run, the Output area contains Hello followed by one newline, exactly Hello\n when written with an escape. The status area reports normal completion with start_main 0. The source contains quotes and a terminator; the output contains neither.

Predict before running

What exact text will appear, and does it end with a newline? Will 0 appear in Output? Make your prediction, then run the example and compare. You should find one line, Hello, with a trailing newline and no printed zero.

Change the greeting

Change only Hello to Welcome inside the quotes. Keep \n. Expected behavior is exactly Welcome\n, with normal status 0. Write your prediction before pressing Run.

Follow a source error to its location

This is an intentionally broken complete-program variant. Its closing brace is missing. Open it to inspect the check result before trying to run it.

Checking reports a source error with reason expected-token: it expected right-brace and found end-of-file. The location is line 4, column 1, immediately after the last instruction. Select the reported location in the playground. The marker can sit at the end of the source because the missing character has no existing text to highlight.

Insert the missing closing brace at that location. The labelled fragment below shows only the character to insert, not an independent program.

Illustrative fragment

}

The corrected program is the original greeting example. Checking now succeeds; choose Run to get Hello\n and status 0. The broken source executes no instructions and produces no greeting, even though the print instruction appears before the missing brace. A source diagnostic describes rejected source. Output comes from executed instructions. A normal status describes how execution ended. Read more about diagnostics and outcomes.

Check your understanding

You are ready to continue when you can explain where execution starts, why the newline is explicit, why zero is not printed, and how you repaired the missing brace. These are self-checks. They save no grade or progress and never lock navigation. Continue to bindings and arithmetic whenever you choose.

What you will learn

You will give values names, calculate with small integers, print a numeric result, and decide when a name may be assigned a new value.

Before you begin

Read first output for the reserved entry, printing, explicit newlines and status 0. This lesson supplies a complete program of its own. Opening it creates a new draft and preserves earlier edits. Run remains your choice.

Name values and calculate

A binding associates a name with an initialized value. let / دع introduces an immutable binding: you cannot later assign that name a new value. var / متغير introduces a mutable binding, which permits later assignment. Both require a starting value. In a declaration, = supplies that initial value. The values 3 and 7 are small integers; ASPL infers their type as i64 / ص64, so you need not write a type here.

+ adds two numbers. * multiplies them. An expression such as left + right computes a value using the two named values. The names are user identifiers, not keywords. The supplied Arabic source keeps the same names left, right and total; changing documentation language does not rename your identifiers.

print takes text, so first use format_i64 / نسق_ص64 to turn an i64 number into its decimal text. format_i64(total) reads total and returns that text. The outer print writes it. A second print writes "\n" to end the line. Formatting and printing are separate operations; neither changes total.

The entry first initializes left to 3 and right to 7. It then initializes total to their sum, 10, and prints 10\n. Finally, return 0 ends normally. The calculated value is output, not the process status.

Predict before running

What value does total hold, and what exact text is printed? If you replace + with *, predict the new result before Run. Addition gives 10; multiplication gives 21. Each is printed with one newline, while the status stays 0.

Multiply instead of adding

Change only the operator in the declaration of total to calculate 3 * 7. Expected output is exactly 21\n and the normal status is 0.

Understand an immutable-assignment error

This intentionally failing variant calculates 21, then tries to assign total + 1 back to the immutable name total.

Checking reports immutable-assignment at total on line 5, column 5. Select that diagnostic to find the name being assigned. No print runs, so the failure produces no program output. The problem is permission to reassign the binding, not the arithmetic or formatting.

For intended mutation, change the declaration of total from let to var, or دع to متغير in the supplied Arabic source. Leave the other bindings immutable. The later = is now assignment: it replaces the stored value with 22.

The correction checks and prints 22\n with normal status 0. A binding declared with var still needs its initial value. You do not need mutation just to calculate a new result once. See the binding and control-flow reference for fuller rules.

Check your understanding

Explain why both declaration forms need initial values, why the multiplication prints 21, and why only the mutation example needs var. Repair the failing assignment and compare 22\n with your prediction. No grade or progress is stored; navigation stays open. Continue to the conditions whenever you choose.

What you will learn

You will define a typed top-level helper, pass an argument, trace its returned value, and explain why that value differs from the program's process status.

Before you begin

Read bindings and arithmetic, conditions and loops. They supply named values, comparisons and ordered execution. This independent program includes its own entry. Open it as a new Home draft and choose Run explicitly; earlier work stays available.

Define and call a helper

fn / دالة declares a function. The helper double is top-level, outside the entry function and every other function body. Its parameter value: i64 / value: ص64 names an incoming integer. The arrow and result type -> i64 / -> ص64 promise an integer result. Braces contain the helper's instructions, and return / أرجع sends a value back to the caller and ends that call.

double(6) is a call. The argument 6 supplies the parameter's value for this invocation. Arguments pass by value. Inside the helper, value * 2 computes 12; the return sends 12 back to the call site. The caller stores it in the immutable result binding. A call must supply the declared number and types of arguments.

Execution begins at the reserved start_main() -> i64 / ابدأ_الرئيسية() -> ص64 entry, not at the first helper declaration. Defining double alone does not run its body. The call temporarily enters it, then execution resumes in the entry. format_i64 / نسق_ص64 converts result to text, and print / اطبع writes it followed by the explicit \n newline.

The helper returns 12 to its caller. The entry prints exactly 12\n, then its own return 0 / أرجع 0 gives normal process status 0. The helper's return neither prints automatically nor sets process status. Returning double(6) directly from the entry would instead give status 12 and, without the print, no output.

Follow the returned value

Predict the helper result, visible output and process status separately.

The new argument changes the computation and the printed data. It does not change the entry's final return.

Change the argument

Change only double(6) to double(9). Expected output is exactly 18\n and normal status 0.

Return on every required path

A function with a non-unit result must return a value of that type on every required path. Our helper has one unconditional return. If you use if and else, every reachable alternative must return or lead to a later return. A closing brace supplies no implicit integer result.

This deliberately broken helper returns only for positive values. Even though the entry calls it with 6, its zero and negative paths can fall through. Checking reports missing-return before any program execution. Run reports the same source error, with no output or process status.

Restore the unconditional return value * 2 shown in the starter to cover all inputs. The corrected complete starter prints 12\n and returns status 0. For the full rules, read the functions reference.

Optional recursion

A helper may call itself. The existing factorial example recursively computes factorial of 5 as 120, stopping at a value of 1 or below. Its entry returns that result directly. It prints nothing and ends with process status 120; that number is neither printed output nor a quiz score. You can leave recursion for later.

Check your understanding

Point to the declaration, parameter, argument, call and both returns. Trace where 12 goes after the helper returns and why the entry status remains 0. Compare the changed argument with your prediction after an explicit Run. The self-check stores no grade or progress and keeps every lesson open. Return to the Tutorial path.

Prepare the native host

Native only, published ASPL 0.7.0. Follow the native installation path and system requirements first. These examples use x86-64 Linux, the System V ABI and glibc. libc.so.6 supplies puts, abs, strlen and memset; libm.so.6 supplies sqrt. They need no input lines, source modules or data assets. A built ELF still needs its named shared libraries.

Download a supplied source variant from the C collection. Keep its original filename and user names. An English-keyword source may still contain Arabic user names and strings. No C example has an action to open it in the browser.

Print through a foreign adapter profile

The puts example declares the exact profile c_int__const_char_ptr, mapping ASPL (string) -> i64 to C int(const char *). Both the declaration and call require unsafe. C receives a temporary copy, not ASPL string storage. puts adds LF after مرحبا. The program checks for a negative C result and otherwise returns 0; the unspecified positive C return is not a useful process status.

aspl check puts.en.aspl
aspl run puts.en.aspl
aspl build -o puts-program puts.en.aspl
./puts-program

Use puts.ar.aspl for the Arabic variant. Success prints مرحبا\n and exits with 0. The double example uses c_double__double with libm.so.6 and sqrt: it checks that sqrt(4.0) is 2.0, prints nothing and exits with 0.

Declare an exact fixed signature

The contextual c / سي tag derives a fixed C signature from source types. In the ordinary example, abs uses i32 -> i32, while strlen uses string -> u64 plus cstring(text). Its Arabic string has ten UTF-8 bytes, so strlen returns 10, not five characters. The program checks both results, prints nothing and returns 0.

aspl check ordinary.aspl
aspl run ordinary.aspl
aspl build -o ordinary-program ordinary.aspl
./ordinary-program

The two supplied variants share the filename ordinary.aspl; save one at a time or put them in separate directories. Match the actual C prototype exactly. Read the signature table before adapting a declaration. ASPL does not import headers or infer a prototype from a symbol name.

Copy bytes into a Buffer

The Buffer example imports core::c, copies 00 FF 41 from a list<u8>, changes the original list, and calls memset through an explicit output span. The first extracted list keeps its copied bytes; the shared native Buffer changes to 20 20 20. It handles oversized extraction as foreign.invalid_argument, closes one alias, checks foreign.closed through another, and closes again successfully.

aspl check buffer.لبات
aspl run buffer.لبات
aspl build -o buffer-program buffer.لبات
./buffer-program

Both variants use buffer.لبات; keep them in separate directories. Success has no output and status 0. Buffer aliases share one native owner. Construction and extraction copy bytes; assignment does not copy the mutable native storage. See Buffer operations and spans.

Recognize failures and limits

check and build validate declarations without opening their libraries. run and generated programs resolve every foreign declaration before the entry function, including unused declarations. An unavailable library or symbol gives status 4 and prevents source effects. A missing unsafe marker or unsupported signature gives a source error with status 1.

An embedded NUL in a C-string loan traps before C entry with status 5. The original string profile reports foreign-string-contains-nul; generic cstring reports invalid-foreign-argument. Invalid byte counts, closed Buffers and writable aliases also trap before entry. Buffer utilities instead return failed result values for documented refusals. Check ok before accessing value or error; close returns result<unit> with no readable value.

Ordinary unsafe calls run synchronously and may block or crash. They have no managed cancellation or callback privileges. The public toolchain supplies reviewed managed HTTP and Raylib bindings, but no public API for installing arbitrary managed bindings. Contributor callback fixtures are excluded from this collection. Use the foreign API reference, HTTP collection or Raylib collection for the applicable contract.

Prepare native HTTP

Native only, published ASPL 0.7.0. Install the native toolchain on x86-64 Linux with glibc 2.34 or later. aspl --version must print aspl 0.7.0. The browser playground and private embedding profile reject HTTP before execution. Downloads on this page preserve supplied source; they do not open a browser draft or run a program.

Use the HTTP collection to download a root and its required modules. Keep Arabic and English variants in separate directories with their original filenames. The module names and user identifiers are unchanged between variants, but the module source bytes differ. Each file imports what it uses: import core::http; activates http, and استورد أساسي::ويب. activates ويب. Only the written prefix is available; supplied members have exact aliases. Both .aspl and .لبات work for roots and imported modules.

The API reference lists the public types, signatures, defaults, limits and error codes. Follow the deployment guide for certificate preparation, system trust and deployment. The earlier raw guide (opens in a new tab) and raw deployment source (opens in a new tab) retain their earlier release scope.

Serve text, JSON and bytes

Download the service family with settings.aspl and handlers.لبات of the selected variant. Save them together. From that source directory, run:

aspl check service.aspl
aspl run service.aspl

For Arabic source use service.لبات. The service stays in the foreground on 127.0.0.1:8080. Reserve that port first. It needs no input lines or data assets for the plain client exercise. Its /upstream route additionally needs a trusted server.pem in the process working directory and a verified peer at https://localhost:9443/hello.

handlers::handle is a named top-level function with no captured locals. Its request and Context<app::Config,app::State> match the router's nominal types. The checker rejects unsafe and blocking handler paths, including ordinary foreign calls and line/file input hidden behind helpers. Other admitted handlers can progress while one waits for an HTTP child call; ASPL execution stays serialized.

GET /hello returns مرحبا من ASPL. POST /submit checks UTF-8 and echoes explicit JSON text with application/json; charset=utf-8; it does not parse or validate JSON structure. POST /bytes echoes arbitrary bytes, and GET /download returns exactly 00 FF 41. /count reports the state before incrementing it. read_state returns a value copy, and replace_state publishes a whole replacement. Reading, waiting and replacing are not atomic. Reread after a wait or use versioned snapshots.

GET /upstream makes a verified child request using app::Config. A child failure becomes a 502 containing its stable code while the parent is live. Parent cancellation revokes child work and discards late output and publication; it does not resume the cancelled handler with a failed result. Forward body bytes deliberately, since peer compressed length/encoding metadata may be stale.

Check client outcomes

Keep the client root beside its matching requests.لبات. With the service running, use another terminal in that source directory:

aspl check client.aspl
aspl run client.aspl

The client verifies text, JSON echo, exact binary bytes and a complete 404 response. It prints checked text, JSON, 00 FF 41, and 404 without a trailing newline and returns 0. http.request returns a successful result for complete 404/500 messages. Inspect status separately. Invalid UTF-8 decoding gives http.invalid_utf8; the original body stays available. JSON has no implicit parser or serializer.

The refusal example assumes no listener at 127.0.0.1:9, prints http.connect_failed and returns 0 after checking that failure. A live peer changes the assumption. Branch on error::code, not human diagnostic text. Recoverable results differ from source errors, terminal traps and execution cancellation.

Verify HTTPS and respect limits

The direct-TLS service uses the same helper modules on 127.0.0.1:8443. Supply server.pem and its matching unencrypted server.key in the working directory. The HTTPS client uses https://localhost:8443 and explicitly trusts server.pem, with localhost in the certificate's DNS SAN. Private CA replaces system trust and keeps chain, date and identity verification mandatory. Missing or invalid server material gives http.tls_config_failed before listening.

aspl check direct-tls.لبات
aspl run direct-tls.لبات

In the separate client terminal:

aspl check client-tls.لبات
aspl run client-tls.لبات

The system-trust client instead calls https://localhost:9443/hello. Success requires a peer trusted by the host. An untrusted local certificate produces http.tls_verify_failed, output containing that code and status 1. Missing or malformed trust gives http.ca_load_failed. See certificate preparation and trust selection.

Follow the complete upstream deployment exercise for the matching peer, working directory, verified requests and failure outcomes.

Redirect following and gzip decoding default to false. Enabled redirects stay within one origin and share the original total deadline. Gzip checks both encoded and decoded limits. There is no automatic transport retry. The limits example demonstrates that lowering outbound capacity below the default 16 idle connections also requires lowering idle capacity. Numeric settings reserve no resources. See message and runtime limits and deadlines.

Progress a session and publish copied state

Use blocking serve when serving owns the application's control flow. Use start to obtain Session<C,S> and call progress explicitly from application code. A successful start has ready listeners; normal handlers run only through progress. Application-only session helpers cannot run inside handlers. Handler Context authority expires with that invocation.

The session family needs free port 127.0.0.1:8081 and no peer or TLS files. It copies state without publishing the local mutation, publishes 11 against a current snapshot, and checks successful false for stale publication. It then requests drain, progresses until SESSION_CLOSED, closes aliases repeatedly and checks http.closed_session. The saved snapshot still contains 10. Success has no output and status 0.

aspl check session.aspl
aspl run session.aspl

Session copies share one managed owner. Closing one invalidates every alias; losing the last reachable alias releases the resource. StateSnapshot<S> contains a copied, read-only value and hidden session/version identity. Foreign-session publication fails with http.invalid_argument. Managed handles inside snapshots retain the same native owner, not a clone of its mutable state. See serving lifetimes and publication.

Shut down and build an ELF

For the plain service, POST /stop from another terminal:

curl --http1.1 --request POST http://127.0.0.1:8080/stop

For the TLS service, use the trusted CA and its port:

curl --http1.1 --cacert server.pem --request POST https://localhost:8443/stop

Handler stop(ctx) requests drain and is idempotent. The current response can finish. serve returns normally only after releasing its owned work. Explicit stop_session likewise needs subsequent progress until closed. close_session revokes work and releases the owner. First Ctrl+C or SIGTERM drains then ends execution with status 7; a second signal skips the rest of drain. A trap stays terminal with status 5 and never becomes an automatic 500. Parent expiry, disconnect or drain expiry can discard handler completion and state publication.

aspl build -o service-program service.aspl
aspl build -o client-program client.aspl
./service-program --aspl-diagnostic-language=en --aspl-color=never

Run ./client-program in another terminal, then POST /stop. Use the Arabic root filename when building that variant. The ELF includes the checked module graph and VM and runs without ASPL, source files or a C compiler. TLS files and any ordinary declared C shared libraries remain external inputs. Generated programs accept the reserved diagnostic/color options; ASPL CLI commands and arbitrary application arguments are not supported. See build and process status.

Prepare the native host

Native only, published ASPL 0.7.0. Install the native toolchain. Import core::raylib or أساسي::رايليب in each source module that uses the library. Either imported prefix accepts exact Arabic and English member aliases. Import both spellings to use both short prefixes. User names, strings and paths retain their bytes.

Checking and building require no display or C compiler. Running a window needs x86_64 Linux, glibc 2.34 or later, a reachable Wayland/EGL or X11/GLX display and OpenGL 3.3 core. XWayland uses the X11 route. The tool embeds the pinned Raylib 6.0 backend; no system Raylib is required. See system requirements.

With both endpoints present, exact XDG_SESSION_TYPE=wayland selects Wayland first; other values select X11 first. With one nonempty WAYLAND_DISPLAY or DISPLAY, only that route is attempted. A safely released failure may fall back to the other endpoint. With neither endpoint, InitWindow returns raylib.host_unavailable. There is no headless window success. A successful backend remains fixed until close.

Download programs from the Raylib collection. Each family lists its supplied variants and any licensed files before source. Keep the original source filenames and asset paths. The sprite family needs its PNG and notice under docs/examples/assets, relative to the process working directory. No source modules are required by these families. The browser rejects the library even when an import is unused.

Check each result

Ordinary operations return result<T>; readiness/validity probes return bool directly. Test ok / نجاح before reading value / قيمة or error / الخطأ. Reading the wrong arm traps. Compare stable ASCII error::code; Raylib messages contain both languages. Use --diagnostic-language=en for CLI diagnostics, or --aspl-diagnostic-language=en for a generated program.

Illustrative fragment

import core::raylib;
fn start_main() -> i64 {
    let opened = raylib::InitWindow(640, 360, "سلام ASPL");
    if not opened::ok { print(opened::error::code); return 1; }
    let closed = raylib::CloseWindow();
    if not closed::ok { print(closed::error::message); return 2; }
    return 0;
}

This fragment illustrates checked lifecycle calls. Complete downloadable programs below retain their catalog outcomes. See the API reference for exact widths, contexts and failures.

Own a window generation

Call SetConfigFlags before opening the window. It replaces the saved next-window flags. SetTargetFPS accepts nonnegative FPS, including zero for uncapped pacing. Open with positive i32 dimensions and a title without NUL. Titles are copied and retained until replacement or native quiescence. SetWindowTitle needs a live window and a closed frame.

One execution holds the process device lease. Device operations run on the process main thread. IsWindowReady is a total probe; WindowShouldClose is a checked observation. A close request does not itself close the window. The application decides when to finish or close it. CloseWindow succeeds when already closed.

Close invalidates texture aliases before destroying the graphics context. Reopen creates a fresh generation. Saved flags and pacing survive, while Escape, input queues, mouse history and timing reset. The window family changes the title, waits for Enter in the terminal, closes and reopens.

Pair drawing frames

Call BeginDrawing, then ClearBackground and drawing operations, then EndDrawing. Draw and clear calls need an open frame. A duplicate begin or unmatched end returns raylib.invalid_order and preserves the current state. End camera mode before ending the frame.

Loads, window lifecycle, title/exit/FPS changes and texture filter/wrap changes require a closed frame. Input and timing observations can read the current sample inside a frame. EndDrawing presents accepted work, polls native events and applies target pacing. GetTime returns f64; GetFrameTime returns f32; GetFPS returns i32. Fresh windows report zero frame time and FPS before their first completed frame.

The frame family presents two short loops and checks timing reset after reopen. FPS is a target, not a guarantee about a busy host.

Read keyboard, mouse and resize samples

Window/input observations require the calling execution's live window and main thread. They read sampled state rather than installing source callbacks. Use exact Key and MouseButton constants; integer construction is not allowed. Down/up describe held state; pressed/released describe transitions; IsKeyPressedRepeat includes repeat observations.

GetKeyPressed consumes one queued key and returns KEY_NULL when empty. GetCharPressed consumes one queued Unicode scalar and returns zero when empty. Call repeatedly to drain queues when needed. A key event and typed text are distinct observations. SetExitKey(KEY_NULL) disables the exit key; opening a new window restores Escape.

Mouse position/delta and wheel values use checked f32 values. Logical GetScreenWidth/GetScreenHeight can differ from physical GetRenderWidth/GetRenderHeight. IsWindowResized reports the current resize sample.

Share and close textures

LoadTexture admits PNG files and requires a live window outside a frame. Paths resolve from the process working directory. Check the result before taking its opaque Texture. GetTextureWidth and GetTextureHeight return checked metadata. Choose POINT/BILINEAR filtering and REPEAT/CLAMP wrapping outside frames.

Texture copies share one closeable managed owner. UnloadTexture through any alias closes every alias and is idempotent. IsTextureValid then returns false. Other access returns raylib.closed_resource, even if the former window is also gone. Accepted drawing retains backing until native use ends, so logical unload during the final frame does not invalidate earlier accepted work. Reopening the window never revives old textures.

Draw with DrawTexture, DrawTextureV, DrawTextureEx, DrawTextureRec or DrawTexturePro. Source rectangles with signed dimensions preserve flips. Zero/negative scale and signed destination rectangles retain admitted Raylib behavior, with derived arithmetic checked before native entry.

Transform Camera2D coordinates

Construct every Camera2D field: offset, target, rotation and positive zoom. Angles use degrees. BeginMode2D(camera) needs an open drawing frame and no active camera mode. Pair it with EndMode2D before EndDrawing. Nested or unmatched modes return raylib.invalid_order without changing the current pair.

Draw inside the mode in world coordinates, then draw screen-space borders or controls after leaving it. GetWorldToScreen2D and GetScreenToWorld2D are pure checked helpers and need no window or frame. Convert sampled mouse coordinates with the same camera when testing world-space objects. Nonfinite inputs, zero zoom and unrepresentable derived transforms fail before native entry.

The camera shapes family draws a rectangle, circle, thick line and triangle through a camera, then a screen-space pixel and border.

Test collisions in one coordinate space

Collision helpers are pure checked operations. They need no display, frame or resource owner and are allowed in HTTP handlers and managed callbacks. Drawing and device operations are application-only; a helper or stored callable cannot bypass their effect restrictions.

Use CheckCollisionRecs and GetCollisionRec for rectangles, or the circle/rectangle/point/triangle tests in the reference. Supply both operands in the same coordinate space. Radius must be nonnegative. Admitted signed or degenerate geometry follows the pinned backend's behavior. Checked derived arithmetic can return raylib.numeric_overflow even when all inputs are finite.

The sprite family checks that rectangles at 24,24 and 30,28 overlap, then draws the returned intersection in red inside camera mode. This tests collision geometry as well as visual placement.

Select embedded or custom fonts

GetFontDefault returns the embedded Arabic/Latin Font with base size 32. CPU text needs no display or audio device. The pinned HarfBuzz, ICU and FreeType stack uses Unicode 17 and embedded Noto Sans Arabic Regular 2.013 and Noto Sans Regular 2.015. Host fonts, locale and ICU_DATA do not replace that baseline. The generated companion notices include the fonts' licenses and FreeType credit/disclaimer.

For a custom font, supply your own licensed single-face TrueType outline file relative to the working directory. LoadFont uses base size 32; LoadFontEx accepts base size 1..4096 and copied list<i32> scalar prewarming hints. Empty hints mean no prewarming, never restricted coverage. Collections, CFF/PostScript, WOFF/WOFF2, bitmap and color-font profiles are unsupported. Malformed required tables return raylib.invalid_font; unsupported profiles return raylib.unsupported_font; file read failures return raylib.load_failed.

Selection tries the custom font then script-preferred embedded fallback. It keeps grapheme clusters and Arabic joining sequences together. Arabic custom selection requires the admitted joining/mark features. No final replacement boxes are accepted; uncovered text returns raylib.missing_glyph.

Font copies share closure. A custom font owns copied file bytes, so replacing the file after loading does not change existing text. UnloadFont closes custom aliases, while existing layouts retain independent font backing. Unloading the default font succeeds without invalidating it. GetFontBaseSize reads metadata; it does not set a rendering size. Font loads require application/main-thread admission outside frames, but need no live window. Default access, measurement, layout creation and CPU unload are permitted in HTTP handlers and managed callbacks.

Keep logical text and measure its layout

Pass text in logical order. Arabic joining, ligatures, marks and mixed Arabic/Latin bidi placement do not rewrite the string, normalize identifiers or change path bytes. MeasureText and DrawText use Auto direction, Start alignment, no wrapping and no extra line spacing. MeasureTextEx, DrawTextEx and DrawTextPro require character spacing zero.

CreateTextLayout takes all six TextOptions fields. font_size is finite 0.5..4096. direction is Auto, LTR or RTL; Auto uses the first strong character, with LTR for neutral-only paragraphs. has_width activates a finite positive width; otherwise width is inactive. alignment is Start, End, Center, Left or Right. Start/End follow the paragraph base direction; Left/Right are physical. line_spacing is finite and nonnegative.

Wrapping uses ICU root line breaks, then emergency grapheme breaks. An oversized cluster may overflow the supplied width. LF, CR, CRLF and U+2029 separate paragraphs; U+2028 breaks a line. Blank/trailing lines, bidi controls, ZWJ/ZWNJ and soft hyphens follow the layout rules. Empty text has zero lines and height. NUL, tab, DEL and other unsupported Cc controls return raylib.invalid_text.

MeasureTextLayout returns TextMetrics. size is the logical box, using the supplied width when active. ink is local glyph bounds including marks and overhangs. Effective font size rounds to 1/64 with ties to even. MeasureText accepts integer sizes 1..4096 and rounds the shaped width upward to checked i32; MeasureTextEx returns logical Vector2 size. These CPU operations work before window creation.

Layouts are immutable shared owners. Unloading one alias closes all aliases and repeated unload succeeds. A layout retains its fonts after custom Font unload and survives window close/reopen. Access to a closed layout returns raylib.closed_resource; the validity probe returns false.

Draw the measured positions

DrawTextLayout draws at logical top-left. DrawTextLayoutPro adds origin and rotation. DrawTextEx and DrawTextPro shape the same logical text with zero character spacing. Origin, rotation and Camera2D transform placement without changing local metrics. Glyph-cache eviction preserves those metrics.

Text drawing requires the application's main thread, a live window and an open drawing frame. A known validation, glyph, numeric or preparation failure submits none of that text request. Previously accepted draws remain valid. Accepted work may retain glyph backing after logical unload until presentation or native quiescence.

The shaped text/audio family prepares and measures its layout before the window opens. Gray outlines show the logical box; red outlines show ink. The original OGG tone and CC0 notice are required external assets; default fonts are embedded.

Initialize audio and update music

InitAudioDevice tries PulseAudio through libpulse.so.0, then direct ALSA through libasound.so.2, including playback-start failures. PipeWire works through its PulseAudio-compatible service. Each fallback requires complete safe release. A successful route stays fixed until close; there is no null-device success. Audio and window share the execution's process device lease but have separate close/rollback scopes.

Load Sound or Music after audio initialization and outside drawing frames. LoadSound decodes copied WAV/OGG/MP3 bytes; LoadMusicStream retains copied bytes, decoder and bounded stream buffers independently of the original file. Playback, pause/resume/stop, volume, pan, pitch, seek, looping and UpdateMusicStream are application/main-thread operations permitted inside a frame. Volume is finite 0..1, pan finite -1..1 and pitch finite and positive. The derived resampling rate must fit the admitted native range; refusal preserves the prior pitch, while converter failure restores it or closes that owner.

Playing streamed music alone does not decode or refill it. Call UpdateMusicStream explicitly, usually once per frame. GetMusicTimeLength and GetMusicTimePlayed report checked f32 seconds. SeekMusicStream admits 0..reported length inclusive. The endpoint means logical EOF; the next update restarts playing looping music or stops nonlooping/empty music. Paused/stopped updates stay inactive. Decoder seek refusal closes that Music's aliases and returns raylib.load_failed.

Sound and Music copies share a closeable owner in the current audio generation. Unload stops/untracks playback; device close invalidates all dependents before native destruction. Reopen never revives old aliases. Backing and memory charges remain until mixer/decoder use ends, independent of playback completion. IsAudioDeviceReady, IsSoundValid and IsMusicValid are total probes; GetMusicLooping reads retained metadata. These may run in handlers/callbacks. Playback observations and SetMusicLooping still require application admission. The mixer never calls an ASPL source callback.

Give HTTP and drawing explicit turns

Import core::http as well as Raylib. HTTP guidance and the HTTP API own complete service declarations. start returns Session<C,S> after listeners are ready and dispatches no handler. Call progress outside drawing frames. Its default budget is 4096 instructions, 2 active ms and zero wait ms. Turns are bounded and serialized; OS/native work can overrun active_ms. A busy handler can yield at its instruction budget while the application continues drawing.

EndDrawing and parked input may maintain transport/deadlines outside drawing but dispatch no source handler. Input inside a frame drives neither HTTP nor handlers. A blocking top-level HTTP client request against its own explicit server can time out. Arrange explicit progress frequently enough for the application.

Application session state/configuration helpers can run inside a frame. Handler Context helpers remain live-handler-only. Reads copy state; snapshots keep hidden session/version identity and their read-only value survives close. Conditional publication replaces whole state and advances its version. A stale same-session snapshot returns successful false; a foreign-session snapshot returns http.invalid_argument. A saved owner/snapshot or callable grants no device/Context authority. Device calls are forbidden transitively in handlers; pure math, CPU text, total probes and read-only owner metadata remain permitted.

stop_session starts drain; continue progress until SESSION_CLOSED. close_session revokes serving immediately without dispatching drain handlers. Repeated normal stop/close succeeds. Closed state helpers return http.closed_session; wrong frame/context returns http.invalid_order or http.invalid_context. Safely released host failures remain latched.

The concurrent HTTP/frame family supplies original Arabic, English and mixed programs. Prepare the loopback upstream and clients described there. The square moves while /busy, /wait and /fast share turns; a delayed upstream lets the snapshot become stale. See HTTP deployment for TLS/trust facilities.

Preserve aliases, user identity and literals

Exact supplied aliases name the same types/operations. Both aliases of one supplied record field count as a duplicate. User records and fields keep their written names. Locale switching selects documentation, not source translation. Strings keep decomposed characters and NUL bytes; a path-shaped literal is not a file read. Text, path and title operations separately enforce their allowed input.

The identity/literals family runs without graphics, audio or an upstream. It uses embedded shaped measurement, exact record/enum/flag aliases and the pure HTTP progress budget. Its ordinary unsafe libc.so.6 abs call retains the C-interoperability contract. It prints a bilingual invalid-tab diagnostic, a literal PNG path and decomposed/NUL content. No PNG download is required.

Text error messages include zero-based logical scalar_index=N and scalar=U+XXXX; malformed native UTF-8 uses byte_offset=N. These are message details, not extra result fields or a message-parsing API. Unsupported controls are escaped in the diagnostic, while ordinary output keeps literal bytes.

Finish and release resources

Check explicit unload/close results on normal completion. Return, trap, limit or cancellation revokes source work and abandons an open frame without intentionally presenting a final frame. Cleanup releases GPU work before its window and mixer/decoder work before its audio device. Backing and charges remain retained when native release cannot be proved. Driver hangs have no hard in-process preemption guarantee.

Default limits are 256 MiB for the VM and one shared 128 MiB Raylib/HTTP backend account. Refusal before native entry preserves state; failure after native effects promises owned cleanup rather than general rollback. See limits and errors.

When distributing an ELF program, keep its generated .THIRD-PARTY-NOTICES companion and required assets/notices. A generated program runs without the source or ASPL compiler but still needs the documented Linux graphics facilities. The original guide source (opens in a new tab) remains an exact published download.

The first SIGINT/SIGTERM permanently stops application code, cancels parked input/application requests and drains only already admitted HTTP handlers outside drawing. A second signal revokes remaining drain. Traps, limits and other cancellation dispatch no drain handlers. Remaining-resource cleanup uses one deadline t + max(R,H), capped by earlier execution and operation/session scopes; retries never renew it. R is Raylib's cleanup allowance. H is the remaining session's allowance, otherwise the maximum of 1000 ms and admitted client cleanup allowances when HTTP work remains. Unused imports and closed headers add none. Terminal statuses retain trap 5, limit 6, cancellation 7 and host failure 8, with separate cleanup attribution for an earlier primary outcome.

Deploy with the actual host dependencies

The tool and generated programs target x86_64 Linux with glibc 2.34 or later. They are ELF64 PIE with interpreter /lib64/ld-linux-x86-64.so.2, direct dependencies libc.so.6 and libm.so.6, RELRO, immediate binding, non-executable stack and no RPATH/RUNPATH. Dynamically loaded host graphics/audio libraries bring their own dependency closures, permissions and drivers. CPU text and pure helpers require only the CPU/glibc baseline; an import alone acquires no display or audio device.

Host loading uses normal loader search with immediate/local scope and required symbol checks. Development symlinks are unnecessary. Display selection follows host preparation; audio tries PulseAudio then ALSA. Invalid arguments, resource refusal, cancellation or unproved cleanup stop retries. All safely failed candidates report the final candidate's category and attempted backends. No graphics/audio route substitutes headless success.

The tool embeds Raylib 6.0, HarfBuzz 14.4.0, ICU 78.3 with full Unicode 17.0.0 data, FreeType 2.14.3 and the default fonts. Application check/build invokes no C compiler, assembler or linker and acquires no device. Recipients need no ASPL runtime, system Raylib, host fonts or source. PNG, WAV/OGG/MP3 and custom font files remain external when used. Preserve working-directory paths and their licenses.

After downloading the shaped family and its OGG/notice into the stated tree:

mkdir -p deploy/docs/examples/assets
aspl build -o deploy/shaped docs/examples/raylib/shaped-text-audio.en.aspl
cp docs/examples/assets/raylib-tone.ogg docs/examples/assets/raylib-tone.NOTICE deploy/docs/examples/assets/
cd deploy
./shaped --aspl-diagnostic-language=en

Ship <program>.THIRD-PARTY-NOTICES beside the executable with asset notices. Runtime does not read the companion. Build publishes it atomically first, then the executable. Notice failure prevents executable publication; later executable failure preserves the old executable and reports the already published notice. Source/module collisions report output-is-source, executable/companion aliases output-path-collision, and unsafe/write/publication failures host-operation-failed with phase/path/partial-result details. Source runs create no companion.

The whole import graph, including unused/transitive imports, selects core, HTTP, Raylib or combined prepared programs. Core/HTTP-only outputs add no Raylib/font/device requirements. Private bytecode/catalog/preparation records must match the selected tool; they are not a stable public ABI. Previously distributed self-contained programs retain their embedded identities. Installation, system requirements, downloads and HTTP deployment provide the related workflows. The original deployment source (opens in a new tab) retains its released bytes and evidence scope.

Entry function

An ASPL program starts at the root file's required ابدأ_الرئيسية / start_main function. It takes no parameters and returns i64. Top-level declarations include functions, records, and imports. Native programs may include user source modules and foreign declarations. Executable statements and bindings belong inside functions.

The entry function cannot be called from source. A missing entry function or an invalid signature fails checking with missing-entry-function or invalid-entry-signature. Calling the entry function fails with entry-call-not-allowed.

Process status

Return an integer from 0 through 255 as the process status. Any other result ends execution with trap / invalid-process-status; ASPL does not truncate it. The same entry contract applies to the browser and native hosts in ASPL 0.7.0.

Status and stdout are independent. A normal return of 1 is a successful ASPL execution. Source errors, traps, recoverable results, cancellation, and host or resource failures have distinct outcomes. Use print to produce output, and native commands to look up CLI status conventions.

Complete example

This checked example returns status 0 and produces no output. The source vocabulary is independent of the documentation locale.

{
  "browser": {
    "check": "success",
    "class": "success",
    "output": "",
    "processStatus": 0
  },
  "native": {
    "check": 0,
    "status": 0,
    "output": ""
  }
}

Linux command grammar

These forms describe the published native ASPL 0.7.0 tool. Follow the installation page for verification and PATH setup.

aspl [COMMON_OPTIONS] check [--] SOURCE
aspl [COMMON_OPTIONS] run [--] SOURCE
aspl [COMMON_OPTIONS] build [-o OUTPUT | --output=OUTPUT] [--] SOURCE

Common options are --diagnostic-language=ar|en and --color=auto|always|never. They precede the command and each may appear once. Values are case-sensitive and use =. Build output options precede the source. -- permits a source path beginning with a dash. Source paths end in .aspl or .لبات; commands take one root source and load its explicit source-module imports. They do not accept source from stdin, multiple roots, public bytecode output or program arguments.

Use aspl --version, aspl --help or aspl build --help for information. Version is the language-independent line aspl 0.7.0. Help and diagnostics default to Arabic, regardless of source vocabulary or process locale. For English, use aspl --diagnostic-language=en --help.

Compiler and execution phases

All three commands read the source, resolve explicit source modules, compile and validate private bytecode. check then discards the result. run prepares native dependencies and executes in the same process. build packages and validates an ELF, writes a temporary in the destination directory and publishes it by atomic rename. It invokes no external compiler or linker. Checking and building never execute the program or load its foreign libraries.

Without an output option, build removes the final source suffix. Explicit output paths are used as supplied. Missing parent directories are not created. A destination that is the source is rejected. A failure before publication retains the old output; successful publication replaces it. Atomic visibility does not promise durability across power loss.

Status and streams

Successful check/build returns zero and is silent unless there are warnings. run and built programs return the entry function's normal integer result from 0 through 255. A result outside that range traps. Normal nonzero results can overlap failure statuses; inspect stderr for diagnostics. Warnings do not change success status.

Program output uses stdout; diagnostics and traps use stderr. run adds no success banner to program output. Use --color=never for plain diagnostics in a script. The tool inherits working directory, environment and standard streams. Foreign code has native process authority and can fail outside ASPL's runtime guarantees.

Built program controls

A built program accepts only --aspl-diagnostic-language=ar|en and --aspl-color=auto|always|never, each once with =. With no controls, diagnostics are Arabic and color is automatic. It accepts no ordinary arguments, --, --help or --version. For example, ./hello --aspl-diagnostic-language=en --aspl-color=never runs the program. See native input and standalone execution.

Native line input

In ASPL 0.7.0, اقرأ_سطر / read_line: () -> string reads one line from inherited stdin. It accepts no arguments or unsafe marker. The builtin prints no prompt, echo or terminator. Print your prompt first; it is visible before the input wait even without a newline. Terminal input, pipes and redirected files use the same reader for aspl run and built programs.

LF and CRLF terminators are removed. An empty line returns an empty string. A final unterminated line is returned once at EOF; a later read traps with input-exhausted. Whitespace, NUL, Arabic marks, direction controls, digits and normalization remain as supplied. Input is data and does not pass through source digit conversion. The reader consumes only the current line, leaving later stdin bytes for later reads or foreign code.

EOF and input failures

The runtime validates each complete line as strict UTF-8. Malformed bytes trap with invalid-input-utf8 and the first invalid byte offset. The default line limit is 65536 payload bytes, excluding LF or CRLF. Exactly that size succeeds; a larger line stops execution with input-line-limit instead of returning truncated text. EOF without a line is a trap, not an empty string. Cancellation or a signal interrupting an input wait is not reported as EOF.

Try piped and redirected input

Download the supplied Input example as input.aspl. It asks for a name, prints the supplied name with its greeting, and returns zero. The English-keyword variant retains the original Arabic prompt and output text.

printf 'Mina\n' | aspl run input.aspl
printf 'Mina\n' > name.txt
aspl run input.aspl < name.txt
aspl build -o input input.aspl
printf 'Mina\n' | ./input
./input < /dev/null

The first three execution forms print ما اسمك؟ مرحبا Mina and a newline. The last command has no line available: it prints the prompt, then traps with input-exhausted, diagnostic stderr and status 5. To choose English diagnostic text for it, use ./input --aspl-diagnostic-language=en < /dev/null.

Standalone program requirements

The published 0.7.0 native templates embed the VM and private bytecode version 7. Private bytecode is not a stable public file format. A built ELF runs after removing source and ASPL from PATH. It still needs the compatible Linux loader and libraries and any external libraries or runtime data its program uses. Building does not verify the availability of those runtime dependencies.

Built programs inherit stdin, stdout, stderr, environment and working directory. Their only accepted controls are native diagnostic options. Use ./program to execute a local file; an executable in the current directory is not automatically on PATH. A native release upgrade or rollback does not change an existing ELF. Rebuild from source with the selected tool when you want that tool's generated program.

Source rules

Source is strict UTF-8 under Unicode 17.0. Identifiers are case-sensitive NFC names, each using one Arabic or Latin script. English keywords and word operators are exact aliases and may mix. Executable digits and punctuation use ASCII; equality, conjunction, and disjunction use matches, and, and or or their Arabic aliases يطابق, تطابق, و, and أو. Numeric prefixes are 0x/0X and 0b/0B, or 0س and 0ث; Arabic hexadecimal uses ا ب ت ث ج ح for values 10 through 15. Statements end with . or ;. Each numeric token stays LTR in logical source order, and display order never changes source bytes.

Identifiers use the Unicode XID_Start and XID_Continue profile with _; NFC normalization determines identity. A leading UTF-8 BOM is allowed and counts toward source size. Raw NUL is legal inside strings and comments and forbidden outside them. \0 in a string also creates a runtime NUL. Strings and comments keep their contents without normalization. LRM and RLM are allowed only at legal token boundaries, while other forbidden controls fail checking. Diagnostic display exposes controls by code point and name.

match is also an equality alias. not / لا / ليس / ليست negates a Boolean and can precede equality as in a not match b. != is unequal; ==, &&, and || are invalid.

Editor digit conversion

Accepted: Arabic and English keywords and either radix alphabet in one program. Rejected: unconverted non-ASCII digits outside strings and comments, an identifier mixing scripts, or a hexadecimal spelling that mixes alphabets. The editor converts Arabic-Indic and Extended Arabic-Indic digits to ASCII outside strings and comments, and makes invisible controls visible.

Typing and pasting in the source editor convert digits only outside strings and comments. Source-file import preserves bytes and bypasses that conversion. Program input and numeric parsing do not pass through the editor. RTL or LTR display and copying preserve logical source order.

Strings and comments

Strings use double quotes. Escapes are \\, \", \0, \n, \r, \t, and \u{...} for one Unicode scalar in one through six hexadecimal digits. Raw line breaks and unknown escapes fail checking. // starts a line comment; /* ... */ is a non-nesting block comment. See numbers for literals and radix prefixes.

ASPL 0.7.0 also accepts Arabic escape aliases. Both vocabularies may appear in the same string, and each pair produces identical bytes. The backslash remains the escape introducer; / is ordinary string content.

\u{...} keeps its ASCII hexadecimal alphabet. \ي{...} accepts ASCII hexadecimal digits plus ا ب ت ث ج ح for values 10 through 15, including combinations of the two alphabets. Both forms require one through six digits, reject surrogate values and values above U+10FFFF, and accept U+0000 in strings. For example, \ي{062ت} and \u{062C} both produce ج. Arabic-Indic digits and separators are invalid in either form. Published 0.6.0 artifacts retain their original escape syntax.

Release scope and related reading

This page describes ASPL 0.7.0. The linked MVP text is a historical record, not a complete description of current extensions.

The numeric extension added radix prefixes and bitwise operators. ==, &&, and || remain invalid. Sum demonstrates mixed vocabulary.

Exact types

There are no implicit conversions. Every typed numeric value keeps its exact width and signedness. Operations need matching operand types, and boundaries and aggregates do not convert values. The only conversion applies a numeric type name explicitly, such as ط8(value) or u8(value), and it can trap when the value is not representable. ص64/i64 remains the type for the entry result, indexes, lengths, and Unicode bounds. Strings are immutable, c_ptr is opaque and nullable, and unit cannot be stored. Initialized bindings may infer their type, if, while require booleans, and return must match its declared result.

The other basic aliases are منطقي / bool, نص / string, مؤشر_سي / c_ptr, and وحدة / unit. Boolean literals are صواب / true and خطأ / false; the null pointer is عدم / null. Equality needs matching types; strings compare exact UTF-8 bytes and pointers compare identity. unit cannot be stored, passed as a value, or compared.

Bindings

دع / let is immutable and متغير / var allows assignment. Every binding needs an initializer. Write a type after : or let checking infer it. Shadowing is forbidden. Typed numbers never convert implicitly, including inside lists, records, or results. 0.7.0 also has list<T>, result<T>, records, and callable values, extending the MVP basic types.

Control flow and evaluation

Conditions must be bool. و / and and أو / or short-circuit; ! negates a Boolean. Operands, arguments, and initializers evaluate left to right. Assignment finishes its right side before changing its target. إذا / if, وإلا / else, and طالما / while use lexical blocks. There is no break or continue. Every path through a non-unit function must return its declared type. An if proves a return when both branches return; a while never proves one. Structurally unreachable code is rejected.

Sum prints 55\n and returns status 0. Diagnostic and correction demonstrates immutable assignment rejection.

Release scope and related reading

This page describes ASPL 0.7.0. The linked MVP text is a historical record, not a complete description of current extensions.

Types and ranges

ع32 / f32 is IEEE 754 binary32; ع64 / f64 is binary64. Each alias pair names one exact type. These names and numeric parse/format names cannot be redefined.

Source literals

A decimal integer with leading zeroes remains decimal. Latin hexadecimal 0x/0X accepts digits and a..f/A..F, while 0س accepts digits and ا ب ت ث ج ح. Binary is 0b/0B or 0ث. Each prefix needs at least one digit. _ may appear only between valid digits, never beside a prefix, decimal point, or exponent marker, and never first, last, or repeated. There are no type suffixes, octal, hexadecimal floats, NaN literals, or infinity literals. A period terminates a statement unless it starts a fraction: 1. is an integer then a terminator, while 1.0. is a float then a terminator.

A decimal float has a fraction with digits on both sides of . or an e/E exponent with an optional sign and at least one digit. 1e2 and 1.0e-2 are valid; .5 is not. A source sign is a unary operator, not part of the literal token. Radix alphabets cannot mix inside one token. All numeric digits are ASCII even with Arabic prefixes.

Literal context and precedence

Precedence runs from calls, indexing, fields, and grouping; through ! - ~, * / %, + -, shifts, &, ^, |, ordered comparisons, equality, Boolean AND, and Boolean OR. Binary operators associate left and unary operators associate right.

Context comes from an annotation, assignment, parameter, return, field, list, result, or typed operand. A literal without context defaults to i64 or f64. Direct minus admits every signed minimum, and a contextual u64 literal reaches 18446744073709551615. The checker does not select the smallest fitting type or convert an already typed value.

Integer operations

Addition, subtraction, multiplication, and division need one matching type and return it. % is integer-only. Addition, subtraction, multiplication, and signed-integer negation trap with integer-overflow rather than wrapping. Unary minus on an already typed unsigned integer is rejected during checking with numeric-operator-not-supported. Division truncates toward zero, the remainder takes the dividend's sign, and zero or signed-minimum divided or remaindered by -1 traps. ~ & ^ | << >> work at the operand's exact width. A shift count may be any integer type and is not converted to the left type. A negative count or one equal to or greater than the width traps with invalid-shift-count. Left shift discards high bits, unsigned right shift fills with zero, and signed right shift extends the sign.

Floating operations and explicit conversion

Each f32 or f64 primitive rounds to nearest even at its own width before the next operation. Multiplication and addition do not fuse. Subnormals, signed zero, infinities, and IEEE results from division by zero remain values. Arithmetic NaNs become positive quiet NaNs and ordered NaN comparisons are false.

An explicit conversion applies any numeric type name to a numeric expression only. Integer-to-integer conversion checks range. Integer-to-float conversion rounds the mathematical integer directly to the target width, nearest even, and every integer is finite; the largest u64 therefore becomes 2^64 in f64. Float-to-integer conversion truncates before range checking, and float-width conversion rounds without trapping. A value-dependent conversion failure happens only when execution reaches it. Its classifications are below-range, above-range, nan, positive-infinity, and negative-infinity. Nested conversions run inside out and retain every rounding point.

Parsing and formatting

Every type has a parser and formatter: حلل_ص8/parse_i8 and نسق_ص8/format_i8; حلل_ص16/parse_i16 and نسق_ص16/format_i16; حلل_ص32/parse_i32 and نسق_ص32/format_i32; حلل_ص64/parse_i64 and نسق_ص64/format_i64; حلل_ط8/parse_u8 and نسق_ط8/format_u8; حلل_ط16/parse_u16 and نسق_ط16/format_u16; حلل_ط32/parse_u32 and نسق_ط32/format_u32; حلل_ط64/parse_u64 and نسق_ط64/format_u64; حلل_ع32/parse_f32 and نسق_ع32/format_f32; حلل_ع64/parse_f64 and نسق_ع64/format_f64.

A parser takes string and returns result<T>; a formatter takes exactly T and returns string. Integer text is an optional ASCII sign followed by ASCII decimal digits. Float text has an optional ASCII sign, digits, an optional fraction with following digits, and an optional e/E exponent with an optional ASCII sign and digits, or exactly nan, inf, +inf, -inf.

These are runtime-text rules, not source-literal rules: whitespace, separators, prefixes, suffixes, NUL, trailing text, and non-ASCII digits fail, as do float forms .5 and 1.. Parsing checks the whole grammar before range. Exact messages are invalid number for T, number out of range for T (MIN through MAX), or finite number out of range for T. A failed result has no diagnostic, source location, or trace.

Formatting is deterministic ASCII and round trips every finite float, with -0, nan, inf, and -inf written exactly.

Numeric storage

Bindings, parameters, returns, record fields, lists, and result payloads preserve all ten types exactly. Each reserved numeric-list slot takes its scalar width: 1 byte for i8/u8, 2 for i16/u16, 4 for i32/u32/f32, and 8 for i64/u64/f64.

Length, capacity, and charges are separate. An empty list has zero capacity, nonempty capacity is between length and max(4, 2 * length), and element charge is capacity * width. Copies share first and detach on mutation, then the last owner reclaims storage. There is no public byte view or promise about addresses, alignment, byte order, or C layout. Memory limits, cancellation, and allocation failure do not publish a partial mutation.

Release scope and related reading

The archived 0.4.0 numeric extension added ten widths, hexadecimal and binary literals, bitwise operations, and per-type text conversion. Its numeric rules remain in 0.7.0, but current private bytecode is version 7, not 4. The browser-result wire is 3. Bytecode is not a public compatibility interface. This page does not rewrite the MVP record that specified only i64 and f64.

Success and intentional failures

Diagnostic fields explain literal rejection versus conversion traps.

Read the complete families:

• numeric-types
• numeric-range-check
• numeric-conversion-trap

Diagnostic record

A diagnostic carries a stable reason key, severity, typed arguments, a primary span, ordered secondary spans, and an optional edit. Language changes wording only. Technical type names, operators, bounds, and values stay full-width ASCII. Warnings do not block execution. Direct execution maps a diagnostic to source. Built programs contain no source map, but report the trapping function name and relative instruction index. The first example assigns an immutable binding. The correction replaces دع / let with متغير / var and normally returns status 1.

Source span and correction

Select a diagnostic to locate it in the checked source snapshot. Transport spans are half-open UTF-8 byte offsets, and the editor selects logical source. A diagnostic may include a proposed edit. In the immutable-binding example the primary span locates the assigned identifier, secondary spans are empty, and no automatic edit is supplied. Manually replace دع / let with متغير / var. Other diagnostics can include ordered secondary spans. Applying a correction and checking again does not run the program. Corrected source succeeds with status 1 and no output.

For an automatic correction, unsafe print("text") produces unsafe-on-safe-call with a removal edit for the unsafe marker. Apply that edit explicitly, then check again. The primary span locates the marker and the replacement is empty.

Distinct outcomes

The example let byte: u8 = 256 is a checking error because the contextual literal is out of range. In contrast, u8(256) has a valid default i64 operand and traps with invalid-numeric-conversion only if reached. parse_u8("256") returns a failed result with code number-out-of-range. None of these outcomes becomes another.

A source error prevents compilation. A warning permits it. A failed result<T> is a value the program can inspect. A trap stops the whole program and cannot be caught. Load failure precedes execution. limit-stop, cancelled, and host-failure are separate outcomes. success with status 1 is language success, even when a shell treats it as nonzero.

Numeric technical fields

The integer numeric-literal-out-of-range checking diagnostic fields are spelling, type, minimum, maximum. Its floating form has spelling, type, classification, where the classification is finite-overflow. numeric-operator-not-supported has operator, type.

Numeric trap fields are ordered: integer-overflow has type, operation, operand-count, operands; integer-zero-divisor has type, operation, dividend; invalid-shift-count has left-type, count-type, count, width; and invalid-numeric-conversion has source-type, target-type, classification, then source-value or source-bits. Unsigned values through full u64 travel without JavaScript-number rounding.

Release scope and related reading

This page describes ASPL 0.7.0. The linked MVP text is a historical record, not a complete description of current extensions.

Print text

The output builtin is اطبع / print: (string) -> unit. It writes string bytes in order, including NUL, without an automatic newline or flush. Add \n explicitly. Neither alias can be redefined. The browser safely displays output bytes without interpreting them as page markup.

Accepted: one string, including an empty string. Rejected: a number, multiple arguments, or storing the result.

Output, status, and host failure

Writing is synchronous; an empty string does not touch the host. Native output retries interrupted writes and continues short writes. Output accepted before failure remains visible. There is no special SIGPIPE handler; a closed pipe may terminate the process through that signal. If the environment ignores or blocks it and writing returns EPIPE, the result is a host failure with status 8.

Output is separate from process status. The browser 256 KiB ceiling rejects a whole crossing write and retains earlier output. Browser output stays safe text even when it contains HTML markup.

Release scope and related reading

This page describes ASPL 0.7.0. The linked MVP text is a historical record, not a complete description of current extensions.

Reading a line and EOF

The builtin اقرأ_سطر / read_line: () -> string reads one line. It takes neither arguments nor an غير_آمن / unsafe marker, and neither name may be defined. Print a prompt before the call because the builtin writes no prompt, echo, or terminator. A line ends in LF or CRLF, which are removed. An empty line produces an empty string. A final unterminated line is returned once at EOF, then the next call traps with input-exhausted.

Accepted: pass, return, compare, print, measure, index, slice, concatenate, or explicitly parse the read string with a numeric parser. Rejected: treating source notation or Arabic-Indic digits as accepted numeric input, or implicitly converting a string to a number.

Exact input and UTF-8

The runtime validates the complete line as strict UTF-8. Whitespace, NUL, Arabic marks, direction controls, Arabic-Indic digits, and normalization form stay exactly as the host supplied them. Program input does not pass through the source editor, lexer, or digit conversion. Invalid input traps with invalid-input-utf8 and the first invalid byte offset.

Line limit and cancellation

Both hosts allow 65536 payload bytes per line, excluding LF or CRLF. Exactly that size is accepted. A larger line ends the run with input-line-limit, never a truncated string. Cancelling while waiting is cancellation, not EOF.

String ownership

The execution owns each successful nonempty input string under shared runtime ownership: literal bytes stay borrowed from the compiled program without copying, while registers, parameters, and returns carry the same immutable bytes across calls and returns. Replacing a binding or cleaning up a frame reclaims the discarded string, so the VM memory limit counts only live strings.

Release scope and related reading

This page describes ASPL 0.7.0. The linked MVP text is a historical record, not a complete description of current extensions.

Line input was added after the output-only MVP builtin contract. See browser input or native input.

Input request

When a program reaches read_line, the playground shows a waiting state, a one-line field, and Send, Close input, and Stop. Send sends the current draft only for the displayed request and clears it after the worker acknowledges it. Close input sends EOF without sending the draft, which remains visibly unsent. Stop cancels the run and is not EOF.

Input draft

The field rejects multiline paste and CR or LF, and shows the byte limit. Draft bytes and digits stay as entered and do not pass through the source editor. Input echoes are separate interface records, not program output or part of its output limit.

Deadline and draft state

The execution limit measures accumulated active time only. Time spent waiting for input does not consume it. Auto, LTR, and RTL keep output bytes, the draft, source snapshot, and request identity, changing display direction and alignment only.

Leaving Home or switching source drafts ends the request. Returning restores document-held data and checks source; it does not restart execution or resend input. Refresh starts without previous output or input. Stop retains output and the unsent input draft. See execution limits and line input.

Release scope and related reading

This page describes ASPL 0.7.0. The linked MVP text is a historical record, not a complete description of current extensions.

Interactive line input extends the MVP browser contract. This page covers input; virtual run files are separate temporary data.

Hosts

The browser runs compiler and VM in a local WebAssembly worker without sending source to a server. It rejects foreign imports even when unused with policy-rejection / foreign-imports-not-supported. User source modules, C interoperability, HTTP, and Raylib require native execution. The native host runs on Linux with process authority and is not a sandbox.

Resource ceilings

MiB = 1048576 bytes; KiB = 1024 bytes.

none means no product ceiling; n/a means not applicable. The first observed ceiling determines the outcome.

Memory accounting

Source includes every byte read, including a leading byte-order mark. Compiler memory includes all live compilation allocations. Execution memory includes frames, slots, C-string loans, and live execution-owned strings, excluding immutable program storage, libraries, and foreign allocations. A structural ceiling wins over a memory ceiling at the same operation. Allocation failure below the ceiling is host-failure / allocation-failed.

Deadlines and output

The check clock starts when the loaded worker accepts the job; the run clock starts when it accepts execution after a successful check. Loading counts against neither clock, and waiting for user input does not count against the run clock. The first observed ceiling determines the outcome; a deadline terminates the worker with time-limit. The output ceiling rejects the entire crossing write and retains prior output as partial. Native execution has no product instruction, time, or output ceiling, subject to the instruction counter's representational maximum.

Release scope and related reading

This page describes ASPL 0.7.0. The linked MVP text is a historical record, not a complete description of current extensions.

In 0.7.0 private bytecode is 7 and browser-result wire is 3. Execution memory also accounts for live list, record, and result storage. Files and input extend the historical MVP scope.

Browser-limited loop

Open this example only in the browser. Do not run it natively, where there is no product instruction ceiling. The first observed limit wins; a slow device can reach the time deadline before the instruction ceiling.

Calling builtins

Builtins are predeclared and need neither an import nor غير_آمن / unsafe. Arabic and English aliases name the same reserved target and cannot be declared or shadowed. Checking enforces argument count and exact types. A conversion such as u8(value) is a checked language operation, not a text parser returning a recoverable result.

Families and names

These names are available in 0.7.0 on both hosts. Browser files are temporary virtual files.

Types, results, and hosts

See output, line input, and numeric parsing and formatting. length measures strings and lists; the other string operations use i64 Unicode scalar bounds. success and failure construct inspectable results. append modifies a mutable list target; join joins list<string> with a string separator. read_text_file returns result<string> and write_text_file returns result<unit>. Expected host failures do not become traps. Qualified library calls such as net_http::get require native execution and an import. Text and data examples provide the current string, result, and file sources.

Release scope

The MVP specified only اطبع / print. This page describes the 0.7.0 builtin set, including later string, input, result, list, file, and numeric extensions.

Exact string values

ASPL 0.7.0 supports these operations in the browser and on the native host. A نص/string is an immutable, strict UTF-8 value. It preserves BOM, NUL, line endings, direction controls, whitespace, and normalization. matches compares exact bytes. "é" and "e\u{301}" are different strings even when they look alike.

Unicode scalar positions

Positions start at zero and count Unicode scalar values, not UTF-8 bytes, UTF-16 code units, or displayed graphemes. A combining mark counts separately; an emoji sequence can contain several scalars. length("aمرحبا😀") is 7.

An index must satisfy 0 <= index < length(text). A slice must satisfy 0 <= start <= end <= length(text). Empty slices, including at the end, succeed. Invalid indexes trap with string-index-out-of-bounds; invalid slices trap with string-slice-out-of-bounds. from_codepoint accepts zero through 1114111 except surrogate values 55296 through 57343; invalid values trap with invalid-unicode-scalar.

Concatenation and joining

+ concatenates two strings and has the usual addition precedence. Format a number explicitly before concatenating it. اجمع_نصوص/join: (list<string>, string) -> string puts the separator between elements only. An empty list produces ""; one element gets no separator. Neither operation changes the inputs or normalizes text.

Strict numeric text

The numeric reference lists every exact-width parser and formatter. Parsing returns a recoverable result, not a trap for ordinary bad text. Integer text accepts an optional ASCII sign and decimal ASCII digits, including leading zeroes. Decimal float text accepts an optional ASCII sign, digits, an optional fraction with digits after the point, and an optional exponent, or exactly nan, inf, +inf, -inf.

Whitespace, non-ASCII digits such as ٢, NUL, radix prefixes, separators, suffixes, and trailing text produce invalid-number. .5 and 1. also fail. Well-formed text outside the target range produces number-out-of-range. The editor's source-digit conversion does not convert text sent through program input or imported files.

The integer example needs two input lines, 256 then 41. The float example needs 12x then 41. Both handle the first failed result and continue to print 42 for the second line.

Scope and complete examples

These current operations extend the historical MVP's string rules. The archived specification remains a record of that earlier scope. Complete supplied variants are available in strings, join, integer parsing, and float parsing.

Typed list values

In ASPL 0.7.0, قائمة<T>/list<T> is a growable sequence of one exact storable element type, supported in the browser and natively. Type arguments use angle brackets; square brackets construct values. Nested lists, records, and results are allowed. unit elements and whole-list equality are rejected during checking.

A nonempty literal infers its element type without numeric coercion. An empty literal needs an expected type from a binding, assignment, argument, or return. Elements evaluate in written order; a trailing comma is allowed.

Illustrative fragment

let empty: list<i64> = [];
let values: list<i64> = [3, 4, 5,];

Reading elements

طول/length: (list<T>) -> i64 returns the element count in constant time. values[index] reads an element by value. The index has type i64 and starts at zero; negative indexes and indexes at or beyond the length trap with list-index-out-of-bounds.

Mutation and independent copies

أضف/append takes a mutable list location and one value of exactly its element type, adds the value, and returns unit. Indexed assignment replaces an existing element; it does not grow the list. Both require a متغير/var root binding. A دع/let binding, function parameter, temporary value, or result payload projection is not a mutable location.

Assignment, arguments, returns, and aggregate fields copy values. Mutating a copy, including a nested list, leaves other copies unchanged. The runtime can share storage until mutation, but it does not expose shared mutable aliases. Mutation resolves indexes left to right once, before evaluating the new value. append(xs, xs[0]) is valid.

Storage and failures

Numeric list slots preserve their exact widths, as described in numeric storage. Length and capacity differ; there is no public byte view or C-layout promise. Runtime-owned lists and their retained elements count against execution memory. Resource limits or allocation failure do not expose a partially committed mutation.

Checking rejects mismatched element types, untyped empty literals, invalid mutation targets, and immutable mutation. An out-of-bounds access is an uncatchable trap, not a recoverable result.

Scope and complete examples

Lists extend the historical MVP. Read every supplied variant in typed lists and list mutation, or continue to records and value semantics.

Named record types

ASPL 0.7.0 supports سجل/record on both hosts. Declare a record at file scope with named, typed fields separated by commas. A trailing comma is allowed. Record names are collected before field types resolve, so declaration order does not matter.

Records are nominal. Two declarations with identical fields are different types; identity belongs to the defining source module. The browser supports records in the entry file; user source modules require native execution.

Illustrative fragment

record Item { name: string, counts: list<i64> }

Construction and field access

Construct a value using the type name and supply every field exactly once. Fields evaluate in written order. Unknown, duplicate, missing, or unit fields are source errors. Direct and indirect recursive record types, including recursion through lists or results, are rejected.

Postfix :: reads a field by value and chains with list indexes more tightly than arithmetic. User field names retain their spelling in Arabic, English, and mixed source. Only builtin result/error fields have supplied bilingual aliases. Parenthesize a record constructor directly in an if or while condition to distinguish its braces from the following block.

Illustrative fragment

let item = Item { name: "tools", counts: [2, 3] };
print(item::name);

Copying and nested mutation

Assignments, arguments, and returns copy record values. A nested list or record in a copy also has value semantics. Change a field or indexed element only through a var root binding. A parameter, let binding, temporary, or result payload projection cannot be mutated. Copy a successful payload into a new mutable binding if you need to change it.

The complete example copies a parser state, changes its index and a nested token field, and verifies that the original still has its old values. It also carries a record in result<record-type>.

Failures and scope

Whole-record equality is not supported. Field/type errors are source errors; an invalid nested list index traps with list-index-out-of-bounds, and reading the wrong result branch traps with wrong-result-branch. Records extend the historical MVP; their current behavior is independent of any C struct layout.

Read all record variants, lists, and recoverable results.

Recoverable values

On both ASPL 0.7.0 hosts, نتيجة<T>/result<T> contains a successful T payload or معلومات_خطأ/error_info. A failed result is ordinary control flow: it emits no diagnostic, source span, or stack trace and does not stop execution. You choose whether to retry, continue, or return a process status.

نجاح/success(value) infers its payload type or checks against an expected result type. success() creates result<unit>, a success with no payload. إخفاق/failure(code, message) takes two strings and needs the expected result type from a declaration, assignment, argument, or return. Without that context, checking fails with result-type-required.

Check before reading a branch

Use postfix :: and test ok before reading the corresponding branch. value on failure or error on success traps with wrong-result-branch. A result<unit> has no readable value; trying to read it is a source error, unit-value-not-allowed. Whole-result equality is rejected. Field access binds more tightly than arithmetic and does not translate user record fields.

Codes, messages, and copies

Branch on stable error codes such as invalid-number, number-out-of-range, and not-found, not message wording. Your own function chooses its own codes and messages. Results and retained payloads have value semantics; result projections are read-only. Assign a payload to a var binding to modify your copy.

Distinct kinds of failure

Bad numeric text and expected text-file failures return results. Invalid types or fields prevent checking. Out-of-bounds indexing and wrong-branch access are uncatchable traps. Memory/time limits, allocation failure, and Stop are separate execution outcomes; they are not failed results you can catch.

The parsing examples and file guide show recovery while the program continues. Diagnostics explains source errors and traps.

Scope and complete examples

Recoverable results extend the historical MVP. Read every supplied results variant and the text-file API for result<string> reads and result<unit> writes.

Whole-file text API

Both builtins are supported in the browser and by native ASPL 0.7.0 execution. They require no import or unsafe marker. Using unsafe on either is a source error, unsafe-on-safe-call.

Reads preserve every content byte, including BOM, CRLF, NUL, and normalization. Empty files return success(""). Invalid UTF-8 returns invalid-utf8. Writes use the string's exact UTF-8 bytes, append no newline, and replace rather than append. Check ok before reading value or error; a successful write has no readable value.

The browser output display labels invisible controls such as BOM and NUL and displays CRLF as a line break. This safe representation does not change file contents. Use file downloads to compare exact bytes.

Per-operation host support

Native paths are not relative to the source file. There is no shell expansion of ~, variables, or wildcards, and no implicit parent-directory creation. Reads follow normal filesystem resolution, including symlinks, but reject directories, devices, and pipes as not-regular-file. Successful writes replace the final entry, including a final symlink, rather than following that final symlink. A failed write preserves the previous destination; a later trap does not undo a completed write.

Browser names reject /, backslash, NUL, control characters U+0000 through U+001F and U+007F through U+009F, and . or ... There are no directories. The store allows 64 files and 8388608 total bytes. Each run also has an 8388608-byte write-update transfer budget, counting name bytes, content bytes, and 64 bytes of overhead per write; repeated replacements consume that budget too. Read and write share these host constraints independently of the prose/source language.

Recoverable file errors

These are recoverable results, not source diagnostics or traps. Resource limits, cancellation, and allocation failure remain separate execution outcomes. A wrong-branch access can still trap. Successful writes before a later failure remain available.

Temporary run files and saved source

Browser virtual files belong to one draft's document-local run data. They survive switching drafts, same-tab reading navigation and Back, locale changes, expansion, and Reset. Reset restores the starting source and clears output/transcripts; it retains files. Refresh, reload, and new tabs lose the files, even when saved draft source returns. Source saving/export does not include run files.

Import files only after opening the intended draft. A whole import batch is validated before changes; replacing same names requires confirmation. Rejected or cancelled imports preserve existing files. Imports, removal, and clear are locked during a run, which uses a stable snapshot. File clear and draft deletion have their own confirmations.

Use the explicit Download button for each imported or successfully written file. Downloads preserve its exact name and bytes, including non-UTF-8 imported bytes. Importing helper.aspl as run data does not make it a native source module or enable browser source imports.

Complete examples and scope

The default read example needs one input line, missing.txt, and no imported file. Its not-found branch prints an error and returns 0. The write example needs no input or asset; it creates or replaces generated.txt with exactly generated\n, then prints Output: saved\n.

Read the practical guide before trying a successful read or saving generated bytes. Complete read and write pages retain the supplied Arabic and English variants. These APIs extend the historical MVP; the archived specification does not define their current host behavior.

Top-level functions

ASPL 0.7.0 supports these rules in native execution and the browser. Define helpers at file scope with fn / دالة, typed parameters and a typed result. Names are unique within a source module; overloading, nested definitions, closures, default arguments and variadic user functions are unsupported. A declaration cannot replace a builtin alias. Executable statements belong inside functions.

Definitions are order-independent and may recurse. Calls evaluate arguments left to right and pass values by value. Parameters are immutable. Lists and records keep their copy semantics across calls. Every path in a non-unit function must return the declared result type. unit represents no value to store or pass.

Illustrative fragment

fn apply(action: fn(i64) -> i64, value: i64) -> i64 {
    return action(value);
}

Typed callable values

A named top-level user function is also a value. fn(i64) -> i64 / دالة(ص64) -> ص64 describes one parameter and a result; parameter names are absent from the type. fn() -> unit describes a callable with no parameters and no result. The full parameter and result types must match; assignment does not convert a callable's signature.

Copy, pass, return and invoke a callable, or store it in a list, record or result. Postfix calls may follow a field, list index or returned callable, as in carrier::callback(38), saved[0](38) or choose()(38). No local environment is captured. matches / يطابق and not matches / لا يطابق compare function identity for compatible callable types; ordering and arithmetic are unsupported.

Accessibility and entry restrictions

Callable values refer only to user functions. The reserved entry start_main / ابدأ_الرئيسية, builtins, foreign declarations and supplied-library functions are not callable values. The entry cannot be called from source either.

Native source-module declarations are private by default. A direct lib::hidden reference fails with private-member. An exported lib::choose() may return a callable to its private helper; receiving and invoking that value is valid. Shared signatures must not expose a private record, including inside a callable, list or result. That failure is private-type-exposure.

Read source modules and exports for native accessibility. The browser supports a single source file and cannot load user source modules.

Failures and complete examples

Wrong arity produces argument-count-mismatch; an incompatible argument, return or callable type produces type-mismatch. A missing non-unit return path produces missing-return. Taking the entry as a value produces undefined-name. These are checking errors, separate from arithmetic or recursion-limit traps during execution.

The factorial helper example returns process status 120 with no output. That is a successful language execution with a nonzero process status, so a shell treats the command as unsuccessful. The callable example prints 42 and returns 0.

See all function variants, callable variants and native check/run/build.

Host and import syntax

This is the native ASPL 0.7.0 source-module contract. Install the native toolchain first. Browser virtual files are run data and do not supply a source-module loader, even when named .aspl or .لبات. Supplied libraries such as core::http, core::raylib and core::c have their own native support and are distinct from user-authored source files and C shared libraries.

Illustrative fragment

import helpers.aspl as lib;
استورد services/معالجات.لبات بسم خدمة.

Use import / استورد, a relative path ending in .aspl or .لبات, and an optional as / بسم namespace. Paths are unquoted descriptors; escape a space with \ . An absolute import path is rejected. Resolution starts at the importing file's directory, including nested imports, rather than the process working directory. Without an alias, the filename stem must be a valid namespace identifier. Use an alias for filenames such as my-file.aspl.

ASPL 0.7.0 accepts \ي{...} alongside \u{...} in import paths, with the same hexadecimal alphabets and scalar limits as string escapes. Import paths reject U+0000. Escaped spaces and ASCII punctuation keep their existing spellings; the short string escapes such as \n and \س are invalid in import paths. Published 0.6.0 artifacts retain their original path escape syntax.

Namespaces and exports

Use lib::answer() to call a directly imported export. Imports do not execute code, merge declarations into the caller, or make transitive namespaces visible. Different source modules may use the same private name. Repeated imports of the same canonical file share its function and record identities, even through different aliases. Two different files defining the same record spelling still define distinct nominal types.

Functions, records and foreign declarations are private by default. Prefix an exported declaration with share / شارك. Exported user names keep their declared spelling; they do not acquire Arabic/English aliases. An exported foreign call still needs its explicit unsafe marker. Exported signatures and record fields cannot expose private types, including through nested callable, list or result types. Export the needed record too, or change the public signature.

Illustrative fragment

share fn answer() -> i64 { return 42; }
share record Reply { value: i64 }

share import is rejected with shared-import: there are no re-exports. Import every namespace you name directly. See the private-declaration failure and corrected module program.

Entry and graph restrictions

Only the root source file defines start_main / ابدأ_الرئيسية, with no parameters and an i64 process status. Imported files must not define an entry; imported-entry rejects them. The root entry cannot be exported; shared-entry rejects that declaration. Entry names cannot be called or stored as callable values.

Cycles fail with import-cycle; namespace collisions fail with namespace-collision. Missing files fail with missing-file. The native graph has at most 1024 source modules and a longest import chain of 256 edges. Every imported declaration is checked, including unused helpers, so importing a file does not hide its type errors.

Check, run and build

Keep the entry and all declared source files in the documented relative layout. These commands need no data asset for this example:

aspl check main.en.aspl
aspl run main.en.aspl
aspl build -o module-program main.en.aspl
./module-program

The source-module example prints 42 followed by LF and returns 0. The built native program contains the checked program and VM and can execute after its source files are removed. It may still need any shared libraries or runtime data files used by that program.

Read the practical guide, callable accessibility, Linux command phases and complete-program collection.

Native serving and session owners

Native only, published ASPL 0.7.0. Read the HTTP guide, example collection and native requirements. Browser and private embedding reject HTTP before execution with unsupported-supplied-library-profile.

serve drives handlers until shutdown and returns result<unit> after releasing its server and child work. start instead completes startup and returns result<Session<C,S>>. Its listeners are ready when it succeeds. Handlers run only when the application calls progress; transport maintenance during input or drawing dispatches no source handlers. progress obeys ProgressBudget, not an unlimited event loop. A validated network attempt freezes configure, and one validated serving attempt consumes the execution's only serving slot even if bind or TLS startup later fails. Pure validation refusals leave that slot and configuration available. Client calls work before, inside and after serving.

Session<C,S> / جلسة<C,S> is an opaque managed owner. Copies share one native resource and shared close. It can be retained in application values but cannot enter configuration/state type arguments at any depth. There is no constructor, public field, equality, or ordinary foreign conversion. Losing the last reachable alias closes its resource; execution termination revokes owners too. Native storage remains charged until cleanup reaches quiescence. Configuration/state copies retain the same managed handles, not cloned mutable native resources.

Application-only operations are start, progress, stop_session, close_session, session_config, session_state, replace_session_state, snapshot_session_state and replace_session_state_if_current. Handler-only operations take the invocation's Context: read_config, read_state, replace_state, snapshot_state, replace_state_if_current, stop and check_response. The checker rejects application-only calls on a handler path, even through helpers. Context expires when its invocation ends and cannot escape or enter aggregates. In Raylib programs, configure/request/serve/start/progress/stop/close are outside-frame operations; the copied application state/config helpers are frame-allowed. An active frame returns http.invalid_order for forbidden calls. Invalid application context returns http.invalid_context.

SessionStatus / حالة_جلسة has SESSION_RUNNING / جلسة_تعمل, SESSION_DRAINING / جلسة_تستكمل_الإغلاق and SESSION_CLOSED / جلسة_مغلقة. stop_session requests drain; continue calling progress until closed. close_session revokes and releases the owner, invalidating every alias. Normal closed progress reports closed, repeated stop/close succeeds, and closed state/config helpers return http.closed_session. A safely released host failure remains latched. Terminal cleanup failure is not a recoverable result.

read_state and session_state return copied values. Mutating them publishes nothing. Unconditional replace_state or replace_session_state replaces the whole state. StateSnapshot<S> / لقطة_حالة<S> has one read-only value / قيمة field plus hidden session/version identity. Snapshot values survive close but grant no Context authority. Every successful publication advances the version. Conditional replacement returns successful true for a current snapshot, successful false for a stale same-session snapshot, or failed http.invalid_argument for a foreign-session snapshot. A read, outbound wait and replacement are not atomic; use conditional publication to detect changes across a wait. See the session example.

Types, functions and defaults

Route<C,S> / وجهة<C,S>, Router<C,S> / موجه<C,S> and Context<C,S> / سياق<C,S> have exactly two concrete application type arguments. C and S can be admissible storable values, including records, lists, results, Buffer, managed handles and registrations. Actual Context and exposed callable values are excluded at every depth, including registration data. These are supplied families, not user-defined generics. If inference cannot determine both arguments, write them explicitly, for example http::router<bool,i64>([]). All routes, handlers, configuration and state must use the same nominal C/S identities. Imports of one canonical module share its type and callable identity.

A handler is a named top-level user function with signature fn(IncomingRequest, Context<C,S>) -> ServerResponse. Refer to it by its name, such as handlers::handle, without calling it. Callable values have no captured environment. Export a module's declarations with share / شارك; other names stay private. Ordinary callable values can be stored, passed, returned and compared with word equality. Handler checking follows all possible targets through modules and rejects unsafe or blocking paths. Ordinary foreign calls and blocking line/file operations cannot become handler-safe by wrapping them.

Records below have ordinary value semantics. Message/header byte lists remain usable after a connection or session ends. Context has no constructor or public fields, cannot enter aggregates, escape its invocation, be compared, or cross an ordinary foreign call. Route and Router are retainable opaque values without public fields or live sockets. Result success is ok / نجاح, payload is value / قيمة, error is error / الخطأ; its code is code / الرمز. Read the payload only after checking success. Human messages may vary.

Default ClientOptions has all three flags false and an empty CA path. Default ServerConfig has an empty listener list and must be completed before serving. listener takes an address and port 1..65535, returns plain transport and empty TLS paths. client_request starts with empty headers/body; response starts with empty headers and false/zero representation-length metadata. text_response sets the supplied Content-Type and exact UTF-8 body. There are no optional arguments or implicit JSON transformations.

The following tables come from the reviewed public declaration catalog. Type notation is shared by both locales. Numeric sizes/counts are i64, and durations are i64 milliseconds. Ranges are inclusive. There is no unlimited sentinel. MiB means 1048576 bytes.

ProgressBudget / ميزانية_تقدم

Header / ترويسة

QueryEntry / عنصر_استعلام

ClientRequest / طلب_عميل

IncomingRequest / طلب_وارد

ClientResponse / استجابة_عميل

ServerResponse / استجابة_خادم

Listener / مستمع

ClientOptions / خيارات_عميل

ServerConfig / إعدادات_خادم

RuntimeConfig / إعدادات_تنفيذ_ويب

MessageLimits / حدود_رسالة

Timeouts / مهل

Functions / الدوال

Byte messages, headers and queries

Bodies are complete buffered list<u8> values. encode_utf8 copies exact UTF-8; decode_utf8 rejects malformed text with http.invalid_utf8. Neither strips BOM/NUL, normalizes Unicode, guesses charset nor replaces invalid bytes. JSON is explicit text and Content-Type; no parser/serializer is included.

Headers are ordered repeated fields, with ASCII token names and byte values. Values accept HTAB, printable ASCII and 0x80..0xFF, rejecting NUL, CR, LF, DEL and other controls. Parsing trims surrounding SP/HTAB and preserves interior bytes, order and name case. header_values matches names case-insensitively, returns every value in order, and never joins with commas or decodes text. Repeated Set-Cookie stays separate. Trailers remain separate from initial fields.

Applications cannot set Content-Length, Transfer-Encoding, Connection, Keep-Alive, Proxy-Connection, TE, Trailer, Upgrade or Expect on outgoing messages, or Host on client requests. The library derives Host/framing and provides Date on server responses when absent. Content-Encoding is explicit application data; server compression is not automatic. Conflicting lengths, Transfer-Encoding with Content-Length, folded fields and ambiguous framing fail. Received control headers remain inspectable metadata. Never copy peer compressed length/encoding headers blindly to a new response.

Client URLs must be absolute ASCII HTTP/HTTPS URIs. Percent-encode non-ASCII path/query text and supply internationalized hosts as A-labels. DNS, IPv4 and bracketed IPv6 are supported. Userinfo, whitespace/controls, malformed escapes, bad ports and IPv6 zone identifiers are rejected. Fragments are stripped; an empty path becomes /. The first request preserves dot segments, slash count and percent spelling. final_url removes the fragment, lowercases scheme/DNS host, omits the default port and uses / for an empty path, preserving query presence and percent spelling.

Incoming target preserves origin-form or HTTP/HTTPS absolute-form encoding; OPTIONS also accepts *. Extract path/query before decoding. authority comes from an absolute target or valid Host. has_query distinguishes /p and /p?. Forwarded headers never change these fields or actual TLS/address metadata. Listener indexes are zero-based. Invalid targets fail before handler dispatch.

query_entries splits the supplied raw query at & and the first = before one percent decode. Do not pass the initial ?. + stays plus, ; stays data, %26 stays within an entry and %252F becomes %2F. Empty segments produce no entries. flag and flag= differ by has_equals; =x has an empty name. Repeated names preserve order, %00 is a valid ASPL NUL, and malformed escape or decoded UTF-8 failures leave the raw query available. query_values uses exact decoded-name matching and maps a bare key to an empty value.

Routes and responses

Methods are nonempty case-sensitive ASCII tokens. CONNECT and upgrades are unsupported. Encoded paths match exactly, including escape case, slashes and dot segments. /a%2Fb, /a%2fb, /a/b and /a/../b differ. Route paths start with /, have no query/fragment and valid escapes; * is OPTIONS-only. Duplicate method/path pairs and a second catch-all fail registration.

Dispatch exact routes first, then HEAD-to-GET fallback, then known-path 405, then unknown-path catch-all or default 404. Explicit HEAD wins. Allow sorts method tokens bytewise and adds HEAD for GET, without inventing OPTIONS. Default text bodies are Not found and Method not allowed, with text/plain; charset=utf-8. Invalid requests never reach a catch-all.

Handler statuses are final 200..599. Complete client 404/500 responses are successful results. Informational responses are consumed within limits; 101/unsupported wire versions fail. HEAD suppresses bodies after validation and accounting. GET fallback computes Content-Length from its returned body; explicit HEAD/catch-all can declare representation length or omit it. Declared length plus a nonempty HEAD body must match that body. False has_representation_length requires zero representation_length.

204/205/304 require empty handler bodies. 204 omits Content-Length, 205 uses zero, and 304 may declare representation length or omit it. Such metadata is allowed only for HEAD/304 and must be nonnegative. Status rules override HEAD fallback. Client no-body outcomes return empty body, zero encoded count and false gzip flag without allocating or decoding a hypothetical representation. 205 still requires valid empty-message framing.

check_response validates session limits and metadata without sending, using only the current invocation's request provenance. Copies retain provenance; editing public method fields does not change real HEAD authority. A request from another invocation or application construction fails http.invalid_argument. Final validation repeats on return. An invalid/oversized handler response uses a bounded generic 500 and closes the connection. A trap stays terminal.

Before dispatch, malformed requests use 400, target excess 414, header/trailer excess 431, body excess 413, unsupported transfer/CONNECT 501, expectations 417, and HTTP versions 505. Valid admitted Expect: 100-continue receives 100 before body receipt. Phase timeouts may produce 408 while the total is live; a complete request without dispatch/handler capacity uses 503. Close rejected connections. Fixed rejection bodies are empty. Transport/TLS admission, parent expiry, disconnect or budget exhaustion may close/refuse without an HTTP error reply.

Redirects, gzip and reuse

Following and gzip decoding are false by default. Enabled following covers 301/302/303/307/308 only within one origin, comparing scheme, host and effective port. Relative references resolve with literal dot-segment processing. 301/302 change POST to GET and drop its body; other methods retain it. 303 keeps HEAD or selects GET and drops the body. 307/308 replay method/body exactly. When dropping a body, remove Content-Type, Content-Encoding, Content-Language, Content-Location, Content-Range, Digest and Content-Digest and derive new framing.

No Location returns the response. Multiple or malformed/unusable Locations fail; an empty relative Location is valid and still bounded by the hop cap. Valid cross-origin destinations return the current response without following, including HTTPS-to-HTTP. redirect_count counts followed transitions and final_url is the last requested URL. All hops share the original total deadline. There is no automatic application transport retry, including failed reuse.

With decoding off, return encoded bytes and generate no Accept-Encoding. With decoding on, generate Accept-Encoding: gzip and reject the caller's Accept-Encoding. Missing/exact identity leaves bytes unchanged; one case-insensitive gzip coding is decoded. Stacked/repeated/unsupported coding fails. Validate complete members and checksums, accept concatenated members, and reject truncation/trailing garbage. Initial headers and trailers retain peer compressed metadata. encoded_body_bytes excludes transfer framing; body is decoded only when gzip_decoded is true. Enforce both encoded and decoded limits before accepting the next bytes.

Reuse is bounded and execution-owned. Its key includes origin and effective TLS trust identity. Consume complete valid framing before reuse or close the socket. Idle connections expire or may be evicted. Normal serve return releases its server/child work; independent client reuse can remain until execution end. There is no public socket/stream/client-close handle.

State, bounds and deadlines

read_config and read_state return value snapshots. Changes to a snapshot do not publish state. replace_state serializes a whole replacement; it is not an atomic read/wait/replace transaction. Managed handles in snapshots retain the same native owner, not a clone of its mutable native state. Extracted bytes are independent values. Context authority expires with its handler invocation.

configure may replace valid execution-wide settings before the first validated network attempt. That attempt freezes settings even if startup fails. Pure helpers do not start networking. The execution permits one validated serve or start attempt, including failed startup after validation, and supports client calls before, inside and after it. Options/listeners/router/configuration are copied per operation/session.

The VM default is 256 MiB and the shared backend default 128 MiB. Native charges include retained capacities, temporary peaks, TLS/DNS/decoder state and events. Live ASPL values remain charged to the VM. Kernel socket buffers are outside allocator accounting, but accepted/idle sockets consume finite counts. Listen backlog requested per listener is at most queued_requests, subject to host clamping. Queue/handler/outbound saturation refuses bounded admission rather than creating hidden queues. Host ceilings and actual memory may constrain a valid numeric setting; a setting reserves nothing and guarantees no admission. idle_client_connections must also be at most outbound_connections. Lowering outbound capacity below the default 16 idle slots requires lowering idle slots too, otherwise configure returns http.invalid_argument. The checked limits.aspl demonstrates refusal and correction.

All deadlines use monotonic time. Client total begins at call entry; server total begins at its first request byte and includes queueing/CPU/outbound/writes. connect_ms includes DNS/TCP/TLS together. TLS/header/body/write phases may shorten the original total, never extend it. Child work is capped by its parent. Server TLS handshake precedes first-request-byte total. Idle covers connection inactivity; drain bounds shutdown waiting. Cleanup uses one original deadline for all owned resources in its scope, default/minimum 1000 ms. 10 ms polling is a responsiveness target, not a hard real-time guarantee.

Parent expiry/disconnect/drain cancellation revokes that invocation and its children, discards late results/state publication, and leaves unrelated handlers live. It does not deliver a failed result into the cancelled parent. A receive half-close alone is not a detected disconnect. Explicit stop drains and returns normally after release. First signal drains then ends execution with status 7; a second skips drain. Traps use status 5, never an automatic 500. VM limits, allocator/internal failures and failed bounded cleanup remain terminal.

Configuration and startup

Use configure(RuntimeConfig) before the first validated network attempt. Invalid ranges or idle_client_connections > outbound_connections return http.invalid_argument without freezing settings. Validated client/serving attempts freeze settings even if transport startup fails; later configuration returns http.already_started. Helpers and offline check/build do not initialize HTTP. Options, listeners and application configuration are copied, not live mutable settings.

Listener::tls=false requires empty certificate/key paths; true requires both nonempty paths. A listener port is 1..65535, and IPv6 listeners are IPv6-only. Validated serve/start consumes the execution's one serving slot. Startup failure releases already-created listeners and work before returning its stable code. Correct the inputs and start a new execution. See deployment configuration and the limits example.

Default and private trust

Default ClientOptions selects host CA discovery, with use_private_ca=false and empty ca_file. use_private_ca=true requires a nonempty private PEM CA path and replaces the host store. Invalid flag/path combinations give http.invalid_argument. Unavailable, malformed, unreadable or oversized selected trust gives http.ca_load_failed before connecting; loaded but unrelated trust gives http.tls_verify_failed during verification. These choices never disable chain, date or identity checks.

The first existing default bundle is authoritative. A bad selected bundle does not fall through, and SSL_CERT_FILE/SSL_CERT_DIR do not override discovery. When no candidate bundle exists, bounded directory discovery applies. Successfully parsed trust is pinned for the execution. See the exact discovery order and local preparation; do not infer that every host trust layout works.

Context-bound upstream requests

request(ClientRequest, ClientOptions) inside a handler requires its live request frame. read_config(ctx) returns the serving application's copied configuration; in the service family, it supplies the upstream URL and explicit CA path. A server's incoming certificate/key is independent of its outgoing trust. The checked handler forwards status and body bytes deliberately, without copying compressed peer representation metadata.

Complete 404/500 responses remain successful client results. Recoverable child failure reaches a live parent as an ordinary result; the sample maps its stable code to a 502 body. Parent expiry, detected disconnect or drain expiry revokes child work and discards late handler output/publication rather than delivering a failed result into the cancelled handler. Child deadlines cannot extend the parent deadline. There is no automatic retry, outbound proxy or rollback of peer effects. Follow the complete TLS upstream exercise.

TLS inputs

TLS 1.2/1.3 clients always verify chain, dates and DNS/IP SAN identity. Direct servers load one PEM chain and matching unencrypted key per listener. Supported ordinary rsaEncryption keys are 2048..8192 bits, with odd exponent greater than one and at most 32 bits. Named P-256/P-384/P-521 curves are supported. Ordinary RSA keys with RSA-PSS signatures are supported; restricted rsassaPss keys, Ed25519/Ed448, other curves and explicit curve parameters are excluded.

Configured TLS file size defaults to 1 MiB, range 1..16 MiB. Key files also have a 65536-byte cap, paths are below 4096 bytes, local certificate PEM blocks at most 65536 bytes and certificate DER at most 49152 bytes. A peer certificate handshake message is at most 524288 bytes. Trust certificates are at most 8192 including duplicates; listener chains at most eight certificates and intermediate CAs at most six. Directory trust scanning is limited to 16384 entries and 8192 unique regular files. See trust discovery and startup failure timing.

Stable recoverable failures

All codes are ASCII and locale-independent. Constructors/helpers/networking return ordinary recoverable results for the expected failures below. Failures may occur after a peer has acted; they promise no remote rollback. Unexpected session host failure cleans up before serve returns http.host_failure.

Current exclusions

Native HTTP/1.1 only. No browser/private embedding networking, HTTP/2/3, CONNECT, WebSocket/other upgrade, streaming body API, multipart helpers, SSE, JSON parsing/serialization, named route parameters, middleware, automatic cookies/authentication, outbound proxy, automatic IDN conversion, server compression, certificate hot reload, SNI-based server certificate selection, client-certificate authentication or automatic cross-origin redirects.

Use the current deployment guide for the published native 0.7.0 workflows. The earlier raw deployment source (opens in a new tab) retains its earlier release scope.

Native contract

Native only, published ASPL 0.7.0. Import core::raylib or أساسي::رايليب in every source module using it. Each imported short prefix admits both member vocabularies; import both spellings to use both prefixes. User identifiers, record fields, strings and paths keep their identity. These supplied operations require no unsafe declaration and expose no native descriptors.

Read the drawing, text and audio guide and example collection. Checking and building require no display or C compiler. Window operations require supported Linux graphics with OpenGL 3.3 core; audio needs a reachable PulseAudio-compatible or ALSA device. CPU text requires neither. See the deployment requirements. The browser and private embedding reject this supplied library with unsupported-supplied-library-profile, including unused imports.

All ordinary calls return checked results; the seven total probes are IsWindowReady, IsTextureValid, IsFontValid, IsTextLayoutValid, IsAudioDeviceReady, IsSoundValid and IsMusicValid, returning bool. Read only the selected result arm. Numeric widths are exact. Convert an already typed wider value explicitly. Tables below retain the accepted paired declarations checked against the production catalog. Context rules apply transitively through helpers and callable values.

Records require every field exactly once. Both aliases of one field count as a duplicate. Records copy by value and mutation needs a mutable root. Key, mouse, filter, wrap, text direction and alignment enums permit storage and same-type equality, without integer construction, arithmetic or ordering. WindowFlags permits same-type |, &, ^, bounded ~ and equality using the five supported bits and the empty set. TextureFilter admits POINT/BILINEAR; TextureWrap admits REPEAT/CLAMP. Texture, Font, TextLayout, Sound and Music are shared opaque managed owners.

Types and fields

Vector2 / متجه2

Rectangle / مستطيل

Color / لون

Camera2D / كاميرا2

TextOptions / خيارات_النص

TextMetrics / مقاييس_النص

Constants

Window and lifecycle

SetConfigFlags / اضبط_أعلام_الإعداد

(flags: WindowFlags) -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Replaces saved next-window flags. Call before opening a window; flags survive reopen.

InitWindow / هيئ_نافذة

(width: i32, height: i32, title: string) -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Positive dimensions; title bytes are copied and retained. New generations reset Escape, input and timing.

IsWindowReady / هل_النافذة_جاهزة

() -> bool

Total probe; handlers/callbacks allowed; no native device entry.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

WindowShouldClose / هل_يجب_إغلاق_النافذة

() -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

CloseWindow / أغلق_النافذة

() -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Closes texture aliases and GPU caches before destroying the context. CPU fonts/layouts survive.

SetWindowTitle / اضبط_عنوان_النافذة

(title: string) -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Retains copied title backing until replacement/native quiescence. Refusal preserves the current title; NUL is refused.

GetScreenWidth / عرض_الشاشة

() -> result<i32>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetScreenHeight / ارتفاع_الشاشة

() -> result<i32>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetRenderWidth / عرض_التصيير

() -> result<i32>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetRenderHeight / ارتفاع_التصيير

() -> result<i32>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsWindowResized / هل_تغير_حجم_النافذة

() -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

Drawing frames and timing

BeginDrawing / ابدأ_الرسم

() -> result<unit>

Application, main thread; obey the drawing/mode pair rules.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

EndDrawing / أنه_الرسم

() -> result<unit>

Application, main thread; obey the drawing/mode pair rules.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

ClearBackground / امسح_الخلفية

(color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

SetTargetFPS / اضبط_معدل_الإطارات

(fps: i32) -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Nonnegative FPS; zero is uncapped. Saved pacing survives reopen.

GetFrameTime / زمن_الإطار

() -> result<f32>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetTime / الزمن

() -> result<f64>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetFPS / معدل_الإطارات

() -> result<i32>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

Keyboard, mouse and resize input

IsKeyPressed / هل_ضغط_المفتاح

(key: Key) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsKeyPressedRepeat / هل_تكرر_ضغط_المفتاح

(key: Key) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsKeyDown / هل_المفتاح_مضغوط

(key: Key) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsKeyReleased / هل_حرر_المفتاح

(key: Key) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsKeyUp / هل_المفتاح_غير_مضغوط

(key: Key) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetKeyPressed / المفتاح_المضغوط

() -> result<Key>

Application, main thread, live window; sampled observations allowed inside a frame.

Consumes one queue entry; an empty queue returns KEY_NULL.

GetCharPressed / المحرف_المدخل

() -> result<i32>

Application, main thread, live window; sampled observations allowed inside a frame.

Consumes one queue entry; returns i32 zero or a checked Unicode scalar.

SetExitKey / اضبط_مفتاح_الخروج

(key: Key) -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

KEY_NULL disables the exit key. Reopen restores Escape.

IsMouseButtonPressed / هل_ضغط_زر_الفأرة

(button: MouseButton) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsMouseButtonDown / هل_زر_الفأرة_مضغوط

(button: MouseButton) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsMouseButtonReleased / هل_حرر_زر_الفأرة

(button: MouseButton) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsMouseButtonUp / هل_زر_الفأرة_غير_مضغوط

(button: MouseButton) -> result<bool>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetMousePosition / موضع_الفأرة

() -> result<Vector2>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetMouseDelta / تغير_موضع_الفأرة

() -> result<Vector2>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetMouseWheelMove / حركة_عجلة_الفأرة

() -> result<f32>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetMouseWheelMoveV / حركة_عجلة_الفأرة_بمتجه

() -> result<Vector2>

Application, main thread, live window; sampled observations allowed inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

2D drawing

DrawPixel / ارسم_بكسلا

(posX: i32, posY: i32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawPixelV / ارسم_بكسلا_بمتجه

(position: Vector2, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawLine / ارسم_خطا

(startPosX: i32, startPosY: i32, endPosX: i32, endPosY: i32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawLineV / ارسم_خطا_بمتجه

(startPos: Vector2, endPos: Vector2, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawLineEx / ارسم_خطا_موسعا

(startPos: Vector2, endPos: Vector2, thick: f32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawCircle / ارسم_دائرة

(centerX: i32, centerY: i32, radius: f32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawCircleV / ارسم_دائرة_بمتجه

(center: Vector2, radius: f32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawCircleLines / ارسم_محيط_دائرة

(centerX: i32, centerY: i32, radius: f32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawRectangle / ارسم_مستطيلا

(posX: i32, posY: i32, width: i32, height: i32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawRectangleV / ارسم_مستطيلا_بمتجه

(position: Vector2, size: Vector2, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawRectangleRec / ارسم_مستطيلا_بسجل

(rec: Rectangle, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawRectanglePro / ارسم_مستطيلا_متقدما

(rec: Rectangle, origin: Vector2, rotation: f32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawRectangleLines / ارسم_محيط_مستطيل

(posX: i32, posY: i32, width: i32, height: i32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawRectangleLinesEx / ارسم_محيط_مستطيل_موسعا

(rec: Rectangle, lineThick: f32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawTriangle / ارسم_مثلثا

(v1: Vector2, v2: Vector2, v3: Vector2, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawTriangleLines / ارسم_محيط_مثلث

(v1: Vector2, v2: Vector2, v3: Vector2, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

Textures and sprites

LoadTexture / حمل_نسيجا

(fileName: string) -> result<Texture>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

PNG only, with process-working-directory paths and copied path bytes. Requires a live window.

IsTextureValid / هل_النسيج_صالح

(texture: Texture) -> bool

Total probe; handlers/callbacks allowed; no native device entry.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

UnloadTexture / حرر_النسيج

(texture: Texture) -> result<unit>

Application, main thread; logical close may occur in a frame. Already closed unload succeeds.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

SetTextureFilter / اضبط_مرشح_النسيج

(texture: Texture, filter: TextureFilter) -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

SetTextureWrap / اضبط_التفاف_النسيج

(texture: Texture, wrap: TextureWrap) -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

DrawTexture / ارسم_نسيجا

(texture: Texture, posX: i32, posY: i32, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Signed source rectangles preserve flipping; zero/negative scale and signed destinations retain admitted Raylib behavior. Derived geometry must remain representable.

DrawTextureV / ارسم_نسيجا_بمتجه

(texture: Texture, position: Vector2, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Signed source rectangles preserve flipping; zero/negative scale and signed destinations retain admitted Raylib behavior. Derived geometry must remain representable.

DrawTextureEx / ارسم_نسيجا_موسعا

(texture: Texture, position: Vector2, rotation: f32, scale: f32, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Signed source rectangles preserve flipping; zero/negative scale and signed destinations retain admitted Raylib behavior. Derived geometry must remain representable.

DrawTextureRec / ارسم_جزء_نسيج

(texture: Texture, source: Rectangle, position: Vector2, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Signed source rectangles preserve flipping; zero/negative scale and signed destinations retain admitted Raylib behavior. Derived geometry must remain representable.

DrawTexturePro / ارسم_نسيجا_متقدما

(texture: Texture, source: Rectangle, dest: Rectangle, origin: Vector2, rotation: f32, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Signed source rectangles preserve flipping; zero/negative scale and signed destinations retain admitted Raylib behavior. Derived geometry must remain representable.

GetTextureWidth / عرض_النسيج

(texture: Texture) -> result<i32>

Read-only owner metadata; handlers/callbacks allowed; closed-owner checks apply.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetTextureHeight / ارتفاع_النسيج

(texture: Texture) -> result<i32>

Read-only owner metadata; handlers/callbacks allowed; closed-owner checks apply.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

Camera2D modes and transforms

BeginMode2D / ابدأ_وضع_ثنائي_الأبعاد

(camera: Camera2D) -> result<unit>

Application, main thread; obey the drawing/mode pair rules.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

EndMode2D / أنه_وضع_ثنائي_الأبعاد

() -> result<unit>

Application, main thread; obey the drawing/mode pair rules.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetWorldToScreen2D / من_العالم_إلى_الشاشة

(position: Vector2, camera: Camera2D) -> result<Vector2>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetScreenToWorld2D / من_الشاشة_إلى_العالم

(position: Vector2, camera: Camera2D) -> result<Vector2>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

Collision geometry

CheckCollisionRecs / هل_يتداخل_مستطيلان

(rec1: Rectangle, rec2: Rectangle) -> result<bool>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

CheckCollisionCircles / هل_تتداخل_دائرتان

(center1: Vector2, radius1: f32, center2: Vector2, radius2: f32) -> result<bool>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

CheckCollisionCircleRec / هل_تتداخل_دائرة_ومستطيل

(center: Vector2, radius: f32, rec: Rectangle) -> result<bool>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

CheckCollisionPointRec / هل_النقطة_في_مستطيل

(point: Vector2, rec: Rectangle) -> result<bool>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

CheckCollisionPointCircle / هل_النقطة_في_دائرة

(point: Vector2, center: Vector2, radius: f32) -> result<bool>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

CheckCollisionPointTriangle / هل_النقطة_في_مثلث

(point: Vector2, p1: Vector2, p2: Vector2, p3: Vector2) -> result<bool>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetCollisionRec / مستطيل_التداخل

(rec1: Rectangle, rec2: Rectangle) -> result<Rectangle>

Pure checked math; handlers/callbacks allowed; no device/frame prerequisite.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

Font selection and ownership

GetFontDefault / الخط_الافتراضي

() -> result<Font>

CPU text; handlers/callbacks allowed; no window required.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

LoadFont / حمل_خطا

(fileName: string) -> result<Font>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Single-face TrueType outlines; copied file bytes survive file replacement. Default fallback remains available.

LoadFontEx / حمل_خطا_موسعا

(fileName: string, fontSize: i32, codepoints: list<i32>) -> result<Font>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Base size 1..4096. list<i32> contains copied scalar prewarming hints; empty means no hints, never restricted coverage.

IsFontValid / هل_الخط_صالح

(font: Font) -> bool

Total probe; handlers/callbacks allowed; no native device entry.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

UnloadFont / حرر_الخط

(font: Font) -> result<unit>

CPU text; handlers/callbacks allowed; no window required.

Alias-safe close. Existing layouts retain independent font backing; unloading the default Font succeeds without closing it.

GetFontBaseSize / حجم_الخط_الأساسي

(font: Font) -> result<i32>

CPU text; handlers/callbacks allowed; no window required.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

Immutable text layouts

CreateTextLayout / أنشئ_تخطيط_نص

(font: Font, text: string, options: TextOptions) -> result<TextLayout>

CPU text; handlers/callbacks allowed; no window required.

Immutable CPU layout; options supply every field. It retains fonts and survives window recreation.

MeasureTextLayout / قس_تخطيط_النص

(layout: TextLayout) -> result<TextMetrics>

CPU text; handlers/callbacks allowed; no window required.

size is the logical box, ink is the local glyph bounds. Measurement and drawing share positions.

IsTextLayoutValid / هل_تخطيط_النص_صالح

(layout: TextLayout) -> bool

Total probe; handlers/callbacks allowed; no native device entry.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

UnloadTextLayout / حرر_تخطيط_النص

(layout: TextLayout) -> result<unit>

CPU text; handlers/callbacks allowed; no window required.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

Shaped text measurement

MeasureText / قس_النص

(text: string, fontSize: i32) -> result<i32>

CPU text; handlers/callbacks allowed; no window required.

Shaped default-font width, rounded upward to checked i32; size 1..4096.

MeasureTextEx / قس_النص_موسعا

(font: Font, text: string, fontSize: f32, spacing: f32) -> result<Vector2>

CPU text; handlers/callbacks allowed; no window required.

Shaped logical size; spacing must be zero and size 0.5..4096.

Shaped text drawing

DrawText / ارسم_نصا

(text: string, posX: i32, posY: i32, fontSize: i32, color: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Shaped Arabic/Latin text in logical order; known preparation failure submits none of this text request. Ex/Pro spacing must be zero.

DrawTextEx / ارسم_نصا_موسعا

(font: Font, text: string, position: Vector2, fontSize: f32, spacing: f32, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Shaped Arabic/Latin text in logical order; known preparation failure submits none of this text request. Ex/Pro spacing must be zero.

DrawTextPro / ارسم_نصا_متقدما

(font: Font, text: string, position: Vector2, origin: Vector2, rotation: f32, fontSize: f32, spacing: f32, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Shaped Arabic/Latin text in logical order; known preparation failure submits none of this text request. Ex/Pro spacing must be zero.

DrawTextLayout / ارسم_تخطيط_النص

(layout: TextLayout, position: Vector2, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Shaped Arabic/Latin text in logical order; known preparation failure submits none of this text request. Ex/Pro spacing must be zero.

DrawTextLayoutPro / ارسم_تخطيط_النص_متقدما

(layout: TextLayout, position: Vector2, origin: Vector2, rotation: f32, tint: Color) -> result<unit>

Application, main thread, inside a drawing frame.

Shaped Arabic/Latin text in logical order; known preparation failure submits none of this text request. Ex/Pro spacing must be zero.

Audio device and sound

InitAudioDevice / هيئ_جهاز_الصوت

() -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

CloseAudioDevice / أغلق_جهاز_الصوت

() -> result<unit>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

Stops and closes dependent Sound/Music aliases before releasing the device.

IsAudioDeviceReady / هل_جهاز_الصوت_جاهز

() -> bool

Total probe; handlers/callbacks allowed; no native device entry.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

SetMasterVolume / اضبط_مستوى_الصوت_العام

(volume: f32) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Volume 0..1.

GetMasterVolume / مستوى_الصوت_العام

() -> result<f32>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

LoadSound / حمل_صوتا

(fileName: string) -> result<Sound>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

WAV/OGG/MP3 files; paths resolve from the process working directory. Resource belongs to the current audio generation.

IsSoundValid / هل_الصوت_صالح

(sound: Sound) -> bool

Total probe; handlers/callbacks allowed; no native device entry.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

UnloadSound / حرر_الصوت

(sound: Sound) -> result<unit>

Application, main thread; logical close may occur in a frame. Already closed unload succeeds.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

PlaySound / شغل_الصوت

(sound: Sound) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

StopSound / أوقف_الصوت

(sound: Sound) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

PauseSound / أوقف_الصوت_مؤقتا

(sound: Sound) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

ResumeSound / استأنف_الصوت

(sound: Sound) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsSoundPlaying / هل_الصوت_يعمل

(sound: Sound) -> result<bool>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

SetSoundVolume / اضبط_مستوى_الصوت

(sound: Sound, volume: f32) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Volume 0..1.

SetSoundPitch / اضبط_حدة_الصوت

(sound: Sound, pitch: f32) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Positive finite pitch and checked derived resampling rate. Refusal before native entry preserves the previous pitch.

SetSoundPan / اضبط_توازن_الصوت

(sound: Sound, pan: f32) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Pan -1..1.

Explicit streamed music

LoadMusicStream / حمل_تدفق_موسيقى

(fileName: string) -> result<Music>

Application, main thread, outside drawing frames; device/owner prerequisites apply.

WAV/OGG/MP3 files; paths resolve from the process working directory. Resource belongs to the current audio generation.

IsMusicValid / هل_الموسيقى_صالحة

(music: Music) -> bool

Total probe; handlers/callbacks allowed; no native device entry.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

UnloadMusicStream / حرر_تدفق_الموسيقى

(music: Music) -> result<unit>

Application, main thread; logical close may occur in a frame. Already closed unload succeeds.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

PlayMusicStream / شغل_تدفق_الموسيقى

(music: Music) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

IsMusicStreamPlaying / هل_تدفق_الموسيقى_يعمل

(music: Music) -> result<bool>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

UpdateMusicStream / حدث_تدفق_الموسيقى

(music: Music) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Explicit application update; no automatic streaming loop or source callback.

StopMusicStream / أوقف_تدفق_الموسيقى

(music: Music) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

PauseMusicStream / أوقف_تدفق_الموسيقى_مؤقتا

(music: Music) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

ResumeMusicStream / استأنف_تدفق_الموسيقى

(music: Music) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

SeekMusicStream / اضبط_موضع_تدفق_الموسيقى

(music: Music, position: f32) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Finite seconds 0..reported length inclusive. Endpoint means logical EOF; later update loops playing music or stops nonlooping/empty music. Decoder refusal closes the owner.

SetMusicVolume / اضبط_مستوى_الموسيقى

(music: Music, volume: f32) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Volume 0..1.

SetMusicPitch / اضبط_حدة_الموسيقى

(music: Music, pitch: f32) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Positive finite pitch and checked derived resampling rate. Refusal before native entry preserves the previous pitch.

SetMusicPan / اضبط_توازن_الموسيقى

(music: Music, pan: f32) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

Pan -1..1.

GetMusicTimeLength / مدة_الموسيقى

(music: Music) -> result<f32>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetMusicTimePlayed / زمن_الموسيقى_المنقضي

(music: Music) -> result<f32>

Application, main thread, live audio device/owner; permitted inside a frame.

Checked widths, owner generations and results follow the guide. Refusal before native entry preserves state.

GetMusicLooping / هل_الموسيقى_تتكرر

(music: Music) -> result<bool>

Read-only owner metadata; handlers/callbacks allowed; closed-owner checks apply.

Reads retained metadata without entering the audio device.

SetMusicLooping / اضبط_تكرار_الموسيقى

(music: Music, looping: bool) -> result<unit>

Application, main thread, live audio device/owner; permitted inside a frame.

An audio control requiring application admission and a live audio owner.

Numeric and resource limits

Active floating inputs must be finite. Window dimensions and camera zoom are positive. Radius and target FPS are nonnegative; line thickness is positive. Derived coordinates and arithmetic must remain representable even when individual inputs are finite. Signed texture rectangles, zero/negative texture scale and admitted degenerate geometry retain the pinned behavior. Records use f32 coordinates, u8 color channels and the exact scalar widths in each signature.

Title and path strings reject NUL. Audio accepts WAV/OGG/MP3; custom fonts accept the selected single-face TrueType outline profile. LoadTexture accepts PNG only. Paths resolve from the process working directory. The sprite family supplies the exact 32 by 16 RGBA atlas and its Apache-2.0 OR MIT notice. Loads and filter/wrap changes need a closed frame. No system Raylib or source-module helpers are required by these public families.

Default allowances are 256 MiB for VM memory and one shared 128 MiB Raylib/HTTP backend account. Native allocations, copied titles/path backing, texture storage and retained backing count against the relevant allowance. Logical close does not release a charge until native use ends. General VM instruction, time, call-frame and slot limits still apply.

Only one execution holds the process device lease. Texture belongs to its window generation; copies share closure. CloseWindow invalidates aliases before destroying the context, and reopen cannot revive them. UnloadTexture is idempotent, including inside a frame; accepted draws may retain backing until presentation/quiescence. Closed-owner checks precede a missing former device. Read-only metadata, total probes, pure transforms and collision helpers are allowed in handlers/callbacks. Device entry and drawing are application-only on the main thread.

BeginDrawing/EndDrawing and BeginMode2D/EndMode2D must pair without nesting. End camera mode before ending a frame. Lifecycle, loads, title/exit/FPS and filter/wrap changes require a closed frame. Sampled input/timing observations are allowed inside one. Refusal before native entry leaves current state unchanged. Failure after effects guarantees owned cleanup rather than rollback. Return, trap, limits or cancellation abandon an open frame; cleanup releases GPU work before its window. Native release that cannot be proved retains backing and lease. Driver hangs have no hard in-process preemption guarantee.

Text sizes are integer 1..4096 or finite f32 0.5..4096, rounded to 1/64 with ties to even. Ex/Pro character spacing must be zero. TextOptions supplies all six fields; active width is finite and positive and extra line spacing finite and nonnegative. Auto direction uses first-strong/LTR-neutral paragraphs; Start/End follow that direction. Logical metrics and ink bounds share drawing positions. Paragraph/line controls, wrapping and oversized clusters follow the text layout guide. Text diagnostic messages include scalar_index/scalar or native byte_offset details, not new result fields.

Font loads copy licensed file bytes and scalar hints. Font and TextLayout are CPU owners surviving window recreation; layout backing survives custom font closure. Default Font unload succeeds without closing it. Sound/Music belong to an audio generation; unload/device close invalidates aliases. Playback controls and explicit streaming updates may run inside frames. Volume is 0..1, pan -1..1, pitch positive with checked resampling rate. Seek admits the reported endpoint as logical EOF; a decoder refusal closes the Music owner. Total probes and retained GetMusicLooping metadata are allowed in handlers, while playback observations are application-only.

Font/decoder/mixer/glyph/cache allocations and retained backing share the backend account. Audio reserves a checked 1 MiB worker stack and 64 KiB guard until successful join. Text drawing preparation failures submit no part of the failed request. Cleanup releases mixer/decoder work before audio closure. See cleanup and interruption for the single nonrenewing deadline and signal drain.

Errors and refusals

Check ok before value or error; inspect error::code and error::message. Wrong-arm access traps. Stable ASCII codes identify failures; new Raylib messages contain both languages. Source diagnostics use the selected CLI language rather than source vocabulary.

Invalid dimensions or NUL title fail before display acquisition. A safely released candidate may fall back to another configured display endpoint. Invalid arguments and exhausted budgets do not trigger host fallback. If every display candidate safely fails, the final candidate's category describes all attempted backends.

Meaningful examples include InitWindow(0, 240, "x") returning raylib.invalid_argument, SetWindowTitle without a window returning raylib.invalid_order, and a camera with zero zoom returning raylib.invalid_argument. Nested camera begin and EndDrawing with camera mode still active return raylib.invalid_order while preserving the current pair. Texture alias unload closes all aliases; later width access returns raylib.closed_resource. Comparing or constructing nominal enums from integers fails source checking with type-mismatch; device calls inside HTTP handlers fail transitive effect checking.

MeasureText("bad\ttext", 32) returns raylib.invalid_text with scalar_index=3 and scalar=U+0009. Nonzero MeasureTextEx spacing and active layout width zero return raylib.invalid_argument. Missing custom font files return raylib.load_failed; malformed required data returns raylib.invalid_font. UnloadTextLayout closes all aliases and later measurement returns raylib.closed_resource. Audio load without initialization returns raylib.invalid_order; nominal TextDirection/TextAlignment cannot be constructed from integers. See the headless identity program and shaped/audio program.

Terminal statuses retain trap 5, limit 6, cancellation 7 and host failure 8. Earlier primary outcomes retain separate cleanup attribution. Select CLI diagnostics with --diagnostic-language=en and generated-program diagnostics with --aspl-diagnostic-language=en.

This current reference covers all 123 Raylib operations, 18 types, six schemas and 161 constants. Explicit HTTP sessions/state/progress keep their HTTP reference authority; the combined workflow explains frame/effect ordering. The original complete reference (opens in a new tab) retains its published raw path and bytes. Contributor adapter inventories and fixtures do not grant public runnable status.

Browser playground

Edit the greeting and choose Run. Checking and execution stay in this browser. Run starts only when you choose it.

Choose your path

Start without installation with your first program in the browser. If you are learning programming, read the Tutorial introduction.

Already write programs? Take the first native program path or go directly to downloads and system requirements.

Use Program and process status to look up the entry function and exit status, or browse the example collections.

You can also open the complete hello program below as a separate draft. It will not replace your current source or run automatically.

First program in the browser

Read the program contract, then inspect the complete hello program below. Choose a source variant, then open it as a new draft on Home. It will not run until you choose Run.

The browser checks and runs ASPL 0.7.0 source locally. It does not execute ELF programs, load Linux shared libraries, or load user source modules. Changing the reading language does not translate a draft.

First native program

Already write programs? Follow the verified native installation and first-program path, then check, run and build. These pages also cover upgrade, native release rollback and uninstall. You do not need to complete the Tutorial.

Downloads and system requirements

Choose from original archives, checksums, package inputs and release history. Check native and desktop system requirements before installation. Console is a separate optional Qt interface; the command line and browser playground do not require it.

Begin without installation

You can start without programming experience. Open your first program in the browser and read the source and output. Changing the documentation language does not translate source, user names, or strings.

Learning path

Begin with output and reading errors. Continue through bindings, arithmetic, conditions, loops, functions, text input, numeric parsing, strings, lists, records, recoverable results, and virtual files.

Lessons are independent. The path ends with a one-file arithmetic quiz in the browser. Afterward, you can choose native installation and learn about source modules. Browse fundamentals examples as you learn.

Start with first output and diagnostics, then bindings and arithmetic, conditions, loops and functions. Each supplies a complete program, a prediction, a small change, a hint and an explained answer. Self-checks store no grade or progress and keep navigation open.

Next, text input teaches prompts, unchanged replies, empty lines, EOF and Stop. Numeric parsing uses a result template to retry invalid integer text. Strings joins names and formatted numbers, then counts and slices Arabic text by scalar positions.

Continue with Lists.

Continue with Records.

Continue with Recoverable results.

Continue with Browser virtual files.

Continue to the one-file quiz.

Choose where to go next for optional native lessons and practical guides.

What you will learn

You will sum the integers 1 through 5, trace a mutable counter and accumulator, and explain why a loop stops.

Before you begin

Read bindings and arithmetic for mutable names and numeric formatting, and conditions for Boolean comparisons. This complete program includes its own entry function. Open it as a new Home draft, then choose Run explicitly. Earlier drafts stay available.

Repeat while a condition is true

var / متغير declares a mutable binding. Both counter and sum have type i64 / ص64, initialized to 1 and 0. The accumulator sum holds the running total. while / طالما tests counter <= 5 before each iteration, including the first. A true condition runs the braced body; a false condition continues after it.

Inside the body, sum = sum + counter adds the current counter to the total. Then counter = counter + 1 advances to the next integer. Assignment replaces a binding's value. The order matters: add the current integer before advancing it.

The reserved start_main() -> i64 / ابدأ_الرئيسية() -> ص64 entry runs the program. After the loop, format_i64 / نسق_ص64 converts the total to text, and print / اطبع writes it with the explicit \n newline. Output is exactly 15\n. The final return 0 / أرجع 0 ends the program normally with process status 0, separately from the printed total.

Trace the iterations

Predict the total and the counter after each body execution before running.

The next test is 6 <= 5, which is false. There is no sixth body execution. The counter update makes this loop finish. Without it, the condition stays true at 1 and execution cannot reach the print. Stop ends such a browser run; it does not make the loop complete normally. If the initial counter were 6, the body would run zero times and the sum would remain 0.

Include one more integer

Change only the upper bound from 5 to 6. Predict the extra iteration. Expected output is exactly 21\n, with normal status 0.

Check your understanding

Explain why both bindings are mutable, when the condition runs, and why the final counter is one past the bound. Compare your trace with the output after an explicit Run. No grade or progress is stored, and navigation stays open. Return to the Tutorial path or read the control-flow reference.

What you will learn

You will compare a value with a threshold, choose one of two messages, and explain what happens below, at, and above that threshold.

Before you begin

Read bindings and arithmetic for initialized names and integer values. This is another independent complete program, including its entry and normal status 0. Open it as a new Home draft without replacing earlier work, then choose Run explicitly.

Choose a branch

let age = 17 initializes a name with an integer. age >= 18 asks whether that value is greater than or equal to 18. A comparison produces a Boolean, a value that is either true or false, rather than a number to print.

if / إذا tests the Boolean condition. When it is true, execution enters the first braced block. else / وإلا supplies the alternative block for a false condition. Exactly one of these blocks executes. After the chosen block, execution continues with the final return. Braces group each branch's instructions; indentation helps you see the groups but does not replace braces.

For 17, the comparison is false, so the lower branch prints Under 18\n. If it were true, the upper branch would print 18 or over\n. The strings include an explicit newline as in the first lesson. The final return 0 is outside both branches, so either choice ends normally with status 0.

Predict all three cases

Keep the threshold at 18. Predict each case before running it. Equality belongs deliberately to the upper branch because the operator is >=.

> would exclude equality, so 18 would take the lower branch instead. = initializes or assigns a binding; == compares two values for equality. Here you need >= to include both equality and larger values.