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

<refnamediv>
<refname>basica</refname>
<refname>gwbasic</refname>
<refpurpose>run BASIC</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>basica</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>basica</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>basica</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>basica</command> is a BASIC interpreter.
The language that it interprets is described in <citerefentry><refentrytitle>BASIC</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Unlike <citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry>, it requires a controlling terminal, and the BASIC mechanisms for dealing with columns and rows on the screen will work with it.
But it cannot be used as a simple Unix filter, and its user interface will soak up typed&#x2010;ahead input into BASIC's own input queue.
</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 textual user interface, and not the same thing.
They refer to whether <command>basica</command> is interacting on the fly with a user (or something pretending to be a user) at a terminal device, 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
</para>
<screen><computeroutput>&#x003e;</computeroutput>
</screen>

<para>
Fatal signals, from the terminal line discipline or otherwise, are intercepted by <command>basica</command> and it will shut down its TUI gracefully in response to them.
The (immediate&#x2010;only) <code>BYE</code> statement will exit BASIC.
</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.
As mentioned further on, the TUI has the usual Unix interactive line&#x2010;editable convention of being suspendable; so one can switch to an editor with a job&#x2010;control shell.
</tip>

</refsection>

<refsection><title>Textual user interface</title>

<para>
The user interface is always active in both interactive and non&#x2010;interactive modes.
This is because it provides mechanisms to the interpreter such as positioning the cursor around the screen.
It uses the process's controlling terminal device; and <command>basica</command> cannot be run without a controlling terminal.
</para>

<para>
In interactive mode the TUI is similar to the <quote>open mode</quote> of the original <citerefentry><refentrytitle>vi</refentrytitle><manvolnum>1</manvolnum></citerefentry>/<citerefentry><refentrytitle>ex</refentrytitle><manvolnum>1</manvolnum></citerefentry>, and to the line&#x2010;editing modes of most shells.
The user can edit a single line at a time.
The arrow keys can move around that line, DEL and BS (whichever keys generate them) delete forwards and backwards, FF or DC2 (usually <keycap>&#x2388;&#160;Control</keycap>+<keycap>L</keycap> and <keycap>&#x2388;&#160;Control</keycap>+<keycap>R</keycap>) redraw the line afresh, SOH and ENQ (<keycap>&#x2388;&#160;Control</keycap>+<keycap>A</keycap> and <keycap>&#x2388;&#160;Control</keycap>+<keycap>E</keycap>) move to the start and end of the line, VT and NAK (<keycap>&#x2388;&#160;Control</keycap>+<keycap>K</keycap> and <keycap>&#x2388;&#160;Control</keycap>+<keycap>U</keycap>) delete to the end or to the beginning of the line, ETX (usually <keycap>&#x2388;&#160;Control</keycap>+<keycap>C</keycap>) is Cancel, SUB (usually <keycap>&#x2388;&#160;Control</keycap>+<keycap>Z</keycap>) is Suspend, and EOT (usually <keycap>&#x2388;&#160;Control</keycap>+<keycap>D</keycap>) is Exit.
</para>

<para>
Although the cursor can be freely moved left, right, up and down within that line, all output cursor motion is relative.
This is not a full-screen textual user interface, and it can operate with video terminals that are not fully featured, although it does expect ECMA-48 as a minimum and is 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 it determines the terminal type and what can be done with the terminal.
</para>

<para>
In non&#x2010;interactive mode, or when a program or a line of immediate mode code is running, the TUI queues up controlling terminal input for <code>INKEY$</code>, with two exceptions.
The first exception is that Cancel or Close will stop a running program and are not queued.
The second exception is that Suspend will suspend the entire interpreter process and is not queued.
</para>

<para>
<code>COUNT</code> has a fixed arbitrary value, but <code>WIDTH</code> will track the controlling terminal width as it changes.
(However, this may not be the same as the width for whatever device is standard output.)
The messages sent by <code>BYE</code> and the implicit <code>HELLO</code> in interactive mode go to the controlling terminal and will not appear in any collected standard output.
</para>

<para>
Output and error messages from BASIC go to standard output and standard error respectively.
Input is not taken from standard input.
</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>

<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>
This override is almost never useful for <quote>open mode</quote> TUI programs such as <code>basica</code> which rely upon automatic right margin wrap but have to account for most terminals not being capable of automatic left margin wrap.
</note></listitem>
</varlistentry>
<varlistentry>
<term><envar>TUICOLOUR</envar></term>
<term><envar>TUICOLOUR_FORCE</envar></term>
<listitem><para>
Control whether colour is used, per <citerefentry><refentrytitle>TUICOLOUR</refentrytitle><manvolnum>7</manvolnum></citerefentry> and <citerefentry><refentrytitle>TUICOLOUR_FORCE</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para></listitem>
</varlistentry>
</variablelist>

</refsection>

<refsection><title>History</title>

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

<para>
Its name is a nod to the <command>BASICA</command> utility on PC-DOS, which provided an <quote>advanced</quote> flavour of the IBM BASIC interpreter that IBM supplied in ROM.
Its <command>gwbasic</command> alias is a nod to the <command>GWBASIC</command> (<quote>Gee Whiz</quote> flavour) utility on MS-DOS, which invoked a standalone Microsoft BASIC on machines that did not necessarily have IBM BASIC in ROM.
Neither of those original commands supported 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>
