# REPL examples These are real calls from recent Sidecat development coordination. Each one ran in a prepared working REPL environment, so each lists the variables and helpers it expects to find there. Sidecat Lisp is its own language. The Clojure grammar is used here only to color the code. ## Select Messages and keep two fields **What it does.** Picks two Messages out of a list by their sequence numbers. For each one it returns only the sequence number and the related item. **Prerequisites.** `coordination-team-messages` already holds a list of Messages read from a team room. ```clojure (map (fn [m] {:sequence (get m :sequence) :related (get m :related)}) (filter (fn [m] (or (= (get m :sequence) 1984) (= (get m :sequence) 1982))) coordination-team-messages)) ``` **How it works.** `filter` keeps the Messages whose sequence is 1984 or 1982. `map` then builds a small map from each kept Message. The result is printed; the list stays as it was. ## Read the Note behind each Message **What it does.** Reads the Content Note that each Message points to. A Note that cannot be read is kept in the result as a failure, next to the ones that could be read. **Prerequisites.** `coordination-team-messages` already holds a list of Messages read from a team room. ```clojure (def coordination-team-rows (map (fn [m] {:sequence (get m :sequence) :content (get m :content) :note (sidecat/try-call "content.note.read" {:content (get m :content)} {:input_mode "domain"})}) coordination-team-messages)) ``` **How it works.** This makes one Note read for each Message. `sidecat/try-call` returns a failure as a value instead of stopping the evaluation, so one unreadable Note does not abort the rest. A successful read looks like `{:ok true :value RESULT}` and a failed one like `{:ok false :error FAILURE}`. `def` stores the rows under the name `coordination-team-rows` for later steps. Running this again repeats every read. ## Remember the last sequence received **What it does.** Records the sequence number of the newest Message, so the next read can start after it. **Prerequisites.** `coordination-team-messages` holds the Messages from the latest read, with the newest one last. `coordination-team-last-read` was defined by an earlier step. ```clojure (def coordination-team-last-read (if (> (count coordination-team-messages) 0) (get (get coordination-team-messages (- (count coordination-team-messages) 1)) :sequence) coordination-team-last-read)) ``` **How it works.** When the list has at least one Message, the new value is the sequence of the last Message in it. When no Messages arrived, the old value is kept. The value lives in the named working environment, so a later call in the same environment can use it. ## Post a Note to a team room from the shell **What it does.** Calls a shared Lisp function, `team-post-note`, that writes a Note, lets the named readers read it, and posts it to a room. **Prerequisites.** The environment `root-development-coordination-20261001` exists and has `team-post-note` in it. Both belong to the Sidecat development team; another node has them only if someone prepares them there. The shell variable `native_ui_communication_input` holds one JSON object with the title, text, readers and room. ```bash sidecat repl call team-post-note \ "$native_ui_communication_input" \ '"ui-communication-future-design-20261003"' \ --environment root-development-coordination-20261001 \ --json ``` **How it works.** The command is shown on several lines for reading; it runs as one command with the same arguments. `sidecat repl call` passes each argument to the function as one complete JSON value. The first argument is the JSON object in the shell variable. The second is a JSON string, which is why it has double quotes inside single quotes. `--environment` selects the named environment instead of the prepared default. `--json` includes the printed value and a JSON form of it in the reply. Inside the function there are three steps: put the Note, grant each explicit reader, post the Note. The function uses `reduce` to carry the grant results forward and to stop at the first grant that fails. The steps are separate calls, so a step that fails leaves the earlier ones in place. In the words of the installed help, "A failed call does not roll back host operations already performed." ## Sharing and discovery These commands exist today for finding and reusing methods. The descriptions follow the installed `sidecat repl` help. - `sidecat repl list` discovers shared methods in your prepared organization, with parameter shapes, descriptions, dependencies and import commands. Listing does not adopt them or open local scratch, and it does not report who adopted or ran a method. - `sidecat repl source NAME` reads the retained source of a shared helper. The read does not evaluate, import, keep or reopen anything. - `sidecat repl use NAME` imports a shared method into your working environment. Importing does not run the method. Plain use stays scratch-only; `sidecat repl use --keep NAME` imports it and keeps it for reopen and restart. - `sidecat repl keep` saves selected local definitions and their dependencies for reopen and daemon restart. It does not share them with the organization. - `sidecat repl share` exports a live method and its dependencies to the prepared organization. Sharing does not keep your workspace or update copies others already adopted. Run any of them with `--help` for inputs and examples. ## Adding an example All examples live in one Markdown file, `static/repl-examples.md`, in the website repository. To add one, add a section to that file with these parts, in this order: 1. A short heading that says what the example does. 2. **What it does.** One or two sentences on the outcome. 3. **Prerequisites.** The variables, helpers and environment that must already exist. 4. The code, in a fenced block marked `clojure` for Sidecat Lisp or `bash` for a shell command. Use an extract from a real call. Remove anything private. 5. **How it works.** A short explanation, including what is not guaranteed. Then send the change through normal documentation review and publication, like any other page. Examples are added by hand when one is worth sharing. There is no recurring job that collects them.