NAME

       zmakebas - convert text file into Spectrum Basic program

SYNOPSIS

       zmakebas [-hlr] [-a startline] [-i incr] [-n speccy_filename] [-o output_file] [-s line] [input_file]

DESCRIPTION

       zmakebas  converts a Spectrum Basic program written as a text file into an actual speccy Basic file (as a
       .TAP file, or optionally a raw headerless file). By default, input comes from stdin, and output  goes  to
       `out.tap'.

       Using  zmakebas  rather  than  (say)  writing  the Basic in an emulator means you can write using a nicer
       editor, and can use tools which work on text files, etc. Also, with the `-l' option you can write without
       line numbers, using labels in their place where necessary.

       The  program  was  originally intended to be used simply to make little loader programs, so they wouldn't
       have to be sourceless binaries.  However, I went to a fair amount of effort to make sure  it'd  work  for
       bigger, more serious programs too, so you can also use it for that kind of thing.

OPTIONS

       -a     make  the  generated  file  auto-start  from line startline.  If `-l' was specified, this can be a
              label, but don't forget to include the initial `@' to point this out.

       -h     give help on command line options.

       -i     in labels mode, set line number increment (default 2).

       -l     use labels rather than line numbers.

       -n     specify filename to use in .TAP file (up to 10 chars), i.e. the  filename  the  speccy  will  see.
              Default is a blank filename (10 spaces).

       -o     output  to  output_file  rather  than  the default `out.tap'. Use `-' as the filename to output on
              stdout.

       -r     write a raw headerless Basic file, rather than the default .TAP file.

       -s     in labels mode, set starting line number (default 10).

INPUT FORMAT

       The input should be much as you would type into a speccy (a 128,  to  be  precise),  with  the  following
       exceptions:

       Lines  starting  with  `#'  are ignored. This allows you to insert comments which are not copied into the
       output Basic file.

       Blank lines are ignored.

       Case is ignored in keywords - `print', `PRINT', and `pRiNt' are equivalent.

       You can optionally use `randomise' as an alternative to `randomize'.

       You can get hex numbers by using `bin' with a C-style hex number, e.g.   to  get  1234h  you'd  use  `bin
       0x1234'.  (It  appears in exactly that form in the speccy listing, though, so don't use it if you want to
       be able to edit the output program on a speccy.)

       You can get a pound sign (character 96 on a speccy) by using a backquote (`).

       One input line normally equals one line of Basic, but you can use backslash as the last  character  of  a
       line to continue the statement(s) on the next input line.

       Rather  than  literally inserting block graphics characters and UDGs as you would on a speccy, you should
       use an escape sequence. These begin with a backslash (`\'). To get a UDG, follow this backslash with  the
       UDG's  letter,  in  the range `a' to `u' (`t' and `u' will only have the desired effect if the program is
       run on a 48k speccy or in 48k mode, though); both upper and lowercase work. To get the copyright  symbol,
       follow  it  with  `*'.  To get a block graphics character, follow it with a two-character `drawing' of it
       using spaces, dots, apostrophes and/or colons. (For example, you'd get  character  135  with  `\':',  and
       character  142  with  `\:.'.) To get a literal `@', follow it with `@'.  (This is needed only if the `-l'
       option was given, but works whether it was or not.) To specify a literal eight-bit character code to dump
       into  the  Basic output file directly (to use for embedded colour control codes and the like), use braces
       and a C-syntax number e.g.  `\{42}' for decimal, and `\{0x42}' for  hex.  Finally,  as  usual  with  such
       things, you can get a literal backslash by following the first backslash with another.

       If  the `-l' option was given, line numbers must be omitted. Instead these are automatically generated in
       the output, and you can use labels where necessary as substitute line numbers for `goto' commands etc.  A
       label is defined with the text `@label:' at the beginning of a line (possibly preceded by whitespace). It
       can be referred to (before or after) with `@label'. Any printable ASCII character other  than  colon  and
       space  can  be  used  in  a  label name. Here's an example of how labels work, showing both the input and
       (listing of) the output - first, the input:

       goto @foo
       print "not seen"
       @foo: print "hello world"

       Now the output:

       10 GO TO 14
       12 PRINT "not seen"
       14 PRINT "hello world"

       Note that case is significant for labels; `foo' and `FOO' are different.

BUGS

       There's almost no syntax checking. To do this would require a complete parser, which would be overkill  I
       think. What's wrong with ``C Nonsense in BASIC'' as a syntax check, anyway? :-)

       Excess  spaces are removed everywhere other than in strings and rem statements. I think this is generally
       what you'd want, but it could be seen as a bad thing I s'pose.

       Labels are substituted even in string literals. That's arguably a feature not a bug - the problem is, the
       label  name  has  to  be followed by whitespace or a colon or EOL when referenced, which is fine for more
       normal references but is less than ideal for references in strings.

       In the label-using mode, two passes are made over the input, which usually means the input must be from a
       file. If you like making one-liner Basic programs with `echo' and the like, I'm afraid you'll have to use
       line numbers. :-)

       The inline floating-point numbers which have to be generated are not  always  exactly  the  same  as  the
       speccy would generate - but they usually are, and even when they're not the difference is extremely small
       and due to rounding error on the speccy's part. For example, 0.5 is encoded by the speccy as 7F 7F FF  FF
       FF  (exponent  -1,  mantissa  approx.  0.9999999997672)  and  by  zmakebas as 80 00 00 00 00 (exponent 0,
       mantissa 0.5).

       zmakebas has most of the same (parsing) problems, relative to the original basic  editor,  that  the  128
       editor has. Specifically, you can't use variable names which clash with reserved words, so e.g. `ink ink'
       doesn't work; and certain tightly-packed constructions you might expect to work, like `chr$a', don't (you
       need a space or bracket after CHR$). These can be more of a problem with zmakebas though, due to the lack
       of syntax checking.

       The way tokenisation is done is sub-optimal, to say the least. If you ran this code on a  Z80,  even  the
       128  editor's  tokenisation  would  seem  quick  in comparison. (Here's a hint of the full horror of it -
       program lines take exponentially longer to tokenise the longer they are.)  However, since I never  had  a
       conversion  take  more  than about a second on my old 486 (it took a second for a 10k program), it hardly
       seems worth the effort of fixing.

       zmakebas has no problem with translating BIN numbers of more than 16  bits,  unlike  the  speccy,  though
       numbers  with  more  than  32  significant bits can only be approximated, and on machines where `unsigned
       long' is no more than 32 bits they'll be very approximate. :-) (If this sounds confusing, you should note
       that  BIN  numbers are translated when entered, and only the 5-byte inline form is dealt with at runtime.
       This also explains why the speccy tolerates the `bin 0x...' construction.)

       On machines without FP hardware, zmakebas will be rather slow (this is due to the need to generate inline
       FP numbers).

       Since  Basic  is an acronym, pedants will doubtless insist I should write it as `BASIC'. But we live in a
       world with `laser' etc., and at least I can be bothered to capitalise the thing, right? :-)

SEE ALSO

       fuse(1), xz80(1), xzx(1)

AUTHOR

       Russell Marks (russell.marks@ntlworld.com).