DUMPBAS(1)

NAME
dumpbas - Formatted hexdump for tokenized Atari 8-bit BASIC files

SYNOPSIS

dumpbas [-v] [-l lineno] [-s start-lineno] [-e end-lineno] input-file

DESCRIPTION

dumpbas reads a tokenized Atari 8-bit BASIC program and prints a formatted hexdump on standard output. The formatting groups the hex bytes by line and statement, and includes special characters to mark different types of token (see FORMATTING, below).

dumpbas does not detokenize BASIC programs or dump information about variable names/values. Use chkbas(1) for that. This tool is intended to help the user learn about the tokenized BASIC format, or as an aid for developing/debugging other tools that process tokenized files. It's an alternative to looking at raw hex dumps.

It's assumed the user has at least some knowledge of BASIC's tokenized SAVE format. The Atari BASIC Sourcebook is a good starting point for learning the tokenized format.

OPTIONS

  Dump Options

-s start-lineno
    Don't dump lines before start-lineno. Default: 0.

-e end-lineno
    Don't dump lines after start-lineno. Default: 32768.

-l lineno
    Only dump one line. This is exactly equivalent to "-s lineno -e lineno".

  General Options

--help
    Print usage message and exit.

--version
    Print version number and exit.

-v  Verbose operation. When displaying a number in verbose mode, it will be prefixed with $ if it's in hex, or no prefix for decimal.

FORMATTING

Every byte in the file is displayed in hex. However, they are grouped by line and statement, and certain tokens get marker characters to help keep track of what they're for. Strings are displayed in quotes, in both hex and ASCII. Floating point constants are displayed as 6 hex bytes with square brackets around them.

  Line Header Markers

@   Separates decimal line number from hex file offset.

^   Prefix for line length.

( ) Surrounds the 2 hex bytes for the line number.

  Statement Markers

>   Prefix for next-statement offset. Every statement begins with this.

!   Prefix for a command token. Every line of BASIC code begins with a command.

:   Suffix for the 14 token; end of statement.

#   Prefix for the 0e token, which introduces a BCD floating point constant.

[ ] Surrounds the 6 bytes of a BCD floating point constant.

$   Prefix for the 0f token, which introduces a string constant.

=   Prefix for the string-length byte of a string constant.

  String Byte Markers

"   A string constant is surrounded by double-quotes.

^   Prefix for a control character. For instance, 03 is displayed as ^C.

|   Prefix for an inverse video character. Example: c1 (inverse video A) is displayed as |A. May be combined with ^, for inverse control characters.

/   Separates the printable ASCII representation of a character from its hex byte. Example: A/41.

  Line header

Each line number begins with the line number (decimal) and offset from the start of the file (hex), followed by the 2 hex bytes for the line number in parentheses, followed by the line length (hex, preceded by ^). Example:

10@0018 (0a 00): ^19

The line number is 10, and the file offset is 0018. The 0a 00 are 10 again, in hex, LSB first. The 19 is the line length.

  Statements

Each statement within the line is displayed separately. For this line of code:

10 ? "HELLO":A=1

The dump looks like:

10@0018 (0a 00): ^19
 >0d !28 $0f =05 "H/48 E/45 L/4c L/4c O/4f" 14:
 >19 !36 80 2d #0e [40 01 00 00 00 00] 16

The first line is the line header. The next two are the two statements. The first one ends with token 14 (the end-of-statement or tokenized colon) and the second ends with 16 (the end-of-line token). The string "HELLO" is visible, and so is the floating point constant 1.

Long statements will wrap, if they're wider than the terminal. If this is a problem, use a wider terminal, and/or pipe through a pager that knows how to scroll horizontally.

EXIT STATUS

0 for success, 1 for failure.

COPYRIGHT

WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

AUTHOR

B.  Watson <urchlay@slackware.uk>; Urchlay on irc.libera.chat ##atari.

SEE ALSO

a8cat(1), a8eol(1), a8xd(1), atr2xfd(1), atrsize(1), axe(1), bas2aplus(1), blob2c(1), blob2xex(1), cart2xex(1), cxrefbas(1), dasm2atasm(1), diffbas(1), dumpbas(1), f2toxex(1), fenders(1), listbas(1), listamsb(1), protbas(1), renumbas(1), rom2cart(1), unmac65(1), unprotbas(1), vxrefbas(1), whichbas(1), xex1to2(1), xexamine(1), xexcat(1), xexsplit(1), xfd2atr(1), xex(5), atascii(7), fauxtari(7).

Any good Atari 8-bit book: De Re Atari, The Atari BASIC Reference Manual, the OS Users' Guide, Mapping the Atari, etc.