Applesoft BASIC reference

Every command, function and operator in Applesoft BASIC — Microsoft's floating-point BASIC as Apple shipped it, in the ROM sockets of the 1979 Apple II Plus where the original machine had Woz's Integer BASIC.

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

Notes and caveats

• No variable may contain a keyword, and IF A THEN is broken. The interpreter scans its token table in token order and takes the first match, skipping spaces as it goes, so AT is found long before ATN or THEN. LATCH=1 is stored as L, AT, CH, and IF A THEN 20 as IF, AT, HEN20. Write conditions as comparisons — IF A<>0 THEN 20 — and keep AT, TO, THEN, NOT, AND, OR, STEP and FN out of your names. The editor flags both.
• Spaces are thrown away, everywhere but inside a string, a REM body and a DATA statement. 10 PRINT 1 and 10 PRINT 1 are the same seven bytes, and because the scan steps over spaces too, PR INT 1 prints and FORI=1TO10 loops.
• Names may be as long as you like but only the first two characters count, so COUNT and COST are one variable. A $ suffix makes a string and % a whole number from −32767 to 32767; everything else is floating point, nine significant digits and up to about ±1E38.
• This is not Integer BASIC, and the Apple II next door is not this. One design with a different BASIC fitted: the two share more than a dozen spellings while agreeing about hardly any of them. Here 7/2 is 3.5.
• AND, OR and NOT reduce their operands to a truth value rather than combining bits: 5 AND 3 and 5 OR 3 are both 1, and NOT 5 is 0. A true comparison is 1 — not the -1 most Microsoft BASICs answer with.
• Multiple statements per line are allowed with :, and line numbers run 0 to 63999. A typed line keeps its first 239 characters and drops everything past them. Falling off the last line simply stops, so END is optional.
• There is no hexadecimal notation anywhere in this BASIC, so PEEK, POKE, CALL and WAIT take decimal — and anything above 32767 is written negative: PEEK(-16384) reads the keyboard.

Command Function Operator

	Syntax & description
-	<number> - <number> | -<number> Subtracts, or negates.
*	<number> * <number> Multiplies.
/	<number> / <number> Divides, keeping the fraction: 7/2 is 3.5. Dividing by zero stops the program with ?DIVISION BY ZERO ERROR.
&	& <statement> Hands the rest of the statement to the machine-code routine vectored at location 1013, which is where an add-on language or toolkit hooks itself into the interpreter. Nothing is vectored there on a stock machine, so an & with no routine behind it drops into the monitor.
^	<number> ^ <number> Raises to a power, by way of the logarithm, so 2^.5 answers 1.41421356 rather than an error.
+	<number> + <number> | <string> + <string> Adds, and joins two strings. A join longer than 255 characters is ?STRING TOO LONG ERROR.
<	<number> < <number> | <string> < <string> Less than.
<=	<number> <= <number> | <string> <= <string> Less than or equal. Two tokens rather than one, the < and the = stored in the order they were typed, which is why it lists back as A < = B.
<>	<number> <> <number> | <string> <> <string> Not equal, stored as a < and a > and listed back as A < > B.
=	<number> = <number> | <string> = <string> Equal, and also the assignment in LET. A true comparison here is 1 rather than the -1 most Microsoft BASICs answer with.
=<	<number> =< <number> | <string> =< <string> Less than or equal, written the other way round. The interpreter reads the pair rather than a spelling, so this and <= are one test.
=>	<number> => <number> | <string> => <string> Greater than or equal, written the other way round; the same test as >=.
>	<number> > <number> | <string> > <string> Greater than. Strings compare too, character by character in the machine's own code order, which is what the Apple II's Integer BASIC cannot do at all.
><	<number> >< <number> | <string> >< <string> Not equal, written the other way round; the same test as <>.
>=	<number> >= <number> | <string> >= <string> Greater than or equal, stored as its two tokens in the order typed.
ABS	ABS(<number>) The argument without its sign.
AND	<number> AND <number> Logical and: 1 when both operands are non-zero, 0 otherwise. Not bitwise - 5 AND 3 is 1, not the 1 the bits would give by coincidence.
ASC	ASC(<string>) The code of a string's first character, 0 to 127 - plain ASCII, not the bit-7 form the Apple II's Integer BASIC answers with and not what the keyboard latch holds. A key read with PEEK(-16384) is compared against ASC("A")+128.
AT	HLIN <x>, <x> AT <y> | VLIN <y>, <y> AT <x> Names the row HLIN draws along or the column VLIN draws down, and the point DRAW and XDRAW put a shape at. It is also matched ahead of ATN and THEN wherever those two letters fall in a name, so LATCH=1 stores as L, AT and CH and CATALOG as C, AT, A and LOG - no variable here may contain a keyword.
ATN	ATN(<number>) Arc tangent, in radians. It is reached only where the raw character after the AT match is an N, which is why ATN( works and AT N( does not.
CALL	CALL <addr> Calls a machine-code routine, which returns with RTS. An address above 32767 may be written negative, so the monitor routine that clears the screen is CALL -936.
CHR$	CHR$(<number>) The character with a given code, 0 to 255. Codes 128 to 255 draw the same characters as 0 to 127, that being the machine's own normal-video form, so CHR$(193) prints an A just as CHR$(65) does.
CLEAR	CLEAR Forgets every variable, array and string, and closes every open FOR and GOSUB. The program itself is untouched.
COLOR=	COLOR=<colour> Sets the colour PLOT, HLIN and VLIN draw in, from 0 black to 15 white. The number is taken modulo 16, so COLOR=19 draws in colour 3.
CONT	CONT Carries on from a STOP or a BREAK, at the statement after the one that stopped. Editing any line in between makes it ?CAN'T CONTINUE ERROR.
COS	COS(<number>) Cosine of an angle in radians.
DATA	DATA <constant>[, <constant>]… Constants for READ to walk, in program order. The rest of the statement is stored as typed rather than crunched, so spaces inside a DATA survive; a string needs quotes only where it contains a comma, a colon or a leading space.
DEF	DEF FN <name>(<param>) = <number> Defines a one-expression function of one numeric argument. The parameter is an ordinary variable and is left holding the last value passed to it. Numeric only: there is no string function to define.
DEL	DEL <line>, <line> Deletes every line from the first to the second inclusive. Both are required: one line is deleted with DEL 100,100, or by typing its number on its own.
DIM	DIM <var>(<number>[, <number>]…) Declares an array, of any number of dimensions and of either type. Subscripts count from 0, so DIM A(3) holds four elements. A DIM is only needed past ten - an array used without one is created with subscripts 0 to 10.
DRAW	DRAW <shape> [AT <x>, <y>] Draws a shape from the shape table in the current HCOLOR=, ROT= and SCALE=, at the given point or from where the last plot left off. The table's address goes in locations 232 and 233 before the first DRAW.
END	END Stops the program and returns to the ] prompt. Optional, unlike the Apple II's Integer BASIC: falling off the last line stops just as quietly.
EXP	EXP(<number>) e raised to the power of the argument.
FLASH	FLASH Prints in flashing video from here on, alternating between normal and inverse about four times a second. The video counter does the flashing, so it costs the program nothing to leave text on screen.
FN	FN<name>(<arg>) Calls a function defined by DEF FN. The definition has to have run before the call: a name that has not been defined is ?UNDEF'D FUNCTION ERROR.
FOR	FOR <numvar> = <number> TO <number> [STEP <number>] Opens a counting loop that runs to the matching NEXT. The limit and the step may both be fractional, and the variable keeps counting past the limit - after FOR I=1 TO 3 ... NEXT I it holds 4.
FRE	FRE(<number>) Free bytes, after collecting the string space - which is the real reason to call it, the collection being what reclaims strings the program has discarded. The count is signed 16-bit, so above 32767 it comes back negative and the true figure is FRE(0)+65536. The argument is ignored.
GET	GET <var> Waits for a single keypress and stores it, without echoing it and without waiting for RETURN. No cursor appears while it waits, so a program that wants one draws it.
GOSUB	GOSUB <line> Calls a subroutine, which returns with RETURN. Twenty-four levels deep: the twenty-fifth answers ?OUT OF MEMORY ERROR, the 6502 stack rather than the workspace being what runs out.
GOTO	GOTO <line> Jumps to a line number, which must be a literal. There is no computed GOTO - GOTO A reads no digits at all and looks for line 0 - and ON ... GOTO is what replaces it.
GR	GR Switches on the lo-res screen and clears it to black: a 40 by 40 grid of coloured blocks with four lines of text under it. The page is really 40 by 48, and PLOT reaches the eight rows behind that text window. TEXT switches back.
HCOLOR=	HCOLOR=<colour> Sets the colour HPLOT, DRAW and XDRAW draw in, 0 to 7. On the real machine those are artefacts of how the dots beat against the colour subcarrier rather than a palette; the hi-res screen is drawn here in monochrome, so what changes is whether a dot is set.
HGR	HGR Switches on hi-res page 1 and clears it to black: 280 by 160 with four lines of text under it. HPLOT still reaches the 32 rows behind that window. Both hi-res pages are ordinary RAM above the program, so a program long enough to reach 8192 has its own text cleared out from under it.
HGR2	HGR2 Switches on hi-res page 2 and clears it to black - the whole 280 by 192 raster, with no text window under it, so nothing a program prints can be seen while it is up.
HIMEM:	HIMEM:<addr> Sets the top of the memory Applesoft will use, which is the address the string space fills down from. Lowering it is how RAM is set aside for machine code or a shape table. The colon is part of the spelling.
HLIN	HLIN <x>, <x> AT <y> Draws a horizontal run of lo-res blocks in the current colour, from the first column to the second inclusive, along row <y>.
HOME	HOME Clears the text window and puts the cursor at its top left. The window rather than the screen: after a TEXT the two are the same, but a program that has narrowed the window by poking locations 32 to 35 clears only what it narrowed to.
HPLOT	HPLOT <x>, <y>[ TO <x>, <y>]… | HPLOT TO <x>, <y> Draws in hi-res: one dot, or a line to each point in turn. The second form continues from wherever the last plot left off, which is how a shape is drawn without repeating its corners. <x> runs 0 to 279 and <y> 0 to 191.
HTAB	HTAB <col> Moves the cursor to a column, 1 to 40, on the row it is already on. Unlike TAB( it moves backwards as readily as forwards, so what is printed next overwrites what was there.
IF	IF <number> THEN <line> | IF <number> THEN <statement> Runs the consequent when the condition is non-zero; there is no ELSE. Everything after THEN belongs to the IF, so a false condition skips the rest of the line. Write the condition as a comparison: IF A THEN 20 is stored as IF, the AT token and HEN20, because the token scan reaches AT long before THEN. IF A<>0 THEN 20 is the way to say it.
IN#	IN#<slot> Reads input from the card in a peripheral slot instead of from the keyboard; IN#0 gives the keyboard back. As with PR#, the emulated machine has no cards fitted.
INPUT	INPUT [<prompt>;] <var>[, <var>]… Prints the prompt, then a ?, and waits for a whole line to be typed. The prompt is a quoted literal followed by a semicolon - a comma there is a syntax error - and a value of the wrong type answers ?REENTER and asks for the line again.
INT	INT(<number>) Rounds down, towards minus infinity rather than towards zero: INT(-1.5) is -2.
INVERSE	INVERSE Prints in inverse video - black on white - from here on. It masks what PRINT writes rather than changing what is already on the screen.
LEFT$	LEFT$(<string>, <length>) The first characters of a string.
LEN	LEN(<string>) How many characters a string holds, 0 to 255.
LET	LET <var> = <expr> Assigns a value. Optional, as on every BASIC here: LET A=1 and A=1 differ by the one token and nothing else.
LIST	LIST [<line>[, <line>]] Lists the whole program, one line, or a range. The listing puts its own spacing back around every token, because the interpreter threw the original spacing away when it stored the line - which is why a listed program never looks quite like the one that was typed.
LOAD	LOAD Reads a program from cassette. The tape carries no name, so what loads is whatever comes next on it. There is no cassette wired to the emulated machine; a program arrives in this IDE through the Transfer dialog instead.
LOG	LOG(<number>) Natural logarithm. Zero or a negative argument is ?ILLEGAL QUANTITY ERROR.
LOMEM:	LOMEM:<addr> Sets the bottom of the variables, which otherwise sit directly above the program. Raising it clears space between the two - and erases every variable in doing so.
MID$	MID$(<string>, <start>[, <length>]) Characters from a position, counting from 1, either to the end of the string or for a given length. There is no assigning into the middle of a string as the Apple II's Integer BASIC does: a string here is built by joining with +.
NEW	NEW Erases the program and every variable with it.
NEXT	NEXT [<numvar>[, <numvar>]…] Closes a FOR loop and jumps back to it. The variable may be left out, which closes the innermost open loop; naming several closes them innermost first.
NORMAL	NORMAL Prints in normal video from here on, undoing INVERSE or FLASH.
NOT	NOT <number> Logical not: 1 when the operand is zero, 0 otherwise. NOT 5 is 0, not the -6 a bitwise BASIC would give.
NOTRACE	NOTRACE Stops TRACE printing line numbers.
ON	ON <number> GOTO <line>[, <line>]… | ON <number> GOSUB <line>[, <line>]… Branches to the first line for 1, the second for 2 and so on. A value of 0, or one past the end of the list, falls through to the next statement; a negative one is ?ILLEGAL QUANTITY ERROR.
ONERR	ONERR GOTO <line> Traps every error from here on and jumps to a line instead of stopping. The code of the error that fired is in location 222 and the line it happened on in 218 and 219, so a handler can tell an ?OUT OF DATA ERROR from a ?TYPE MISMATCH ERROR.
OR	<number> OR <number> Logical or: 1 when either operand is non-zero, 0 otherwise. Not bitwise - 5 OR 3 is 1, not 7.
PDL	PDL(<number>) How far a paddle is turned, 0 to 255 with 128 at the centre. The game connector carries four of them, numbered 0 to 3; the on-screen controller drives 0 and 1 as the two axes of a stick.
PEEK	PEEK(<addr>) The byte at an address, which may be written negative above 32767: PEEK(-16384) is the keyboard latch, and a value over 127 there means a key is waiting. Reading one of the machine's soft switches throws it exactly as writing to it would.
PLOT	PLOT <x>, <y> Lights one lo-res block in the colour COLOR= set. <x> runs 0 to 39 and <y> 0 to 47; outside that stops the program with ?ILLEGAL QUANTITY ERROR.
POKE	POKE <addr>, <byte> Stores a byte in memory. An address above 32767 may be written negative, so the keyboard strobe at 49168 is cleared with POKE -16368,0.
POP	POP Forgets the innermost GOSUB return address, so the next RETURN goes back a level further. It turns a subroutine into a jump after the fact.
POS	POS(<number>) The column the cursor is in, counting from 0 - one less than the HTAB that would put it there. The argument is ignored.
PR#	PR#<slot> Sends everything PRINT writes to the card in a peripheral slot instead of to the screen; PR#0 gives the screen back. No cards are fitted to the emulated machine, so 0 is the only slot with anything behind it.
PRINT?	PRINT [<expr>[;|,]]… Prints numbers and strings. A trailing ; holds the cursor where it is and a trailing , steps to the next 16-column tab zone. A number is shown to nine significant digits with no leading zero, so a half prints as .5. Can be typed ?, which is this machine's whole abbreviation scheme.
READ	READ <var>[, <var>]… Takes the next constant from the DATA statements. Reading past the last one is ?OUT OF DATA ERROR; RESTORE rewinds to the first.
RECALL	RECALL <array> Reads an array back from cassette, element by element, into an array of the same name. There is no cassette wired to the emulated machine.
REM	REM <comment> A comment, to the end of the line. The text is stored as typed - spaces and all, which nothing else on a line survives - and comes back unchanged in a listing.
RESTORE	RESTORE Rewinds READ to the first DATA statement in the program. There is no way to rewind to a particular one.
RESUME	RESUME Returns from an ONERR handler to the statement that raised the error and runs it again - so a handler that has not fixed the cause loops for ever.
RETURN	RETURN Returns from a subroutine to the statement after its GOSUB.
RIGHT$	RIGHT$(<string>, <length>) The last characters of a string.
RND	RND(<number>) A random fraction from 0 up to but not including 1. A positive argument gives the next number in the sequence, 0 repeats the last one, and a negative one seeds the sequence - the same negative value always starts the same run.
ROT=	ROT=<number> Sets the rotation DRAW and XDRAW apply to a shape, 0 to 63, with 0 upright and 16 a quarter turn clockwise. At SCALE=1 the shape is too coarse for most of the 64 to change anything.
RUN	RUN [<line>] Clears the variables and starts the program, at the given line or at the lowest one. Legal inside a program too, where it restarts it.
SAVE	SAVE Writes the program to cassette as two records, beeping once for each: a three-byte header giving the length, then the program text. There is no cassette wired to the emulated machine, but the Transfer dialog writes the same two records as audio.
SCALE=	SCALE=<number> Sets the size DRAW and XDRAW draw a shape at, 1 to 255, where each unit is one screen dot per step in the shape table. 0 means 256.
SCRN(	SCRN(<x>, <y>) The colour of one lo-res block, 0 to 15, so a program can read its own picture back rather than keeping a copy of it in an array.
SGN	SGN(<number>) -1, 0 or 1, by the sign of the argument.
SHLOAD	SHLOAD Reads a shape table from cassette, places it below HIMEM: and points locations 232 and 233 at it. There is no cassette wired to the emulated machine, so a shape table reaches a program here as a memory block instead.
SIN	SIN(<number>) Sine of an angle in radians.
SPC(	SPC(<number>) Inside a PRINT, prints that many spaces. Unlike TAB( it is relative, so it always moves.
SPEED=	SPEED=<number> Sets how fast characters are printed, 0 slowest and 255 full speed. It is a delay between characters rather than a screen setting, so it slows a listing as readily as a program's own output.
SQR	SQR(<number>) Square root. A negative argument is ?ILLEGAL QUANTITY ERROR.
STEP	FOR <numvar> = <number> TO <number> STEP <number> The amount a FOR loop adds each time round. It may be negative, and it may be fractional - this BASIC has floating point where the Apple II's Integer BASIC has none.
STOP	STOP Stops the program and reports BREAK IN <line>, naming the line it stopped on. CONT carries on from there.
STORE	STORE <array> Writes a whole array to cassette. As with RECALL there is no cassette here; the Transfer dialog is how data leaves this IDE.
STR$	STR$(<number>) A number as the string PRINT would have shown, leading zero and all - which is to say without one, STR$(.5) being .5.
TAB(	TAB(<col>) Inside a PRINT, moves the cursor to a column, counting from 1. It only ever moves forward: a column left of where the cursor already is does nothing at all.
TAN	TAN(<number>) Tangent of an angle in radians.
TEXT	TEXT Returns to the full 40 by 24 text screen from either graphics mode and gives the text window the whole screen back. It does not clear what is there; HOME does.
THEN	IF <number> THEN <line> | IF <number> THEN <statement> The consequent of an IF: a line number to jump to, or a statement to run. A bare variable in front of it is the trap - IF A THEN 20 stores as IF, the AT token and HEN20, the scan having taken the A and the T of THEN as an AT. A comparison keeps the two apart.
TO	FOR <numvar> = <number> TO <number> The value a FOR loop counts to, inclusive, and the joiner between two points in HPLOT. It is half of this machine's most famous trap: AT is matched before TO can be, so the interpreter reads the raw character after the match to decide between them - A TO B comes out as A, TO and B, while A T O B comes out as AT, O and B.
TRACE	TRACE Prints each line number as the program reaches it, as #10, #20, before the line runs. It survives a NEW; NOTRACE stops it.
USR	USR(<number>) Calls the machine-code routine jumped to from location 10, with the argument in the floating-point accumulator, and answers with whatever the routine leaves there. Nothing is vectored there on a stock machine, so a JMP has to be poked into 10, 11 and 12 first.
VAL	VAL(<string>) A string read as a number, stopping at the first character that cannot be part of one: VAL("12X") is 12 and VAL("X") is 0.
VLIN	VLIN <y>, <y> AT <x> Draws a vertical run of lo-res blocks in the current colour, from the first row to the second inclusive, down column <x>.
VTAB	VTAB <row> Moves the cursor to a row, 1 to 24, in the column it is already in. With HTAB it addresses any cell on the screen.
WAIT	WAIT <addr>, <mask>[, <byte>] Spins until a location changes: it reads the address, exclusive-ORs with the third argument (0 where it is left out), ANDs with the mask, and returns when the result is non-zero. Nothing else runs while it waits, and no key interrupts it.
XDRAW	XDRAW <shape> [AT <x>, <y>] Draws a shape by inverting every dot it covers instead of setting it, so drawing the same shape twice in the same place leaves the screen exactly as it was. That is how a moving shape is erased without keeping a copy of the background.

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

<constant>

a literal number or string, not an expression

<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

<name>

a name the program defines for a function or procedure

<param>

a parameter, where the definition introduces it

<arg>

a value, where the call passes it

<start>

the position something starts at, counting from 1

<length>

how many characters

<x>

a horizontal graphics coordinate

<y>

a vertical graphics coordinate

<col>

a text column

<row>

a text row

<colour>

a colour, by number

<prompt>

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

<addr>

a memory address

<mask>

a bit mask, one bit per item

<slot>

a peripheral slot, 0 to 7

<shape>

a shape in the shape table, by number

<array>

an array, named without a subscript

Showing 113 of 113 keywords