In this chapter we will split away parts of our Hello World program into reusable header files and libraries. We will also abstract away our string printing technique into a macro which may be invoked at will, on arbitrary strings. We will then multiply the output of our program tenfold.

The prelude to our program—the PRG information and the BASIC program—are going to be the same in many, many programs. Thus, we should put them into a header file to be included later. The .include directive will load a file and insert it as source at the designated point. A related directive, .require, will include the file as long as it hasn't been included yet elsewhere. It is useful for ensuring a library is linked in. For pre-assembled code or raw binary data, the .incbin directive lets you include the contents of a binary file directly in the output. This is handy for linking in pre-created graphics or sound data. If you only wish to include part of a binary file, .incbin takes up to two optional arguments, naming the file offset at which to start reading and the number of characters to read. As a sample library, we will expand the definition of the chrout routine to include the standard names for every KERNAL routine. Our header file will then .require it. We'll also add some convenience aliases for things like reverse video, color changes, and shifting between upper case/graphics and mixed case text. We'd feed those to the chrout routine to get their effects. Since there have been no interesting changes to the prelude, and the KERNAL values are standard, we do not reproduce them here. (The files in question are and .) The c64kernal.oph header is likely to be useful in your own projects, and it is available in the platform/ directory for easy inclusion.

A macro is a way of expressing a lot of code or data with a simple shorthand. It's also usually configurable. Traditional macro systems such as C's #define mechanic use textual replacement: a macro is expanded before any evaluation or even parsing occurs. In contrast, Ophis's macro system uses a call by value approach where the arguments to macros are evaluated to bytes or words before being inserted into the macro body. This produces effects much closer to those of a traditional function call. A more detailed discussion of the tradeoffs may be found in .

A macro definition is a set of statements between a .macro statement and a .macend statement. The .macro statement also names the macro being defined. No global or anonymous labels may be defined inside a macro: temporary labels only persist in the macro expansion itself. (Each macro body has its own scope. A label map will trace back through macro expansions to describe were a label inside a macro body came from.) Arguments to macros are referred to by number: the first is _1, the second _2, and so on. Here's a macro that encapsulates the printing routine in our Hello World program, with an argument being the address of the string to print: .macro print ldx #0 _loop: lda _1, x beq _done jsr chrout inx bne _loop _done: .macend

Macros may be invoked in two ways: one that looks like a directive, and one that looks like an instruction. The most common way to invoke a macro is to backquote the name of the macro. It is also possible to use the .invoke command. These commands look like this: `print msg .invoke print msg Arguments are passed to the macro as a comma-separated list. They must all be expressions that evaluate to byte or word values—a mechanism similar to .alias is used to assign their values to the _n names.

expands our running example, including the code above and also defining a new macro greet that takes a string argument and prints a greeting to it. It then greets far too many targets.