CLI: Developer's Overview to the Command Line Interface for BIE

OVERVIEW

The command line interpreter can be used to create objects defined in the galaxy source code and invoke methods defined on these objects. The compile time reflective information used in CLI is obtained by annotating source files with stylized comments and using Perl scripts to extract the comments and produce C++ code.

The code for CLI consists of the following:

• cli.ll, cli.yy - lexer and parser for the interpreter.

• galext, gal_constr_gen, gal_method_gen gal_static_gen, and gal_string_gen - perl scripts that extract stylized comments from header files and produce C++ code.

• The classes AData, ArgList, Expr, CallExpr, SimpleExpr, ForStatement PrintStatement, AssignStatement, MethodTable, and SymTab.

ADDING A CLASS, METHOD, CONSTRUCTOR, OR GLOBAL VARIABLE TO CLI

The perl script 'galext' takes as input a list of files in which special comments have been added. The Makefile controls which files are passed in, and the files vary depending on which modules are shipped in a distribution.

All special comments are of the form

+ <information>

The following comments are currently recognised by the extractor:

+ CLICLASS classname SUPER superclassname [max_dimensions] This makes CLI aware of the class "classname". SUPER and [max_dimensions] are optional. [max_dimensions] indicates that an array of objects of type classname can be created with maximum dimensions = max_dimensions.

+ CLASS classname SUPER superclassname [max_dimensions] This makes MethodTable aware of the class "classname", but the class is not normally available in CLI. This construct is used for classes not available in CLI, but for which reflective operations are required by other parts of the system (e.g. the persistence module). CLI can access these classes by setting the global variable "restrictcli" to false. Again, SUPER and [max_dimensions] are optional.

+ CLICONSTR arg1type arg2type arg3type ... Declares a constructor for the current class and the types of the arguments to CLI. The types should be entered exactly like as C++ types (e.g. int double) with no spaces within a single type (e.g. pointer to Tile should be entered as Tile*). Where a constructor has optional arguments, the different invocations can be declared using multiple CLICONSTR comments.

+ CONSTR arg1type arg2type arg3type ... Declares a constructor for the current class and the types of the arguments, but only makes the constructor available internally and not to CLI.

+ CLIMETHOD returntype MethodName arg1type1 arg2type.... Declares a method in the current class and the types of the arguments to CLI.

+ METHOD returntype MethodName arg1type1 arg2type.... Declares a method in the current class and the types of the arguments, but only makes the method available internally and not to CLI.

+ STATICCLIMETHOD returntype MethodName arg1type1 arg2type.... Declares a static method in the current class and the types of the arguments to CLI. A static method does not require an object to be invoked. However, static calls not invoked on an object are not yet supported in CLI.

+ STATICMETHOD returntype MethodName arg1type1 arg2type.... Declares a static method in the current class and the types of the arguments, but only makes the constructor available internally and not to CLI. A static method does not require an object to be invoked.

+ GLOBAL vartype varname Declares a global variable to be available within CLI.

CLI can access "non-CLI" methods by setting the global variable "restrictcli" to false. It is anticipated that this facility will only be for testing and not for general use. A CLICLASS or CLASS comment must precede use of all constructor and method declarations. However, CLI scoped methods or constructors cannot be declared in non-cli classes.

DOCUMENTATION FOR CLASSES, METHODS, AND CONSTRUCTORS

A stylized comment for a class or a method should be followed by a description comment. Short description comments can be specified using a series of lines that each begin with a //* comment. Longer description comments can be enclosed within C-style comments beginning with /**. These comment will be extracted and stored as the description for the class/method, and are accessible through CLI's desc command. These comments are also extracted by doxygen, meaning both the CLI and doxygen documentation can be specified with a single comment.

VARIABLE TYPES IN CLI

The CLI (through the AData object) only understands a subset of basic variable types and pointers. Your classes and methods can not be instanteated or called from within the CLI unless these basic types are used. The type list is:

• bool
• unsigned int
• int
• float
• double
• string
• type* -- where type is any other understood object including classes and the basic types above. For example:
  • set mystat = new EnsembleStat()
• (*type)[N] -- arrays of objects including classes and the basic types above. For example:
  • set myarray = new EnsembleStat[6]

NB: For convenience, we made a decision to have the basic character type be a string, although you will notice that the code base still contains hooks for the char* type. The CLI command takes all literal character strings and assigns them to a string variable, e.g. set myfile = "my.file" defines a variable "myfile" to be type string. You can always convert a string to a char* internally using the member function c_str().

ERRORS AND WARNINGS FROM GALEXT

The galext script emits error messages and will stop a build for serious errors. For example, possible errors include:

• Superclass specified for a class not declared.
• Badly specified comment (e.g. method name missing, global variable name missing).
• Declaration of a CLI method, or CLI constructor, in a non-cli class.

Warnings are emitted for less serious problems, but a warning will not stop a build from finishing. Warning messages are sent to a log file called cli.warnings. Situations where warnings are produced include:

• Missing description of a class, method, or constructor.
• Description comment not associated with a class, method, or constructor comment

AUTOMATICALLY GENERATED FILES.

• methods.out

This file is produced by the galext script, and contains information about classes, methods, constructors, and globals. It is used by the scripts gal_constr_gen and gal_method_gen to write C++ source files containing constructor and method invocation code respectively. The script gal_string_gen writes the contents of the methods.out file to a constant character array in the file MethodString.cc. This string is processed when CLI is loaded.

• includes.out

This file contains a list of all the header files that class information was extracted from. The file is then used by the gal_constr_gen and gal_method_gen scripts to include all necessary header files.

• Constructors.cc

Automatically generated C++ source file that is used by MethodTable to launch constructors. MethodTable describes the constructor to be called by passing the signature (i.e. name, return type, and argument list). The code in this file unpacks the arguments, calls the constructor, and packs up the constructed object in a returned value.

• Methods.cc

Automatically generated C++ source file that is used by MethodTable to launch methods. MethodTable describes the method to be called by passing the signature (i.e. name, return type, and argument list). The code in this file unpacks the arguments, calls the method on the given object, and returns the return value.

• StaticMethods.cc

Automatically generated C++ source file that is used by MethodTable to launch static methods when they are invoked without an object. When static methods are invoked on an object, they are handled in Methods.cc. As in Methods.cc, MethodTable describes the method to be called by passing the signature. The code in this file unpacks the arguments, calls the method on the given object, and returns the return value.

• MethodString.cc

This file includes a string containing the exact contents of the methods.out file. This string is parsed by MethodTable when CLI is launched, giving MethodTable information about classes, methods, and constructors defined by the stylized comments. The methods.out file is not used directly by MethodTable so that this file does not need to be available when CLI is run, meaning executables can be moved to a different machine more easily.

• GlobalArray.cc

Automatically generated C++ source file that defines a table containing information about global variables. There is one entry in the table for each CLI global variable (those defined using "//+ GLOBAL"). Each entry contains the name, the type, and the memory address.

• GlobalArray.h

Automatically generated C++ header file containing a declaration of each CLI global variable (those defined using "//+ GLOBAL").

• SizeVals.cc

Automatically generated C++ source file that implements the function SizeVal::size_value. This function returns the size of a value held in an AData object.

• SizeVals.h

Automatically generated C++ header file that includes files required by the SizeVals.cc file.

HOW THE INTERPRETER WORKS

On starting the interpreter, a MethodTable is initialized, and will contain a table of classes. Each entry in the table stores a class name, super class name and contains a pointer to an array of methods. Each entry in the method array contains the method name, argument signature (a string with the types of the arguments concatenated), return type and a pointer to a linked list of argument types. A symbol table is created to store variables defined in the interpreter. Another table holds CLI global variables and handles conversions between the global array format and the CLI's AData format.