# rhun extension protocol 1.1 Protocol 1.1 extends [version 1](../v1/v1.md). Existing messages keep their v1 meaning and framing. The first line remains `hello 1 FEATURES...`; `RHUN_PROTOCOL=1.1` advertises the host's maximum protocol revision. An extension sends new requests only after rhun agrees to their feature in the `0 features` event before `ready`. A host that does not know a feature ignores its name. Feature agreement examines the complete bounded hello line, including names after unknown features. Decimal fields must fit their documented bounds without wrapping. A request whose body length cannot be parsed keeps its v1 meaning: `error ID syntax`, only its line is dropped, no body is read and the stream continues (three syntax errors in a row still stop the extension). A reply whose body length cannot be parsed ends the extension stream; a bounded body on a stray provider reply is drained before the next message is parsed. ## Command identity The host accepts `OWNER/NAME.command` in user key bindings and command lookup. The command palette shows this identity beside its title and shortcut, and searches it as well as the title. An exact qualified query selects that command alone, before fuzzy matching. The shorter `NAME.command` alias remains available when exactly one installed, non-removed extension has that extension name. An ambiguous alias does not invoke either command, even when only one owner currently registers that local command. A disabled extension still counts toward ambiguity, so disabling one does not reroute a saved shortcut to another publisher. The same rule applies to a short extension name in host controls: use `OWNER/NAME` when more than one publisher uses the name. Names in `0 run NAME.command DOC` events stay unchanged. Runtime `register` names are local to the extension. Another publisher's equal extension or command name does not prevent registration; an extension cannot register over its own manifest or runtime command. ## Feature: `commands` An extension lists `commands` in `hello 1 ...`. When the host agrees, it may send: | Request | Reply | Effect | | --- | --- | --- | | `ID unregister NAME` | `ok ID` | removes the caller's runtime command, its default shortcut, and its palette entry | `NAME` has the same grammar as `register`: 1 to 40 lowercase ASCII letters, digits or underscores. It names the local command, without the extension prefix. Missing commands and manifest commands return `error ID refused not a runtime command of this extension`. Malformed names return `syntax`. Without agreed `commands`, the request returns `unknown` and changes nothing. Removing one command preserves the caller's other commands and all other extensions' commands. The same name can be registered again after removal. Existing user key-binding configuration is kept, so its binding returns if that runtime command is registered again. An open command palette closes when its command storage changes; other menus resolve their saved command names again when clicked. ## Feature: `workspace_watch` Extensions can subscribe to coalesced filesystem invalidations for the current workspace. Declare `project = read` (or `write`) in `[needs]`, request `workspace_watch` in `hello 1`, and wait for feature agreement before subscribing. This feature grants no additional file access. | Request | Reply | Effect | | --- | --- | --- | | `ID watch-workspace` | `ok ID HANDLE` | subscribes the current runtime to workspace invalidations | | `ID unwatch-workspace HANDLE` | `ok ID` | removes that runtime's subscription | The host sends `0 watch HANDLE changed` when it observes a possible change, and `0 watch HANDLE rescan` when the extension should recover its view of the workspace. Both events require reconciliation with disk. Events can combine multiple changes or repeat; they do not enumerate operations, preserve every intermediate state, or identify changed paths. Hidden directories are included. Extensions must not infer deletions from an incomplete scan. Handles are positive integers through 2147483647, owned by one runtime. Repeated subscription returns its existing handle. Another runtime cannot remove it. Stop, process exit and workspace change retire subscriptions; subscribe again for the new runtime or workspace. Stale handles are never reassigned. Missing permission or workspace, exhausted capacity and invalid requests return an error without creating a subscription. The host shares directory watches across subscribers and preserves its editor watches when a subscription ends. It bounds subscriptions to 128 and tree coverage to 512 directories, 32768 entries and 4095-byte paths, with at most 4096 entries per directory. Incomplete coverage uses recovery invalidations, including a two-second periodic rescan signal. A subscriber must bound its own scanning and preserve its previous view when reconciliation fails. Go exposes `WatchWorkspaceContext`, `UnwatchWorkspaceContext` and `ParseWorkspaceWatch`; Rust exposes `watch_workspace`, `unwatch_workspace` and `parse_workspace_watch`; C exposes `rx_watch_workspace`, `rx_unwatch_workspace` and `rx_parse_workspace_watch`. ## Single-provider selection Formatting, rename, document symbols and signature help use a per-language provider preference. These are host settings, so extensions keep their existing v1 provider declarations and request/reply messages. When several providers match and no default exists, the host asks the user and saves the qualified `owner/name` choice. Definitions, references and code actions keep their combined results from matching providers. A request waits up to five seconds for the selected extension to become ready, including time waiting for a process slot. The host rechecks the document, selection, path, language, manifest patterns and negotiated feature before sending it. An unavailable preference is an actionable error, with no fallback. Explicit actions may start an idle or crashed extension; a user-stopped or disabled extension stays stopped until the user enables or restarts it. Headless controls for testing are `provider-set KIND LANGUAGE OWNER/NAME`, `provider-set KIND LANGUAGE -` to clear, and `print-providers`. Kinds are `format`, `rename` and `symbols`, and `signature`. The control command takes single-word languages; the INI file also accepts language names containing spaces. Automatic signature triggers do not show a chooser or an unavailable-provider error. Without a saved preference they use a sole eligible provider only when it is running; competing idle or starting providers make the choice ambiguous too. A shown or pending signature session keeps its original provider for both triggers and updates, even if the saved preference changes. Explicit Show Signature Help closes that session and resolves the current choice afresh. ## Managed saves The optional host setting `[files] format_on_save = true` uses the existing native format request and workspace-edit reply before writing. It adds no wire feature. The default is false; `format_on_save_timeout` defaults to 2,000 milliseconds and accepts 250 through 30,000. Automatic saves use the saved formatter or a sole eligible provider, including cold activation within the deadline. They never show a chooser or restart a user-stopped provider. If formatting is unavailable, ambiguous, fails or times out, the current buffer is saved with a warning. The document's ID, destination and version are rechecked before applying a reply. A stale reply is discarded and the latest buffer is saved. A formatter's edit can only target the existing document being saved; a foreign group rejects the entire edit without opening tabs. Save cancellation sends `0 cancel ID` for an outstanding format request and performs no write. Closing or retargeting the document cancels its old save, and late replies are ignored. Save Without Formatting cancels the request and writes the current text. Save-before-close and Save All continue only after the actual file write succeeds. ## Capacity and shared scheduling The host can run all 128 installed extension records concurrently. The earlier 16-process limit no longer holds matching providers idle behind extensions that stay running. The editor reserves enough event watches for their input and output pipes plus its other services. On Linux and macOS it raises its descriptor soft limit toward 1,024 when the inherited hard limit permits, preserving larger inherited limits. A restricted hard limit can still constrain starts. Parsing has a shared soft budget per 16 ms window: 4 ms of work, 2,000 message steps or 1 MiB consumed, whichever comes first. A framed header and its completed body each count as a message step. Existing per-extension message, byte, time and flood limits still apply. A complete message handler is atomic and may exceed the soft time/byte budget; subsequent work waits. Shared throttling alone does not count as flooding. Suspended programs resume in rotating order, with both their own and the shared deadlines respected. Stop also cancels queued restarts, an idle activation and queued commands, so it cannot start later without an explicit restart. `print-ext-budget` reports cumulative windows/yields and the highest message and byte totals seen in a shared window for headless checks. ## Text snapshots and document events Before answering `text DOC`, the host sends pending document events through the returned version. An extension that replaces its cache with the reply can discard queued edit or resync events at that version or earlier. Later edit batches begin after the snapshot, so they can be applied without repeating changes already included in the text. Repeated text reads do not repeat a resync event for the same version. ## Feature: `save-actions` A provider declares `[provides] save_actions = PATTERNS`, `documents = write` in `[needs]`, and `save-actions` in `hello 1 ...`. A matching document activates it and receives the same opened and edits stream as other language providers. The host agrees to the feature before ready. Protocol 1.1's complete manifest schema is [v1.1.json](https://github.com/rhun-editor/extension-protocol/blob/main/v1.1/v1.1.json); the frozen v1 schema remains unchanged. The opt-in `[files] code_actions_on_save` setting lists source kinds separated by spaces. Each kind is `source` or a hierarchy such as `source.organizeImports` or `source.fixAll.eslint`. Segments contain ASCII letters, digits, underscores or hyphens. A kind is at most 128 bytes, with at most 32 kinds and 4,096 bytes in the setting. Empty disables it. An ancestor covers its listed descendants, so `source source.fixAll` runs `source` once. Invalid changes preserve the previous valid setting and show a warning. `code_actions_on_save_timeout` defaults to 2,000 milliseconds and accepts 250 through 30,000. This is one deadline for the whole source phase, including activation. Source actions precede formatting, which has its own deadline. Eligible matching providers run in qualified `owner/name` order for each configured kind. Disabled, user-stopped, failed and unnegotiated providers are skipped. No matching provider is quiet. Errors or a timeout skip the remaining source phase and continue to formatting with a warning. A user edit makes the remaining automatic transforms stale; the current text is saved. Save Without Formatting bypasses all automatic save participants. | Direction | Request | Successful reply | | --- | --- | --- | | Host to extension | `ID save-actions DOC VERSION KIND` | `ok ID LEN` followed by a workspace edit, or `ok ID 0` | | Extension to host | `ID save-apply SAVE_REQUEST DOC VERSION LEN` followed by a workspace edit | `ok ID NEW_VERSION` | `SAVE_REQUEST` is the host's active source request ID. Request IDs are 1 through 2147483647, DOC is positive, and VERSION is nonnegative. The ordinary workspace-edit limits apply. A returned or intermediate edit may only target the existing saving document. Any foreign group rejects the whole edit before opening files. Empty edits do not advance its version. Intermediate edits require agreed `save-actions`, documents write authority, the same peer, request and document, and the live version last credited by that save. A wrong or retired invocation returns `refused`; an obsolete version returns `stale`. Ordinary `apply` does not advance the save's credited version. After intermediate edits, the final reply uses their credited version for its workspace edit, or an empty edit when there is nothing left to apply. The host revokes intermediate authority before sending `0 cancel SAVE_REQUEST`, saving, retargeting or closing the document. Late intermediate edits are rejected and late final replies are ignored. Extensions must observe cancellation and bound their work. Go's typed handler receives a context cancelled directly by the input reader; Rust and C handlers are serial, so custom asynchronous dispatchers must use the cancel event's request ID to retire their work. ## Feature: `snippets` This feature adds native editable fields to prepared UTF-8 text. It uses the existing `complete` provider; no new manifest property is needed. A completion's INSERT contains expanded text, and EXTRA may contain records with no following body: ``` field GROUP START END PARENT 0 ``` START and END are half-open byte offsets into INSERT, on UTF-8 character boundaries. GROUP is 0 through 2147483647. The first occurrence of a positive group is its primary editable field; other occurrences are linked mirrors and must initially contain identical bytes. Group 0 is an optional single final selection, empty for a caret. Without it, the final caret is INSERT's end. Positive groups are visited in increasing numerical order, with 0 last. Empty prepared text stays empty, even when the completion has a nonempty label. Existing cursor metadata remains a fallback for hosts that do not agree to snippets. Invalid field metadata is ignored as a whole by completion acceptance, leaving plain INSERT and its ordinary cursor behavior. PARENT is 0 for a root, or the one-based index of an earlier field record that is a different positive group's primary. That primary must contain this occurrence. Mirrors cannot contain child fields. Overlapping nonempty ranges, and empty ranges strictly inside nonempty ranges, must follow their declared ancestor chain. Coextensive parent and child ranges are allowed; unrelated empty fields may coincide at boundaries. Same-group occurrences cannot overlap or nest. Each occurrence's group depends on its containing primary ancestor groups; cycles in this group dependency graph are invalid even when the record-parent graph is acyclic. The final marker is non-owning: it may overlap or cross other fields, creates no group propagation dependency, and cannot be another record's parent. Its own PARENT, when nonzero, must contain the whole final selection. Advancing past the positive groups selects this range and finishes the innermost session. An initially nonempty final range follows edits to its content without absorbing adjacent fields. If deletion collapses the range, later typing in the same occurrence restores the range; typing in a different occurrence keeps its boundary. Initially empty final markers retain their rightward caret affinity. A primary group can offer literal values using a separate EXTRA record, before or after fields: ``` choice GROUP COUNT LEN ``` The LEN-byte body contains exactly COUNT options. Each option is `OPTION_LEN` and LF followed by exactly OPTION_LEN UTF-8 bytes. Options can be empty, multiline, or contain NUL. GROUP must name a positive primary group, with only one choice record per group. COUNT is 1 through 256, and each option is at most 1 MiB. The first option must equal the initial primary bytes. Choice records and fields are validated together. One bad choice invalidates all new snippet metadata. Choices remain native after the provider stops. Freeform field editing remains available. The host displays all choices in declared order. Enter or a click replaces the entire active primary and keeps the field active; Tab also advances once. Shift+Tab closes without applying and moves to the previous field. Escape closes choices before ending field editing. Choosing the same bytes does not create an undo record. The Choose Value command reopens the list. Explicit provider completion from an exactly selected active primary collapses to its end; ordinary provider request position and replacement-range rules then apply. Limits are 512 field records, 256 positive groups, nesting depth 32, and 4 MiB for an explicit prepared record including framing. Existing completion-list limits still apply. A completion on an older host keeps its plain text; that host skips unknown EXTRA records using their declared body lengths. Extensions must check agreement before using the explicit insertion request: ``` ID snippet DOC VERSION L1 C1 L2 C2 LEN ``` The LEN-byte body is one prepared completion-item record, without a list header: ``` 0 0 0 0 snippet 0 INSERT_LEN 0 EXTRA_LEN ``` Exactly INSERT_LEN text bytes and EXTRA_LEN field and choice record bytes follow the header. No label, detail, documentation, extra edit, or unknown record is allowed in this explicit body. DOC is a positive existing document ID, VERSION is nonnegative and exact, and the range uses positive one-based lines and byte columns. Documents write authority and a writable document are required. The host validates the entire request before replacing the range. Invalid explicit metadata rejects the request without edits. Success replies `ok ID NEW_VERSION`, selects the first positive field, and starts a session without switching to an inactive target tab. Fieldless text inserts normally; final-only metadata selects its range and finishes immediately. Tab and Shift+Tab move through fields, and Escape ends the session. A completion popup takes its keys first. Accepted sessions are independent of the provider process. Inactive tabs retain their session. Undo and redo, reloading, readonly state, non-user document mutations, or moving the selection outside the active primary end the session. Returning the selection cannot revive it. Each user edit and its mirror updates undo together. Replacing or editing through a parent field retires affected nested fields. Retiring a primary retires its whole group; external mirror text remains as ordinary text. Retiring only a mirror leaves its primary and other mirrors live. The final marker survives field retirement. Inserting a prepared snippet within the active primary pauses the enclosing session. Inner field numbers are local. Tab after the inner final field returns to its final caret and resumes the enclosing field; the next Tab continues the enclosing field order. Shift+Tab at the first inner field stays there. Escape ends every enclosing level. Fieldless and final-only insertions retain enclosing links without adding a navigation level. Ordinary completions also retain those links when all their edits fit inside the active primary. Invalid completion field data is discarded without discarding valid enclosing links. An additional edit outside that primary ends the old session before accepting the completion. The same applies when a new positive-field session would exceed 32 levels, 512 total occurrences, 256 total groups, or 4 MiB of retained choice payload across the stack. The new snippet still inserts and starts independently. Malformed explicit insertion leaves the existing stack unchanged. Mirrors propagate in group dependency order. A nonempty replacement preserves its original left and right boundary positions, so a surviving empty field at the old end stays after the new text. For originally coincident empty occurrences, record order determines side affinity. The host preflights the complete propagation, including ancestors, before mirror writes. If the operation would insert more than 4 MiB through mirroring across all enclosing levels, it ends the session and retains the primary user input without making a partial mirror batch. Template parsing, variables and transforms are separate from this prepared-text wire representation. ### Read-only insertion context After agreeing to `snippets`, an extension with documents read authority can request: ``` ID snippet-context DOC VERSION L1 C1 L2 C2 ``` There is no request body. DOC must name an open document, VERSION must match exactly, and the ordered range uses positive one-based line and byte columns at UTF-8 boundaries. All numbers are unsigned decimal within signed 64-bit range; ID is 1 through 2147483647. The request has exactly these eight fields. Readonly documents and inactive tabs are allowed. It does not move the cursor, change the selection, edit the document, or grant write authority. Success is `ok ID VERSION LEN` followed by exactly LEN bytes. The body begins: ``` context 1 LINE COL TABWIDTH SPACES CRLF SELECTED_LEN LINE_LEN PATH_LEN WORKSPACE_LEN INDENT_LEN COMMENT_LEN ``` LF ends the header. Exactly six raw UTF-8 strings follow in the listed order, without separators: | String | Meaning | | --- | --- | | Selected text | The exact requested range, independent of the editor's current selection | | Current line | The range start's line, excluding its newline | | Path | The document's absolute display path, or empty for an untitled document | | Workspace | The current project root, or empty without a project | | Indentation | Leading spaces and tabs up to the range start, stopping at the first other byte | | Line comment | The grammar's line-comment token, or empty when unavailable | LINE and COL repeat L1 and C1. TABWIDTH is the target document's effective width, 1 through 16. SPACES and CRLF are 0 or 1. These settings include the target document's option overrides. The six strings may contain NUL; selected text may contain line breaks. Body framing uses byte lengths throughout. The header is at most 256 bytes excluding LF. The complete body, including header and strings, is at most 4 MiB. The host rejects larger snapshots with `toobig` and invalid UTF-8 with `refused`, without truncation. Standard `syntax`, `needs`, `unknown`, `nodoc`, `badpos`, and `stale CURRENTVERSION` errors also apply. Pending document events precede a successful context reply. This partial snapshot does not replace a whole-document text cache. An extension can prepare a snippet using these values and insert it using the same version and range; an intervening edit produces `stale`. The context contains no clipboard contents, environment values, clock or random data. ### Declared initial mirror variants The additive `snippet-variants` feature requires `snippets` as well. With both agreed, a prepared program's EXTRA may include `variant FIELD 0` followed by LF, with no body. FIELD is the one-based field-record index, 1 through 512. Declarations may precede or follow fields and choices. At most 512 distinct declarations are allowed. Each must name an existing positive-group mirror whose initial bytes differ from its primary. Primary fields, final selections, equal copies, duplicate declarations and absent indices are invalid. Decimal indices accept leading zeroes; the final body-length token must be exactly `0`. All ordinary field, UTF-8, ancestry, graph, choice and encoded-size constraints still apply. An unequal mirror without a declaration is invalid. Choice option zero still matches the primary. A variant changes only initial validation. After an edit to its group, the native editor copies the primary value to ordinary mirrors using the existing undo and navigation behavior. Declarations do not execute transforms or retain a dependency on the extension process. Explicit insertion requires agreement and rejects invalid metadata atomically. For completion, invalid or unnegotiated metadata is discarded together while the insertion text remains usable. Older hosts skip the unknown zero-body record and reject the unequal field bytes, producing the same plain-text fallback. Extension authors must check both features before emitting variants. Plain prepared-snippet SDK validation remains strict; use the program API for declarations. ### Compiled field transforms The additive `snippet-transforms` feature requires `snippets`. When both are agreed, EXTRA may contain one `transforms 0 LEN` header followed by LF and exactly LEN ASCII bytes. The reserved token is exactly `0`. The body is canonical RFC 4648 standard Base64 with required padding. Whitespace, line breaks, the URL alphabet, misplaced padding and nonzero unused bits are invalid. The record may precede or follow fields, choices and variants. A second record is invalid, including an empty binding payload. The decoded body is an SNTX program. Each binding names an existing one-based field index, 1 through 512, in a positive group. Primaries and mirrors may both have transforms; final selections cannot. Initial bytes still obey ordinary equality or explicit variant rules. The SDK encoders sort bindings by field index without changing caller arrays. The host owns validated programs independently of the extension process. On Tab or Shift+Tab, every alive transformed occurrence in the group being left uses its own current value. Typing still copies the primary value to ordinary mirrors. Initial activation and cancellation do not run transforms. Shift+Tab at the first group runs the group and reselects it; revisiting a group runs its transforms again. Outputs are prepared together, including enclosing mirror propagation, then applied as one undo group before selecting the destination. Failure preserves document text and selection and ends the live session. The batch has a shared 16,777,216 work-unit budget, 50 ms deadline and 4 MiB inserted-byte cap. Output comparison, case conversion, matching and indentation share the budget. Undo and redo restore the complete accepted change. The first output line keeps its whitespace. CRLF, CR and LF become LF. Each later line, including a trailing empty line, receives the original insertion line's leading ASCII spaces and tabs, then normalization with the document's current tab width and spaces setting. Completion captures this prefix at its main edit before additional edits. The captured prefix, choices and compiled programs share the existing 4 MiB aggregate metadata budget across nested sessions. All existing encoded-body limits include the Base64 expansion: `4 * ceil(raw_bytes / 3)` plus the record header. Explicit insertion remains at most 4 MiB and completion lists at most 1 MiB. SDK encoders reject an invalid explicit-sized program before emitting it. Invalid completion metadata falls back to insertion text as a whole. A valid program whose completion item exceeds the completion budget is omitted and marks the list incomplete. Malformed outer completion or EXTRA framing follows ordinary list rejection. Unnegotiated transforms reject explicit insertion and discard completion snippet metadata. Extension authors must check both features before sending this record. #### Portable binary programs All integers below are unsigned little-endian 32-bit words. There is no alignment, terminator, implicit padding, or trailing data. Program version is 1 and Unicode version is `0x00100000` (Unicode 16.0.0). All reserved words and unused operands must be zero. Lengths and offsets are in bytes. Validators reject an invalid program before executing it. Use SDK compilers or import validated compiled programs rather than constructing bytes from untrusted integers. SNTX begins with eight words: magic `0x58544e53` (`SNTX`), version, Unicode version, binding count, total length, and three reserved words. The count is 0 through 512 and total length is at most 4 MiB. Each 24-byte record contains field index, absolute regex offset, regex length, absolute replacement offset, replacement length, reserved zero. Field indices strictly increase. Blobs start immediately after the record table and partition the rest of the payload: regex then replacement for each binding, without gaps. A zero-count payload is exactly the 32-byte header. SDKs omit the record for no bindings. RNRX begins with twelve words: magic `0x58524e52` (`RNRX`), version, Unicode version, flags, capture count, instruction count, class count, range count, repeat count, entry instruction index, total length, reserved zero. Flags are `g=1`, `i=2`, `m=4`, `s=8`, `u=16`, `y=32`, `d=64`; other bits are invalid. Consumption uses Unicode scalars in both modes, while case equivalence distinguishes `i` and `iu`. Captures are at most 64, instructions 1 through 8192, classes at most 256, ranges at most 8192 and repeats at most 256. The whole regex is at most 256 KiB. Entry and all branch targets are zero-based instruction indices. Arrays follow the header in the order below. Each instruction is four words: opcode, X, Y, Z. A consuming instruction falls through to the next instruction, which must exist. Unused operands are zero. | Opcode | Meaning and operands | | --- | --- | | 0 | Match/return, no operands. | | 1 | Match scalar X. | | 2 | Match dot, no operands. | | 3 | Match class X. | | 4 | Assert X: 1 start, 2 end, 3 word boundary, 4 non-boundary. | | 5 | Save capture slot X; slots 2 through `2*(captures+1)-1`. | | 6 | Clear Y capture slots starting at X; X and Y even, X at least 2, Y positive. | | 7 | Split to X then Y, without fallthrough. | | 8 | Jump to X. | | 9 | Match capture X, 1 through capture count. | | 10 | Initialize repeat X, then fall through. | | 11 | Test repeat X, using body target Y and exit target Z. | | 12 | Advance repeat X and jump to Y. | | 13 | Call assertion at X, continue at Y. Z bit 0 negates, bit 1 searches backward. | | 14 | Assert kind X (1 through 4), with explicit local `i`/`m` bits in Y (mask `0x06`), and Z zero. | | 15 | Match capture X (1 through capture count), with explicit local `i` bit in Y (`0` or `2`), and Z zero. | Instructions 14 and 15 fall through to a following instruction, which must exist. Their Y operand replaces only the indicated flag bits for that operation; other global flags retain their values. Local flags never persist into later instructions or branches. Class records are `(first_range, range_count)` pairs that partition the range array in class order, including empty classes. Ranges are inclusive `(low_scalar, high_scalar)` pairs, sorted and disjoint within each class, with adjacent ranges merged. Scalars exclude surrogates; no range may cross the surrogate gap. Repeat records have four words: minimum, maximum, flags, reserved zero. Counts are at most `0x7fffffff`; maximum may instead be `0xffffffff` for unbounded. Maximum is otherwise at least minimum. Repeat flag bit 0 selects lazy order; other bits are invalid. Matching uses bounded backtracking, rollback and assertion storage. Storage exhaustion fails the whole batch. RNRF begins with eight words: magic `0x46524e52` (`RNRF`), version, Unicode version, record count, UTF-8 blob length, total length, and two reserved words. At most 8192 24-byte records follow, then exactly the blob. Total length is at most 4 MiB. Records contain opcode, capture index, A offset, A length, B offset, B length. Offsets are relative to the blob. Used strings, including empty ones, partition the blob in record order, A then B. Unused offset/length pairs are zero. Capture indices are at most `0x7fffffff`; absent captures resolve as empty. Literal records require index zero. | Opcode | Result | Strings used | | --- | --- | --- | | 0 | Literal A | A | | 1 | Capture | none | | 2, 3, 4 | Uppercase, lowercase, capitalize capture | none | | 5, 6, 7, 8 | Camel, Pascal, snake, kebab case capture | none | | 9 | A when capture is nonempty | A | | 10 | Capture when nonempty, otherwise A | A | | 11 | A when capture is nonempty, otherwise B | A, B | Transforms preserve unmatched input around replacements. Global zero-width matches advance the next search by one scalar without dropping intervening text. Sticky matching starts at the current search offset. If there is no match and the format has a nonempty else branch, the whole format resolves once with absent captures and replaces the input. Otherwise a no-match transform preserves the input. Case conversion uses pinned Unicode full mappings and contextual final sigma. Word case formats use Unicode letters and ASCII digits. ## Feature: `command-args` Commands learn where they were invoked from and receive a body. With `command-args` agreed, every invocation of one of the extension's commands is ``` 0 run EXT.NAME DOC FROM LEN ``` followed by exactly LEN body bytes. `EXT.NAME` and `DOC` are v1's (the command's full name and the document it is about, 0 without one); the two trailing fields are always present, LEN is 0 without a body. Without the feature the extension receives v1's `0 run EXT.NAME DOC` and no body. | FROM | Invoked by | DOC | Body | | --- | --- | --- | --- | | `palette` | the command palette, a headless `cmd`, a menu listing all commands | the active document | empty | | `key` | a key binding | the active document | the binding's ARGS (at most 4096 bytes) | | `menu` | a menu item, a tab-strip or view button | the target's document when it has one, else the active one | `TARGET` LF, then the item's args | | `ref` | a command reference (code lens, tree item, status item, notification button, inlay hint part) | the reference's document (a lens, a hint), else the active one | the reference's ARGS, verbatim | A command invoked while its extension starts is held with its FROM, document and body (at most 65536 bytes) and delivered after `ready` and the catch-up; a later invocation replaces it. ### Command references Inside any body, the extra record ``` command NAME ARGS_LEN ``` followed by exactly ARGS_LEN bytes names one of the extension's own commands, manifest or runtime-registered, by its local name NAME (1 to 40 of `[a-z0-9_]`, without the extension prefix). ARGS are opaque, at most 8192 bytes, and come back verbatim as the body of `0 run EXT.NAME DOC ref LEN` when the user activates whatever carries the reference. A record with a bad name or more than 8192 bytes of ARGS is a syntax error of the message that carries it. A reference whose command no longer exists when it is used shows "This command is no longer available" and sends nothing. Code lens, tree items, status items, notification buttons, inlay hint parts and menu-like lists use this record. Headless controls: `cmd-args NAME ARGS...` invokes a command as a reference would (FROM `ref`, ARGS as the body) and `cmd-ref EXT NAME [ARGS]` parses the record `command NAME LEN` + ARGS for extension EXT and invokes it. ### Running commands: `run-command` and `call` | Direction | Request | Reply | | --- | --- | --- | | extension to rhun | `ID run-command NAME LEN` + ARGS | `ok ID LEN` + RESULT, or `error ID CODE TEXT` | | rhun to the command's owner | `ID call EXT.NAME DOC CALLER LEN` + ARGS | `ok ID LEN` + RESULT, or `error ID CODE TEXT` | NAME is a rhun built-in (`NAME` or `rhun.NAME`) or another extension's command (`OWNER/EXT.NAME`, or `EXT.NAME` when unambiguous, the rule of "Command identity"). An extension's own commands are `refused its own command` (call the handler directly). ARGS are at most 65536 bytes. - Built-ins: v1 section 8a's list with its `needs`; the result is always empty (`ok ID 0`). `goto_line` (`LINE` or `LINE COL`, one-based; it moves the cursor without the palette), `find`, `replace` (the find field's text), `find_in_files`, `quick_open` and `command_palette` (the palette field's text) take ARGS: one line of UTF-8 without control characters, at most 1024 bytes. ARGS for another built-in are `syntax`. `goto_line`, `quick_open`, `command_palette` and `find_in_files` while the palette or a prompt is open are `busy a prompt is open`. - Another extension's command runs only when its owner declares `NAME.callable = yes` in `[command-options]` and agreed `command-args`; otherwise `refused not callable`. rhun starts an idle owner as a command invocation would, then sends it `call`: DOC is the active document (or 0), CALLER the caller's `OWNER/NAME`. The owner's `ok` (its RESULT, at most 1048576 bytes; more is `toobig`) or `error` (its code and text) goes back to the caller unchanged. rhun waits 10 seconds including the start; then the caller gets `error ID cancelled timeout` and the owner `0 cancel ID`. An owner that stops first answers `cancelled`; a caller that stops has its calls cancelled. A caller has at most 8 calls waiting (`busy 8 calls outstanding`). There is no user prompt: a callable command runs with its owner's `[needs]`, and the owner sees CALLER. - Other errors: `refused no such command`, `refused not a command an extension may run` (v1's text), `refused the extension is turned off`, `needs documents=write`, `needs terminal=yes`, `needs terminal=run` (the task commands). Without the agreed feature `run-command` returns `unknown`. ### `[command-options]` Per command of the manifest, `NAME.FIELD = VALUE`; all optional: ```ini [command-options] copy_relative.icon = copy # icon for menu items and tab-strip or view buttons copy_relative.when = projectOpen # enablement: false hides it from the palette and menus; its keys fall through copy_relative.palette = no # not listed in the palette (menus and keys still run it) copy_relative.callable = yes # other extensions may run-command it ``` A bad line or a clause that does not compile drops that one entry and is listed on the extension's page; it never fails the manifest. The palette evaluates `when` with the focus it had before it opened. The extension's page has a **Contributions** block: its commands (each with the binding in force), its bindings (`active`, `overrides built-in TITLE`, `shadowed by your [keys]`, by `built-in` or by `OWNER/NAME`, or `refused: WHY`), menu items, status items, settings, grammars and `[language.NAME]` keys, file icon themes, declared views, and the dropped entries. Headless: `print-ext-page-contributions EXT` prints it as `head TEXT` and `row plain|warning|error TEXT -- DETAIL` lines. ## Keys An extension binds keys in its manifest's `[keys]` section; the user's config file takes the same grammar in its `[keys]` section. ```ini [keys] # KEYS = COMMAND [ARGS] [when CLAUSE]: KEYS one stroke or two separated by a space; a leading # linux: / mac: / windows: limits it to that system; ARGS run to " when " (they cannot contain it) ctrl+k ctrl+c = rhun.toggle_comment when editorFocus && !editorReadonly ctrl+alt+l = insert_log console.log when resourceLang == JavaScript mac:ctrl+shift+r = reveal ``` A stroke is modifiers and a key joined by `+` (`ctrl`, `shift`, `alt`, `super`; `cmd` and `meta` are `super`; on macOS Command arrives as `ctrl`), the key a character or a key name (`Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `Up`, `Down`, `Left`, `Right`, `Home`, `End`, `PageUp`, `PageDown`, `Insert`, `Space`, `F1`-`F12`, or an X keysym name such as `KP_Add`). A key containing `=` is written with its name (`ctrl+equal`), since the INI line splits at the first `=`. COMMAND in a manifest is `NAME` (its own command, manifest or runtime-registered), `rhun.NAME` (a built-in) or `EXT.NAME` / `OWNER/EXT.NAME` (another extension's); in the user's `[keys]` it is any command's name, and `none` removes every binding of exactly those strokes. ARGS are the body of `0 run EXT.NAME DOC key LEN` (at most 4096 bytes); built-ins ignore them. Precedence: the user's `[keys]` > an extension's `[keys]` > rhun's built-in bindings > an extension's `[commands]` default keys (v1, single strokes, which still never take a built-in's key). Among bindings of the same rank the earlier one wins. A key goes to the best binding whose first stroke matches, whose clause holds and whose command is enabled (`[command-options]` `when`). When the best match starts a chord, rhun waits for the second stroke, showing `Ctrl+K — waiting for the next key` in the status bar: the second stroke runs the chord; Escape ends the wait quietly; another key ends it with the toast `Ctrl+K Ctrl+X is not bound`; a click, a focus change or 5 seconds end it too. When a single-stroke binding of the same rank shares the first stroke, the status bar says `… or pause for TITLE` and a 1-second pause runs that one. Chord second strokes and extension bindings also match the key on the first (Latin) keyboard layout, so `ctrl+k c` works on a Cyrillic layout. Select Color Theme is `ctrl+k ctrl+t`. Checks, for extensions' bindings: a chord's first stroke needs ctrl, alt or super; a typing key (a character, Enter, Tab, Backspace, Delete, Escape, the arrows, Home, End, PageUp, PageDown, Insert) without ctrl, alt or super is accepted only when its clause has, as a top-level `&&` term, `!textInputFocus`, `viewFocus` or `view == …`, so no extension takes typing away from a text field; a command that does not exist is refused (until a runtime command of that name is registered). Refused bindings stay listed with the reason. Keymaps rebind keys to commands; they do not give modal editing (operators, counts, a kill ring), and an extension cannot take typing keys while text has the keys. The palette command **Keyboard Shortcuts** lists every binding with its source, clause and what shadows it; Enter runs its command. Headless controls: `print-keys [EXT]` prints a line per binding (`STROKES COMMAND source=user|builtin|ext:OWNER/NAME|default:OWNER/NAME rank=R [args=A] [when=W] state=active|shadowed:SOURCE|refused:command|when|typing|prefix|strokes`), `print-chord` prints `chord=none` or `chord=STROKE fallback=COMMAND ms=N`, and `key-latin LATIN COMBO` presses COMBO as a layout that is not Latin reports it, with LATIN on the first layout. ## When clauses Menu items, key bindings, status items and view actions take a `when` clause: an expression over context keys that decides whether they apply. A clause is at most 512 bytes, compiles to at most 64 operations and nests `!` and parentheses at most 8 levels deep. ```abnf clause = ws or ws or = and *( ws "||" ws and ) and = unary *( ws "&&" ws unary ) unary = "!" ws unary / "(" ws or ws ")" / "true" / "false" / test test = key [ ws tail ] / quoted ws ( "in" / "not" 1*SP "in" ) ws list tail = cmp ws value / "=~" ws value / "in" ws list / "not" 1*SP "in" ws list cmp = "==" / "!=" / "<=" / ">=" / "<" / ">" value = quoted / bare ; always a literal, never a key list = key / quoted ; space-separated words quoted = "'" *( %x20-26 / %x28-7E / UTF8-2-4 ) "'" / DQUOTE *( %x20-21 / %x23-7E / UTF8-2-4 ) DQUOTE bare = 1*( ALPHA / DIGIT / "_" / "-" / "." / "/" / ":" / "*" / "?" / "+" / "#" / "@" / "$" ) key = builtin / config-key / ext-key builtin = ALPHA *( ALPHA / DIGIT ) ; a name of the table below config-key = "config." word "." word ; word = 1*( %x61-7A / DIGIT / "_" ) ext-key = [ owner "/" ] name "." local / [ owner "/" ] name ".setting." word local = %x61-7A *( ALPHA / DIGIT / "_" ) ; at most 40 bytes ws = *( SP / HTAB ) ``` Every key's value is a byte string; an absent key is empty. A bare key (and the result of the whole clause) is true when its value is non-empty and not `false` or `0`; built-in booleans are `true` or `false`. `==` and `!=` compare bytes exactly. `<`, `<=`, `>`, `>=` compare signed decimal integers and are false when either side is not one. `=~` matches the whole value against a glob: `*` any run, `?` one UTF-8 character, every other byte itself, case-sensitively (there are no regular expressions). `X in L` is true when X's value (or the quoted literal) equals one of L's space-separated words; `not in` negates it. `!` applies to the test or parenthesized group that follows it (`!key == v` is `!(key == v)`), comparisons bind tighter than `&&`, which binds tighter than `||`. Quotes have no escapes. A clause that does not compile is reported with the byte offset of the error, for example `unknown key resourceExtt at byte 0`; the item, binding or status item it guards is dropped and the problem is listed on the extension's page. A typo in a built-in key is an error; an unknown key of another extension evaluates empty. Extension keys: an extension sets `KEY` (feature `context-keys` below, or `[context]` defaults); everyone reads it as `NAME.KEY`, or `OWNER/NAME.KEY` when two installed extensions share NAME (an ambiguous `NAME` is a compile error). In an extension's own manifest `NAME.KEY` always means its own key. `NAME.setting.KEY` is the extension's `[settings]` value KEY, as `0 setting` sends it, and is read-only. `config.SECTION.KEY` is a rhun setting as written in its config file (`config.editor.word_wrap == true`, `config.editor.line_height == 1.5`). Built-in keys. Inside a menu, the `resource*` and `editor*` keys describe the menu's target. | Key | Value | | --- | --- | | `editorFocus` | the active tab is a text document and has the keys | | `textInputFocus` | the editor, the palette or a prompt, the find bar, the settings page or the commit message has the keys | | `paletteFocus`, `findFocus`, `explorerFocus`, `agentsFocus`, `terminalFocus`, `scmInputFocus`, `settingsFocus` | that part has the keys | | `findVisible`, `completionVisible`, `signatureVisible`, `snippetActive` | the find bar, the completion list, signature help show; a snippet session is live | | `viewFocus`, `view`, `viewItem` | an extension view has the keys; its id; the focused or targeted tree item's context value | | `activeTab` | `doc`, `image`, `settings`, `git`, `extensions`, `view`, or empty | | `activeTabPinned`, `tabCount` | boolean; a number | | `resourceLang` | the grammar's name with spaces as `_` (`Visual_Basic`); empty without one | | `resourceExt`, `resourceFilename`, `resourceDirname`, `resourcePath` | `.rs` (the last suffix, with its dot), `main.rs`, its folder, the absolute path; empty for an untitled document | | `resourceScheme` | `file` or `untitled` | | `resourceInProject` | the path is inside the project folder | | `editorReadonly`, `editorDirty`, `editorHasSelection`, `editorHasMultipleSelections` | of the active (or target) document | | `editorProviders` | the provider kinds declared for it, words of `complete signature definition references symbols actions rename format` | | `vimMode` | `normal`, `insert`, `visual`, `vline` while vim mode is on, else empty | | `sidebarVisible`, `agentsVisible`, `terminalVisible` | that panel shows | | `projectOpen`, `projectPath` | a project folder is open; its path | | `gitRepo`, `gitBranch`, `gitChanges` | git runs in a work tree; its branch; the number of changed files | | `isLinux`, `isMac`, `isWindows`, `isWayland` | the system rhun runs on | | `remoteName`, `remoteHost` | in a remote window: `ssh`, `docker`, `podman` or `wsl`, and the host or container; empty in a local window | | `targetKind` | in a menu: `editor`, `file`, `folder`, `root`, `tab`, `terminal`, `extension`, `view`, `item`; else empty | | `explorerResourceIsFolder`, `explorerResourceIsRoot`, `tabKind` | of an explorer or tab menu's target | | `debugState`, `inDebugMode`, `debugType` | the debugger's state (`inactive`, `false` and empty while no session runs) | | `gitTrusted` | git may run in the project folder (`false` while the trust pause holds) | | `scmProvider`, `scmResourceGroup`, `scmResourceStatus` | in a source control row's menu: `git` or the provider's `OWNER/NAME`; the row's group; its status letter (see Source control) | The test vectors `tests/data/when-vectors.txt` (rhun) and `v1.1/when-vectors.txt` (extension protocol repository) list clauses with their results in a fixed context and errors with their offsets. Headless controls: `when CLAUSE` prints `when=1`, `when=0` or `when error at N: TEXT`; `print-context [KEY]` prints every built-in key, or any one key a clause can name, as `KEY=VALUE`. ## Feature: `context-keys` An extension lists `context-keys` in `hello 1 ...` to set keys of its own for when clauses. | Request | Reply | Effect | | --- | --- | --- | | `ID set-context KEY VALUE` | `ok ID` | sets the extension's key KEY | KEY is `local` above: a lowercase letter, then ASCII letters, digits and underscores, at most 40 bytes. VALUE is the rest of the line: one line of UTF-8 without control characters, at most 256 bytes (more is `toobig 256 bytes`); `-` removes the value set at run time, so the `[context]` default applies again. An extension has at most 64 keys, its `[context]` defaults included (one more is `toobig 64 keys`). A bad KEY or VALUE is `syntax`. Values set at run time are removed when the program stops. A change takes effect at the next frame. Without the agreed feature the request returns `unknown`. The manifest section `[context]` gives defaults, valid before the program starts and after it stops: `KEY = VALUE` lines with the same KEY and VALUE rules. ```ini [context] mode = normal enabled = true ``` ## Menus An extension adds items to rhun's menus in its manifest; they need no feature (without `command-args` a clicked item sends v1's `0 run EXT.NAME DOC` and no target). ```ini [menu.explorer] # ITEM.FIELD: command (default: ITEM), group, order, when, args, submenu copy_relative.command = copy_relative copy_relative.group = copy copy_relative.order = 10 copy_relative.when = !explorerResourceIsRoot run_make.command = make_targets run_make.when = resourceFilename == Makefile more.submenu = tools # this item opens [submenu.tools] more.group = 9_tools [submenu.tools] title = Demo Tools lint.command = lint_file lint.when = resourceExt in '.js .ts' ``` Locations: `editor` (the editor's context menu), `explorer` (an explorer row's menu and the menu of its empty area), `tab` (a tab's menu), `terminal` (the terminal's menu), `extension` (its title-bar button and its row in the extensions dropdown: the items replace the list of all its commands, followed by Settings and details), and, drawn by views and the tab strip, `editor_title`, `view_title`, `view_item`, `view_item_inline`; on source control rows `history_commit`, `history_file`, `scm_resource` and `scm_group`, and in a version control panel's header `scm_title` (targets under Source control below). ITEM is 1 to 40 of `[a-z0-9_]`. `command` names a command as `[keys]` does (`NAME`, `rhun.NAME`, `EXT.NAME`); `args` are bytes added to the body; `order` is a whole number (default 0); `when` is a clause evaluated for the menu's target (inside a menu the `resource*` and `editor*` keys describe the target, and `targetKind`, `explorerResourceIsFolder`, `explorerResourceIsRoot` and `tabKind` are set). An item shows when its command exists, its `[command-options]` `when` holds and its own clause holds. Order: rhun's own items first, then the extensions' groups sorted by name (an item without `group` is in a group named after its extension), a line between groups; within a group by `order`, then the extensions' order, then the item's name. Labels are the commands' titles, at most 60 bytes. A submenu row (its title and `›`) opens its items in place of the menu; a submenu inside a submenu is refused. Caps: 16 items per extension per location, 32 extensions' items in one menu. A bad line, an unknown location, a clause that does not compile, a nested submenu or a 17th item drops that entry and is listed on the extension's page; the manifest still loads. A clicked item sends `0 run EXT.NAME DOC menu LEN` with the body `TARGET` LF and the item's `args`. DOC is the target's document when it has one, else the active document. TARGET is one line: | Location | TARGET | | --- | --- | | editor | `editor VERSION L1 C1 L2 C2`: the document's version and the selection (one-based line and byte column of its start and end) after the right click placed the cursor | | explorer | `file PATH`, `folder PATH`, or `root PATH` for the empty area (the project folder) | | tab | `tab doc DOC PATH` (`-` for an untitled document), `tab image PATH`, `tab view VIEW`, `tab settings`, `tab git`, `tab extensions` | | terminal | `terminal N`, N the one-based terminal tab | | extension | `extension` | | editor_title | as `tab`, for the active tab | | view_title | `view VIEW` | | view_item, view_item_inline | `item VIEW ID`, ID the tree row's id (the rest of the line) | `editor_title` items are icon buttons at the end of the tab strip, before which the tabs scroll: at most 3, in menu order, then `…` opening the others as a menu. A button's icon is its command's `[command-options]` `icon` (a built-in name or `ext:NAME`; a dot without one), hovering shows the command's title, a click runs it at once. `view_title` and `view_item_inline` items are drawn the same way in a view's header and on a tree row; `view_item` items make a tree row's context menu. For these the key `view` is the view (`OWNER/NAME.KEY`) and `viewItem` the row's context value. A command that no longer exists when its item is clicked shows "This command is no longer available". Headless controls: `print-menu` lists an extension's rows as `LABEL [OWNER/NAME]` and submenu rows with a trailing ` >`; `menu-pick LABEL` clicks a row; `print-contrib-problems EXT` lists the dropped entries as `problem=[SECTION] KEY: TEXT`; `print-title-buttons` lists the tab strip's buttons as `button EXT.NAME at=X,Y,W,H` and `more at=X,Y,W,H`; `view-item-menu VIEW ID [CONTEXT]` opens a tree row's menu at the mouse. ## Feature: `status-items` Status bar items: up to 8 per extension (manifest and runtime together; v1's `status` text is not counted), left or right of the status bar, with text, icons, a tooltip, a color, a `when` clause and a command a click runs. | Request | Reply | Effect | | --- | --- | --- | | `ID status-item ITEM LEN` + body | `ok ID` | adds or replaces item ITEM (1 to 40 of `[a-z0-9_]`) | | `ID status-remove ITEM` | `ok ID` | removes it; a manifest item is hidden until the program stops; an unknown ITEM changes nothing | ``` ALIGN PRIORITY TEXT_LEN TOOLTIP_LEN EXTRA_LEN LF ``` ALIGN is `left` or `right`; PRIORITY −1000 to 1000, higher further left on both sides (ties: the extensions' order, then the item's name); TEXT one line of UTF-8 without control characters, at most 120 bytes; TOOLTIP at most 500 bytes, may hold line breaks. The three lengths must use the body exactly. EXTRA holds records, each `NAME ARGS... LEN` + LEN bytes, unknown ones skipped: `command NAME ARGS_LEN` + ARGS (a command reference), `color NAME 0`, `background NAME 0` (`error` or `warning`), `when LEN` + the clause. Colors are `fg`, `muted` (the default), `accent`, `error`, `warning`, `success`. A bad body or record is `syntax` and changes nothing; a ninth item is `toobig 8 items`. Without the agreed feature both requests return `unknown`. In TEXT, `$(NAME)` is an icon: a built-in name or `ext:NAME` from the manifest's `[icons]`; any other `$(...)` stays text; at most 4 icons are drawn. Built-in icons: `chevron-right chevron-down chevron-up folder file close search spark dot plus minus check terminal back user arrow-up arrow-down refresh sync branch discard file-plus folder-plus sliders play stop debug bug warning error info bell gear edit trash eye pin lock copy filter list beaker cloud more extensions`. Together the items take at most 40 % of the status bar; the lowest priorities are dropped first, and one item's content is cut at 240 logical pixels. Right items stand left of the updater's item, the lowest priority rightmost; left items follow the cursor position, the highest priority leftmost, as far as the file's items leave room. Hovering an item shows its tooltip; a click runs its command with FROM `ref` and the reference's ARGS (an item without a command does nothing). Runtime items are removed when the program stops. Manifest items show while the extension is installed and enabled, running or not; their command must be one of the extension's own commands, and a click starts the program: ```ini [status] # ITEM.FIELD: text tooltip command args align (left|right) priority color background when tasks.text = $(play) Tasks tasks.tooltip = Run a task of this project tasks.command = run_task tasks.align = left tasks.priority = 20 tasks.when = projectOpen [icons] # NAME = PNG in the extension's folder, used as ext:NAME in status items, menus and buttons logo = icons/logo.png ``` An `[icons]` NAME is 1 to 40 of `[a-z0-9_-]`, at most 32 per extension; the PNG at most 65536 bytes and 256 pixels a side. A PNG whose pixels are all grey is drawn as a mask in the text's color, any other as it is. v1's `status` text is the item `_v1` (right, priority 0, muted, no command) with or without the feature. Headless control: `print-status` prints a line per item: `side=left|right prio=N owner=OWNER/NAME item=ITEM text=TEXT tooltip=TOOLTIP command=NAME shown=0|1 at=X,Y,W,H`. ## Language configuration How the editor types, indents and comments a language. The same keys are read from a grammar (a `.syn` file: built-in, `~/.config/rhun/syntax/`, an extension's `syntax/`) and from a manifest `[language.NAME]` section for a grammar that exists (NAME is the grammar's name, `_` for a space: `[language.Plain_Text]`). The grammar keys `comment`, `toggle_comment`, `block`, `ident` (extra word characters) and `colon_indent` (`:$` in `indent_open`) keep their meaning and may be set in `[language.NAME]` too. | Key | Value | Without it (the behaviour before these keys) | | --- | --- | --- | | `brackets` | two-byte pairs Match brackets outlines, at most 16 | `() [] {}` | | `autoclose` | OPEN CLOSE token pairs, space separated, each 1 to 8 bytes, at most 16 pairs | `( ) [ ] { } " " ' ' `` ` `` ` `` | | `autoclose_code` | OPEN tokens that close only outside strings and comments | `" ' `` ` `` | | `surround` | one-byte OPEN CLOSE pairs typing OPEN wraps a selection in | the one-byte `autoclose` pairs | | `indent_open` | tokens opening a block; `^T` only as a line's first code token, `T$` only as its last | `{ ( [` | | `indent_close` | tokens closing one | `} ) ]` | | `indent_middle` | tokens closing and reopening one (`else elif`) | none | | `indent_dedent_after` | first words after which the next line is one level less (`return pass`) | none | | `continue` | line markers Enter continues (`/// //! - >`) | none | | `doc_block` | `START MIDDLE END` (`/** * */`) | none | | `fold` | `brackets` or `indent` | `brackets` | | `fold_markers` | `START END` (`#region #endregion`), after an optional line comment token | none | A token is at most 14 bytes; lists hold at most 32. A bad value is a warning in a grammar and a problem on the extension's page; that key keeps its default. **Tokens.** A line's code tokens are its words (runs of word bytes: letters, digits, `_`, every byte of a multibyte character, and `ident`) and punctuation (the configured tokens, longest first, else one byte), leaving out strings and comments; words compare exactly (ignoring case in a `case = insensitive` grammar). **Enter**, at each cursor (L the cursor's line, *before* and *after* its code tokens left and right of the cursor): 1. In a line starting, after its indentation, with a `continue` marker T followed by a blank or the line's end, the new line gets the indentation and `T `; a line holding only T loses T instead (the list ends there). After `doc_block`'s START or MIDDLE inside a comment the new line gets ` MIDDLE ` (`MIDDLE ` under a MIDDLE line); Enter between START and END puts END on its own line. 2. *net* is +1 per `indent_open` token in *before* and −1 per `indent_close` token, a leading closing token not counted and a leading middle one counted +1. 3. The new line has L's indentation and one unit more when *net* > 0, one unit less when L's first word is in `indent_dedent_after`. 4. When *net* > 0 and *after* starts with a closing or middle token, that rest goes to a line of its own at L's indentation (`{|}`), unless both are brackets that are not partners (`{|]`). **Auto-outdent.** When a line becomes its indentation and one closing or middle token (a word followed by a character that is not a word byte, or punctuation the typed character completes, or Enter after such a line), its indentation is what Enter after the previous non-blank line gives, and that line's block is deeper, the line loses one unit, in the same undo step as the character. A line aligned by hand is left alone. **Auto-close** (Settings > Editor > Auto-close brackets) inserts CLOSE when the typed character completes an OPEN, before a blank, a closer or the line's end; a quote pair (OPEN = CLOSE) not next to a word byte or the same quote; `autoclose_code` pairs not inside strings and comments. Typing a CLOSE that is next types over it; Backspace between an empty pair deletes both. **Toggle Comment** uses `block` when the language has no line comment (HTML, XML). **Merging**, per key: a user grammar's own value; else the first enabled extension, in discovery order, whose `[language.NAME]` sets it; else the grammar's; else the default. An extension setting a key another one sets is listed on both pages. Folding ranges come from a folding provider, else indentation; `fold_markers` regions (START's line to END's, nested) are ranges too. Built-in grammars set these keys for Lua, Python, Ruby, Crystal, Shell, Fish, Elixir, Julia, MATLAB, Vim script, Markdown (`continue = - * >`), Rust and C# (`///`), and C-like doc comments. ```ini [language.Lua] continue = --- indent_middle = else elseif ``` Headless control: `print-langconf` prints the active document's keys, a line each: `KEY=VALUE source=default|grammar|user|ext:OWNER/NAME`. ## File icon themes An extension ships explorer icons as `icon-themes/NAME.icons` (INI, at most 256 KB) and the PNGs it names, in paths relative to that file: ```ini title = Minimal # files without an entry: this theme's file icon (default) or rhun's own icons (rhun) fallback = default [icons] # NAME = PNG [COLOR] | rhun:ICON [COLOR]; with a COLOR (red orange yellow green blue purple pink # cyan grey white accent muted) a PNG's alpha is drawn as a mask in that color of the theme file = png/file.png muted folder = png/folder.png accent folder_open = png/folder-open.png accent rust = png/rust.png cargo = rhun:config orange [files] Cargo.toml = cargo [extensions] rs = rust d.ts = typescript_def [languages] Rust = rust [folders] src = folder_src [folders_open] src = folder_src_open ``` A file's icon: `[files]` (its whole name, ignoring case), then `[extensions]` (the longest that ends the name after a dot, ignoring case), then `[languages]` (the grammar rhun gives the name), then `file`; with `fallback = rhun` a miss before `file` uses rhun's icon. A folder's: `[folders]` (closed) or `[folders_open]` (open), then `folder` or `folder_open` (`folder` when there is no `folder_open`), then rhun's folder. A PNG is at most 65536 bytes and 256 pixels a side (32 or 64 square is best); one that cannot be read shows rhun's icon. At most 512 icons and 4096 mapping lines. SVG and VS Code icon-theme JSON are not read. The theme's id is `OWNER/NAME/THEME` (THEME the file's name without `.icons`). The setting `[ui] file_icons` is `rhun` (the default), `none` (no file icons) or such an id; a missing or turned-off theme draws rhun's icons and keeps the setting. The command **Select File Icon Theme** lists rhun, None and every theme, previews the selected one in the explorer while it is open, and saves the choice. Headless control: `print-icon NAME [folder|folder-open]` prints `icon=rhun:ICON color=COLOR`, `icon=theme:OWNER/NAME/THEME:ICON` or `icon=none`. ## Feature: `tests` A test controller publishes a tree of test items; rhun keeps the tree, shows it in Testing and in the editor gutter, starts runs the user asks for, and stores their results. The controller runs its tests, usually by asking rhun to start a program as the user (`test-exec`). ### Manifest ```ini [provides] # the files this controller has tests in: it gets opened and edits for them as a provider does, # and starts when one opens, when Testing is shown, or when a test command runs tests = *_test.go *.rs # run kinds it offers besides run: debug, coverage tests.profiles = run debug coverage [needs] documents = read project = read # programs rhun may start for this extension, with the user's environment and access, during a # test run the user started (test-exec): bare names, space separated, at most 16 of 64 bytes tests = go cargo ``` The extension lists `tests` in `hello 1 ...` and sends nothing of this section before rhun agrees in `0 features`. Without agreement every request below answers `error ID unknown`. ### Items An item has an `ID` (1 to 512 bytes, no LF, CR or NUL; unique within the extension and stable across sessions), a kind, an optional range in a file, a label and flags. One body shape carries items everywhere: ``` PARENT_LEN N LF PARENT N items: KIND L1 C1 L2 C2 FLAGS ID_LEN LABEL_LEN PATH_LEN EXTRA_LEN LF ID LABEL PATH EXTRA ``` - `PARENT` empty: the controller's roots. Otherwise an existing item's id. - `KIND`: `group` (module, package, crate, folder), `file`, `suite`, `test`. - `L1 C1 L2 C2`: all `0` for no range; otherwise one-based lines and byte columns with `L1 C1` at or before `L2 C2`, in `PATH`. A range needs a path. - `FLAGS`: `-`, or a comma list of `lazy` (the item has children rhun has not been given; it asks with `tests-resolve` when the user expands it) and `nodebug` (no Debug for it). - `LABEL`: one line, at most 200 bytes. `PATH`: absolute (`/…`, `C:/…`), or `#DOC` for an open document's file, or empty. - `EXTRA`: extra records `NAME ARGS… LEN` LF and LEN bytes; unknown names are skipped. `desc LEN`: dim text after the label (one line, 200 bytes). `error LEN`: a discovery problem shown on the row (1000 bytes). - At most 10,000 items and 4 MiB per body, 50,000 items per extension, 100,000 in all (`toobig`). - A body applies whole or not at all: a malformed item is `syntax`, a bad range `badpos`, an unknown parent `refused unknown parent`, an existing item placed below itself `refused`. - Ranges are lines of the file as the controller read it: when its document is open, rhun moves them, and the places of failure messages and coverage lines, through the user's edits since they came, until the controller sends them again. ### Messages | Direction | Message | Reply | Effect | | --- | --- | --- | --- | | rhun → ext | `ID tests-resolve LEN` + PARENT id (empty: roots) | `ok ID LEN` + items body for that PARENT, or `error ID CODE TEXT` | sent for the roots once the controller agreed `tests`, and for a `lazy` item when it is expanded. The answer replaces PARENT's children and clears `lazy`; an error's TEXT shows on the row. rhun waits 30 s, then sends `0 cancel ID` and shows "no answer in 30 s" | | ext → rhun | `ID test-items MODE LEN` + items body | `ok ID` | `MODE` `replace`: PARENT's children become exactly these, in this order (an item that keeps its id keeps its results, expansion and children; the others go with their descendants); `add`: adds or updates these, the others stay. An existing id elsewhere in the tree moves under PARENT | | ext → rhun | `ID test-remove N LEN` + N ids, each ending in LF | `ok ID` | removes them and their descendants; unknown ids are ignored | | rhun → ext | `ID test-run RUN PROFILE N LEN` + N ids, each ending in LF | `ok ID 0`, or `error ID busy TEXT` / `refused TEXT` | starts run `RUN` (unique for the session) of those items and their descendants; `N` 0: everything. `PROFILE` is `run`, `debug` or `coverage` (only those the manifest offers). An error ends the run errored and TEXT is shown | | ext → rhun | `ID test-update RUN LEN` + results body | `ok ID` | results and output (below). `error ID stale run over` once the run ended; `refused` for another extension's run | | ext → rhun | `ID test-end RUN` | `ok ID` | the run is over | | rhun → ext | `0 test-cancel RUN` | | the user cancelled: stop and send `test-end` | | ext → rhun | `ID test-coverage RUN LEN` + coverage body | `ok ID` | line coverage found by this run; any number of messages, merged | | ext → rhun | `ID test-exec RUN LEN` + command body | `ok ID EXEC` | rhun starts a program for this run (below) | | rhun → ext | `0 test-out EXEC STREAM LEN` + bytes | | `STREAM` `out` or `err`: what the process wrote, as read (at most 64 KiB an event, not split at lines) | | rhun → ext | `0 test-exit EXEC CODE` | | the process ended: `CODE` its exit status, `signal N`, or `killed` (rhun stopped it: Cancel, the run ending, the extension stopping) | Runs are concurrent: at most 4 running per extension and 8 in all; more wait, queued, until a run ends. Two runs may include the same item; the latest report wins. After Cancel rhun sends `test-cancel`, stops the run's processes after 2 s (SIGTERM to the process group, SIGKILL 2 s later) and ends the run itself after 5 s. Items still queued or running when a run ends go back to the result they had before it. When the extension stops, its runs end errored ("the extension stopped") and their processes stop. rhun's own run ids for requests count with the other requests it sends (v1 section 12). ### Results body At most 1 MiB and 2,000 records: ``` N LF N records: STATE MS ITEM_LEN EXTRA_LEN LF ITEM EXTRA ``` - `STATE`: `queued`, `started`, `passed`, `failed`, `errored`, `skipped`, or `-` (output only). - `MS`: the duration in milliseconds, or `-`. - `ITEM` empty means the run itself (only `-` and `errored`, for a problem that belongs to no item such as a build that failed). A record for an unknown item is dropped and counted. - Extra records, in order: `message LEN` + text (8,000 bytes kept; may hold LF) starts a new message of this record's item (16 per item per run); `location L1 C1 L2 C2 LEN` + PATH: where the current message points; `expected LEN` and `actual LEN` + bytes (64 KiB each): the current message's values (rhun shows a diff); `output LEN` + bytes: appended to the item's output (to the run's for an empty ITEM). - rhun keeps 256 KiB of output per item per run and 4 MiB per run, then notes "[output cut]". All runs together keep at most 32 MiB of messages, values and output; the oldest finished runs are dropped first (their items keep state, duration and the first message line). Ten finished runs are kept. - The whole body is checked before anything applies (`syntax`, `toobig`). ### Coverage body At most 4 MiB a message, 20,000 files and 1,000,000 ranges per run, 1,048,576 lines per file: ``` N LF N files: PATH_LEN M LF PATH, then M records: L1 L2 COUNT LF ``` Lines `L1` to `L2`, one-based and inclusive, as the file was when the run started; `COUNT` hits (0: not run). Per line rhun keeps "some hit" and "some miss": covered, partly covered (both) or missed. The first coverage message of a new run replaces older coverage. ### Running programs as the user: `test-exec` Command body, at most 256 KiB, no NUL anywhere: ``` PROGRAM_LEN CWD_LEN ARGC ENVC LF PROGRAM CWD ARGC arguments: LEN LF bytes ENVC variables: LEN LF NAME=VALUE ``` rhun checks, in this order, and answers with the first failure: | Check | Error | | --- | --- | | the folder is not one a `rhun://` link opened and git is paused for | `refused folder not trusted` | | the body parses; at most 1,000 arguments of 32 KiB and 64 variables named `[A-Z_][A-Z0-9_]*` | `syntax`, `toobig` | | `PROGRAM` is a bare name (`[A-Za-z0-9._+-]`, 64 bytes) | `refused the program must be a bare name` | | it is a word of `[needs] tests` | `needs tests=NAME` | | the run has fewer than 4 live processes and all runs fewer than 8 | `busy` | | the user allows this extension to run programs as the user in this project: asked once per extension and project, showing the command (the request waits for the answer; one question at a time) | `cancelled` when declined, when the run ends or the extension stops; `busy a question is open` | | it is found on the user's PATH (the login shell's environment when rhun was not started from a terminal) | `nofile NAME not found` | | `CWD` (empty: the project) is an existing folder inside the project after resolving links | `refused the folder is not inside the project` | The program gets the user's environment plus the variables, the folder, input from the null device, and a process group of its own (a job object on Windows); it is not confined. rhun reads its output only while the extension's outgoing queue holds less than 256 KiB, so a chatty program waits rather than growing memory. When rhun quits, test processes are killed. Headless controls for testing: `cmd testing`, `cmd test_run_all` (and the other `test_*` commands), `test-select OWNER/NAME [ID]`, `test-expand`/`test-collapse OWNER/NAME [ID]`, `test-action run|debug|coverage|cancel`, `wait-tests`, `wait-test-items N`, `print-tests [all]`, `print-test-result OWNER/NAME ID`, `print-test-runs`, `print-coverage PATH`, `print-testing` (the Testing section's rows), `print-gutter` (the active file's test glyphs and coverage), `test-gutter LINE [right]`, `test-action goto|failure|diff|output`. rhun shows the results as well as the tree: a glyph at the first line of each `test` and `suite` with a range in an open file (its state; a click runs it), each failure message with a location as a problem with an error mark (its first line and the first lines of its expected and actual values), and a line-number tint per line of a coverage run's files. ## Terminals and tasks An extension can run programs in terminal tabs of rhun's panel (feature `terminals`) and publish tasks that rhun lists, runs, and turns into problems (feature `tasks`). The programs run as the user, outside the extension's sandbox. Each run stays visible as a tab. ### Manifest: `terminal` ```ini [needs] # suggest (= v1's yes): propose a line for your terminal, which runs when you press Enter # run: also run programs in terminal tabs, outside the limits above, once allowed per project # input: also type into the terminals it started; output: also read what they show terminal = run ``` Each level includes the ones before it. The install dialog and the page show them in the warning color: run is "run programs in terminal tabs, without the limits above, after you allow it in a project", input adds "and type into them", output adds "and read what they show, including what you type there". A 1.0 host reads `run`, `input` and `output` as `no`. With `run`, v1's `cmd` also takes `run_task`, `run_build_task`, `run_test_task`, `rerun_last_task`, `restart_task`, `stop_task` and `show_task` (below `run`: `needs terminal=run`). **The approval.** The first program an extension starts in a project (`terminal-open`, `terminal-restart`, `task-start`, `task-run`, or the user picking one of its tasks) opens a dialog: "Let TITLE run programs in PROJECT?" with the exact command (shell quoting, the middle elided past 96 bytes, "and N tasks it depends on" when it has dependencies) and its folder. **Allow** runs it and remembers the extension and project: later runs do not ask. Cancel answers `cancelled` and remembers nothing. One question at a time (`busy` meanwhile); `cancel ID` closes an open question (`cancelled`). The extension's page lists "Runs programs as you in:" with **Forget**. The approvals live in `extensions.ini` (`allow_run = /abs/project` lines, at most 64 per extension, `-` without a project), where the extension cannot write. `test-exec` and the debugger's adapters ask the same question and share the approval. ### Definitions `terminal-open`, `tasks-set` and `task-run` carry definitions: a header line, its byte fields, then optional records. ``` TASK_ID FORM LABEL_LEN CMD_LEN CWD_LEN EXTRA_LEN LF