Adding New Commands

This section is for C/C++ programmers who want to add new commands (i.e. command keywords) into the PiXCL language, and as such are expected to be reasonably familiar with the PiXCL application syntax.

The most common updates to the PiXCL interpreter take the form of new commands. This can be

merging a series of existing interpreted command operations into one compiled command. An example of this is identfying the current browser, starting it and displaying a web page. See the DisplayBrowser command.
creating new graphic draw commands e.g. the DrawMirrorText command.
adding support for new abilities in Windows. Support for the Windows Seven Libraries with eight commands is an example.

The PiXCL interpreter code is quite modular and very robust, and adding a new command keyword and argument list requires very little code. There are two types of command:

Fixed Argument commands that have 'N' arguments. These are the most common types of commands, with around 790 in PiXCL 10.2.
Variable Argument commands , such as DialogBox which have a variable number of arguments. These are 62 variable argument commands in PiXCL 10.2.

Let's create a new fixed arg command called MyFixCommand and a variable arg command called MyVarCommand . These commands are defined in text.cpp. Eventually the function declarations will be moved to pixcl.h (requiring a full rebuild) but this is not necessary initially.

A fixed command has an ARGLIST structure that defines the syntax, and sometimes one or more TOKENLIST structures if specific command TOKEN string values are to be used. A separate TOKENLIST is preferred but not essential for each TOKEN in the command arguments. For example, a command that has two sets of TOKEN strings and integer values could implement them all in one TOKENLIST if all the integer values are unique, but the preferred programming style is to use separate TOKENLISTs for each set.

The code would be something like this:

BOOL ProcMyFixCommand (VOID); // declaration

ARGLIST alMyFixCommand [] = {

P_BRACKET_LEFT, '\0',

... arguments defined here

P_BRACKET_RIGHT,'\0',

P_END

};

The P_BRACKET_LEFT and P_BRACKET_RIGHT element types (defined in pixcl.h ) are required, and all ARGLIST structures must end with a P_END type. A common programming error is to omit this, the Parse functions don't know where the ARGLIST ends, and odd syntax errors are the usual result.

In keyword table ArgFixedTab[ ] in strict alphabetical order you add

"MYFIXCOMMAND ", alMyFixCommand, ProcMyFixCommand,

"MYFIXCOMMAND " is upper case for readability only: the interpreter is case insensitive for all keywords built into the interpreter.

A variable argument command has at least one ARGLIST and often several ARGLIST structures to handle varying sets of command arguments.

BOOL InterpretMyVarCommand (VOID); // declaration

ARGLIST alMyVarCommand1 [] = {

P_BRACKET_LEFT, '\0',

... arguments defined here

P_END

};

ARGLIST alMyVarCommand2 [] = {

... more arguments defined here

P_BRACKET_RIGHT,'\0',
P_END
};

In keyword table ArgVariableTab[ ] in strict alphabetical order you add

"MYVARCOMMAND ", '\0', InterpretMyVarCommand,

Note the difference here. A fixed argument command is handled with a Proc* function, while a variable argument command is handled by an Interpret* function.

The Proc* function is reached after the interpreter identifies the command arguments and passes pointers to each one in the anArgBuffer[ ] integer array. anArgbuffer entries are pointers that are cast to the correct PiXCL data type i.e. integer, string, float and double constants and variables.

The Interpret* function on the other hand is passed the list of ARGLIST and TOKENLIST pointers via extern keywords, and the function code is responsible for interpreting each ARGLIST by calling ParseArgList(...).

Suppose that the new commands are created in a file MyNewCommnds.cpp, then this and text.cpp are the only two files needed to be compiled to build the new version of the interpreter. The Visual Studio project Post Build settings copy the new EXE to the PiXCL installation directory, where the new command can be immediately tested.