Ubuntu Manpage: petcat - convert and display PETSCII or BASIC files

NAME

       petcat - convert and display PETSCII or BASIC files

SYNOPSIS

       petcat [ -text | -<version> | -w<version> | -k<version> ] [ -l hexaddr ] [ -c | -nc ] [ -o
       outfile ] [ -skip offset ] [ -- ] [ file list ]

DESCRIPTION

       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. Simon's Basic vs. Basic 7.0.
       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 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.  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 distinquished, but standard C64 and C128 versions are  used
       as default.
       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.

   Clarification
       Since CBM programs usually contain unprintable characters, a way to spesify them has  been
       created.   Normally,  petcat  uses  the  same  codes  as most printers, but for tokenizing
       programs scanned from magazines, it can use the following convention:

       {DOWN}      stands for single control code

       {6 RIGHT}   contains amout of consecutive codes

       List of valid mnemonics:
                   {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}

       List of alternate mnemonics:
                   {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}

OPTIONS

-l load_address
Specify load_address (in hex) for tokenized program.

-c Causes 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.

-nc Suppress control codes.

-f Force overwrite of existing output file. Default true.

-h Print filename and start address for each Basic file expanded. Default true.

-nh Suppress file header in printout.

-o file Redirect output to the specified file. This option overrules -h. When file 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.

-skip offset
Skip offset bytes in the beginning of input file.

-text Force text mode even if the input file looks like a Basic program, i.e. the first
byte in file is 01.

-k<version>
Just prints all valid keywords for the specified Basic version. Without any
version, all names of supported BASIC versions are listed instead.

-w<version>
Tokenise program listing using keywords set from the specified Basic version.

-<version>
Changes the set of keywords for the specified Basic version and expands tokenized
input file. Without this option petcat uses V7.0 keywords in expanding.

Versions
1 Basic 1.0

2 Basic 2.0

a Basic 2.0 with AtBasic

t Basic 2.0 with Turtle Basic

super su se Basic 2.0 with Super Expander

simon si Basic 2.0 and Simon's Basic

speech sp Basic 2.0 with Speech Basic v2.7

4 Basic 4.0

4e Basic 4.0 Extension

3 Basic 3.5

7 Basic 7.0

10 Basic 10.0

RESTRICTIONS

       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".

AUTHOR

         Jouko Valta    (jopi@stekt.oulu.fi)

Thanks to

         Frederik Ekman (d91fe@lelle.pt.hk-r.se)
         Marko Mäkelä   (msmakela@nic.funet.fi)
         Russell Alphey (r.alphey@dce.vic.gov.au)
         André Fachat   (a.fachat@physik.tu-chemnitz.de)
         Onno Ebbinge   (ebbin200@hio.tem.NHL.NL)
         Frank Kontros  (jeno@kontr.uzhgorod.ua)