BlueScript: Core Procedures

The result of the last command executed in the block.

Processes a script as a nested block.

Halts processing with a BREAK condition. This condition will halt processing of a loop (e.g. the body of while or foreach) and continue execution of the script after the end of the loop construct. If execution is not currently within a loop then an error will be raised.

The exception code corresponding to the termination code of the given script body. A termination code of 0 corresponds to normal termination. See the description for other termination codes.

Evaluates the given script trapping errors if they occur. If an optional variable name is specified then the result of evaluating the script is stored in the given variable, regardless of whether the script generates a result or an error. In other words, if the script generates a result, the result is stored in the given variable and if the script generates an error, the error message is stored in the given variable. If no variable name is specified then the result of evaluating the script is discarded.

This procedure returns the result code generated by evaluting the script, as an integer. The following result codes are defined:

0

OK - indicates that evaluation completed successfully.

1

ERROR - indicates than an error was generated.

2

CONTINUE - indicates that an uncaught "continue" command was encountered.

3

BREAK - indicates that an uncaught "break" command was encountered.

4

RETURN - indicates that a return command was encoutnered.

Integers are used so that a Boolean test on the result can be performed to detect abnormal termination. For example:

Halts processing with a CONTINUE condition. This condition will halt processing of the current iteration of a loop (e.g. the body of while or foreach) and continue on to the next iteration of the loop. If the loop involves a test condition, then the test condition is evaluated before starting the next interation.

Creates a contextual procedure. A contextual procedure is like a global procedure except that it is only visible in the current context as well as any nested context (e.g. the inside of a foreach or while loop). The procedure is removed when the context is destroyed (e.g. the function returns).

See the proc command below for details on arguments.

Halts processing with an ERROR condition. The result of the interpreter is set to the argument, which is analogous to an error message. An error exception will then be generated which will halt processing entirely, unless it is caught (e.g. by a catch call).

The result of evaluating the expression.

Evaluates the given infix expression. Any variable or procedure calls in the expression are evaluated in the context of the expr call. The result of the evaluation is returned.

For efficiency, it is better to use a list construct rather than a string construct. For example, the following:

is generally more efficient than: If the argument to the expression is static, then the interpreter can cache the parse tree for the expression. In the latter case, the argument to expr is not static - it is the result of a substitution, so the parse tree of the infix expression must be rebuilt on each call to the expr procedure.

The script body is evaluated once for each element in list, in the order in which the elements appear in list. For each iteration, the variable var is set to the current element of list for which body is being evaluated.

The value of variable var if is set, or an empty string otherwise.

Declares that variable var is global. Any references to the variable var after a global command, within the same context or a nested context will refer to the variable var in the global context rather than the local context. The variable var need not already exist in the global context. However if it does not exist in the global context it will not be set to any value until it is explicitly set (e.g. via the set command).

Note that the use of global in the middle of a script can have some unintended side effects. For example, if the following script is part of a procedure body:

Then the first reference to x (before the call to global) refers to x in the local context. The call to global actually destroys the local variable x - the value is lost and cannot be retrieved. Also note that there is no way to undo the effects of a global in the current context. In this case, the reference to x will be to the global x until the local context is destroyed.

Calling global while in the global context has no effect.

The last result of the evaluated condition, or an empty string if no condition is executed.

A classical "if" construct.

True (1) if name is the name of a procedure in the current context or false (0) if there is no such procedure.

True (1) if name is the name of a variable that is set in the current context, or false (0) if there is no such variable.

Creates a global procedure. A global procedure is one that can be accessed from any context. Procedures use a different namespace from variables. Thus it is valid to have a procedure and a variable with the same name. These two objects will be unrelated.

args specifies the number and names of arguments that the procedure takes as a list. For example an args value of:

specifies that the procedure takes three arguments. When the procedure is called, then a new local context is created and the three arguments will be stored in the local variables x, y, z in the new context.

The argument list has two mechanisms for supporing variable numbers of arguments. The first is the specification of default values. For example, the specification of an argument list as:

means that if the third argument (z) is not specified in a call to the procedure, then it should take on the default value "foo". Default values can only be defined for the right-most arguments. For example, the following definition is invalid:

However, more than one argument can be given a default value so long as, for every argument with a default value, every argument to its right must also have a default value. For example, the following:

is a valid way of specifying default values for all arguments.

The second method is the catch-all argument. If the last argument name in the argument list is args then any arguments passed to the procedure that are not consumed by other arguments in the list are placed in a local variable called args. In other words, args will contain a list of all arguments not handled by other arguments (which will be empty if there are no extra arguments). For example, if a procedure has the following argument list:

and the procedure is called with the following arguments:

The variable x would be set to "a", the variable y would be set to "b" and the variable args would be set to the list "c d e".

Default values and catch-all arguments can be combined, for example: the following argument list is valid:

Halts processing with a RETURN condition. The result of the interpreter is set to the argument. If the argument is not specified then the result of the interpreter is set to the empty string.

The value of variable var.

If value is specified, then the value of variable var is set to value. The value of variable var is returned if and only if it is set.

Evaluates script until it halts - whether from reaching the end, encountering an exceptional condition (break, continue, return), or encountering an error. The script post will be executed regardless of how script halts. The idea is that post can be used to contain "clean-up" code (e.g. closing an open file). After post is evaluated, the procedure returns as though post had never been called - i.e. with whatever condition came out of script.

Note that if an error is generated while processing post, processing of post will halt and an error will be generated.

An empty string.

"Unsets" the given variable var if it is set. If it is not set, then this procedure call has no effect. After it is "unset", it is as though the variable had never been set.

A classic "while" construct. The script body is evaluated so long as the infix expression expr evaluates to a true value.