Commands & composition

Command lookup checks built-ins, macros, struct constructors and members, named functions, then PATH. External programs are started directly, without passing the expression through another shell. The command name may also come from a text variable, as in ($EDITOR file.txt); its value is one program name, without implicit splitting into flags.

Command heads accept text, function values, and explicit command references. Numeric, boolean, and nil heads are not callable, including values read from variables. Use str to explicitly construct a text command name. int, float, and bool are reserved builtins.

map constructs a map. Its built-in operations are map/get, map/set, map/del, map/has, map/keys, map/vals, and map/len; all take a map value first, such as $config or {name parsh}. Updates return new maps; use set to replace a variable’s value. See maps for signatures and examples.

Use type to inspect command lookup without executing the command:

(type type cd echo)
(defn greet (name) (echo hello $name))
(type greet)
(type -a echo)
(let kind (type -t greet))
(if (type -t optional-tool) (optional-tool))

type accepts multiple names, including list arguments, and supports these Bash-style options:

-a: show every match, including all executable paths in PATH order.
-t: print builtin, macro, struct, function, or file for each match.
-p: print the external command path, or nothing for a built-in, macro, struct, or function.
-P: search PATH even when a built-in or function has the same name.
-f: skip function, macro, and struct lookup.

Options can be combined; -- ends option parsing. No arguments succeeds silently. An unknown name gives status 1; an invalid option gives status 2. Output supports capture and redirection. In the browser playground, external commands are reported by the host’s available command names; -p and -P return those names.

(echo (pwd))
(| (find . -name "*.rs") (sort))
(|> files.txt (| (find . -name "*.rs") (sort)))
(|>> log.txt (echo another entry))
(<| input.txt (sort))
(|2> errors.txt (grep needle missing.txt))

The operators are:

|: connect external commands in a pipeline.
|>, |1>: create or truncate a file and redirect stdout.
|>>, |1>>: create or append a file and redirect stdout.
<|: read stdin from a file.
|2>: create or truncate a file and redirect stderr.
|2>>: create or append a file and redirect stderr.

Redirection always takes the path first and an expression second. Wrappers can nest and can enclose an entire pipeline. Pipeline stages in v1 must be external command calls; functions and state-changing built-ins run outside pipelines.

For example, write stdout to a fresh log and append stderr to another:

(|1> output.log
  (|2>> errors.log
    (make)))

Top-level commands stream output immediately. When an external command or pipeline is used as a value, stdout is captured as UTF-8, trailing LF characters are removed, and the result stays one argument. Stderr keeps its existing destination. Use a pipeline or file redirection for binary output. Explicit redirection takes precedence over capturing that expression’s output.

For complete results, raw-byte capture, $?, exceptions, and background execution, see execution results and tasks.