LavishScript:Preprocessor

Overview

The preprocessor is what initially reads script files from disk. As they are read, the preprocessor may handle commands directed to it, called directives. Preprocessor directives begin with # and must be at the beginning of the line. The preprocessor will also perform simple text replacements and macros.

In standard preprocessing, defines are generally synonymous with macros. LavishScript separates the two for different uses.

Defines

In LavishScript, a define is like an alias. A name gets replaced by another word or phrase. Names may consist of alphanumeric characters as well as underscores, so long as they do not begin with a number, and are case sensitive. Replacements may be anything at all, including nothing.

Valid Names

• Test
• X
• Four4
• _LAVISHSCRIPT_

Invalid Names

• 1
• 4Four
• Man@
• *Play

Define Directives

• #define <Name> <Replacement>

All occurences of <Name> from this point on will be replaced with <Replacement>

• #undef <Name>

Occurences of <Name> will no longer be replaced from this point on

Built-in Defines

Individual applications (such as Inner Space and Fury) may add their own built-in defines. The following are built into LavishScript itself

• _FILE_

The full filename of the current source file

• _LINE_

The current line number, of the current source file

• _LAVISHSCRIPT_

LavishScript version number, such as 1.08

Macros

In LavishScript, a macro is like a mini-function. Macros use parameters, which are then treated as defines within the macro when used later.

Creating Macros

#macro <Name>([Parameters])
  [statements...]
#endmac

Parameters themselves are not required, but the parentheses are. Each parameter should be a Name, and separated by commas.

Macros may later be removed with

#unmac <Name>

Using Macros

Macros can be used anywhere on any line in the script which is not a preprocessor directive. Macros are used by including the name, parentheses, and any replacements, like so:

#macro XOR(a,b)
  ${Math.Calc[a^b]}
#endmac

echo XOR(1,2)

The above after preprocessing would be whittled down to:

echo ${Math.Calc[1^2]}

Some macros may be several lines in length, so it is important to know how the macro is meant to be used. Macros that use only a single line, such as the above, will simply be inserted in the original line.

Branches

The LavishScript preprocessor supports standard preprocessor branching directives, including #if, #ifndef and #ifdef. #else, and #elif may be used in conjunction with the initial branching directives, and all must eventually end with #endif.

#if

#if is used much like the If command, but as preprocessor directives are not commands, the arguments given to #if should not be quoted. #if will conditionally process portions of the file, allowing some to remain unused by the script.

#if 0
 this works a lot like
 a "block comment".
 none of these lines
 will make it into the script
#endif

#else may be used to process a consecutive portion of the file, if the first part was not processed.

#if 0
 this will not be processed!
#else
 echo this will be processed!
#endif

#if will process any Mathematical Formulae given, like so:

#if 12+24==36
 #echo 12+24 is in fact 36
#else
 #echo 12+24 is not 36
#endif

#if also processes defines, which may also be used in formula:

#if _LAVISHSCRIPT_<1.08
 #error Requires LavishScript 1.08 or later. _LAVISHSCRIPT_ is not sufficient
#endif

#elif may be used as an "else if" -- if the above case did not match, this will be checked just like an if.

#if _LAVISHSCRIPT_<1.08
 #error Requires LavishScript 1.08 or later. _LAVISHSCRIPT_ is not sufficient
#elif _LAVISHSCRIPT_==1.10
 #error LavishScript 1.10 is incompatible with this script.
#endif

#ifdef

#ifdef simply determines whether a Name is defined, and otherwise works just like #if (but does not support #elif).

#ifdef _LAVISHSCRIPT_
 #echo _LAVISHSCRIPT_ is defined (first part gets replaced!)
#else
 #echo _LAVISHSCRIPT_ is undefined
#endif

#ifndef

#ifndef is the complement to #ifdef. It executes the first portion if the Name is undefined.

#ifndef _LAVISHSCRIPT_
 #echo _LAVISHSCRIPT_ is undefined
#endif

Using Multiple Script Files

#include is used to insert entire source files into the current position. The filename must be given as an argument to #include, enclosed in double quotes.

#include "MyFile"

#includeoptional works like #include, but will not produce an error if the file does not exist

#includeoptional "MyFile"

Displaying Text

#echo can be used to display some text (generally to a console, though there is no native LavishScript console -- they are provided by the applications) at the time of preprocessing.

#echo MyScript version 12

#error can be used to display some text, and then prevent any further preprocessing or execution of the script. This would usually be used in some sort of branch. #error will display the current source file and line number before the error message.

#error Error!