GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


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



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.109 seconds. Last modified: November 04 2018 12:49:43.