From 028b2a57446789fe7bafb8ab678c1f0f43b34645 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Fri, 7 Jun 2024 04:47:04 -0400 Subject: dumpbas: added. --- dumpbas.1 | 267 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 dumpbas.1 (limited to 'dumpbas.1') diff --git a/dumpbas.1 b/dumpbas.1 new file mode 100644 index 0000000..9da3e11 --- /dev/null +++ b/dumpbas.1 @@ -0,0 +1,267 @@ +.\" 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-07" "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 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 +.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 \fInum\fP \fB\-e\fP \fInum\fP". +.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 both hex and ASCII. Floating +point constants are displayed as 6 hex bytes with square brackets around them. +.sp +If \fBdumpbas\fP is run on the following program: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 ? "HOW MANY TIMES";:INPUT N +20 FOR I=1 TO N +30 ? "HELLO ";:? I;"/";N:NEXT I +40 REM WAIT FOR KEY +50 POKE 764,255 +60 ? "PRESS ANY KEY" +70 IF PEEK(764)=255 THEN 70 +80 POKE 764,255:GOTO 10 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNote:\fP The "PRESS ANY KEY" was entered in inverse video. +.sp +\&...it produces the following output: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C + 10@0021 (0a 00): ^1b + >17 !28 $0f =0e "H/48 O/4f W/57 /20 M/4d A/41 N/4e Y/59 /20 T/54 I/49 M/4d E/45 S/53" 15 14: + >1b !02 80 16 + 20@003c (14 00): ^11 + >11 !08 81 2d #0e [40 01 00 00 00 00] 19 80 16 + 30@004d (1e 00): ^1d + >0f !28 $0f =06 "H/48 E/45 L/4c L/4c O/4f /20" 15 14: + >19 !28 81 15 $0f =01 "//2f" 15 80 14: + >1d !09 81 16 + 40@006a (28 00): ^12 + >12 !00 57 41 49 54 20 46 4f 52 20 4b 45 59 9b + 50@007c (32 00): ^15 + >15 !1f #0e [41 07 64 00 00 00] 12 #0e [41 02 55 00 00 00] 16 + 60@0091 (3c 00): ^15 + >15 !28 $0f =0d "|P/d0 |R/d2 |E/c5 |S/d3 |S/d3 | /a0 |A/c1 |N/ce |Y/d9 | /a0 |K/cb |E/c5 |Y/d9" 16 + 70@00a6 (46 00): ^20 + >20 !07 46 3a #0e [41 07 64 00 00 00] 2c 22 #0e [41 02 55 00 00 00] 1b #0e [40 70 00 00 00 00] 16 + 80@00c6 (50 00): ^1f + >15 !1f #0e [41 07 64 00 00 00] 12 #0e [41 02 55 00 00 00] 14: + >1f !0a #0e [40 10 00 00 00 00] 16 +32768@00e5 (00 80): ^0f + >0f !19 $0f =07 "H/48 :/3a B/42 ./2e B/42 A/41 S/53" 16 +.ft P +.fi +.UNINDENT +.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 +^). From the example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10@0021 (0a 00): ^1b +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The line number is \fI10\fP, the file offset is \fI0021\fP\&. The \fI0a 00\fP are 10 again, in +hex, LSB first. The \fI^1b\fP is the line length. +.SS Statements +.sp +Each statement within the line is displayed separately. Line 10\(aqs first statement: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +>17 !28 $0f =0e "H/48 O/4f W/57 /20 M/4d A/41 N/4e Y/59 /20 T/54 I/49 M/4d E/45 S/53" 15 14: +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This looks cryptic, but it includes a lot of information. +.INDENT 0.0 +.IP \(bu 2 +\fI>\fP is the marker for the statement offset (\fI17\fP). +.IP \(bu 2 +\fI!\fP marks a command token (unmarked tokens are operator +tokens). \fI28\fP is the token for \fB?\fP (short form of PRINT, which has a +separate token). +.IP \(bu 2 +\fI$\fP marks the string\-constant token (\fI0f\fP). +.IP \(bu 2 +\fI=\fP marks the string length byte (\fI0e\fP). +.IP \(bu 2 +The string itself is printed inside double quotes, with each character in +both ASCII and hex (e.g. \fIH/48\fP). +.IP \(bu 2 +The \fI15\fP is unmarked. It\(aqs the semicolon after the string. +.IP \(bu 2 +There\(aqs a \fI:\fP at the end of the line (after the \fI14\fP, which is the end\-of\-statement +token). +.UNINDENT +.sp +Line 10\(aqs second statement: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +>1b !02 80 16 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fI80\fP is a token for a variable (variable tokens always have bit 7 set, so they\(aqre +always >= 80 hex). The \fI16\fP is the end\-of\-line token. +.sp +Line 20\(aqs first statement has an example of a floating point constant: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +#0e [40 01 00 00 00 00] +.ft P +.fi +.UNINDENT +.UNINDENT +.INDENT 0.0 +.IP \(bu 2 +\fI#\fP marks the token for a FP constant. +.IP \(bu 2 +The actual 6\-byte constant is surrounded with \fI[\fP and \fI]\fP\&. +.IP \(bu 2 +The last token is \fI16\fP, which is BASIC\(aqs end\-of\-line token. +.UNINDENT +.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), +\fBdasm2atasm\fP(1), +\fBdumpbas\fP(1), +\fBf2toxex\fP(1), +\fBfenders\fP(1), +\fBprotbas\fP(1), +\fBrenumbas\fP(1), +\fBrom2cart\fP(1), +\fBunmac65\fP(1), +\fBunprotbas\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. +. -- cgit v1.2.3