CLI: Using the Command Line Interface to BIE

OVERVIEW

BIE's Command Line Interface (CLI) controls the engine through a simple ASCII line-oriented interface. CLI supports interactive use, or can read scripts containing a collection of commands. From CLI, one can set and create variables, create objects, invoke methods, start and stop execution, connect I/O streams, define data filters, and invoke visualization tools (if included in the distribution).

CLI is part of the same OS process as the engine, and uses readline to provide command line history and line editing. Variable accesses, constructor calls, and method calls are all type-checked. This page describes how to use CLI and what it is capable of. For an example of a CLI script detailing a complete session, see this page. Developers should see the developer's overview.

CLI COMMANDS

Listing Classes and Methods

CLI's built in list command can be used to find a class or method of interest.

To list all classes available in CLI:

list classes

To list all the methods and constructors that are callable in a specific class:

list methods <classname>

Where callable, this command will include methods in superclasses. It also specifies the argument types expected when calling.

Getting descriptions of Classes and Methods

CLI's built in desc command is used to get a description of a class, method, or constructor.

To obtain a description of a class:

desc <classname>

To obtain a description of a method:

desc <classname> <methodname>

Where there is more than one method with the specified method name, descriptions for all methods with that name are printed.

Assignment to a variable using set

To assign to a variable, use the set command. Variables can be assigned to variables, literals (integer, floating point, boolean, and string), objects, and arrays.

For example, the following assignments could be valid (for more details of constructors, method calls, and arrays, see below):

  set var1 = "value"
  set var  = var1
  set var  = 12345
  set var  = 12.345
  set var  = true
  set var  = new class(args ...)
  set var  = new class[array_size]
  set var  = object->method(args)

If var is a global variable, type checking is performed to ensure a valid assignment. Otherwise a new session variable is created and assigned the value on the right hand side. If a session variable with the same name exists, it is overwritten.

Constructors and new

Creating a new object is done as it is in C++, using the new keyword. For example:

set var  = new class(args ...)

The specific constructor invoked is chosen by comparing the arguments passed in to the formal parameters of all the constructors for the type of object being created. If there are no constructors that match the argument list given, an error is returned. C++ preference rules apply where more than one constructor could accept the argument list: for example a constructor taking an int would be preferred to one taking a floating point value if the user gave an integer argument. However, if there was only a constructor taking a floating point number, then this constructor would be invoked. In the case where the argument is a pointer to a class, any arguments which are subclasses will also be accepted. There are situations where a call is ambiguous and could refer to more than one constructor, even after applying preference rules, but this is very rare.

Method call

The syntax for calling a method is similar to C++:

The syntax for this is

objectvar->method(args)
set var = objectvar->method(args)

The specific method invoked is chosen by comparing the arguments passed in to the formal parameters of all the methods with the given name. If there are no methods that match the argument list given, an error is returned. C++ preference rules apply for methods with the same name, just like they do for constructors.

Printing variables and values

The print command prints the type value of the expression evaluated on the right hand side. For example:

print <var>
print <literal>
print object->methodcall(args)

To print the type and value of every variable (including globals):

printall  

To print the names of objects that have a certain type or are a subtype:

printobject <classname>

CLI scripts

CLI can be used interactively, can be script driven, or can use a mixture of script and interactive commands. To run a CLI script, use the '-f' flag together with the script name when invoking CLI on the command line. If the interactive command is placed at the end of a script, when reached this will allow interaction at the CLI command prompt. This means that a script can be used to start a simulation, and the user can also view statistics or change aspects of the simulation during execution.

Everything after a '#' character on a line is a comment and is ignored.

The help command

To view help on commands and details of their syntax from CLI, type the help. This will display a list of possible help topics. Select one to display help information.

TessTool

TessTool is a GUI tool that can be used to visualize tessellations and to see statistics relating to the data and the simulated models. TessTool is an ongoing development project, and so may not be in your copy of the distribution. See the TessTool pages for more details.

Undocumented

for loops, sockets, visualizer.