API reference¶
This page documents selected APIs from the root loom package and the core
and feature packages used in the examples. It is not an exhaustive export
listing. Feature-package APIs are documented in reference/api/features.md.
Root package exports are declared in
src/package-exports.lisp;
core and feature package exports are declared beside their package sources.
Line and column numbers throughout are zero-based; a
(line . column) pair denotes a position between characters, exactly like
Emacs point, so end positions in a region are exclusive.
Application¶
These symbols from loom/application expose the command-specification and
keybinding layer used by the editor's interactive commands.
%selected-window¶
Return the currently selected window for application-level command code.
%selected-buffer¶
Return the buffer displayed by the selected window.
%editor-buffers¶
Return the buffers registered with the current editor state.
%register-buffer¶
Register a buffer with the current editor state.
%unregister-buffer¶
Remove a buffer from the current editor state's registry.
%order-region¶
Normalize two buffer positions into start and end order for a region.
with-prompts¶
Execute a command body with the editor's prompt helpers bound for interactive input.
command-spec¶
The command specification type used by the command registry.
define-command-specs¶
Define or replace command specifications in the declarative command catalogue.
define-command-spec-catalog¶
Compose command specifications from predeclared grouped catalog variables.
*command-specs*¶
The variable holding the currently registered command specifications.
command-completion-candidates¶
Return command names available for extended-command completion.
find-extended-command¶
Return the registered command for its interactive name, or NIL if none matches.
Lookup trims spaces and tabs and ignores case; it does not return the command
specification.
defkeys-single-chord-p¶
Return true when a key definition describes one chord rather than a sequence.
defkeys-chord¶
Convert one command-spec chord to a runtime key descriptor, a
(modifiers . code) cons. Supported modifiers are :control and :alt.
defkeys-key-sequence¶
Convert a single chord or a sequence of chords to a list of runtime key descriptors. Neither converter installs keymap bindings.
install-default-keybindings¶
Install loom's default command bindings into the supplied editor keymap.
Buffer¶
make-buffer¶
Create and return a new, empty-undo-history buffer. name defaults to
"*scratch*"; path associates the buffer with a file for buffer-save
without performing any I/O; initial-content seeds the buffer's text.
buffer-p¶
Return true when object is a loom buffer.
buffer-name¶
Return buffer's display name, as a string.
buffer-path¶
Return the pathname/namestring buffer is associated with, or nil when no
path is associated. make-buffer can associate a path without loading or
saving a file.
buffer-major-mode¶
Return the major-mode identity associated with buffer, initially
:fundamental. The core stores this identity without interpreting it;
feature packages provide its semantics.
buffer-set-major-mode¶
Store mode as buffer's major-mode identity and return buffer.
buffer-truncate-lines¶
Return buffer's line-display preference: t to truncate long lines, nil to
wrap them, or :default to follow the major mode. Resolving :default to a
boolean needs mode metadata, so use
loom/feature/mode:buffer-truncate-lines-p for the answer a renderer wants.
buffer-set-truncate-lines¶
Set buffer's line-display preference to t, nil, or :default, and return
buffer. The setting belongs to the buffer rather than a window, so the same
file shown in two windows cannot disagree with itself. It is not persisted in a
session.
buffer-text¶
Return buffer's entire contents as a single string, including internal
newlines between lines.
buffer-line-count¶
Return the number of lines in buffer, always at least 1 (an empty buffer
has one empty line).
buffer-line¶
Return the text of line-number in buffer, with no trailing newline.
Signals an error if line-number is out of range.
buffer-point-line¶
Return the zero-based line number of buffer's point.
buffer-point-column¶
Return the zero-based column (in characters) of buffer's point on its
current line.
buffer-set-point¶
Move buffer's point to (line, column), clamping an out-of-range position.
Returns buffer.
buffer-mark¶
Return the position of buffer's mark, or (values nil nil) if no mark is
set.
buffer-set-mark¶
Set buffer's mark to (line, column), clamped. Returns buffer.
buffer-insert-string¶
Insert string into buffer at point, moving point to just after it. Marks
buffer modified, records undo information, and clears any explicit redo
history. Returns buffer.
buffer-delete-char¶
Delete a single character adjacent to point: the character before point
(Backspace) when backward is true, otherwise the character at/after point
(Delete). A no-op at a buffer boundary. Returns buffer.
buffer-delete-region¶
Delete the text between the two positions (end exclusive), clamped to the visible region. The end must not precede the start. A nonempty deletion moves point to the clamped start; an empty range leaves point and undo history unchanged. Returns the deleted text as a string. Read-only buffers signal an error even for an empty range.
buffer-region-string¶
Return, without modifying buffer, the text between the two positions (end
exclusive).
buffer-modified-p¶
Return true if buffer has unsaved changes since it was created, loaded, or
last saved.
buffer-read-only-p¶
Return true when buffer rejects text mutations, including undo and redo.
buffer-set-read-only¶
Set whether buffer rejects text mutations and return buffer. The interactive
C-x C-q command toggles this state for the selected buffer.
buffer-mark-saved¶
Mark buffer as saved and return buffer.
buffer-mark-modified¶
Mark buffer as modified and return buffer.
buffer-offset¶
Convert a zero-based line and column in buffer to its zero-based character
offset.
buffer-position-line¶
Return the line component of a buffer position.
buffer-position-column¶
Return the column component of a buffer position.
make-buffer-span¶
Create a span from the zero-based character offsets start and end.
buffer-span-start¶
Return the start offset of span.
buffer-span-end¶
Return the exclusive end offset of span.
buffer-point-offset¶
Return buffer's point as a zero-based character offset.
buffer-offset-position¶
Convert offset to the corresponding zero-based line and column position in
buffer.
buffer-undo¶
Undo the most recent change group in buffer, Emacs ring-style: repeated
calls keep walking back through history, and once exhausted further calls
are a no-op. Returns buffer.
buffer-redo¶
Redo the most recently explicitly undone change group in buffer. A normal
edit clears the explicit redo history. Returns buffer.
buffer-record-undo-boundary¶
Record an undo boundary, so edits before and after this call belong to
distinct groups that buffer-undo steps between independently. Returns
buffer.
buffer-load¶
Read the file at path and return a new buffer whose buffer-path is
path, initial text is the file's contents, and buffer-name is derived
from the filename. A file that is not writable is loaded as a read-only buffer.
buffer-save¶
Write buffer's contents to buffer-path. Signals an error if buffer has
no associated path or is read-only. Clears buffer-modified-p on success.
Returns buffer.
Renderer¶
make-loom-renderer¶
Create and return a new loom renderer backed by a cl-tty-kit screen and
double-buffered diff renderer of the given width/height (terminal
columns/rows).
loom-renderer-width¶
Return the renderer's current width in terminal columns.
loom-renderer-height¶
Return the renderer's current height in terminal rows.
loom-renderer-string-width¶
Return the terminal display width of string.
loom-renderer-truncate-string¶
Return string truncated to at most width terminal columns.
loom-renderer-clip-index¶
Return (values index leading-blank) for the first character of string fully
visible past start-column terminal columns. leading-blank is 1 when a
full-width character straddles start-column, since half a character cannot be
drawn and that cell is left empty.
loom-renderer-wrap-segments¶
Return the (start . end) character ranges that fill successive width-column
rows, always at least one, never ending inside a full-width character.
loom-renderer-segment-cells¶
Return how many terminal columns into segment the character column sits.
This is the goal column a vertical move carries between wrapped rows.
loom-renderer-segment-column¶
Return the character column cells columns into segment, clamped to the
segment's end.
loom-renderer-write-string¶
Write string into the renderer's back buffer at terminal position (x, y).
loom-renderer-draw-horizontal-line¶
Draw a horizontal separator of width cells at (x, y).
loom-renderer-draw-vertical-line¶
Draw a vertical separator of height cells at (x, y).
loom-renderer-clear¶
Clear the renderer's back buffer and return renderer.
loom-renderer-draw-buffer¶
Draw buffer's currently visible region into renderer's screen, occupying
the rectangle at (x, y) sized width by height. Does not flush to a
terminal. Returns renderer.
loom-renderer-present¶
Flush renderer's pending screen diff to stream (defaults to
*standard-output*), positioning the cursor at cursor when supplied.
Returns renderer.
loom-renderer-resize¶
Resize renderer's underlying screen and renderer to width/height.
Returns renderer.
Keymap¶
make-keymap¶
Create and return a new, empty keymap. When parent is supplied, lookups
fall through to that keymap. A locally defined first chord shadows the
corresponding parent subtree, so a mode can replace a complete prefix while
the rest of the global bindings remain available.
keymap-define-key¶
Bind key-sequence (a list of key-event descriptors) to command, a
zero-argument function designator invoked against *editor-state*. A
sequence that is a strict prefix of another bound sequence implicitly
becomes a prefix key. Returns keymap.
keymap-lookup¶
Look up key-sequence in keymap. Returns the bound command, the keyword
:prefix if key-sequence is a strict prefix of one or more bindings, or
nil.
make-keymap-state¶
Create and return a new dispatch state for keymap that tracks in-progress
prefix-key accumulation across successive keymap-state-dispatch calls.
keymap-state-sequence¶
Return the key-event sequence currently accumulated by state.
keymap-state-dispatch¶
Feed one key-event into state: returns :pending while accumulating a
prefix key, invokes and returns the bound command's value once a complete
sequence resolves, or returns nil and resets on an unbound sequence.
The input dispatcher layers the selected buffer's major-mode keymap over the editor's top-level keymap before dispatching each event. This keeps global bindings available while allowing a mode-local binding to take precedence.
Minibuffer¶
make-minibuffer¶
Create and return a new, inactive minibuffer. history, when supplied, is a
cl-history-kit history object driving Up/Down recall while active.
minibuffer-active-p¶
Return true if minibuffer is currently prompting for input.
minibuffer-prompt-string¶
Return minibuffer's current prompt text, or nil when inactive.
minibuffer-input-string¶
Return the text typed into minibuffer so far, or "" when inactive.
minibuffer-activate¶
(loom:minibuffer-activate minibuffer prompt
&key on-confirm on-cancel on-change on-key
completion-function)
Begin an interactive input session, displaying prompt. on-confirm is
called with the final input string on confirm (e.g. RET); on-cancel on
cancel (e.g. C-g). on-change is called with the current input after every
edit to it, which is what lets a prompt act while it is still being typed
rather than only at RET. on-key is called with each key event before it is
classified, and consumes the event by returning true. That is how a caller
keeps a chord like C-s from being typed into the input. Returns
minibuffer.
minibuffer-set-prompt¶
Replace an active minibuffer's prompt without disturbing its input. A prompt
that reports state cannot use minibuffer-message for it, because the message
line is the same screen row the active prompt occupies. Inactive minibuffers
ignore this.
minibuffer-complete¶
Complete the active minibuffer input against candidates and return
minibuffer.
minibuffer-handle-key¶
Feed one key-event to an active minibuffer: characters append to the
input, Backspace/Delete edit it, Up/Down recall history, RET confirms, C-g
cancels. A no-op when inactive. Returns minibuffer.
minibuffer-message¶
Display text as a transient status message; unlike minibuffer-activate,
does not solicit input or affect minibuffer-active-p. Returns minibuffer.
minibuffer-message-string¶
Return the current transient status message, or NIL when none is active.
minibuffer-history-entries¶
Return the minibuffer's recalled input strings in newest-first order as a serializable list.
minibuffer-set-history-entries¶
Replace the minibuffer's recalled input strings with the newest-first list of
strings in entries. Signals an error when entries is not a proper list of
strings.
Window¶
make-window-tree¶
Create and return a new window tree with a single, initially selected
window displaying initial-buffer over the full width by height area.
window-tree-windows¶
Return a list of every leaf window in tree, in stable order.
window-tree-selected-window¶
Return tree's currently selected (focused) window.
window-tree-layout¶
Return the serializable layout description of tree.
make-window-tree-from-layout¶
Reconstruct a window tree from layout, whose leaf nodes contain the buffers
to display.
window-tree-selected-index¶
Return the index of the selected leaf window in tree.
window-tree-select-index¶
Select the leaf window at index and return it.
window-tree-width¶
Return tree's width in terminal columns.
window-tree-height¶
Return tree's height in terminal rows.
window-split¶
Split window into two along direction (:horizontal, i.e. C-x 2, or
:vertical, i.e. C-x 3); both initially show the same buffer. Selection
moves to the new window, which is returned.
window-select-next¶
Select the next window in tree, cycling back to the first after the last
(C-x o). Returns the newly selected window.
window-delete¶
Delete window from tree when another leaf can remain selected, then
return the selected window. If window is the only leaf, leave the tree unchanged
and return that window.
window-delete-other-windows¶
Remove every leaf except window, select it, and return that window.
window-buffer¶
Return the buffer currently displayed in window.
window-set-buffer¶
Display buffer in window (C-x b), replacing what it previously showed.
Returns window.
window-x¶
Return window's left edge, in terminal columns, relative to its tree's
origin.
window-y¶
Return window's top edge, in terminal rows, relative to its tree's origin.
window-width¶
Return window's width in terminal columns.
window-height¶
Return window's height in terminal rows.
window-scroll-line¶
(loom/core/window-tree:window-scroll-line window)
(setf (loom/core/window-tree:window-scroll-line window) line)
Return or set window's zero-based first visible buffer line.
window-scroll-column¶
(loom/core/window-tree:window-scroll-column window)
(setf (loom/core/window-tree:window-scroll-column window) column)
Return or set window's leftmost visible screen column. This counts terminal
cells rather than buffer characters, so it stays comparable with the two cells
a full-width character occupies. Unlike window-scroll-line it is not part of
window-tree-layout, so restoring a session resets the horizontal offset to
0 while preserving the saved vertical scroll line.
window-scroll-sub-row¶
(loom/core/window-tree:window-scroll-sub-row window)
(setf (loom/core/window-tree:window-scroll-sub-row window) row)
Return or set which wrapped segment of window-scroll-line occupies the
window's first row. Only a wrapping buffer leaves it at anything but 0, and
like window-scroll-column it is transient rather than part of
window-tree-layout.
window-tree-resize¶
Resize tree to width/height, re-laying-out every window
proportionally. Returns tree.
The following interactive window commands use loom:*editor-state* and take
no arguments.
split-window-below¶
Split the selected window horizontally and return the new selected window.
split-window-right¶
Split the selected window vertically and return the new selected window.
other-window¶
Select the next window in the current window tree and return it.
delete-window¶
Delete the selected window and return the remaining selected window. If it is the only window, leave it unchanged.
delete-other-windows¶
Keep only the selected window and return it.
switch-to-buffer¶
Prompt for a registered buffer's name and display it in the selected window.
kill-buffer¶
Prompt for a buffer's name and remove it from the editor's registry, replacing it in windows displaying it. A modified buffer prompts for discard or cancellation, and for saving when it has an associated path.
File tree¶
make-file-tree¶
Create and return a new file tree rooted at root-path; initially not
visible, every directory starts collapsed. Its default child lister performs
no filesystem access and returns no children; install a lister to populate it.
file-tree-child-lister¶
Return the function used to provide tree's direct children. The function
accepts one path and returns (child-path . kind) conses.
file-tree-install-child-lister¶
Install lister as tree's child provider and return tree. This is the
composition boundary between the pure file-tree state and filesystem or
cached directory data.
file-tree-prefetch-paths¶
Return the root path followed by the currently expanded directory paths. The concurrent file-tree runtime uses this list to decide which directories to prefetch.
file-tree-visible-p¶
Return true if tree's sidebar is currently shown.
file-tree-toggle¶
Toggle whether tree's sidebar is shown. Returns the new visibility state.
file-tree-entries¶
Return the flattened list of currently visible entries in tree, respecting
expand/collapse state, as (path . depth) conses in display order.
file-tree-entry-kind¶
Return :file or :directory for a currently reachable entry in tree, or
nil if the path is not reachable. Collapsed directories are not searched.
file-tree-selected-path¶
Return the path of tree's currently selected entry, or nil.
file-tree-move-selection¶
Move tree's selection cursor by one visible entry in direction (:up or
:down); a no-op at either end. Returns the newly selected path.
file-tree-toggle-expand¶
Toggle the expand/collapse state of the directory at path. Signals an
error if path is not a directory in tree. Returns the new expanded-p
state.
file-tree-create-file¶
Create a new, empty regular file through *loom-filesystem*. Signals an error
if path already exists and returns path.
file-tree-create-directory¶
Create a new, empty directory through *loom-filesystem*. Signals an error if
path already exists and returns path.
file-tree-rename¶
Move or rename the entry at old-path to new-path through
*loom-filesystem*. Signals an error if old-path is missing or
new-path already exists, and returns new-path.
file-tree-delete¶
Delete the file or directory at path recursively through the filesystem
dispatch. Signals an error if path does not exist and returns tree.
These mutations use the direct native path only with the real filesystem and a wild pathname; other paths use the CL-BOUNDARY-KIT or CL-HOST-KIT boundary.
loom-fs-list-directory¶
List path's direct children as (child-path . :file-or-:directory)
conses, via cl-host-kit. This is the infrastructure lister used for real,
disk-backed sidebar listings. Directories precede files, and each group is
sorted by namestring. Symbolic links and other special entries are omitted.
The following interactive file commands use loom:*editor-state* and take
no arguments. Paths are read from the minibuffer when needed.
toggle-file-tree¶
Toggle the current editor's file-tree sidebar and return the new visibility state.
file-tree-select-next¶
Select the next visible file-tree entry and return its path.
file-tree-select-previous¶
Select the previous visible file-tree entry and return its path.
file-tree-open-selected¶
Open the selected file or toggle the selected directory's expansion.
file-tree-create-file-command¶
Prompt for a path and create a file.
file-tree-create-directory-command¶
Prompt for a path and create a directory.
file-tree-rename-command¶
Prompt for a new path and rename the selected file-tree entry.
file-tree-delete-command¶
Delete the selected file-tree entry.
find-file¶
Prompt for a path and load its file into a new buffer. If the file does not exist, create an empty buffer associated with that path without writing it.
save-buffer¶
Save the selected buffer to its associated path, prompting for a path if it has none.
write-file¶
Prompt for a path and display a new buffer carrying the selected buffer's
text, point, and mark under that path. Save it unless the target already
exists; an existing target produces an overwrite warning, and C-x C-s
confirms the overwrite. The original buffer remains registered.
Auto-save feature¶
Public symbols from loom/feature/auto-save.
auto-save-path¶
Return the #file-name# sidecar pathname for a file path.
auto-save-eligible-p¶
Return true when a buffer has a file path, is modified, and is writable.
write-auto-save-file¶
Write text to an auto-save sidecar pathname without changing buffer state.
auto-save-buffer-to-file¶
Write an eligible buffer to its sidecar and leave its normal modified state unchanged.
auto-save-mode, toggle-auto-save¶
Enable or disable automatic saving globally or for the selected buffer.
delete-auto-save-file¶
Delete the sidecar for a file after a normal save. Missing sidecars are ignored.
auto-save-current-buffer, maybe-auto-save¶
Run an explicit auto-save pass or run the interval-gated pass used by the event loop.
Editor state¶
*editor-state*¶
The single, dynamically-bound editor-state struct that every command
reads and mutates. Bound by loom's entry point before any command runs, and
nil otherwise.
editor-state¶
The root state struct for one running Loom session. It holds application
services and references; slice-owned state is grouped in the editor-session
returned by editor-state-session.
make-editor-state¶
Construct an editor-state from keyword arguments. :session is required and
must contain the slices needed by omitted state values. :window-tree must be
the same object as the session's :core/window-tree slice. If :workspaces is
nil, it defaults to the session's :feature/workspace slice; if
:keyboard-macro is omitted, that value defaults to the session's
:feature/keyboard-macro slice.
editor-state-session¶
Return the editor-session envelope referenced by state. Session hooks
receive this value so slices can access their own state.
editor-state-window-tree¶
Return state's window-tree-* protocol object laying out every visible
buffer.
editor-state-workspaces¶
Return state's named workspace manager. Each workspace owns an independent
window tree over the shared buffer registry.
editor-state-minibuffer¶
Return state's minibuffer-* protocol object.
editor-state-keymap¶
Return state's top-level keymap-* protocol object.
editor-state-file-tree¶
Return state's file-tree-* protocol object for the sidebar.
editor-state-concurrent-runtime¶
Return the file-tree concurrent runtime attached to state, or nil.
editor-state-renderer¶
Return state's loom-renderer-* protocol object used to draw each frame.
register-session-hook, run-session-hooks¶
(loom/core/editor-session:register-session-hook kind owner function)
(loom/core/editor-session:run-session-hooks kind session &rest arguments)
Register and dispatch session hooks. The supported kinds include :tick,
:key-input, :input-event, :render, :terminal-modes, :before-save,
:after-save, and :buffer-close, along with the root lifecycle events
:startup, :signal, :suspend, :resume, :shutdown, and :exit-status.
Hooks run in slice-owner order and preserve registration order within an owner.
Lifecycle hooks must use the :feature/lifecycle owner. Save hooks receive the
editor-session value from editor-state-session and the saved buffer; key and
input-event hooks return :pass or :handled.
editor-state-terminal-sessions¶
Return the PTY-backed terminal sessions owned by state.
editor-state-kill-ring¶
Return state's Emacs-style kill ring: a list of killed strings, most
recent first, that C-y/M-y consume.
editor-state-buffers¶
Return the buffers currently owned by state.
editor-state-recent-files¶
Return remembered file paths in most-recent-first order. When remembering a
path, Loom uses its truename if available, otherwise its pathname namestring.
The list is bounded by loom:*editor-recent-file-limit*.
editor-state-bookmarks¶
Return the hash table of named bookmark values attached to state.
editor-path-string¶
Return the stable string representation used for recent-file and bookmark
paths, or nil when path is absent.
remember-recent-file¶
Record path at the front of the current state's bounded recent-file list.
editor-state-lsp-session¶
Return the active LSP session attached to state, or nil.
editor-state-registers¶
Return the register bank attached to state.
editor-state-keyboard-macro¶
Return the keyboard-macro state attached to state.
editor-state-isearch¶
Return the incremental-search session that is live while its prompt is up, or
nil. The renderer reads it to highlight matches, which is why it lives here
rather than inside the search command. Transient, and not persisted into a
session.
editor-state-prefix-argument¶
Return the pending prefix argument attached to state, or nil.
self-insert-command¶
Insert character into the selected buffer of *editor-state*, repeated
according to *current-prefix-argument* (one insertion when it is nil).
A zero or negative prefix inserts nothing.
*current-prefix-argument*¶
The dynamically-bound prefix argument available while a command executes.
prefix-argument-for-editor¶
Return the prefix argument attached to *editor-state*, creating one when
none is attached.
prefix-argument-action¶
Decode a key descriptor against argument. Return (kind . value) for a
universal, digit, or negative-prefix action, or nil for an ordinary key.
This function does not mutate argument.
apply-prefix-argument-action¶
Apply the decoded kind (:universal, :digit, or :negative) and value
to the prefix argument attached to *editor-state*. :digit uses value;
the other kinds ignore it. An unknown kind signals an error.
prefix-argument-value-for-editor¶
Return the numeric value of *editor-state*'s pending prefix argument.
consume-prefix-argument-for-editor¶
Return the pending numeric prefix of *editor-state*, or 1 when inactive,
and reset its prefix-argument object to the inactive state.
record-undo-boundary-for-command¶
Record an undo boundary for the selected buffer when self-insert-p differs
from the previous command's self-insert flag. Consecutive self inserts share
one undo group. Update the flag in *editor-state*.
Numeric prefix arguments¶
The following values and operations represent universal, digit, and negative prefix arguments independently of the editor-state integration above.
prefix-argument¶
The prefix-argument value type.
make-prefix-argument¶
Construct an inactive prefix-argument object with numeric value 1.
prefix-argument-active-p¶
Return true when argument represents an active prefix.
prefix-argument-explicit-p¶
Return true when the prefix was explicitly entered.
prefix-argument-value¶
Return the signed numeric value of argument.
prefix-argument-universal¶
Activate an inactive argument with magnitude 4, or multiply an active
argument's magnitude by 4. Return the mutated argument object.
prefix-argument-digit¶
Use digit as the first explicit digit, or append it to an already explicit
magnitude. digit must be an integer from 0 through 9. Return the mutated
argument object.
prefix-argument-negative¶
Activate argument if needed, toggle its sign, and return the mutated
argument object.
prefix-argument-consume¶
Return the numeric value of an active argument, or 1 when inactive, then
reset the argument object.
prefix-argument-reset¶
Reset argument to inactive with magnitude 1 and clear its explicit and
negative flags. Return the mutated argument object.
Concurrent file-tree runtime¶
The concurrent runtime is a bounded directory-listing cache built on
cl-concurrent-kit. main performs the initial root listing synchronously,
submits uncached root and expanded directories to worker threads, and applies
available results on the render lane. Generation numbers prevent a result for
an invalidated directory from replacing newer cache state. This runtime is
specific to file-tree listings; it is not a general background editor or LSP
runtime.
make-loom-concurrent-runtime¶
(loom/feature/file-tree:make-loom-concurrent-runtime
&key directory-lister (parallelism 4) (queue-capacity 64))
Create a runtime. directory-lister defaults to
loom-fs-list-directory; the worker pool has parallelism workers and a
bounded submission queue of queue-capacity. The total in-flight bound is
parallelism + queue-capacity. Returns the runtime.
loom-concurrent-runtime-directory-entries¶
(loom/feature/file-tree:loom-concurrent-runtime-directory-entries runtime path)
=> (values entries present-p)
Read the cached direct entries for path. The second value is true when a
cache entry exists, including an empty directory.
loom-concurrent-runtime-directory-error¶
(loom/feature/file-tree:loom-concurrent-runtime-directory-error runtime path)
=> (values condition present-p)
Read a cached directory-listing error for path. The second value indicates
whether an error was recorded.
loom-concurrent-runtime-prime-directory¶
Seed path's cache from a synchronous listing, advance its generation, and
clear its cached error. Returns entries.
loom-concurrent-runtime-invalidate-directory¶
Advance path's generation and remove its cached entries, error, and pending
promise. Returns the runtime.
loom-concurrent-runtime-invalidate-path¶
Invalidate path and its parent directory, then return the runtime. File-tree
mutations use this to make both a changed entry and its containing listing
stale.
loom-concurrent-runtime-prefetch¶
(loom/feature/file-tree:loom-concurrent-runtime-prefetch runtime paths)
=> (values promises accepted-count)
Try to submit uncached, non-pending paths to the bounded worker pool. Returns the promises for accepted submissions and the number accepted. A full queue, an already cached/pending path, or a shut-down runtime causes a path to be skipped rather than blocking the render lane.
loom-concurrent-runtime-drain¶
Drain all currently available worker results on the calling thread and return the number drained. Apply results from the current generation and discard older results; both count toward the return value.
loom-concurrent-runtime-shutdown¶
Stop the worker pool, close the result channel, and return runtime.
Shutdown is idempotent.
Feature APIs¶
Feature-specific public interfaces are documented in the Feature APIs reference.
CLI and commands¶
loom:main uses application name loom and the package version declared in
loom.asd. --help/-h and --version/-V are handled by cl-cli; registered
lifecycle options and file requests are parsed into an opaque startup context.
The CLI accepts loom [+LINE[:COL]] FILE...; the position applies to the first
file and later files open at line 1, column 1. With no file, the editor opens
.. There are no subcommands.
install-default-keybindings installs the command registry's bindings into
the top-level keymap. The declarative catalogue is maintained in
src/application/command-definitions.lisp, while
src/application/command-registry.lisp stores specifications, completion
candidates, and M-x lookup. The registry includes movement, editing,
search/replace, file, window, file-tree, help, keyboard-quit, and quit
commands. M-x invokes execute-extended-command, which prompts for a
command name and dispatches a registered command. The window and file-tree
command entry points above are exported by their feature packages. Use the
keymap or M-x for interactive invocation.
Entry point¶
main¶
Runtime entry point for the loom binary. It dispatches raw command-line
arguments through cl-cli and exits with the returned status. The ASDF
program-op build uses loom:main as the dumped image's :toplevel for
sb-ext:save-lisp-and-die; the build operation is separate from this runtime
function.