chrysalisp-cmd-apps

name	chrysalisp-cmd-apps
display-name	ChrysaLisp CMD Apps
description	Use when writing or modifying ChrysaLisp command-line apps (cmd/*.lisp) — options, stdin/stdout, pipes, and pipe-farm parallelism.

ChrysaLisp CMD App Skill

A ChrysaLisp command app is a short-lived task in cmd/ named <name>.lisp. It takes options and paths, does work on them, and writes results to stdout. The general ChrysaLisp disciplines (see the chrysalisp skill, LLM.md, and docs/ai_digest/) apply on top of these app-specific patterns.

How CMD Apps Run

CMD apps run inside the TUI or Terminal app (apps/tui/), which uses the Pipe class from lib/task/pipe.inc:

• You type bare command names — no cmd/ prefix, no .lisp extension. Each element of the command line resolves to cmd/<name>.lisp automatically, with its remaining words passed as arguments.

• The kernel launches each task and runs its main function (via class/lisp/run.vp), so the app's entry point is (defun main ()).

• Elements are chained into a pipeline; each element's stdout feeds the next element's stdin, all via message-passing streams.

• Task distribution binders control where each stage is placed in the cluster (see LLM.md and docs/ai_digest/task_pipelines.md):

  • | (distribution): launches the next task with +kn_call_child, triggering emergent load balancing. The search starts at the previous task's node, so stages land near their data source.

  • ! (pinning): launches the next task with +kn_call_open, pinned to the exact same node as the previous task. Use it for communication-intensive stages that should share local memory.

• Example:

  files obj/vp/ | grep -v apps/ | grep -v /create | grep -v /type | trace -l

Canonical Structure

Copy cmd/template.lisp as the starting point:

(import "lib/options/options.inc")
(import "lib/task/cmd.inc")

(defq usage `(
(("-h" "--help")
"Usage: template [options] [path] ...

    options:
        -h --help: this help info.
        -j --jobs num: max jobs per batch, default 1.

    If no paths given on command line
    then will take paths from stdin.")
(("-j" "--jobs") ,(opt-num 'opt_j))
))

;do the work on a file
(defun work (file)
	(print "Work on file: " file))

(defun main ()
	;initialize pipe details and command args, abort on error
	(when (and
			(defq stdio (create-stdio))
			(defq opt_j 1 args (options stdio usage)))
		;from args ?
		(if (empty? (defq jobs (rest args)))
			;no, so from stdin
			(lines! (# (push jobs %0)) (io-stream 'stdin)))
		(if (<= (length jobs) opt_j)
			;do the work when batch size ok !
			(each (const work) jobs)
			;do the jobs out there, by calling myself !
			(each (lambda ((job result)) (prin result))
				(pipe-farm (map (# (str (first args)
						" -j " opt_j
						" " (slice (str %0) 1 -2)))
					(partition jobs opt_j)))))))

Key Patterns

• Options: The usage form is a quasiquote: the first element pairs ("-h" "--help") with the help text; each following element is (short long) ,(handler 'var) where handler is opt-flag, opt-num, or opt-str. Initialize every option variable with its default before (options stdio usage) runs — typically in the same defq — because options only overwrites what was given on the command line.

• Args and stdin: (options stdio usage) returns the remaining args; args[0] is the program name, so jobs are (rest args). When no paths are given, read them from stdin line by line.

• Self-invocation for parallelism: When the job batch exceeds opt_j, farm it out by calling yourself: build each child's command line from (first args) (the program name) plus your flags plus the job paths, and run them with (pipe-farm (partition jobs opt_j)). Results come back as ((job result) ...); print each result with prin.

• Quoting: Job paths arrive quoted; strip the surrounding quotes with (slice (str %0) 1 -2) when rebuilding command lines. Encode tricky arguments (e.g., patterns) with hex-encode and decode them on the child side (see cmd/grep.lisp).

• Cooperative scheduling: Call (task-slice) periodically in long loops (e.g., per line of a large file) so the scheduler can run other tasks.

• Output: Write results to stdout with print/prin; that is all the pipe needs.

Examples

• cmd/template.lisp: minimal starting point.

• cmd/wc.lisp: multiple flags, default-all behavior, single-file fast path.

• cmd/grep.lisp: a positional pattern argument, many modes, hex-encoded pattern passing, and both file-mode (farmed) and stream-mode (stdin) paths.