diff options
Diffstat (limited to 'dumpbas.1')
| -rw-r--r-- | dumpbas.1 | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/dumpbas.1 b/dumpbas.1 new file mode 100644 index 0000000..5867bf4 --- /dev/null +++ b/dumpbas.1 @@ -0,0 +1,237 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "DUMPBAS" 1 "2024-06-25" "0.2.1" "Urchlay's Atari 8-bit Tools" +.SH NAME +dumpbas \- Formatted hexdump for tokenized Atari 8-bit BASIC files +.SH SYNOPSIS +.sp +dumpbas [\fB\-v\fP] [\fB\-l\fP \fIlineno\fP] [\fB\-s\fP \fIstart\-lineno\fP] [\fB\-e\fP \fIend\-lineno\fP] \fIinput\-file\fP +.SH DESCRIPTION +.sp +\fBdumpbas\fP 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 \fBFORMATTING\fP, below). +.sp +\fBdumpbas\fP does not detokenize BASIC programs or dump information +about variable names/values. Use \fBchkbas\fP(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\(aqs an alternative to looking at raw hex dumps. +.sp +It\(aqs assumed the user has at least some knowledge of BASIC\(aqs tokenized +SAVE format. The \fBAtari BASIC Sourcebook\fP is a good starting point +for learning the tokenized format. +.SH OPTIONS +.SS Dump Options +.INDENT 0.0 +.TP +.B \fB\-s\fP \fIstart\-lineno\fP +Don\(aqt dump lines before \fBstart\-lineno\fP\&. Default: \fI0\fP\&. +.TP +.B \fB\-e\fP \fIend\-lineno\fP +Don\(aqt dump lines after \fBstart\-lineno\fP\&. Default: \fI32768\fP\&. +.TP +.B \fB\-l\fP \fIlineno\fP +Only dump one line. This is exactly equivalent to "\fB\-s\fP \fIlineno\fP \fB\-e\fP \fIlineno\fP". +.UNINDENT +.SS General Options +.INDENT 0.0 +.TP +.B \fB\-\-help\fP +Print usage message and exit. +.TP +.B \fB\-\-version\fP +Print version number and exit. +.TP +.B \fB\-v\fP +Verbose operation. When displaying a number in verbose mode, it will +be prefixed with \fI$\fP if it\(aqs in hex, or no prefix for decimal. +.UNINDENT +.SH FORMATTING +.sp +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\(aqre 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. +.SS Line Header Markers +.INDENT 0.0 +.TP +.B \fB@\fP +Separates decimal line number from hex file offset. +.TP +.B \fB^\fP +Prefix for line length. +.TP +.B \fB(\fP \fB)\fP +Surrounds the 2 hex bytes for the line number. +.UNINDENT +.SS Statement Markers +.INDENT 0.0 +.TP +.B \fB>\fP +Prefix for next\-statement offset. Every statement begins with this. +.TP +.B \fB!\fP +Prefix for a command token. Every line of BASIC code begins with a +command. +.TP +.B \fB:\fP +Suffix for the \fI14\fP token; end of statement. +.TP +.B \fB#\fP +Prefix for the \fI0e\fP token, which introduces a BCD floating point constant. +.TP +.B \fB[\fP \fB]\fP +Surrounds the 6 bytes of a BCD floating point constant. +.TP +.B \fB$\fP +Prefix for the \fI0f\fP token, which introduces a string constant. +.TP +.B \fB=\fP +Prefix for the string\-length byte of a string constant. +.UNINDENT +.SS String Byte Markers +.INDENT 0.0 +.TP +.B \fB"\fP +A string constant is surrounded by double\-quotes. +.TP +.B \fB^\fP +Prefix for a control character. For instance, \fI03\fP is displayed as \fI^C\fP\&. +.TP +.B \fB|\fP +Prefix for an inverse video character. Example: \fIc1\fP (inverse video \fIA\fP) +is displayed as \fI|A\fP\&. May be combined with \fI^\fP, for inverse control characters. +.TP +.B \fB/\fP +Separates the printable ASCII representation of a character from its hex byte. +Example: \fIA/41\fP\&. +.UNINDENT +.SS Line header +.sp +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: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10@0018 (0a 00): ^19 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The line number is \fI10\fP, and the file offset is \fI0018\fP\&. The \fI0a 00\fP +are 10 again, in hex, LSB first. The \fI19\fP is the line length. +.SS Statements +.sp +Each statement within the line is displayed separately. For this line of code: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 ? "HELLO":A=1 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The dump looks like: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The first line is the line header. The next two are the two +statements. The first one ends with token \fI14\fP (the end\-of\-statement +or tokenized colon) and the second ends with \fI16\fP (the end\-of\-line +token). The string \fI"HELLO"\fP is visible, and so is the floating point +constant \fI1\fP\&. +.sp +Long statements will wrap, if they\(aqre 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. +.SH EXIT STATUS +.sp +0 for success, 1 for failure. +.SH COPYRIGHT +.sp +WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details. +.SH AUTHOR +.INDENT 0.0 +.IP B. 3 +Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&. +.UNINDENT +.SH SEE ALSO +.sp +\fBa8eol\fP(1), +\fBa8utf8\fP(1), +\fBatr2xfd\fP(1), +\fBatrsize\fP(1), +\fBaxe\fP(1), +\fBblob2c\fP(1), +\fBblob2xex\fP(1), +\fBcart2xex\fP(1), +\fBcxrefbas\fP(1), +\fBdasm2atasm\fP(1), +\fBdumpbas\fP(1), +\fBf2toxex\fP(1), +\fBfenders\fP(1), +\fBlistbas\fP(1), +\fBprotbas\fP(1), +\fBrenumbas\fP(1), +\fBrom2cart\fP(1), +\fBunmac65\fP(1), +\fBunprotbas\fP(1), +\fBvxrefbas\fP(1), +\fBxexamine\fP(1), +\fBxexcat\fP(1), +\fBxexsplit\fP(1), +\fBxfd2atr\fP(1), +\fBxex\fP(5), +\fBatascii\fP(7). +.sp +Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC Reference +Manual\fP, the \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc. +.\" Generated by docutils manpage writer. +. |