<?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>1</manvolnum>
<refmiscinfo class="manual">user commands</refmiscinfo>
<refmiscinfo class="source">BASIC</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv>
<refname>basic</refname>
<refpurpose>run BASIC</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>basic</command>
<group choice='opt'>
<arg choice='plain'>-v</arg>
<arg choice='plain'>--verbose</arg>
</group>
<group choice='opt'>
<arg choice='plain'>-x</arg>
<arg choice='plain'>--xtrace</arg>
</group>
<arg choice='opt'>--dump</arg>
</cmdsynopsis>
<cmdsynopsis>
<command>basic</command>
<group choice='opt'>
<arg choice='plain'>-v</arg>
<arg choice='plain'>--verbose</arg>
</group>
<group choice='opt'>
<arg choice='plain'>-x</arg>
<arg choice='plain'>--xtrace</arg>
</group>
<arg choice='opt'>--dump</arg>
<group choice='plain'>
<arg choice='plain'>-c</arg>
<arg choice='plain'>--command <replaceable>command</replaceable></arg>
</group>
<arg choice='opt' repeat='rep'><replaceable>argument(s)</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>basic</command>
<group choice='opt'>
<arg choice='plain'>-v</arg>
<arg choice='plain'>--verbose</arg>
</group>
<group choice='opt'>
<arg choice='plain'>-x</arg>
<arg choice='plain'>--xtrace</arg>
</group>
<arg choice='opt'>--dump</arg>
<arg choice='plain'><filename><replaceable>filename</replaceable></filename></arg>
<arg choice='opt' repeat='rep'><replaceable>argument(s)</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>
<command>basic</command> is a BASIC interpreter.
The language that it interprets is described in <citerefentry><refentrytitle>BASIC</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Unlike <citerefentry><refentrytitle>basica</refentrytitle><manvolnum>1</manvolnum></citerefentry>, it does not require a controlling terminal, does not absorb typed&#x2010;ahead input, and can be used as a simple Unix filter.
But the BASIC mechanisms for dealing with columns and rows on the screen will not work with it.
</para>

<para>
The <arg choice='plain'>--xtrace</arg> command&#x2010;line option sets the initial tracing mode, which may be altered by the <code>TRON</code> and <code>TROFF</code> (a.k.a. <code>TRACE&#x00A0;ON</code> and <code>TRACE&#x00A0;OFF</code>) statements.
</para>

<para>
The <arg choice='plain'>--verbose</arg> command&#x2010;line option controls the verbosity of error messages.
In verbose mode, extra information is printed.
</para>

<refsection><title>Non&#x2010;interactive modes</title>

<para>
If invoked with the <arg choice='plain'>--command</arg> command&#x2010;line option, it will treat <replaceable>command</replaceable> as one or more lines of BASIC code, tokenize it, and run it.
The interpreter is in immediate mode.
Line numbers are not allowed, but immediate&#x2010;only statements are.
</para>

<para>
If invoked with a <filename><replaceable>filename</replaceable></filename>, it will read a full BASIC program from that file, and run it.
The interpreter is in program mode.
Line numbers may be used, but immediate&#x2010;only statements are prohibited.
</para>

<note>
Immediate and program modes are modes of the BASIC interpreter and are described in in <citerefentry><refentrytitle>BASIC</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Interactive and non&#x2010;interactive modes are modes of the user interface, and not the same thing.
They refer to whether <command>basic</command> is interacting on the fly with a user (or something pretending to be a user) via standard input, or it is running a pre&#x2010;written command line or program file.
</note>

</refsection>

<refsection><title>Interactive mode</title>

<para>
If invoked with neither <replaceable>command</replaceable> nor <replaceable>filename</replaceable>, it enters an interactive mode.
Program code may be entered and altered by entering lines starting with a line number, which will be tokenized and upserted into the (single) program stored in memory.
Immediate code may be entered by entering numberless lines, which are tokenized and then run immediately.
</para>

<para>
This is signalled by the usual BASIC convention of printing
</para>

<screen><computeroutput>READY.
</computeroutput></screen>
<para>
followed by the interactive prompt (currently nothing).
</para>

<tip>
Although interactive mode has the temptation of the Home Computer BASIC experience, the recommended way of working, as explained in detail in <citerefentry><refentrytitle>BASIC</refentrytitle><manvolnum>5</manvolnum></citerefentry>, is to use the operating system as far as possible to list and edit programs, per Dartmouth DTSS and Acorn BASIC, and run them from file non&#x2010;interactively or use <code>LOAD</code> interactively.
</tip>

</refsection>

</refsection>

<refsection><title>Unix filter</title>

<para>
The user interface is a straightforward Unix filter, reading lines as they come from standard input.
There is no line editing at all beyond what the operating system supplies on terminal devices.
There are no ways to cancel a running program and return to immediate mode.
</para>

<para>
Fatal signals, from the terminal line discipline or otherwise, will kill the whole interpreter unceremoniously.
Either end of input or the (immediate&#x2010;only) <code>BYE</code> statement will exit BASIC.
A (terminal or explicit) suspend signal will suspend the interpreter program without its knowledge.
</para>

<para>
<code>INKEY$</code> will not work as expected, <code>COUNT</code> will have a fixed arbitrary value, and <code>WIDTH</code> will be calculated just once at program startup.
The messages sent by <code>BYE</code> and the implicit <code>HELLO</code> in interactive mode will appear in any collected output.
In general, interactive mode in <code>basic</code> is as poor as it is for <citerefentry><refentrytitle>dash</refentrytitle><manvolnum>1</manvolnum></citerefentry> when both <code>vi</code> and <code>emacs</code> modes are turned off.
(The Almquist shell is one of the few shells where it is still possible to turn the built&#x2010;in line editor completely off and use the native Unix terminal line discipline's behaviour.)
</para>

<para>
Output and error messages from BASIC go to standard output and standard error respectively.
They expect ECMA-48 as a minimum and are not completely interoperable with the (historic in this century) really dumb <quote>glass teletype</quote> class of video terminal, or with paper terminals.
See <citerefentry><refentrytitle>TERM</refentrytitle><manvolnum>7</manvolnum></citerefentry> and <citerefentry><refentrytitle>TerminalCapabilities</refentrytitle><manvolnum>3</manvolnum></citerefentry> for how <command>basic</command> determines the terminal type and what can be done with the terminal.
</para>

<para>
The <arg choice='plain'>--dump</arg> command&#x2010;line option causes the tokenized program read from file, or the tokenized <replaceable>command</replaceable> from the command line, or a tokenized line of input read in interactive mode, to be printed out before it is run.
The code is printed out as tokenized.
This reveals what has and has not been recognized as a BASIC keyword, or a numeric or string literal; and also shows numbers as they have been normalized by the BASIC interpreter.
</para>

</refsection>

<refsection><title>Environment variables</title>

<variablelist>
<varlistentry>
<term><envar>COLUMNS</envar></term>
<listitem><para>
Unix standard override for the number of columns on standard output.
In the absence of this variable, the terminal line discipline, if present, is queried for the terminal width, defaulting to 80 columns for non&#x2010;terminals.
This can be used from BASIC via the <code>WIDTH</code> special variable.
</para><note>
Because <command>basic</command> has neither a full&#x2010;screen nor an open&#x2010;mode user interface, the width will not reflect the terminal width if that changes.
</note></listitem>
</varlistentry>
<varlistentry>
<term><envar>CLICOLOR</envar></term>
<term><envar>CLICOLOR_FORCE</envar></term>
<listitem><para>
Control whether colour is used, per <citerefentry><refentrytitle>CLICOLOR</refentrytitle><manvolnum>7</manvolnum></citerefentry> and <citerefentry><refentrytitle>CLICOLOR_FORCE</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
</variablelist>

</refsection>

<refsection><title>History</title>

<para>
This <command>basic</command> was written in 2026, inspired by a post on Hacker News.
</para>

<para>
Its name is a nod to the <command>BASIC</command> utility on PC-DOS, which did little more than invoke the IBM BASIC interpreter that IBM supplied in ROM.
That original command did not support the <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>&#x2010;like syntax that this command has.
</para>

</refsection>

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

</refentry>
