The Baron reference

The tables. For the friendly walk-through, start with the guide; for zero-page allocation in depth, see Zero page allocation.

Contents

• Command line reference
• Keyword reference
• Expression reference
• Version history

Command line reference

baron [-v | -vv] [--check] [-D <sym>=<expr>] [-p <path>] [--inf] [-o <image.ssd>] [--title <t>]
      [--opt <0-3>] [--cycle <0-99>] [--pad] [-log<n> <file>] [--symbols <file>] [--warn <n>]
      <source files>

-p and -o are the two output gates, and neither is implied: a run given neither still assembles, reports and prints (-v, PRINT, -log<n> are unaffected), but the assembled bytes go nowhere and a warning says so. --check asks for exactly that on purpose, and stays quiet.

Anything that is not a switch is a source file, and each assembles independently - a fresh symbol table per file, diagnostics reported per file as it finishes. Diagnostics go to stderr in the file:line:col: error: message shape; success is silent.

The exit code is 0 exactly when every file assembled (warnings alone stay 0). Every file is assembled even after a failure - one run reports everything - but nothing is written (no binaries, no image, no logs) unless the whole batch succeeded.

Development builds also accept baron --test [group], which runs the unit test suite.

Keyword reference

Everything is case-insensitive. Statements are separated by newlines or :; comments run from ; or \ to the end of the line.

Labels, symbols and scopes

Data

Structure and control

Sections and output

Attributes Baron acts on: org (assembly address; default: continue the enclosing section - the default section starts at 0), filename (the request to save; an empty filename is a config error), load (default org), exec (default load), cmos (truthy enables the 65C02 instruction set for this section - see the note under Reserved names), guard (an address the section's emission must not reach; overrunning it is a non-halting error reporting the overshoot - checked at each ENDSECTION, so per piece of a reopened section), transform (the name of a FUNCTION, as a string: at ENDSECTION the section's bytes, as a list of numbers, are replaced by what it returns - a list of bytes, or a string - and that is what the parent receives; the section's labels keep their untransformed addresses. It runs once every byte is final, and a change of size sends the assembly round again until the sizes settle. Not on a virtual section, and a transformed section cannot be reopened), and virtual (truthy makes the section assign addresses but keep no bytes: it cannot be saved, and its code is ignored by the zero-page allocator. Inside a real section it takes no room, so it needs an org of its own. As a parent it is a memory map: it steps past each child that continues its address, while the children keep their own bytes and can be saved; a child with its own org takes no room in it). Other keys are carried through untouched.

The address attributes take the BBC's full 32-bit host addresses (&FFFFxxxx = the I/O processor, &0000xxxx = the second processor): load and exec keep the whole value for the catalogue, while org and guard apply their low 16 bits - the 6502's actual address - to the assembly.

The last byte of memory is &FFFF. A section may fill right up to it, but a byte placed past it is a non-halting error ("Program counter runs past &FFFF by N bytes"), reported once per section at the statement that went over.

A filename destined for a disc image follows DFS rules: an optional single-character directory prefix ("D.NAME"; default $), then a name of up to 7 characters.

Zero-page allocation

The full story - liveness, footprints, sections, every error - is in Zero page allocation.

Reserved names

TRUE, FALSE and PI are reserved outright - they cannot name a label or symbol anywhere. Any other spelling is fair game wherever a name is defined: labels (.next, .clr), FOR variables, macro and FUNCTION parameters, ZA_AUTO names and -D defines may all share a spelling with a mnemonic, directive or macro, because references are read where an operand is expected, and no mnemonic, directive or macro name means anything there. The one exception is a plain assignment, whose name starts the statement - there the keywords win, so next = 5 will not parse. Prefix the name with @ to force it to read as a name: @next = 5 binds next, referenced bare (the C# idiom). Inside a FUNCTION body, a local's assignment starts its statement too, so the body keywords (IF, ELIF, ELSE, ENDIF, ASSERT, FOR, NEXT) cannot name locals. Macro and FUNCTION names stay restricted - they become keywords themselves, and a FUNCTION cannot take a builtin function's name (LO, REPLACE, WHERE, ...). All the NMOS 6502 mnemonics are recognised, plus the 65C02 extras (BRA, STZ, PHX, ...) - usable inside a section carrying cmos = TRUE; elsewhere the target is plain NMOS and a CMOS-only encoding is refused with its own message.

Expression reference

Values

Character literals

A character literal is exactly one character between single quotes, and it is simply a number: the character's code. It goes anywhere a number does - LDA #'A' loads 65, 'z'-'a' is 25, and EQUB 'h', 'i' emits two bytes.

Any character except a newline or the single quote itself may sit between the quotes, ';' and ':' included. There are no escape sequences, so write 39 for a quote. For the codes of a whole string, see CODES under Element-wise functions.

Range forms

Endpoints must be whole numbers, at most 2^53 either way (where numbers stop holding every integer); either or both may be any constant expression. .. binds looser than arithmetic and comparisons, so 0..n-1 needs no parentheses.

Operators, tightest first

Subscripts

x[sel, sel, ...] - one selector per axis, outermost first; fewer selectors than axes leaves the trailing axes whole (M[1] is a row; M[1][2] and M[1, 2] are the same element). Three selector kinds:

Ranges subscript via their elements ((100..200)[10] is 110). Strings are rank 1 and always yield a string: "hello"[1..3] is "ell", "hello"[4..0] is "olleh".

Broadcasting

Operators and element-wise functions map across lists and ranges, NumPy-fashion. The rules, in order:

1. A range becomes its list of elements.
2. A single value (a number, or a string) pairs with everything in the other side, however deep: {{1, 2}, {3, 4}} * 10 is {{10, 20}, {30, 40}}.
3. Two lists of the same depth pair off element-wise - lengths must match ({1, 2} + {1, 2, 3} is a shape error), except that a length-1 list repeats: {1, 2, 3} + {10} is {11, 12, 13}.
4. The shallower side is held whole and applied to each element of the deeper: a rank-1 list against a rank-2 one applies per row ({{1, 2, 3}, {4, 5, 6}} * {1, 0, 0} is {{1, 0, 0}, {4, 0, 0}}), and a column against a row is the outer product ({{1}, {2}} + {10, 20} is {{11, 21}, {12, 22}}).

The rules recurse, so nesting and ragged tails work: {1, {2, 3}} * 2 is {2, {4, 6}}. A string is a single value here, like a number: {"a", "b"} + "!" is {"a!", "b!"}.

Only operators and the element-wise functions broadcast. Every other function takes its arguments whole: LEN({{1, 2}, {3}}) is 2, not {2, 1}. The one exception is FIND's second argument, which maps. A user FUNCTION takes its arguments whole too, and maps over a list only when everything in its body does: sqr(0..15) is a 16-element list because x*x maps, but an IF needs one number or boolean, so a list condition is an error. WHERE is the element-wise choice that maps instead.

Element-wise functions

All broadcast; trigonometry is in radians.

String, search and type functions

List functions

Bit and compression functions

The building blocks of a section transform that compresses. A field of n bits holding v is written as the single number 2^n + v (the top set bit marks the width).

Constants

Your own FUNCTION names join the table as they are defined, callable as name(args).

Version history

See the GitHub releases page for what changed in each version.