path: root/unmac65.rst

.. RST source for unmac65(1) man page. Convert with:
..   rst2man.py unmac65.rst > unmac65.1
.. rst2man.py comes from the SBo development/docutils package.

=======
unmac65
=======

------------------------------------------
Detokenize Atari 8-bit Mac/65 SAVEd files.
------------------------------------------

.. include:: manhdr.rst

SYNOPSIS
========

**unmac65** [*-options*] *file.m65*

DESCRIPTION
===========

**unmac65** reads files created with Mac/65's SAVE command (usually called
.M65 files) and converts them back to plain text assembly source.

OPTIONS
=======

-a
  Use ATASCII EOLs. This option is not available in Atari version,
  since it already uses ATASCII.

-c
  Convert non-printable characters constants to hex bytes.

**-cc**
  Convert all character constants to hex bytes.

-e nnn[,iii]
  Renumber the program, starting at line *nnn*, with increment *iii*.
  *nnn* must be present, and must be an integer greater than or equal
  to zero. *iii* is optional, must be positive (non-zero), and
  defaults to 10 if not given.

  Mac/65's maximum line number is 65535. unmac65 will happily renumber
  lines with no upper bound (other than unsigned int overflow), so pay
  attention.

-h
  Show command-line help.

-i
  Convert inverse video (in comments and strings) to standard ASCII.
  Lines that were converted will get a comment "*; XXX inverse*" at
  the end. This option also enables the -c option.

  If the program contained any inverse-video strings, the resulting
  output will *not* reassemble correctly; you'll have to edit it to
  e.g. change the formerly inverse video strings to a list of hex
  bytes.

  This option is not available in the Atari version.

-l
  Lowercase mnemonics and hex constants (but not labels or comments).

**-la**
  Lowercase mnemonics, hex constants, labels, and comments (but not
  strings or character constants).

-n
  No line numbers in output.

-o file
  Output to *file* (default = standard output).

-q
  Add closing single-quote to character constants. Changes this::

    LDA #'A

  ...to this::

    LDA #'A'

-p
  Omit leading . (period) from pseudo-ops (e.g. print BYTE for .BYTE).

-t
  Replace leading spaces with tabs.

**-ta**
  Replace spaces between all fields with tabs.

-v
  Verbose output (dump tokens in hex). Useful for examining damaged
  .M65 files, or debugging unmac65 itself.

Human-readable Output Options
-----------------------------

The -m, -r, and -u options are not available for the Atari, and may or
may not be useful on non-Linux OSes.

-m
  Print inverse video as pseudo-underlined, using backspace and
  underscore. Useful for piping to more(1) or less(1). Can be combined
  with -u.

-r
  Print inverse video as reverse video using xterm/ANSI compatible
  escape sequences. Can be combined with -u. Useful for piping to
  less(1) provided its -r or -R option is used.

-u
  Print ATASCII control characters as their nearest Unicode
  equivalents (encoded in UTF-8). Depending on your terminal,
  combining this option with -r may not work properly. Also, depending
  on the font(s) your terminal is using, you may see boxes instead of
  control characters. If this happens, try a different font, or a
  different terminal (the author recommends rxvt-unicode).

Options may not be bundled (use "-p -t", not "-pt").

Unlike most UNIX-flavored programs, the CLI options are
case-insensitive. This is to make life easier for users of the Atari
version, where uppercase is the normal way of doing things.

The -c, -cc, -l, -la, -n, -p, -t, -ta options are provided to assist in
porting Mac/65 programs to other assemblers, such as ca65 or dasm.
unmac65's output with none of these options (or with -n only) is
acceptable as input for the atasm assembler. This is true even if there
are inverse video strings: they look funny when viewing the file, but
atasm handles them correctly.

The -v option prints the hex bytes for each line (preceded by ";;" and
the line number) after that line's detokenized listing.

Note that the output from -m, -r, -u is intended for humans to read.
They're not very useful if you're trying to port Mac/65 code to a
different assembler, as none of them know what to do with the
underlines, ANSI codes, or pseudo-ATASCII Unicode characters.

FILE FORMAT
===========

A tokenized Mac/65 file consists of:

Header: 2 byte $FE $FE signature, followed by the 2 byte program length
in LSB/MSB format. Length doesn't include the 4 header bytes.

The rest of the file consists of lines of code. Each line is:

Line number, 2 bytes (LSB/MSB format)

Line length, 1 byte. Total length, including the line number and length
bytes.

Tokens. Length minus 3 bytes of tokens. If the line is labelled, the
label will appear first, as a tokenized string (see below).

Whether or not there's a label, the next byte is the token for a
mnemonic (or pseudo-op). Lines containing only a comment will have a
special token meaning "no mnemonic".

After the mnemonic token, 0 or more bytes of operands. Quoted strings or
labels as operands are stored as a tokenized string. Hex or decimal
constants are preceded by a token indicating the length (one or two
bytes) and the type (hex or decimal).

If there is a comment, the last byte of the operand field will be an
ASCII semicolon. The remaining bytes on the line are the comment in
ASCII form.

Tokenized strings can occur in the label or operand parts of the line.
The first byte is the length of the string in bytes, with the high bit
set (e.g. $84 for a 4-byte string), followed by that number of ASCII
bytes. The length doesn't include the first byte, so e.g. the string
"ABC" is stored as $83, $41, $42, $43. Mac/65 doesn't allow empty
strings, so a zero-length string (length byte $80) is an error.

There are separate sets of tokens for mnemonics/pseudo-ops and operands.
Mnemonic/pseudo-op tokens run from 0 to $5F, and operand tokens run from
0 to $4D (with 0-$09 being "special", and a few invalid tokens in the
range $0A-$4D). See the C source for the full list (or a hex/ascii dump
of the Mac/65 ROM, which is where I got the lists to put them in the C
source). Also, you can run unmac65 with the -v option to get a
line-by-line hex dump of the tokens.

DIAGNOSTICS
===========

unmac65: line XX contains NN non-printable ATASCII characters <= $1F

Self-explanatory. Depending on what you're going to use the converted
file for, this may or may not be a problem. Non-fatal. This warning
doesn't occur in the Atari version of unmac65. Also, it doesn't occur if
the -u option is in use.

unmac65: line XX contains NN inverse ATASCII characters >= $80

Self-explanatory. Depending on what you're going to use the converted
file for, this may or may not be a problem. Non-fatal. Use the -i option
to convert inverse video to normal. This warning doesn't occur in the
Atari version of unmac65. Also, it doesn't occur if any of the -i, -m,
or -r options are in use.

unmac65: not a mac/65 file (missing $FEFE header)

Self-explanatory. Fatal error.

unmac65: corrupt or truncated file?

The length of the last line in the file is longer that the number of
bytes remaining in the file (according to the file header). Fatal error.

unmac65: unexpected EOF?

The file is shorter than the file header's program length. Probably the
file is truncated; less probably, the length header got scrambled
somehow. Fatal error.

unmac65: file is too short (N bytes)

The minimum length for a Mac/65 file is 4 bytes (which would be an empty
program containing no lines). The input file was shorter than 4 bytes.
Fatal error. (Actually, Mac/65 will never produce a 4-byte file, it's
just the theoretical minimum)

unmac65: file is valid but contains no lines of code

Self-explanatory. Mac/65 creates a file like this if the SAVE command is
given before entering any code (at startup or after a NEW). The SAVEd
file will be 5 bytes in length, and utterly useless. Non-fatal warning.

unmac65: line #lll <= prev line #mmm

The line numbers in the file are supposed to be stored in ascending
order. Somehow this file has the line numbers out of order. Non-fatal,
but probably the rest of the file will be garbage.

unmac65: internal error, state n

This is a "this should never happen" error. It indicates a bug in the
program. If you ever see this error, please notify the author, and send
a copy of the Mac/65 program that caused it. This is a non-fatal error,
but the output might be garbage.

[$nn?] or <$nn?> in the output (where nn is 2 hex digits)

These indicate unknown/invalid tokens. Either the file is damaged, or
there is a bug in the program. These are non-fatal errors. If you ever
see them, please contact the author, and send a copy of the Mac/65
program that caused them.

unmac65: ignoring extra junk at EOF

The file contains more bytes than the program length header says it
should. This usually means the file was stored on an old DOS disk or
transferred with a broken XMODEM implementation, and was padded to the
sector/block size. Alternately, the header bytes got corrupted somehow
(this is highly unlikely, especially if there are no other
errors/warnings). Non-fatal error.

Other errors are possible (e.g. disk full, I/O error reading input), but
they're not specific to unmac65; no need to list them all there.

Fatal errors result in unmac65 terminating. A non-fatal error can
usually be recovered from, though the line that caused it will probably
be printed strangely.

It's probably worth mentioning also that Mac/65 source files can contain
ATASCII graphics or escape codes, although it's not a very common
practice. If you see strange stuff and/or your terminal misbehaves when
writing to standard output, try writing to a file (-o option) instead.
See also the -m, -r, -u options for human-readable output. The Atari
version will render ATASCII graphics just fine, of course.

EXIT STATUS
===========

unmac65 will normally exit with a zero (success) status upon completion.
A non-zero status indicates a fatal error.

LIMITATIONS
===========

The main difference between Mac/65's LIST output and unmac65's output is
that Mac/65 lines up the label, mnemonic, and comment fields (if the
field contents are short enough to fit in the allotted width), while
unmac65 makes no attempt to do so. If the field alignment is important
to you, try the -t or -ta options (which insert hard tabs, unlike
mac65's spaces). A future version of unmac65 may correct this minor
flaw, but as it stands, I've tested quite a few .M65 files by running
them through unmac65, then ENTERing unmac65's listed file in Mac/65 and
reSAVEing them... In all cases, the newly created tokenized files
compare identically to the original .M65 file. If you come across a file
that doesn't do this, yet is valid (can be assembled without error by
Mac/65), please send it to me, so I can fix unmac65!

Although a few helpful options have been added for porting Mac/65
sources to other assemblers, unmac65 doesn't completely automate the
process. Depending on the assembler you're using, you may still have a
lot of manual edits to make. A future version of unmac65 may add a few
more options, but some hypothetical complex porting functions (like
"convert to ca65 format") would require implementing a much more complex
parser (such as a yacc-based recursive descent parser). Most likely this
will never happen, if only because I want the program to be usable on
the Atari itself, with its limited memory and C compiler support.

There are a few ways that an invalid file can sneak past unmac65's error
checking. The same files wouldn't load correctly in Mac/65 either, but
generally don't cause any errors in Mac/65 (just silent failure). It'd
be nice if unmac65 could act as a "M65 lint" for Mac/65 users.

unmac65 is mostly developed/tested against the OSS Mac/65 v1.01
cartridge. The various disk versions appear to use the same tokenized
format, but haven't been well tested. If you have problems, please
contact the author.

(A further limitation is that the documentation isn't very concise.
Sorry about that.)

.. include:: manftr.rst