<?xml version="1.0" encoding="UTF-8"?>
<!-- **************************************************************************
.... For copyright and licensing terms, see the file named COPYING.
.... **************************************************************************
.... vim: indentexpr=:
.-->
<?xml-stylesheet href="docbook-xml.css" type="text/css"?>

<refentry id="BASIC">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>BASIC</refentrytitle>
<manvolnum>5</manvolnum>
<refmiscinfo class="manual">file formats</refmiscinfo>
<refmiscinfo class="source">BASIC</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv>
<refname>BASIC</refname>
<refpurpose>interpreted BASIC language for video terminal environments</refpurpose>
</refnamediv>

<refsection><title>Description</title>

<para>
Beginners's All&#x2010;purpose Symbolic Instruction Code (BASIC) is an interpreted computer programming language.
It is the language understood by the <citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>basica</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and <citerefentry><refentrytitle>list</refentrytitle><manvolnum>1</manvolnum></citerefentry> commands.
</para>

<para>
There was an American standard for BASIC, although not an international one.
However, the few BASICs that adhered to it never became popular, and the ones that became popular effectively determined the quite different <emphasis>de facto</emphasis> standard.
This dialect follows the latter, with influences from Microsoft Home Computer Era BASIC, VSI BASIC, BBC BASIC, and in particular Sinclair SuperBASIC.
</para>

<refsection><title>Basics of BASIC</title>

<para>
BASIC source files are Unicode text, encoded in WTF-8.
There is no already&#x2010;tokenized file format.
Code is converted from human&#x2010;readable form to an internal tokenized form as it is read from file or entered interactively, and turned back into that human&#x2010;readable form when a program is saved or listed.
</para>

<note>
This has the famous side&#x2010;effect that programs are normalized to an extent.
Numeric literals, for example, lose their insignificant leading zeroes.
TABs, VTs, FFs, and CRs are converted to (single) SPCs.
</note>

<para>
The interpreter processes the sequence of tokens, sometimes over and over, as it executes the program.
There is no machine code compiled form.
Tokens can be BASIC language keywords, numeric and string literals, various punctuation sequences, or variable names.
</para>

<para>
BASIC comprises a series of statements; there are no other syntactic elements.
(This dialect of the language has no in&#x2010;line assembly language like BBC BASIC nor a pre&#x2010;processor macro system like VSI BASIC.)
Most statements end at a colon (<code>:</code>) or the end of the line.
A few do not require a colon.
The <code>REM</code> statement, which is used to insert remarks into code or to <quote>comment out</quote> code that should not be run, ignores colons but respects line ends.
</para>
<note>
<code>REM</code>, being a statement, takes effect after tokenization.
Invalid tokens cannot be <quote>commented out</quote> by <code>REM</code>.
</note>

</refsection>

<refsection><title>Immediate and program modes</title>

<para>
When executing, the BASIC interpreter is always in one of two modes.
In immediate mode, it is executing, there and then, a line of statements that has just been given to it.
In program mode, it is executing the program that it has been storing in memory, that has been entered/loaded and possibly edited before being run.
</para>

<note>
Interactive and non&#x2010;interactive modes are modes of the textual user interface and are described in <citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>basica</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
Immediate and program modes are modes of the interpreter, and not the same thing.
It is quite possible to non&#x2010;interactively execute BASIC code in immediate mode, or for a program running in program mode to be interactive.
It is also possible for the BASIC interpreter to not be executing, whilst the textual user interface is prompting in interactive mode for an immediate line to run or otherwise loading, upserting, or editing the program in memory.
</note>

<para>
Immediate mode starts with a line being entered using the user interface, and ends with the end of the line or <code>BYE</code>.
Program mode starts with <code>RUN</code>, <code>GO&#x00A0;TO</code>, or <code>GO&#x00A0;SUB</code> executed in immediate mode; and ends with the interpreter reaching the end of the program, a Cancel or Close event from the user interface, <code>END</code>, or <code>STOP</code>.
Program mode resumes from interruptions with <code>CONT</code>, the end of a loop construct, <code>NEXT</code>, <code>EXIT</code>, <code>RETURN</code>, <code>GO&#x00A0;TO</code>, or <code>GO&#x00A0;SUB</code>; executed in immediate mode.
</para>

</refsection>

</refsection>

<refsection><title>Language</title>

<note>
This is a fairly abridged language reference.
There are scads of books, magazine articles, floppy disc shareware archives, and WWW sites on BASIC from the past 50 years.
</note>

<caution>
This BASIC follows Unix conventions and is case&#x2010;sensitive.
Keywords <emphasis>must</emphasis> be in upper case, otherwise they will be treated as variable names.
Variable names that differ in case name different variables.
</caution>
<tip>
<citerefentry><refentrytitle>list</refentrytitle><manvolnum>1</manvolnum></citerefentry> displays keywords and variable names differently, making it simpler to determine when BASIC has and has not recognized a keyword.
</tip>

<refsection><title>Line numbers</title>

<para>
This BASIC does not require line numbers, with two exceptions.
To insert/update (upsert) a line in immediate mode, it must have a number, otherwise it will be understood as immediate code to be executed there and then.
Lines that are the targets of either <code>GO&#x00A0;TO</code> or <code>GO&#x00A0;SUB</code> must have numbers.
</para>

<tip>
The preferred way of operating with multiple&#x2010;line programs should be editing them as files with a Unix text editor, and either loading them with <code>LOAD</code> or loading and running them with the filename argument form of <citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>basica</refentrytitle><manvolnum>1</manvolnum></citerefentry>, just as with most other programming lanuages on Unix(&#x2010;like) systems.
In this vein, tools for certain specialized BASIC tasks, <citerefentry><refentrytitle>commodore-basic-detokenize</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>petscii-to-wtf8</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and <citerefentry><refentrytitle>petscii-to-ecma48</refentrytitle><manvolnum>1</manvolnum></citerefentry>, are supplied as Unix filter programs rather than as capabilities of this BASIC interpreter.
</tip>
<note>
Both <code>LOAD</code> and the filename argument form of those utilities use the filename as it stands; there is no implied extension to files containing BASIC programs.
</note>

<para>
Upserted program lines are placed in order into the program in memory.
However, no restriction is placed on programs loaded with <code>LOAD</code> or as command&#x2010;line filenames.
They can have line numbers in any order.
BASIC preserves the line ordering that is in the file, and executes from line to line in that order, irrespective of any line numbers, which should be regarded as just labels.
</para>

</refsection>

<refsection><title>Immediate mode only statements</title>

<para>
Various statements are only valid in immediate mode, and are errors if they are encountered in programs.
Mostly, they deal with the mechanics of loading and editing programs, which of course must not be done whilst a program is actually running.
</para>

<variablelist>
<varlistentry>
<term><code>HELLO</code></term>
<term><code>BYE</code></term>
<term><code>GOODBYE</code></term>
<listitem><para>begin a BASIC session or quit BASIC (there being an implicit <code>HELLO</code> in interactive mode)</para></listitem>
</varlistentry>
<varlistentry>
<term><code>RUN</code></term>
<listitem><para>run the program that is currently stored in memory; equivalent to <code>GOTO&#x00A0;<replaceable>number</replaceable></code> where <replaceable>number</replaceable> labels the first line of the program</para></listitem>
</varlistentry>
<varlistentry>
<term><code>CONT</code></term>
<listitem>
<para>continue running the program that is currently stored in memory, after <code>STOP</code></para>
<para>
This BASIC spells the continue statement keyword as <code>CONT</code>, like IBM BASIC/BASICA and Sinclair SuperBASIC.
Sinclair ZX BASIC spelled it <code>CONTINUE</code>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>LIST</code></term>
<term><code>EDIT</code></term>
<listitem><para>list and (if a line editor is available) edit the program that is currently stored in memory; these are not preferred</para></listitem>
</varlistentry>
<varlistentry>
<term><code>LOAD</code></term>
<term><code>SAVE</code></term>
<listitem><para>load or save a program to or from memory</para></listitem>
</varlistentry>
<varlistentry>
<term><code>CLEAR</code></term>
<listitem><para>erase all non&#x2010;special variables</para></listitem>
</varlistentry>
<varlistentry>
<term><code>NEW</code></term>
<listitem><para>erase all non&#x2010;special variables and the currently stored program</para></listitem>
</varlistentry>
<varlistentry>
<term><code>TRON</code> (alternatively <code>TRACE&#x00A0;ON</code>)</term>
<term><code>TROFF</code> (alternatively <code>TRACE&#x00A0;OFF</code>)</term>
<listitem><para>turn tracing of program execution on or off</para></listitem>
</varlistentry>
</variablelist>

<para>
Historically, these are things that were part of Dartmouth DTSS and not of Dartmouth BASIC itself.
Modern multiple process operating systems automate loading and clearing a process's program and variable space, have external commands for listing and editing and saving source text files (sometimes even naming them these names), have external debuggers, and handle log&#x2010;in and log&#x2010;out.
</para>

</refsection>

<refsection><title>Control flow statements</title>

<variablelist>

<varlistentry>
<term>
<code>IF&#x00A0;<replaceable>expression</replaceable></code> <code>THEN&#x00A0;<replaceable>statements</replaceable></code>&#x2026; <code>: ELSE&#x00A0;<replaceable>statements</replaceable></code>&#x2026; <code>: END&#x00A0;IF</code> 
</term>
<listitem>
<para>
These statements combine to execute two sets of statements conditionally, based upon evaluating the <replaceable>expression</replaceable>.
<code>THEN</code> and <code>ELSE</code> are two of the few statements that do not require terminating with a colon.
<code>ENDIF</code> is an alternative spelling of the end of the construct.
</para>
<para>
Because this BASIC treats <code>THEN</code> and <code>ELSE</code> as statements, they can occur anywhere that a statement can occur.
Some other interpreted BASICs have special parsing rules that require that they appear as the first keyword on a line.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<code>WHILE&#x00A0;<replaceable>expression</replaceable></code> <code>: <replaceable>statements</replaceable></code>&#x2026; <code>: END&#x00A0;WHILE</code>
</term>
<listitem>
<para>
These statements combine to execute a set of statements conditionally in a loop, while evaluating the <replaceable>expression</replaceable> at the beginning of each loop pass remains true.
<code>ENDWHILE</code> and <code>WEND</code> are alternative spellings of the end of the loop.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<code>REPEAT</code> <code><replaceable>statements</replaceable></code>&#x2026; <code>: END&#x00A0;REPEAT</code>
</term>
<listitem>
<para>
These statements combine to execute a set of statements unconditionally in a loop.
The <code>NEXT&#x00A;</code> statement transfers control back to the start of the loop to begin the next pass.
The <code>EXIT&#x00A;</code> statement transfers control to the end of the loop and exits it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<code>FOR&#x00A0;<replaceable>variable</replaceable>&#x00A0;=&#x00A0;<replaceable>first</replaceable>&#x00A0;TO&#x00A0;<replaceable>last</replaceable>&#x00A0;STEP&#x00A0;<replaceable>increment</replaceable></code> <code>: <replaceable>statements</replaceable></code>&#x2026; <code>: END&#x00A0;FOR</code>
</term>
<listitem>
<para>
These statements combine to execute a set of statements repeatedly, with <replaceable>variable</replaceable> taking successive values from <replaceable>first</replaceable> to <replaceable>last</replaceable> in each loop pass.
<code>ENDFOR</code> is an alternative spelling of the end of the construct.
The <code>NEXT&#x00A;<replaceable>variable</replaceable></code> statement transfers control back to the start of the loop to begin the next pass, or skips to the next <code>END&#x00A0;FOR</code> and exits the loop if the last value has been reached.
The <code>EXIT&#x00A;<replaceable>variable</replaceable></code> statement transfers control to the end of the loop and exits it, potentially terminating the loop early.
</para>
<caution>
<code>NEXT</code> is not the end of a <code>FOR</code> loop and <code>EXIT</code> is not a way to end a program.
</caution>
</listitem>
</varlistentry>

<varlistentry>
<term>
<code>CASE&#x00A0;<replaceable>expression</replaceable>&#x00A0;OF</code> <code>: WHEN&#x00A0;<replaceable>expression</replaceable> : <replaceable>statements</replaceable></code>&#x2026; <code>: OTHERWISE : <replaceable>statements</replaceable></code>&#x2026; <code>: END&#x00A0;CASE</code>
</term>
<listitem>
<para>
These statements combine to execute one from a set of statements, comparing each <replaceable>expression</replaceable> against the initial controlling <replaceable>expression</replaceable> and executing the relevant statements if the comparison evaluates to true.
<code>ENDCASE</code> is an alternative spelling of the end of the construct.
</para>
<para>
This construct is from ARM BASIC, and is one of the things that this BASIC does not take from Sinclair SuperBASIC.
(SuperBASIC has <code>SELECT&#x00A0;<replaceable>variable</replaceable>&#x00A0;ON</code> <code>: ON&#x00A0;<replaceable>variable</replaceable>=<replaceable>expression</replaceable> <replaceable>statements</replaceable></code>&#x2026; <code>: ON&#x00A0;<replaceable>variable</replaceable>=REMAINDER <replaceable>statements</replaceable></code>; <code>: END&#x00A0;SELECT</code>, which would overload <code>ON</code> yet further, and involves unnecessary repetition of <replaceable>variable</replaceable> and a non&#x2010;syntactic remainder expression.)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<code>GO&#x00A0;TO&#x00A0;<replaceable>expression</replaceable></code>
<code>GO&#x00A0;SUB&#x00A0;<replaceable>expression</replaceable></code>
</term>
<listitem>
<para>
This statement transfers control to the line number given by <replaceable>expression</replaceable>.
(Yes, this is computed <code>GOTO</code> and yes that is also an alternative spelling of the statement.)
The <code>GO&#x00A0;SUB&#x00A0;<replaceable>expression</replaceable></code> statement (alternatively <code>GOSUB</code>) does the same, but additionally pushes the location of its own successor statement onto a stack, and control can be transferred back to that point with the <code>RETURN</code> statement.
</para>
<para>
The spellings <code>GO&#x00A0;TO</code> and <code>GO&#x00A0;SUB</code> are from SuperBASIC, and indeed Sinclair ZX BASIC before it.
They cause <code>GO</code>, <code>SUB</code>, and <code>TO</code> to be keywords; although the latter is a keyword <emphasis>anyway</emphasis> from use in <code>FOR</code>, <code>LIST</code>, and <code>DIM</code>.
SuperBASIC added the alternative spellings without spaces, which Sinclair ZX BASIC did not have, but were what Dartmouth BASIC originally had.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
Per SuperBASIC, all pseudo&#x2010;structured constructs are finalized by a variant of <code>END</code>: <code>END&#x00A0;IF</code>, <code>END&#x00A0;WHILE</code>, <code>END&#x00A0;REPEAT</code>, <code>END&#x00A0;CASE</code>, or <code>END&#x00A0;FOR</code>.
(BBC BASIC also had <code>END&#x00A0;IF</code>.)
Neither <code>DO</code> nor <code>LOOP</code> are keywords in this BASIC, just as they were not in BBC BASIC, any Sinclair BASIC, nor any of the Microsoft BASICs before Visual BASIC.
The equivalent to the BBC BASIC's <code>UNTIL <replaceable>expression</replaceable></code> is the construct <code>IF NOT <replaceable>expression</replaceable>: THEN EXIT : ENDIF</code>.
</para>

<para>
Most of the flow control statements push things onto and pop them off a stack.
This stack is not the interpreter's own processor execution stack, but a data structure maintained by the interpreter to record locations and control flow within a BASIC program.
The statement that ends a construct looks for and pops a matching topmost stack record that was pushed by the statement that began the construct; as do intermediaries like <code>NEXT</code>, <code>ELSE</code>, <code>EXIT</code>, and <code>WHEN</code> except that they do not pop the stack.
</para>

<para>
<code>END</code> (on its own) ends running the program and clears the stack, returning to immediate mode.
<code>STOP</code> is a debugging aid that ends running the program, returning to immediate mode, but rather than clearing the stack records where the program stopped so that it can be continued from there with <code>CONT</code>.
</para>

</refsection>

<refsection><title>Operators</title>

<para>
Various punctuation characters, sequences of punctuation characters, and keywords are operators in BASIC, which can be used in expressions:
</para>
<variablelist>
<varlistentry>
<term><code>AND</code></term>
<term><code>EOR</code></term>
<term><code>IMP</code></term>
<term><code>OR</code></term>
<listitem><para>infix logical bitwise and, exclusive or, implication, and inclusive or operations</para></listitem>
</varlistentry>
<varlistentry>
<term><code>&#x003C;</code></term>
<term><code>&#x003E;</code></term>
<term><code>&#x003C;=</code></term>
<term><code>&#x003E;=</code></term>
<term><code>=</code></term>
<term><code>&#x003C;&#x003E;</code></term>
<term><code>&#x003C;=&#x003E;</code></term>
<listitem><para>infix less than, greater than, less than or equal, greater than or equal, equal, not equal, and trinary comparisons</para></listitem>
</varlistentry>
<varlistentry>
<term><code>+</code></term>
<term><code>-</code></term>
<listitem><para>infix arithmetic addition and subtraction operations</para></listitem>
</varlistentry>
<varlistentry>
<term><code>*</code></term>
<term><code>/</code></term>
<term><code>DIV</code></term>
<term><code>MOD</code></term>
<listitem><para>infix arithmetic multiplication, floating point division, integer division, and integer modulus operations</para></listitem>
</varlistentry>
<varlistentry>
<term><code>+</code></term>
<term><code>-</code></term>
<term><code>NOT</code></term>
<listitem>
<para>
unary prefix arithmetic negation and identity operations, and logical bitwise not
</para>
<warning>
The <code>NOT</code> operator is a bitwise not, rather than a boolean one, and any non&#x2010;zero value is considered a successful condition expression.
In particular, <code>IF NOT <replaceable>number</replaceable></code> will only execute a <code>ELSE</code> when <replaceable>number</replaceable> is all bits 1 (i.e. the bitwise not of <code>FALSE</code>).
The relational operators evaluate to the proper <code>TRUE</code> or <code>FALSE</code> values, so <code>IF A% = 0</code> is the right expression for testing whether an integer is zero.
<code>IF NOT (A% = 0)</code> will invert the condition, but <code>IF A% &#x003C;&#x003E; 0</code> is of course simpler.
</warning>
</listitem>
</varlistentry>
</variablelist>

</refsection>

<refsection><title>Functions</title>

<para>
Various keywords are functions in BASIC, which can form primary expressions:
</para>
<variablelist>
<varlistentry>
<term><code>ASC</code></term>
<term><code>CHR$</code></term>
<listitem><para>conversion between an ASCII code and the (1 byte) character that it encodes</para></listitem>
</varlistentry>
<varlistentry>
<term><code>WTF8$</code></term>
<listitem><para>conversion between a Unicode code and the WTF-8 string that it encodes</para></listitem>
</varlistentry>
<varlistentry>
<term><code>COS</code></term>
<term><code>SIN</code></term>
<term><code>TAN</code></term>
<term><code>ACS</code></term>
<term><code>ACOS</code></term>
<term><code>ASN</code></term>
<term><code>ASIN</code></term>
<term><code>ATN</code></term>
<term><code>ATAN</code></term>
<listitem><para>the trigonometric functions and their inverses</para></listitem>
</varlistentry>
<varlistentry>
<term><code>LOG</code></term>
<term><code>LN</code></term>
<term><code>EXP</code></term>
<listitem><para>logarithms and exponentiation</para></listitem>
</varlistentry>
<varlistentry>
<term><code>SPC$</code></term>
<listitem><para>creating a sequence of SPC characters (no TABs or newlines) for aligning output</para></listitem>
</varlistentry>
<varlistentry>
<term><code>TAB$</code></term>
<term><code>CLS$</code></term>
<term><code>COLOUR$</code></term>
<term><code>VDU$</code></term>
<listitem><para>creating ECMA-48 control sequences for positioning output, clearing the screen, and setting colours and attributes; according to the <envar>TERM</envar> and <envar>COLORTERM</envar> environment variables</para></listitem>
</varlistentry>
<varlistentry>
<term><code>HEX$</code></term>
<term><code>OCT$</code></term>
<term><code>STR$</code></term>
<listitem><para>converting a number to its hexadecimal, octal, or decimal representation</para></listitem>
</varlistentry>
<varlistentry>
<term><code>DEG</code></term>
<term><code>RAD</code></term>
<listitem><para>interconverting degrees and radians</para></listitem>
</varlistentry>
<varlistentry>
<term><code>ABS</code></term>
<term><code>SGN</code></term>
<term><code>INT</code></term>
<listitem><para>obtaining the absolute value, sign, or integer part of a number</para></listitem>
</varlistentry>
<varlistentry>
<term><code>LEFT$</code></term>
<term><code>MID$</code></term>
<term><code>RIGHT$</code></term>
<listitem><para>returning the left, middle, or right parts of a string</para></listitem>
</varlistentry>
<varlistentry>
<term><code>LEN</code></term>
<term><code>DIM</code></term>
<listitem><para>returning the length of a string and the dimensions of an array</para></listitem>
</varlistentry>
<varlistentry>
<term><code>INSTR</code></term>
<listitem><para>finding the position of a string inside another string</para></listitem>
</varlistentry>
<varlistentry>
<term><code>STRING$</code></term>
<listitem><para>creating multiple concatenated copies of a single string</para></listitem>
</varlistentry>
<varlistentry>
<term><code>SQR</code></term>
<listitem><para>obtaining the square root of a number</para></listitem>
</varlistentry>
<varlistentry>
<term><code>INKEY$</code></term>
<listitem><para>wait for an input key control sequence, with a timeout</para></listitem>
</varlistentry>
</variablelist>

</refsection>

<refsection><title>Pseudo&#x2010;variables</title>

<para>
Various keywords are pseudo&#x2010;variables in BASIC, which can form primary expressions:
</para>
<variablelist>
<varlistentry>
<term><code>PI</code></term>
<listitem><para>a <emphasis>best approximation</emphasis>, in floating point, to the value of &#x03C0;</para></listitem>
</varlistentry>
<varlistentry>
<term><code>TRUE</code></term>
<term><code>FALSE</code></term>
<listitem><para>true and false as returned by relational operators and as useful for bitwise logical operators</para></listitem>
</varlistentry>
<varlistentry>
<term><code>NAN</code></term>
<term><code>INF</code></term>
<listitem><para>floating point (positive, quiet) Not-A-Number and (positive) Infinity values</para></listitem>
</varlistentry>
<varlistentry>
<term><code>ENV$</code></term>
<term><code>ARG$</code></term>
<listitem><para>querying the Unix environment and argument string collections</para></listitem>
</varlistentry>
<varlistentry>
<term><code>UNAME$</code></term>
<listitem><para>querying the operating system (kernel) name</para></listitem>
</varlistentry>
<varlistentry>
<term><code>DATE$</code></term>
<listitem><para>obtaining the current date and time in ISO 8601 form</para></listitem>
</varlistentry>
<varlistentry>
<term><code>GET$</code></term>
<listitem><para>effectively <code>INKEY$(-1)</code></para></listitem>
</varlistentry>
</variablelist>
</refsection>

<refsection><title>Other statements</title>

<para>
Various keywords are statements in BASIC:
</para>
<variablelist>
<varlistentry>
<term><code>HELP</code></term>
<listitem><para>print some help text</para></listitem>
</varlistentry>
<varlistentry>
<term><code>CLG</code></term>
<listitem><para>clear the graphics screen (if available)</para></listitem>
</varlistentry>
<varlistentry>
<term><code>PRINT</code></term>
<listitem><para>print a list of output values, optionally separated by TAB characters and optionally ended with a newline sequence</para></listitem>
</varlistentry>
<varlistentry>
<term><code>LET</code></term>
<listitem><para>assign the value of an expression to a target, declaring it if neccessary and it is a scalar variable</para></listitem>
</varlistentry>
<varlistentry>
<term><code>SWAP</code></term>
<listitem><para>swap the values of two variables</para></listitem>
</varlistentry>
<varlistentry>
<term><code>DIM</code></term>
<listitem><para>declare an array or a scalar variable</para></listitem>
</varlistentry>
</variablelist>

<para>
<code>LET</code> is optional in an assignment.
However, if it is omitted, the variable is not implicitly declared, and if it has not been declared earlier, the assignment causes an error.
</para>

<para>
Before use in an expression or in an assignment without <code>LET</code> every variable must have already been declared with a previously executed <code>LET</code>, <code>DIM</code>, or <code>FOR</code>.
A <emphasis>very</emphasis> common programming error in the Home Computer BASICs, that Microsoft had to invent <code>OPTION EXPLICIT</code> for and TrueBASIC people invented <code>OPTION TYPO</code> for, is mis&#x2010;spelling a variable name and accidentally using some other variable.
In this BASIC, the stricter behaviour that Microsoft and the TrueBASIC people came up with is not optional.
</para>

</refsection>

</refsection>

<refsection><title>Differences from other dialects of BASIC</title>

<refsection><title>Spaghetto!</title>

<para>
Elements like <code>THEN</code>, <code>WHEN</code>, <code>WEND</code>, <code>END&#x00A0;FOR</code>, <code>ELSE</code>, and <code>END&#x00A0;IF</code> may give the appearance of structured code, but they are in fact statements as well.
Because of <code>GOTO</code>, they may even appear out of order in the program, as long as they are executed by the interpreter in the properly nested order that respects the BASIC stack.
</para>

<para>
<code>GOTO</code> can be used to create awful unmaintable code, and is famously a bad thing.
The BBC BASIC x86 manual has an example in its section on (the BBC BASIC) <code>REPEAT</code> where an <code>UNTIL&#x00A0;TRUE</code> has to be inserted in order to properly pop the BASIC stack.
It calls it <quote>ghastly</quote>.
</para>

<para>
Compiled BASICs militated against this, by enforcing a grammar for the token sequence; but this BASIC is interpreted.
</para>

<para>
BBC BASIC was even worse and kept multiple separate stacks for different control flow constructs, allowing for (say) a <code>RETURN</code> from a subroutine inside a <code>REPEAT</code> or a <code>FOR</code> loop.
This BASIC, like later ARM BASIC and BBC BASIC x86, has a unified stack, and thus at least enforces a nested order across all constructs.
</para>

</refsection>

<refsection><title>Video terminal I/O</title>

<para>
In general, the multiple fixed&#x2010;width fields paradigm of Dartmouth BASIC and the Home Computer BASICs is not followed when it comes to <code>PRINT</code>.
Moreover, neither <citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry> nor <citerefentry><refentrytitle>basica</refentrytitle><manvolnum>1</manvolnum></citerefentry> can track the <quote>count</quote> position of standard output, as (unlike Home Computer BASICs) they have no access to display hardware cursor position information (and standard output need not be a terminal device at all).
</para>

<para>
A more Unix&#x2010;like TAB-separated style is followed instead.
A comma in a <code>PRINT</code> statement emits a TAB character, to whatever output file or device standard output may be; and there is no justification (left or right) within fields, elements being output with no padding.
</para>

<para>
This BASIC is designed around video terminals being controlled by ECMA-48 control sequences.
It adopts the idea from TrueBASIC that instead of specialized keywords in <code>PRINT</code>, programs call functions that simply make the requisite strings containing the control sequences, and those strings can be assigned to a variable or printed as&#x2010;is.
So instead of there being specialized <code>VDU</code>, <code>CLS</code>, <code>LOCATE</code> (IBM BASIC/BASICA), <code>AT</code> (Sinclair ZX BASIC), and <code>COLOUR</code> statements, and there being specialized <code>PRINT TAB</code> or <code>PRINT @</code> (Dragon BASIC) syntax specific to <code>PRINT</code>, there are <code>CLS$</code>, <code>COLOUR$</code>, <code>TAB$</code>, and <code>VDU$</code> that create ECMA-48 control sequences appropriate to the current terminal, following the same design logic as <code>CHR$</code>, <code>SPC$</code>, and TrueBASIC's <code>USING$</code>.
The <quote>$</quote> added to the keywords indicates that they are returning a string.
</para>

<para>
The one&#x2010;argument <code>TAB$(C%)</code> generates an absolute horizontal position control sequence string for a video terminal, rather than a sequence of SPC and NEL characters designed for a line printer.
It can reposition in both directions on the current output line.
The two&#x2010;argument <code>TAB$(C%,R%)</code> generates an absolute horizontal and vertical position control sequence string.
</para>

<para>
The one&#x2010;argument <code>VDU$(I%)</code> is only well&#x2010;defined when that argument is a character code in the ECMA-35 C0 or C1 control character ranges.
Do not use it for other character codes.
Depending from the values of the <envar>TERM</envar> and <envar>COLORTERM</envar> environment variables, it will either give the same result as <code>WTF8$</code> or return a 7&#x2010;bit ECMA-35 alias encoded string.
It is intended that whatever it gives will match how <code>GET$</code> encodes C0 and C1 control characters, so that it can be used to parse that.
</para>

<para>
The two&#x2010;argument <code>VDU$(I%,J%)</code> switches an ECMA-48 <quote>graphic rendition</quote> on and off.
<code>J%</code> should be either <code>TRUE</code> or <code>FALSE</code> and <code>I%</code> encodes the GR:
</para>
<variablelist>
<varlistentry><term>1</term><listitem><para>boldface</para></listitem></varlistentry>
<varlistentry><term>2</term><listitem><para>faint</para></listitem></varlistentry>
<varlistentry><term>3</term><listitem><para>italics</para></listitem></varlistentry>
<varlistentry><term>4</term><listitem><para>underline</para></listitem></varlistentry>
<varlistentry><term>7</term><listitem><para>inverse</para></listitem></varlistentry>
<varlistentry><term>9</term><listitem><para>strikethrough</para></listitem></varlistentry>
<varlistentry><term>51</term><listitem><para>frame</para></listitem></varlistentry>
<varlistentry><term>52</term><listitem><para>encircle</para></listitem></varlistentry>
<varlistentry><term>53</term><listitem><para>overline</para></listitem></varlistentry>
</variablelist>
<note>
Some graphic renditions when turned off will also turn off some of the others at the same time.
See ECMA-48 for details.
</note>

<para>
The <code>GETS$</code> pseudo&#x2010;variable and the <code>INKEY$(I%)</code> function may return strings of greater than length 1.
Depending from the values of the <envar>TERM</envar> and <envar>COLORTERM</envar> environment variables, control characters may be encoded as if by <code>WTF8$</code> or as a 7&#x2010;bit ECMA-35 alias string.
Function keys, extended keys, and consumer keys are encoded as Shift State 2, 3, or L modified characters, or as full ECMA-48 FNK or private FNK sequences.
</para>
<note>
<citerefentry><refentrytitle>basica</refentrytitle><manvolnum>1</manvolnum></citerefentry> renormalizes some private FNK control sequences, because cross&#x2010;terminal function key handling would be a right old mess otherwise.
</note>

</refsection>

</refsection>

<refsection><title>See also</title>
<variablelist>
<varlistentry>
<term><citerefentry><refentrytitle>TERM</refentrytitle><manvolnum>7</manvolnum></citerefentry></term>
<term><citerefentry><refentrytitle>COLORTERM</refentrytitle><manvolnum>7</manvolnum></citerefentry></term>
<listitem>
<para>The affect the results of <code>TAB$</code>, <code>CLS$</code>, <code>COLOUR$</code>, and <code>VDU$</code>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsection>

<refsection><title>Author</title>
<para><author><personname><firstname>Jonathan</firstname> <surname>de Boyne Pollard</surname></personname></author></para>
</refsection>

</refentry>
