1. Getting started

Start the interactive shell with srsh, run a script by path, or evaluate a single expression.

srsh
srsh script.rsh one two
srsh -e "[1,2,3] |> sum"
srsh --check script.rsh
srsh -c "printf 'hello\n'"
srsh --norc

At the prompt, assignments, expressions, functions, and blocks are parsed as RSH. Other input is handled as a shell command. The editor understands multiline blocks, collections, command continuations, and bracketed paste.

2. Shell commands and jobs

These forms run commands through the shell executor:

cat *.log | grep ERROR | sort -u
make -j8 && put built
generate > output.txt 2> errors.txt
long_job &
jobs
fg %1

Implemented operators are |, &&, ||, ;, and background &. Redirections include <, >, >>, 2>, and 2>>. The shell supports process groups, jobs, fg, bg, wait %N, aliases, globbing, tilde expansion, and nested command substitution.

No-match globs stay literal. SRSH is not a Bash parser, so existing Bash scripts should still be run with Bash.

3. Values and literals

42  -12  0xff  0b1010  0o755  1_000_000
3.14159  2.5e6
yes  no  void

"hello #{name}"
'no interpolation #{name}'
[[raw text #{name}]]

[1, 2, 3]
%[name: "srsh", ready: yes]
1 .. 10
0 ..< 10

Double quoted strings interpolate full RSH expressions. Single quoted and raw strings do not. Maps use %[...]. Ranges can include or exclude the upper bound.

Member access uses value.name and indexed access uses value[index]. Safe forms return void when access cannot be completed:

host := cfg?.server?.host ?? "localhost"
first := cfg?.hosts?[0] ?? host

4. Bindings and assignment

name := "Robert"
count := 4
count += 1
name ++= "!"

$EDITOR := "vim"
home := $HOME
first_arg := $1
last_status := $?

:= creates a local in the current lexical scope. Compound assignment updates the nearest existing local. A leading $ on assignment writes the process environment. Shell commands can expand locals, environment variables, positional arguments, $?, and $!.

Tasks receive isolated copies of ordinary lists and maps. Shared mutation must use a prototype object, atom, or channel.

5. Operators and value pipelines

Operator groups, from loose to tight, are approximately:

??
or  ||
and &&
== != === !== =~ !~ in
< <= > >=
|>
.. ..<
+ - ++
* / %
**

++ concatenates strings. + is numeric unless its operands support a sensible arithmetic addition. Strict equality uses ===.

The value pipeline inserts its left side as the first argument to the call on its right:

names := glob("src/**/*.rb")
  |> map(::path => basename(path))
  |> uniq
  |> sort

6. Functions, lambdas, and tasks

fn scale(x, by := 2)
  return x * by
end

fn square(x) => x * x

double := ::x => x * 2
sum_rest := ::(head, *tail) => tail |> sum

task fetch(url)
  return cmd("curl", "-fsS", url).check().out
end

Functions are first-class values and closures capture lexical values. Parameters may have defaults and one trailing rest parameter. A task has the same parameter rules, but calling it starts work immediately and returns a task handle.

Short named functions use :: name(args) ... .::. A caret is accepted as the short spelling of return.

7. Control flow

if score >= 90
  emit "great"
else
  emit "keep going"
end

each users -> user
  = user.name
end

while pending
  work()
end

Integers are iterable, so each 3 -> i visits 0, 1, and 2. Maps yield key and value pairs. Lists and pairs can be destructured.

head, second, *rest := [10, 20, 30, 40]

? ready => emit "go"
@ users -> user => = user.name
@? pending
  work()
.@

The short block markers are ? ... .? for conditions and @ ... .@ for loops. Use break or ^!, and continue or ^>.

The original times N ... end loop and fn name arg ... end function spelling remain available for older scripts.

8. Pattern matching

match status
| 200..299 => = "ok"
| [401, 403] => = "auth"
| ? it >= 500 => = "server"
| _ => = "other"
end

Patterns may be values, ranges, lists, partial maps, prototype references, or guard expressions. The matched value is available as it in a guard. The short form begins with ?? and ends with .??.

9. Collection functions

The collection toolbox works in call form, pipeline form, and usually method form.

total := [1,2,3,4,5,6]
  .filter(::x => x % 2 == 0)
  .map(::x => x ** 2)
  .sum()

by_ext := files |> group(::path => ext(path))

File, path, string, and JSON helpers include:

10. Prototypes, traits, and objects

RSH uses prototypes with composable traits instead of class inheritance.

trait Printable
  fn show() => "#{self.name}=#{self.value}"
end

proto Counter(name, start := 0) with Printable
  slot name := name
  slot value := start

  fn inc(by := 1)
    self.value += by
    return self
  end
end

counter := Counter("requests", 10)
counter.inc()

Slot compound updates are synchronized. Reflection helpers include fields(), methods(), protoof(), is(), and clone().

11. Namespaces and modules

space build
  root := "out"
  fn artifact(name) => root ++ "/" ++ name
end

use "./lib/net.rsh" as net

= build.artifact("app")
= net.fetch(url)

A space may contain bindings, functions, tasks, prototypes, traits, nested spaces, bridges, and code declarations. use runs a file inside its own namespace. Relative paths are resolved against the importing script, and import cycles are rejected.

12. Errors and cleanup

try
  cfg := json(readfile("config.json"))
catch err
  = err.message
  cfg := %[]
finally
  audit("attempted")
end

defer rmfile(tmp)
result := attempt(:: => risky())

Caught errors provide at least .type and .message. Deferred calls and blocks run last-in, first-out when the current script or function scope exits, including on return and error. fail() raises an error and assert() checks a condition.

13. Concurrency

jobs := urls |> map(fetch)
pages := await_all(jobs)

job := &:: => expensive_io()
= job.await(2.0)

hits := atom(0)
hits.swap(::n => n + 1)

queue := chan(8)
queue.send("hello")
= queue.recv(1.0)

Task methods are await, done, status, and cancel. race(tasks) cancels losers. await_all(tasks) preserves order and cancels unfinished siblings when one fails.

parallel(values, fn, workers) uses Ruby threads and suits files, networks, and subprocess waits. pmap(values, fn, workers) uses Unix fork workers for CPU work and preserves input order.

14. Structured command values

job := cmd("git", "rev-parse", "--verify", ref)
result := job.check()
sha := result.out.trim()

Use cmd() when filenames, URLs, or other data must stay separate arguments and must not be parsed as shell text.

15. C ABI bridges

bridge libc from "libc.so.6"
  getpid() -> i32
  strlen(cstr) -> usize
  gethostname(ptr, usize) -> i32
end

buf := cbuf(256)
libc.gethostname(buf, buf.size())
= buf.string()

@self loads symbols from the current process. Supported ABI names are:

Buffer methods include size, address, ptr, read, write, string, and clear.

16. Code values and reflection

code cleanup
  rm build/tmp/cache
end

= sourceof(cleanup)
run(cleanup)

formula := "x * 3"
= eval(formula)

code ... end parses source without running it. Dynamic helpers are eval, code, run, valid, and sourceof. Introspection functions include locals, fns, protos, and traits.

17. Built-in function reference

18. Shell configuration

Shell strictness is controlled with regular shell commands:

option pipefail yes
option nounset yes
option noclobber yes
option strict yes

strict enables pipefail and nounset. It does not copy Bash set -e.

Use scheme --list, scheme NAME, plugins, and reload to manage the interactive environment. Ruby plugins are trusted code. Plugin and theme files must pass owner and mode checks before automatic loading.

Core shell commands are:

A simple theme file uses ANSI SGR values:

# ~/.srsh/themes/amber.theme
border=1;33
title=1;37
key=33
value=0;37
ok=32
warn=33
error=31
dim=90
path=33
host=36
mark=35

Ruby plugins receive the SRSH API and may register builtins, hooks, aliases, and themes. RSH plugin files run as ordinary RSH scripts.