diff options
Diffstat (limited to 'dumpbas.rst')
| -rw-r--r-- | dumpbas.rst | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/dumpbas.rst b/dumpbas.rst new file mode 100644 index 0000000..6dc32b9 --- /dev/null +++ b/dumpbas.rst @@ -0,0 +1,145 @@ +======= +dumpbas +======= + +------------------------------------------------------- +Formatted hexdump for tokenized Atari 8-bit BASIC files +------------------------------------------------------- + +.. include:: manhdr.rst + +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*". + +.. include:: genopts.rst + +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. + +.. include:: manftr.rst |