Chapter 6
Source format

This chapter describes how a source file is laid out: what a line is, the four parts TATARA divides it into, and the rules for labels, comments, upper and lower case, spaces and tabs, line length and line endings. It is the chapter to come back to when TATARA reports that a line is “not a directive, a macro or an instruction” and the line looks right.

6.1 Lines

A source file is a text file, and TATARA reads it one line at a time. Each line is one of three things:

• an empty line, which TATARA skips;
• a comment line, which holds only a comment for the reader;
• a statement: an instruction for the Z80, a directive for TATARA, or the name of a macro (chapter 16).

You can write a source file with any editor that saves plain text, either on the MSX or on another computer. Section 6.6 explains why a file written on a PC or a Mac can be assembled as it is.

6.2 The four fields

TATARA divides every line into up to four fields, always in the same order:

label      operation  operand       ; comment
 

Figure 6.1 shows a line with all four.

Label.

A name for the address of the line (chapter 2), such as start:. The next section says where a label can be written, and chapter 7 what a name can contain.

Operation.

What the line does: an instruction such as ld, a directive such as db, or the name of a macro. It ends at the first space or tab after it. This field is called the operation.

Operand.

What the operation works on, such as de,msg. It runs from the operation to the comment, or to the end of the line, and can contain spaces: in db "Hello from Tatara." the whole of "Hello from Tatara." is the operand. What an operand can hold depends on the operation (chapters 8 to 11).

Comment.

Text for the reader, from a semicolon to the end of the line. TATARA ignores it.

Every field can be left out. Table 6.1 shows the shapes a line usually takes.

6.3 Where a label goes

TATARA recognises a label in one of two ways:

1. A word that starts in column 1, the first character of the line, is a label, with or without a colon after it.
2. A word that does not start in column 1 is a label only if a colon ends it.

An indented word without a colon is therefore the operation. In this source, INDENT2.AS, start is indented and has no colon, so TATARA takes it for an operation, and there is none of that name:

  start   ld      a,1 
          end
 

INDENT2.AS(1): ERROR: not a directive, a macro or an instruction.
 

With a colon after start, the same indented line is accepted.

A label written with two colons, as in putstr::, is also made public, which is what the PUBLIC directive does (chapter 12).

The examples follow one convention, and it is a good one to copy: a label starts in column 1 and ends with a colon, and everything else on the line, and every line without a label, is indented with tabs.

6.4 Comments

A comment starts with a semicolon and runs to the end of the line. A line can be a comment and nothing else, and then the semicolon can be in column 1, as in the first lines of HELLO.AS.

A semicolon inside a string does not start a comment. In this line the string is "a;b", and the comment starts at the second semicolon:

        db      "a;b"           ; the semicolon is part of the string
 

A quotation mark that is not closed on the same line does not start a string. This matters for the one Z80 instruction that has an apostrophe in it:

        ex      af,af'          ; swap the two AF registers
 

6.5 Upper and lower case

Instructions, register names and directives can be written in upper or lower case, or in a mixture: LD A,B, ld a,b and Ld A,b are the same line.

Names are not case-sensitive either, unless TATARA is run with /C (chapter 5): without it, msg, MSG and Msg are the same name. Chapter 7 says more.

The text inside a string keeps its case: "Hello" and "HELLO" are different strings.

The examples write their code in lower case, and the include files write their names in upper case, as the MSX documentation does: ld c,_STROUT.

6.6 Spaces, tabs, line length and line endings

6.6.1 Spaces and tabs

Spaces and tabs separate the fields, and any number of either, in any mixture, can be used between two fields. Tabs keep the fields in straight columns, and the examples use them for that reason. In a listing, each tab moves to the next column that is a multiple of eight (chapter 18).

6.6.2 Line length

A line can be up to 255 characters long. A longer line stops TATARA with this message:

ERROR: source line too long.
 

6.6.3 Line endings

Every text file marks the end of each line with one or two control characters. MSX-DOS and Windows use two, CR and LF; macOS and Linux use LF alone. TATARA ends a line at LF and ignores CR, so it reads both kinds of file, and a source written on another computer can be copied to the MSX and assembled without being converted. The last line of a file is read even if it has no line ending.

A file that uses CR alone, as some very old Macintosh programs write, is read as one long line, and TATARA stops with the message above.

6.6.4 Ctrl-Z

Some MSX-DOS editors put a Ctrl-Z, the character 1Ah, after the last line of a file, a habit inherited from CP/M. TATARA stops reading at a Ctrl-Z, and ignores anything that comes after it.