The EEL Preprocessor

EEL includes a preprocessor that can do macro substitution on the source text, among other things. You give preprocessor commands by including lines that start with "#" in your source text. A backslash character "\" at the end of a line makes the preprocessor command continue to the next line. This section lists the available preprocessor commands.

#define identifier replacement-text

This command defines a textual macro named identifier. When this identifier appears again in normal text (not in quotes), it is immediately replaced with the characters in the replacement text.

The rules for legal macro names are the same as the rules for identifiers in the rest of EEL: a letter or the underscore character "_", followed by any number of letters, digits, or underscore characters. Identifiers which differ by case are different identifiers, so mabel, maBel, and MABEL could be three different macros. For clarity, it's best to use all upper case names for macros, and avoid such names otherwise.

When the EEL compiler starts, the macro _EEL_ is predefined, with replacement text (1). The macros UNICODE and BUNICODE are also defined, with the same values. You can test for UNICODE to write EEL code that must also compile in older versions of Epsilon without Unicode support.

Note that these textual EEL macros are not related to keyboard macros. Only the EEL compiler knows about textual macros; Epsilon has no knowledge of them. You cannot bind a textual macro to a key, for example. Keyboard macros can be bound to a key, and the EEL compiler doesn't know anything about them, only the main Epsilon program. To further confuse matters, other editors refer to their extension languages as macro languages, and call all editor extensions "macros". In this manual, we never use the word "macro" to mean an editor extension written in EEL.

#define identifier(arg1,arg2,arg3,...) replacement-text

A macro with arguments is like a normal macro, but instances of the identifier in normal text must be followed by the same number of text sections (separated by commas) as there are arguments. Commas inside quotes or parentheses don't separate text sections. Each of these text sections replace the corresponding identifier within the replacement text. For example, the preprocessor changes

#define COLOR(fg, bg) ((fg) + ((bg) << 4)) int modecol=COLOR(8, 3); int mcol=COLOR(new_col(6,2),name_to_col("green"));
to

int modecol=((8) + ((3) << 4)) int mcol=((new_col(6,2))+((name_to_col("green"))<<4))
The command

#undef identifier

removes the effect of a prior #define for the rest of a compilation.

The command

#include <filename>

inserts the text in another file at this point in the source text. #include's may be nested. In the above format, the EEL compiler searches for the file in each of the #include directories specified on the command line, or in a default location if none were specified. See EEL Command Line Flags.

If you use quote marks (" ") instead of angle brackets (< >) around the file name of the #include command, the EEL compiler will first look in the directory of the original file for the included file, before searching the #include directories as above. With either delimiter, the compiler will ignore attempts to include a single file more than once in a compilation.

The command

#tryinclude <filename>

is the same as the #include command, except it's not an error if EEL cannot locate the specified file. EEL just ignores the command in that case.

The EEL compiler keeps track of the current source file name and line number to provide error messages during compilation, and passes this information along in the bytecode file (unless you used the -s command line option to suppress this). Epsilon then uses this information for the EEL debugger and profiler, and displays it when certain errors occur. You can change the compiler's notion of the current line and source file with the command

#line number "filename"

This makes the compiler believe the current file is filename, and the #line command appears on line number of it. If the file name is omitted, only the line number is changed.

#if constant-expression
... text ...
#endif

The #if command permits sections of the source text to be conditionally included. A constant expression (defined in Constant Expressions) follows the #if. If the value of the constant expression is nonzero, text from this point to a matching #endif command is included. Otherwise, that region is ignored. As part of the constant expression, the defined() keyword may be used; defined(XYZ) evaluates to 1 if a macro named XYZ has been defined, otherwise 0.

#if constant-expression
... text ...
#else
... text ...
#endif

If an #else command appears between the #if and the #endif, the text following the #else is ignored whenever the text preceding it is not. In other words, the text following the #else is ignored if the constant is nonzero.

#if constant-expression
... text ...
#elif constant-expression
... text ...
#else
... text ...
#endif

There may also be one or more #elif commands before an #else or #endif command. EEL evaluates each constant expression in turn, and includes the text following the first of these constant expressions that yields a nonzero value, skipping over all remaining commands in that block.

#ifdef identifier
... text ...
#endif

#ifndef identifier
... text ...
#endif

You can use the #ifdef command in place of the #if command. It ignores text between the command and a matching #endif if the identifier is not currently defined as a textual macro with the #define command. The text is included if the macro is defined. The #ifndef command is the same, but with the condition reversed. It includes the text only if the macro is undefined. Both commands may have #else or #elif sections, as with #if.

Previous Up Next
EEL Command Line Flags Epsilon Extension Language Lexical Rules