<?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="list">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>list</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">user commands</refmiscinfo>
<refmiscinfo class="source">BASIC</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv>
<refname>list</refname>
<refpurpose>list a BASIC program</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>list</command>
<arg choice='opt' repeat='rep'><replaceable>filename(s)</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>
<command>list</command> lists one or more BASIC program files.
The language that it understands is described in <citerefentry><refentrytitle>BASIC</refentrytitle><manvolnum>5</manvolnum></citerefentry>, and it uses BASIC's tokenizer.
</para>

<para>
The user interface is a straightforward Unix filter, reading lines as they come from standard input or reading the contents of the files given as <arg choice='plain'><replaceable>filename(s)</replaceable></arg>.
For each file, it will tokenize a full BASIC program from that file, and list it.
For standard input, it will tokenize one full BASIC program file until EOF, and list that.
Line numbers may be used, but immediate&#x2010;only statements are prohibited.
</para>

<note>
<code>list</code> does not add line numbers of its own, nor does it require that line numbers be in any particular order.
However, if two lines have the same number, <citerefentry><refentrytitle>BASIC</refentrytitle><manvolnum>5</manvolnum></citerefentry> will overwrite the earlier line with the later one as the file is being loaded.
</note>

<para>
The program is written to standard output, colourized to indicate BASIC keywords, operators, literals, and other tokens.
All FFs, TABs, CRs, and VTs are collapsed to SPC characters by the tokenizer.
</para>

<caution>
<code>list</code> prints all strings as they are given in the program code, including any embedded escape sequences and control sequences, a common idiom in programs from the Home Computer Era.
Programs can be pre&#x2010;processed through <citerefentry><refentrytitle>vis</refentrytitle><manvolnum>1</manvolnum></citerefentry> or post&#x2010;processed by a tool that ignores most control sequences, such as <citerefentry><refentrytitle>console-tty37-viewer</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</caution>

</refsection>

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

<variablelist>
<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>list</command> was written in 2026, to accompany <citerefentry><refentrytitle>basic</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>

<para>
It was inspired by the fact that in Dartmouth BASIC, <code>LIST</code> was actually a DTSS operating system command.
</para>

</refsection>

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

</refentry>
