path: root/system/vice/man/petcat.1

.TH PETCAT 1 "March 2017" "VICE" "C64 Program Development"
.nr X
.SH NAME
petcat \- convert and display PETSCII or BASIC files
.SH SYNOPSIS
.IR petcat
[
.B \-text
|
\-<\fIversion\fR>
|
.B \-w<\fIversion\fR>
|
.B \-k<\fIversion\fR>
] [
.B \-l \fIhexaddr\fR
] [
.B \-c
|
.B \-nc
] [
.B \-o \fIoutfile\fR
] [
.B \-skip \fIoffset\fR
] [
\--
] [
.B file list
]
.SH DESCRIPTION
.IR petcat
converts input files from the most common CBM file formats into
printable ASCII form and writes to standard output. The type
of input file is determined automatically, if possible, and
appropriate conversion is performed.
Since a few of the BASIC versions have keywords defined differently,
the right conversion has to be selected on the command line.
Where such confusion cannot happen, automatical recognition of input
is used. This is useful when expanding several files at once or if
the program contains code for several versions, selected according to
the hardware; eg. Simons' Basic vs. Basic 7.0.
.br
Please note that each input file is converted individually,
but the output is produced as continuous flow. Also, all input
files that are read trough a pipe, are concatenated before they
reach
.IR petcat
so any machine language section in between the BASIC programs causes
all consecutive files to be taken as one machine language program.
For that reason files containing machine language parts attached to
them must be input separately, otherwise the remaining files won't
be expanded.
.IR petcat
recognizes normal PETSCII text files (SEQ), program files containing
directory listing, and BASIC programs. Both the original CBM files and
files with a PC64 `P00' header are accepted. The different BASIC versions
are not automatically distinguished, but standard C64 and C128 versions
are used as default.
.br
In order to tokenize a text file into a BASIC binary file the desired
BASIC version must be exclusively specified so that correct set of
keywords will be used.
If line numbers are not found in the beginning of each program line,
the cruncher creates the missing line numbers by adding 2 to the numeric
value of previous one.
Since also line numbers deviating from strictly ascendind order are
accepted, care must be taken when editing such a program on a C64 again.
.SS Clarification
.LP
Since CBM programs usually contain unprintable characters, a way to
specify them has been created.
Normally,
.IR petcat
uses the same codes as most printers, but for tokenizing programs
scanned from magazines, it can use the following convention:
.br
.TP 12
.BR "{DOWN}"
stands for single control code
.TP
.BR "{6 RIGHT}"
contains amout of consecutive codes
.TP
List of valid mnemonics:
.br
{wht} {dish} {ensh} {swlc} {down} {rvon} {home} {del} {esc} {red}
{rght} {grn} {blu} {orng} {F1} {F3} {F5} {F7} {F2} {F4} {F6} {F8}
{sret} {swuc} {blk} {up} {rvof} {clr} {inst} {brn} {lred} {gry1}
{gry2} {lgrn} {lblu} {gry3} {pur} {left} {yel} {cyn}
.TP
List of alternate mnemonics:
.br
{wht} {up/lo lock on} {up/lo lock off} {return} {lower case} {down}
{rvs on} {home} {delete} {esc} {red} {right} {grn} {blu} {orange}
{f1} {f3} {f5} {f7} {f2} {f4} {f6} {f8} {shift return} {upper case}
{blk} {up} {rvs off} {clr} {insert} {brown} {lt red} {grey1} {grey2}
{lt green} {lt blue} {grey3} {pur} {left} {yel} {cyn}
.SH OPTIONS
.TP 8
.B \-l \fIload_address\fR
Specify \fIload_address\fR (in hex) for tokenized program.
.TP
.B \-c
Causes
.IR petcat
to interpret also control characters.
By default, these strings are the same as used by printers. However,
an alternate set is attempted whenever none within the primary set
matches. Default is ON, unless text mode is selected.
.TP
.B \-nc
Suppress control codes.
.TP
.B \-f
Force overwrite of existing output file. Default true.
.TP
.B \-h
Print filename and start address for each Basic file expanded. Default true.
.TP
.B \-nh
Suppress file header in printout.
.TP
.B \-o \fIfile\fR
Redirect output to the specified \fIfile\fR. This option overrules -h.
When \fIfile\fP has extension `.P00' and also -w option is specified, the PC64
file header is written automatically. .P00 file cannot be written on stdout
but to a file only.
.TP
.B \-skip \fIoffset\fR
Skip \fIoffset\fR bytes in the beginning of input file.
.TP
.B \-text
Force text mode even if the input file looks like a Basic program, i.e.
the first byte in file is 01.
.TP
.B \-k<\fIversion\fR>
Just prints all valid keywords for the specified Basic \fIversion\fR.
Without any \fIversion\fR, all names of supported BASIC versions are
listed instead.
.TP
.B \-w<\fIversion\fR>
Tokenise program listing using keywords set from the specified Basic
\fIversion\fR.
.TP
\-<\fIversion\fR>
Changes the set of keywords for the specified Basic \fIversion\fR and
expands tokenized input file.
Without this option
.IR petcat
uses V7.0 keywords in expanding.
.SS Versions
.TP 14
.B 1
Basic 1.0
.TP
.B 2
Basic 2.0
.TP
.B a
Basic 2.0 with AtBasic
.TP
.B t
Basic 2.0 with Turtle Basic
.TP
.B super su se
Basic 2.0 with Super Expander
.TP
.B simon si
Basic 2.0 and Simons' Basic
.TP
.B speech sp
Basic 2.0 with Speech Basic v2.7
.TP
.B 4
Basic 4.0
.TP
.B 4e
Basic 4.0 Extension
.TP
.B 3
Basic 3.5
.TP
.B 7
Basic 7.0
.TP
.B 10
Basic 10.0
.SH RESTRICTIONS
.LP
Line numbers must be less than 65536.
Maximum line length is 255 bytes. Leading white space is ignored.
Blank lines and line numbers not followed by any text are rejected.
While expanding, Machine Language section concatenated to a BASIC
program is ignored.
While crunching, control codes that appear outside quotes are not
interpreted.
The low order byte of load address must be "01".
.SH SEE ALSO
.BR cat(1),
.BR tr(1),
.BR sed(1),
.BR fvcbm(1),
.BR petlp(1),
.BR cbmconvert(1),
.BR iso2asc(1),
.BR ascii(7),
.BR "\fICBM Tokens Documentation\fP",
.BR "CBM's \fIProgrammers' Reference Guide\fP series"
.P
@HTMLDOC@
.SH AUTHOR
  Jouko Valta    (jopi@stekt.oulu.fi)
.SH Thanks to
  Frederik Ekman (d91fe@lelle.pt.hk-r.se)
  Marko M\(:akel\(:a   (msmakela@nic.funet.fi)
  Russell Alphey (r.alphey@dce.vic.gov.au)
  Andr\('e Fachat   (a.fachat@physik.tu-chemnitz.de)
  Onno Ebbinge   (ebbin200@hio.tem.NHL.NL)
  Frank Kontros  (jeno@kontr.uzhgorod.ua)