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.

(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.

(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.

(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.

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.