zmakebas(1)

💖 zmakebas — convert text file into Spectrum Basic program 💖

okay so bestie, welcome to zmakebas(1), a lil tool from the Retrocomputing Tools corner of the universe ✨ it takes your cute little text file and turns it into a real, actual Spectrum Basic program. no cap. 🎀

---

✨ SYNOPSIS ✨

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

---

🌸 DESCRIPTION 🌸

so what does zmakebas actually do? it converts a Spectrum Basic program that you wrote as a text file into an actual speccy Basic file — either as a .TAP file, or optionally as a raw headerless file if that's more your vibe. by default the input comes from stdin, and the output goes to out.tap. 💅

the way that using zmakebas instead of, say, writing the Basic in an emulator is iconic because you get to write in a nicer editor, and you can use tools that work on text files and all that. also — and this is the bestie part — with the -l option you can write without line numbers, using labels in their place wherever you need them. obsessed. 🫶

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. main character energy fr fr. 👑

---

🎀 OPTIONS 🎀

• -a — makes 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, okay? 🙈
• -h — gives you help on the command line options. your lil cheat sheet, iykyk. 💜
• -i — in labels mode, sets the line number increment (default 2).
• -l — use labels rather than line numbers. the ✨aesthetic✨ choice.
• -n — specify the filename to use in the .TAP file (up to 10 chars), i.e. the filename the speccy will see. default is a blank filename (10 spaces). yeah. ten whole spaces. it's giving minimalist. 😭
• -o — output to output_file rather than the default out.tap. use - as the filename to output on stdout, bestie. 🌈
• -r — write a raw headerless Basic file, rather than the default .TAP file.
• -s — in labels mode, sets the starting line number (default 10).

---

🦋 INPUT FORMAT 🦋

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

• lines starting with # are ignored. this lets you insert comments which are not copied into the output Basic file. sneaky but make it fashion. 💅
• blank lines are ignored.
• case is ignored in keywords — print, PRINT, and pRiNt are all equivalent. slay. ✨
• 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 (\). here's the whole menu:

• to get a UDG, follow that 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 💀

okay bestie, buckle up, this is the messy section. 😭

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) — go say hi, bestie. 🫶

---

💜 AUTHOR 💜

Russell Marks (zgedneil@gmail.com).

---

and that's the whole thing!! Version 1.2b, 19th December, 2021 — mwah, love u, go make something iconic with it 💖✨🎀🦋🌸