Script mode (rat run)

The script declares > main[args]. args is a Rat array of strings — the CLI command and the script path are stripped before binding, so rat run hello.rat one two hands main ['one', 'two']. << N returns the exit code.

> main[args]
log('hello from rat run', args)
<< 0

Output (stdout):

hello from rat run [one, two]

Any integer returned via << becomes the process exit code (clamped to a byte). A non-int return — or no return at all — falls through to 0. Use this to signal pass / fail to whatever shell or CI step invoked the script.

> main[args]
(len(args) == 0)
    error('usage: rat run check.rat <name>')
    << 2
log('checking', args[0])
<< 0

In script mode log(...) and debug(...) write to stdout; error(...) writes to stderr. Pipe stdout to a log file while errors still show on the terminal, exactly as you'd expect from a normal CLI tool.

> main[args]
log('processing', len(args), 'items')
[a] in args
    (a == '')
        error('skipping empty arg')
    log(' ->', upper(a))
<< 0

Top-level > server declarations and > name[params] functions are available to main, exactly like a page handler. Use them to factor a script the same way you'd factor a page: state at the top, helpers below, main at the bottom.

> server
greeting: 'hi'

> shout[s] >> upper(s)

> main[args]
log(shout(greeting), '— args:', args)
<< 0

A > service [name] declared in the script is a singleton for that run. Methods share their state frame; reads from outside the service see the live values. Drop a counter, a registry, or any other "carry state across helpers" piece into a service and call it the usual way.

> service [counter]
n: 0
bump[]
    n << n + 1
    << n

> main[args]
log(counter.bump())   # 1
log(counter.bump())   # 2
<< 0

Script mode refuses > page, > session, > local declarations at load with a script-mode hint. These tiers exist because a browser is on the other end of the wire; without one, there's nothing to react against. Move shared state to > server or a service.