1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
|
=======
listbas
=======
--------------------------------------------------------
List the source of a tokenized Atari 8-bit BASIC program
--------------------------------------------------------
.. include:: manhdr.rst
SYNOPSIS
========
listbas [**-a** | **-d** | **-m** | **-x** | **-U**] [**-B**] [**-u**] [**-i**] [**-l**] [**-n** | **-C**] [**-v**] [**-c** *colors*] **input-file**
DESCRIPTION
===========
**listbas** acts like the *LIST* command in BASIC. It reads a
tokenized (SAVEd) BASIC program and prints the code in human-readable
format.
By default, output is Unicode in UTF-8 encoding, with ANSI/VT220
escape sequences for inverse video and color syntax highlighting.
**listbas** supports several BASIC dialects used on the Atari. By
default, the BASIC dialect is autodetected by running **whichbas**\(1)
as an external process.
OPTIONS
=======
BASIC options
-------------
**-b**
Set the BASIC dialect the program was written in. This disables
autodetection. Supported dialects are:
**-ba**
Atari BASIC.
**-ba+**
OSS BASIC/A+.
**-bt**
Turbo BASIC XL.
**-bxl**
OSS BASIC XL.
**-bxe**
OSS BASIC XE.
If you see lots of "bad token XX" messages, or if the code just doesn't
make any sense, you're using the wrong BASIC option. **whichbas**\(1)
can usually detect the BASIC a program was written in, but if the
results are ambiguous, **listbas** will assume Turbo BASIC XL.
**-i**
Include the immediate mode command (line 32768) in the output.
**-l**
Do not print line numbers at the start of each line. **GOTO**, **GOSUB**,
**TRAP**, and **THEN** target line numbers are still printed.
Output modes
------------
The default output mode is Unicode/UTF-8 representations of ATASCII
characters.
**-U**
Output Unicode/UTF-8 representations of ATASCII characters. This is
the default output mode; the **-U** option is provided so you can
override **-a**, **-d**, **-m**, **-x** in **LISTBAS_OPTS** (see
**ENVIRONMENT**, below).
**-x**
Output Unicode/UTF-8 representations of the XL International Character
Set, rather than ATASCII.
**-a**
Output raw ATASCII; no translation to the host character set. Must be
used with redirection; **listbas** will not write ATASCII to the terminal.
**-m**
Output "magazine listing". See the **-m** option for **a8cat**\(1) for details.
Color is supported in this mode. No Unicode/UTF-8 characters are printed in
this mode.
**-d**
Print dots rather than Unicode/UTF-8 characters. Color and inverse
video are still supported in this mode, but no Unicode/UTF8 characters
are printed. Use this only if your terminal *really* doesn't support
Unicode (e.g. **rxvt**\(1))... but even then, **-m** is preferred,
because you can't tell what the dots are supposed to represent.
Other display options
---------------------
**-C**
Enable color syntax highlighting. This option is enabled by default;
the **-C** option is provided so you can override **-n** in
**LISTBAS_OPTS** (see **ENVIRONMENT**, below).
**-n**
No color. Has no effect if **-a** is in effect, since this
mode doesn't support color anyway. Disabling color does not
disable reverse video.
**-B**
Use bold for color output. This may make it easier to read on
some terminals. Or, it may hurt your eyes...
**-u**
Use underlining for inverse video, rather than reverse video output.
**-c** *colors*
Customize the color scheme. See **COLORS**, below, for the format of the
*colors* argument. Once you've found a set of colors you like,
you can place this option in the **LISTBAS_OPTS** environment variable
to use your colors by default. See **ENVIRONMENT**, below.
.. include:: genopts.rst
COLORS
======
Color output only works on terminal emulators (or real terminals)
that support ANSI/VT220 style escape codes. This includes all modern
terminal emulators, and most not-so-modern ones in the UNIX world. See
**NOTES** for a list of tested terminal emulators.
You can customize the colors by using the **-c** *colors* option, either
on the command line, or in the **LISTBAS_OPTS** environment variable.
*colors* is a string of exactly 8 characters, each of which must be the
digits *0* through *7* to specify a color, or the letter *n* to specify
no color.
The colors are the standard ANSI ones, plus *n*:
*0*
Black.
*1*
Red.
*2*
Green.
*3*
Yellow (or brown/orange, on some terminals).
*4*
Blue.
*5*
Purple (aka violet).
*6*
Cyan.
*7*
White.
*n*
No custom color. Output will be in the terminal's default foreground color.
The order they're used in the *colors* argument is:
**1**
BASIC keywords. Default: *3* (yellow).
**2**
Operators, including quotes around strings and commas between **DATA** items. Default: *2* (green).
**3**
Functions. Default: *5* (purple).
**4**
Constants (numeric or string). Default: *1* (red).
**5**
Line numbers (at the start of a line only; **GOTO** and **GOSUB** line numbers
are constants). Default: *6* (cyan).
**6**
**REM** text. Default: *4* (blue).
**7**
**DATA** items (but not the commas between them). Default: *6* (cyan).
**8**
Variable names. Default: *n* (uncolorized).
So, the default color scheme is equivalent to:
**-c** *3251646n*
Black and white are not used by default because presumably, one or the
other is the background color of the terminal.
NOTES
=====
**listbas** will refuse to operate on a LIST-protected program with
scrambled variable names. For code-protected programs, it will stop at
the line with the invalid offset. Use **unprotbas**\(1) to remove the
protection.
--
**listbas** is similar to Jindroush's **chkbas**\(1). The main differences are:
- **listbas** prints ATASCII graphics as Unicode equivalents, so the listing
looks very similar to how it would appear on the Atari.
- **listbas** does color syntax highlighting.
- **listbas** supports OSS BASIC/A+ in addition to Turbo and BXL/BXE.
- **listbas** doesn't show information about the variables. Use **vxrefbas**\(1)
for that.
- **listbas** will not write ATASCII data to your terminal. By default, it
converts ATASCII characters into Unicode/UTF-8 characters
that won't confuse the terminal. When outputting raw ATASCII (**-a** option),
it refuses to run if standard output is a terminal.
- **listbas** only lists line 32768 (the immediate mode command) if
specifically asked to do so.
- **listbas** doesn't print a banner on startup.
- **listbas** tells you if the program is protected, and refuses to operate
on variable-protected programs. For code-protected programs, it lists
the program up to the "poisoned" line (normally the last line).
--
The color and inverse/bold/underline support assumes your terminal supports
ANSI/VT220 escape codes... but it does *not* use **curses**\(3X) or
**terminfo**\(5), or even look at **TERM** in the environment. It just
blindly emits the escape codes. Likewise, Unicode characters are printed
in UTF-8 encoding, without actually checking whether the terminal or the
current locale supports UTF-8.
**listbas** has been tested and is known to work in at least these
terminals:
**rxvt-unicode**, aka **urxvt**. This is the terminal the author uses.
**xterm** - tested frequently. Requires the XTerm.locale resource
to be set to **UTF-8** (e.g. in **~/.Xdefaults**\), or the **-lc**
and/or **-en UTF-8** command line options.
**Linux console** - works fine, but good luck finding a font with
all the Unicode graphics characters. Better use **-m**.
**kitty** - very fancy terminal emulator that supports both X11 and
Wayland. **listbas** was only tested on X11.
**xfce4-terminal** - version 0.8.10, with XFCE4 4.16.0.
**konsole** - the KDE terminal, from KDE 5.90.
**gnome-terminal** - version 3.43.90.
**st** - minimal terminal from suckless.org, version 0.9.2.
**mlterm** - version 3.9.3.
**kmscon** - version 9.0.0. https://github.com/Aetf/kmscon
**fbterm** - version 1.8. https://github.com/sfzhi/fbterm
Also, **rxvt** and **aterm** don't support Unicode, but they will
otherwise work (display color and inverse) with the **-m** or **-d**
options to **listbas**.
--
I thought about adding an HTML output option, but there's no need: if you want
a colorful listing of an Atari BASIC program, install **aha**\(1) from
https://github.com/theZiz/aha (or your distro's package repo) and run
something like::
listbas PROGRAM.BAS | aha > program.html
ENVIRONMENT
===========
**LISTBAS_OPTS**
If this environment variable is set, **listbas** parses its value as though
the contents were placed on the command line as options, preceding any actual
option. Example::
export LISTBAS_OPTS="-c123456 -d"
If you place the above line in your shell's startup script, **listbas** will
use your custom color scheme, and will default to the "dots" output mode. If
you then run **listbas** the **-c** and/or **-x**, **-m** options, the options
on the command line will override the environment.
EXIT STATUS
===========
0 for success, 1 if there was an error reading the input (e.g. file
not found), or 2 if the input file has invalid tokens (if this
happens, you will also see a warning about it on stderr).
.. include:: manftr.rst
|