Atom BASIC reference

Every command, function and operator in Atom BASIC, the BASIC built into the Acorn Atom.

In this reference: Hardware · Escape codes · File formats · Argument notation

Notes and caveats

• A keyword can be typed as a dotted prefix — P. for PRINT, GOS. for GOSUB — which the ROM expands to the first keyword the letters begin. Because the Atom stores program text as it is typed, an abbreviated keyword is genuinely fewer bytes. The shortest form of each is shown beside it in the table below, and the search box finds a keyword by it.
• Data files. FIN/FOUT open a file for input/output and BGET/BPUT read/write a byte, while SGET/SPUT transfer whole strings; in this IDE they are served from the emulator's virtual filesystem, and each file a program writes appears as its own tab in the editor. On the emulated tape ROM there is no SHUT, so an output file is saved as each BPUT runs.
• Memory and bit operators. Real Atom BASIC reaches memory through the indirection operators ? (byte), ! (4-byte word) and $ (string) instead of PEEK/POKE, and offers the remainder operator % and the bitwise operators & (AND) and : (XOR). There is no DIV or MOD — those are BBC BASIC — and no symbolic spelling of bitwise OR: the OR keyword is itself bitwise, as AND is, so 5 AND 3 is 1 rather than a yes-or-no answer.
• Two arithmetics. A–Z are integers, where / truncates. The floating-point ROM's %A–%Z are reals, reached through FPRINT, FIF and the other F statements — and the power operator ^ belongs to that half only: %A=2^3 works, while 2^3 in an integer expression is rejected. It is computed through logs, so 2^3 prints as 8.00000000 and 2^3^2 as 63.9999998.
• True is 1. A comparison yields 1, not the -1 of the BBC BASIC that followed this machine, so an expression like X=X+(A>B) counts the other way after a port.

Command Function Operator

	Syntax & description
-	<number> - <number> | -<number> Subtraction / negation.
:	<number> : <number> Bitwise exclusive-OR (XOR) of two integers, setting each result bit where exactly one operand bit is set.
!	!<addr> | !<addr>=<number> Word indirection: reads or writes the 4-byte word at an address, low byte first. As a statement, !addr=value stores four bytes; in an expression, !addr reads them. The dyadic form base!offset addresses base+offset.
?	?<addr> | ?<addr>=<byte> Byte indirection: reads or writes the single byte at an address (the Atom equivalent of PEEK/POKE). As a statement, ?addr=value stores a byte; in an expression, ?addr reads one. The dyadic form base?offset addresses base+offset.
*	<number> * <number> Multiplication.
/	<number> / <number> Division.
&	<number> & <number> Bitwise AND of two integers (distinct from the logical AND keyword used in conditions).
%	<number> % <number> Remainder after integer division (for example 7 % 3 is 1). Not to be confused with %A–%Z, the floating-point ROM variables.
^	%<var> = <number> ^ <number> Raises to a power, computed through logs so the result is approximate. Floating point only: %A=2^3 works, and the same expression in integer arithmetic is rejected.
+	<number> + <number> Addition.
<	<number> < <number> Less than.
<=	<number> <= <number> Less than or equal.
<>	<number> <> <number> Not equal.
=	<var> = <expr> | <expr> = <expr> Assignment / equality. A true comparison is 1.
>	<number> > <number> Greater than.
>=	<number> >= <number> Greater than or equal.
$	$<addr> | $<addr>=<string> String indirection: addresses the string stored at a location, terminated by a carriage return. $addr="TEXT" stores a string; PRINT $addr prints one.
ABS	ABS(<number>) Returns the absolute (unsigned) value of n.
AND	<number> AND <number> Logical AND used to combine conditions (bitwise masking uses the & operator). Arithmetic on A–Z is integer-only.
ATN	ATN(<number>) Returns the arctangent of n in radians (requires the floating-point ROM).
BGET	BGET <file> Reads and returns the next byte from an input file opened with FIN.
BPUTB.	BPUT <file>, <byte> Writes the low byte of the value to an output file opened with FOUT. In the IDE these bytes are stored in the emulator's virtual filesystem, and the file appears as its own tab in the editor.
CH	CH <number> Reads a character or key code.
CLEARC.	CLEAR <number> Selects a screen mode and clears it: CLEAR 0 is the 32×16 text screen, while CLEAR 1–4 select graphics modes, with CLEAR 4 the highest resolution (256×192).
COS	COS(<number>) Returns the cosine of n in radians (requires the floating-point ROM).
COUNT	COUNT Returns the current text cursor column — the number of characters printed since the last newline — like POS in other dialects.
DIMDI.	DIM <var>(<number>) Reserves space for an array or a byte buffer of the given size for later indexed or ?/! access.
DOD.	DO <statement>… UNTIL <number> Begins a loop whose body repeats until the UNTIL condition is true (tested at the bottom, so the body always runs at least once). Because 0 is false, 'UNTIL 0' loops forever.
DRAWDR.	DRAW <x>, <y> Draws a line from the current graphics cursor to x,y; drawing to the cursor's own point plots a single dot.
ENDE.	END Stops the program cleanly and returns to the prompt.
EXP	EXP(<number>) Returns e raised to the power n (requires the floating-point ROM).
EXT	EXT <file> Returns the length (extent) in bytes of an open file.
FDIMFD.	FDIM %<var>(<number>) Reserves space for a floating-point array indexed from zero (requires the floating-point ROM).
FGETFG.	FGET <file>, %<var> Reads a floating-point value from an input file opened with FIN (requires the floating-point ROM).
FIF	FIF <number> THEN <statement> Runs the statement after THEN only when a floating-point comparison is true (requires the floating-point ROM).
FIN	FIN <filename> Opens a file for input and returns a handle to pass to BGET, or 0 if no such file exists. In the IDE it reads from the emulator virtual filesystem.
FINPUTFI.	FINPUT %<var> Reads a floating-point value from the keyboard into a %A–%Z floating-point variable (requires the floating-point ROM).
FORF.	FOR <numvar> = <number> TO <number> [STEP <number>] Begins a counted loop over an integer variable, closed by NEXT. The counter is one of A–Z and steps by 1 unless STEP gives another value.
FOUT	FOUT <filename> Opens a file for output and returns a handle to pass to BPUT. In the IDE the file lives in the emulator's virtual filesystem, and appears as its own tab in the editor.
FPRINTFP.	FPRINT <number> Prints a floating-point value; the floating-point counterpart of PRINT (requires the floating-point ROM). Abbreviate as FP.
FPUTFPU.	FPUT <file>, %<var> Writes a floating-point value to an output file opened with FOUT (requires the floating-point ROM).
FUNTILFU.	FUNTIL <number> Closes a DO loop, repeating until a floating-point condition becomes true (requires the floating-point ROM).
GET	GET <port> Reads and returns a value from the given hardware I/O port.
GOSUBGOS.	GOSUB <line> Calls the subroutine at the given line; a later RETURN resumes after the GOSUB. Abbreviate as GOS.
GOTOG.	GOTO <line> Jumps unconditionally to a line number, which may itself be a computed expression. Abbreviate as G.
IF	IF <number> THEN <statement> Runs the statement after THEN only when the condition is non-zero (true). Atom BASIC has no ELSE, and THEN takes a single statement.
INPUTI.	INPUT [<prompt>,] <var> Reads a number from the keyboard into a numeric variable (A–Z), or text into a string when the target is a $ string. An optional quoted prompt is printed before the cursor.
LEN	LEN(<number>) Returns the length of the string stored at the given address (a $ string), not counting its terminating carriage return.
LETL.	LET <var> = <number> Assigns a value to a variable; the LET keyword is optional, so V=expr works on its own. Only one variable is assigned per statement.
LINKLI.	LINK <number> Calls a machine-code routine at the given address; addresses are commonly written as hex with a # prefix (e.g. LINK #FFE3).
LISTLIS.	LIST [<line>, <line>] Lists the program text, optionally restricted to a start and end line range.
LN	LN(<number>) Returns the natural (base-e) logarithm of n (requires the floating-point ROM).
LOADLO.	LOAD <filename> Loads a named program from cassette into memory.
LOG	LOG(<number>) Returns the base-10 logarithm of n (requires the floating-point ROM).
MOVEM.	MOVE <x>, <y> Moves the graphics cursor to x,y without drawing. The graphics origin is the bottom-left of the screen.
NEW	NEW Erases the program currently held in memory.
NEXTN.	NEXT [<numvar>] Marks the end of a FOR loop and advances the counter, looping back while the limit is not yet passed. Naming the variable is optional.
OLDO.	OLD Recovers the previous program after a NEW, provided its text has not yet been overwritten.
OR	<number> OR <number> Logical OR used to combine conditions (bitwise OR uses the \ operator). Arithmetic on A–Z is integer-only.
PI	PI Returns the constant 3.14159265 (requires the floating-point ROM).
PLOTPL.	PLOT <action>, <x>, <y> Plots at x,y with a mode that controls whether the point is set, cleared, or inverted. The Atom has no colour list like the BBC.
PRINTP.	PRINT [<expr> | &<number> | $<addr>][,|;|']… Prints values to the screen (abbreviate as P.); it adds no trailing newline, so use a quote ' to emit a carriage return. A comma tabs to the next field, a semicolon suppresses spacing, & prints a value in hexadecimal, and $<addr> prints the string stored at that address.
PTR	PTR <file> Returns the read/write pointer of an open file (the number of bytes transferred so far); it can also be assigned to seek to a position within the file.
PUTPU.	PUT <port>, <byte> Writes a value to the given hardware I/O port.
REM	REM <comment> Marks a comment; the rest of the line is ignored by the interpreter.
RETURNR.	RETURN Returns from a GOSUB to the statement following the most recent call.
RND	RND Returns a random integer; test its sign for a coin flip since arithmetic on A–Z is integer-only.
RUNRU.	RUN Runs the program in memory from its lowest line number.
SAVES.	SAVE <filename> Saves the program in memory to cassette under a name.
SGET	SGET <file> Reads a whole string (up to a carriage return) from an input file opened with FIN — the string companion of BGET.
SGN	SGN(<number>) Returns the sign of n as -1, 0, or 1.
SHUTSH.	SHUT Closes all open cassette or disc files.
SIN	SIN(<number>) Returns the sine of n in radians (requires the floating-point ROM).
SPUTSP.	SPUT <file>, $<addr> Writes a string (the characters at an address, up to a carriage return) to an output file opened with FOUT — the string companion of BPUT.
SQR	SQR(<number>) Returns the square root of n (requires the floating-point ROM).
STEP	FOR <numvar> = <number> TO <number> STEP <number> Sets the increment added to the FOR counter on each pass; it may be negative to count down.
STOPST.	STOP Halts the program and prints a STOP report.
TAN	TAN(<number>) Returns the tangent of n in radians (requires the floating-point ROM).
THENT.	IF <number> THEN <statement> Introduces the single statement executed when the preceding IF condition is true.
TO	FOR <numvar> = <number> TO <number> Separates the start and end values of a FOR loop counter.
TOP	TOP Returns the address of the byte just past the end of the program text, marking the start of free memory.
UNTILU.	UNTIL <number> Closes a DO loop, testing its condition at the bottom and repeating the body until the expression is true (non-zero).
WAITW.	WAIT Pauses for one display frame (about 1/50 s), typically used to pace animation.

Argument notation

Anything in <angle brackets> is a value you supply; everything else is typed exactly as shown. [square brackets] mark an optional part, | separates alternatives, and … means the part before it can repeat. The arguments on this page are:

<number>

a numeric expression

<string>

a string expression

<expr>

a value of either type, where the keyword takes both

<byte>

a value from 0 to 255

<var>

a variable of either type

<numvar>

a numeric variable

<line>

a line number

<statement>

one BASIC statement

<comment>

free text, to the end of the line

<x>

a horizontal graphics coordinate

<y>

a vertical graphics coordinate

<action>

which of several things the keyword should do

<prompt>

text shown before the input; a literal, not an expression

<file>

an open file, by the number it was opened on

<filename>

the name of a file on tape or disc

<addr>

a memory address

<port>

an input/output port, by number

Showing 83 of 83 keywords