Amulet HTMLCompiler Macro Preprocessor

The Amulet macro preprocessor allows you to create macros which are used to make textual substitution throughout the HTML project. The macros are defined in a text file which is included in your HTML project by inserting a META tag in your main HTML page. Almost all text within the HTML project will be scanned by the Amulet macro preprocessor and text substitutions will be made. The only exception is the Amulet defined APPLET "NAME=" parameters. All other text, including static text strings, will be scanned by the macro preprocessor and substitutions will occur when an exact match to the macro definition is found. Macro expansion occurs at compile time within the HTMLCompiler.

The Amulet macro preprocessor is case sensitive. To be considered an exact match, the macro name must be found in the scanned string and must be surrounded by word separators. The following are considered word separators:

.?!,;:()="

and

start of string, end of string, and spaces.

Note:   is NOT considered a space, so if it is desired to use the literal macro name within the HTML project, it can be either preceded or followed by a   which ends up looking on the Amulet LCD as a regular space. Another option is to precede or follow the literal variable name with a  which puts in a space holder that the Amulet doesn't display. The only problem with using  is that some HTML editors "help you" by changing  to  which will not work.

Because the preprocessor scans all the text in your HTML project, it is advised to use macro names that will not show up normally. We suggest starting all of your macro names with an uncommon character, like % or #. Another common practice is to bracket the macro name with %, such as %macro%. This will serve two purposes. One, it makes it easy to see your macros when looking at your HTML source. Two, you won't have to worry about having the preprocessor do a text substitution when you didn't really mean it. The Amulet macro preprocessor is very flexible, though, so you are not required to use any special characters, but care should be taken in the naming of macros.

Enabling the HTMLCompiler Preprocessor:

By default, the Amulet HTMLCompiler preprocessor is not enabled. You can enable the preprocessor by specifying an include file. Click here to see an example. The syntax for specifying an include file is:

<META NAME="Macro" SRC="filename">

The include file, filename, needs to include the relative path to the file if it resides in a different directory than the HTML calling page. For instance, if using a macro file named Macro.txt, which resides in the root directory, but the calling page resides in a sub-directory, the META declaration would look like this:

<META NAME="Macro" SRC="..\Macro.txt">

And conversely, if Macro.txt resides in a sub-directory called Folder2 and the calling page resides in the root directory, the META declaration would look like this:

<META NAME="Macro" SRC="Folder2\Macro.txt">

Defining macros:

All macros must start with #define, followed by white space, then the macro name, more white space, then the textual substitution. Neither the macro name nor the textual substitution are allowed to have any white space within it. White space is considered either spaces or tabs. Inside the include file, any text to the right of the comment characters // is treated as a comment. It is okay to have a comment on the same line as the macro definition.
As an example, the syntax is as follows:

#define macroName textSubstitution

As you can see from the examples above, it is legal to use macros to define other macros. Forward references are allowed. For example, both of the following are legal:

#define  %getCnt  %cnt.value()                // forward reference to %cnt is okay!
#define  %cnt     Amulet:InternalRAM.byte()

as well as

#define  %cnt     Amulet:InternalRAM.byte()
#define  %getCnt  %cnt.value()

Using macros to initialize InternalRAM:

A powerful feature of the Amulet HTMLCompiler preprocessor is that it enables you to use defined macros anywhere in the HTML project, including in the initialization of Internal RAM variables. For example, to initialize an Internal RAM byte variable referenced by the macro %counter to a value of 16, you would use the following nomenclature in the Internal RAM initialization file:
InternalRAM.byte(%counter) = 16

You can also use a macro as the value of an InternalRAM variable as well. For example:

InternalRAM.byte(%counter) = %time