XScript Language Reference
From VCGR Wiki
Contents
|
Introduction – What is XScript?
The XScript scripting language is an XML-based scripting language developed by the Global Bio Grid research group at the University of Virginia for use with it's Genesis II grid software. Originally the language was designed to support only minimal capabilities – enough to get the project started until something better could be developed – but has grown into a more sophisticated and fully featured language in its own right.
Today, the XScript language supports many of the language features that one would expect from a programming language including loops, conditionals, and exceptions. While the language is still not officially supported, the need for documentation remains. To that end, this document serves as the language reference for the XScript 1.0 scripting language.
Namespaces
The XScript language supports two namespaces for it's XML elements. The first one is used for language elements and is abbreviated as gsh. The second indicates that the element is for a Genesis II grid command and is abbreviated geniix. We will use the first of these, gsh, as the default namespace for all XML in this document and thus assume that the root element of all XScript scripts looks like the one shown in the figure below.
<xml version="1.0" encoding="utf-8" ?>
<gsh:script
xmlns:gsh="http://vcgr.cs.virginia.edu/genii/xsh/script"
xmlns:geniix="http://vcgr.cs.virginia.edu/genii/xsh/grid"
xmlns="http://vcgr.cs.virginia.edu/genii/xsh/script">
...
</gsh:script>
Running XScript Scripts
Before we delve into the language itself, a word about running XScript scripts is in order. Genesis II supports multiple scripting languages through the use of the Java Scripting API. In order to differentiate between the various scripting languages, Genesis II uses filename extensions to determine the correct language to use when running scripts. Thus, to run a JavaScript script, one would indicate a file whose filename ended in the .js extension. Similarly, to run an XScript script file, the filename must end with the .xml filename extension.
XScript Variables/Macros
Every attribute value and text content node of an XScript script can include a reference to a variable. If included, the value of this variable will be inserted at run time as a macro replacement. Further, variables are scoped by their statement level. This makes it possible to write scripts that contain multiple variables of the same name without additional variable definitions interfering with outer definitions.
Variables in XScript documents are indicated by surrounding the variable name with ${ and }. Thus, to indicate the value of the NAME variable, one would use the string ${NAME} anywhere that text was expected (such as for an attribute value or as the text content of an appropriate XScript statement).
Arrays are also supported in the XScript language, though at the time of the writing of this document, only for accessing passed in as parameters to either the script itself, or to functions. The length of an array in XScript is indicated with the ${ARRAY_VARIABLE} expression syntax, while the elements inside of the array are indicated with the ${ARRAY_VARIABLE[INDEX]} syntax. Thus, to echo all elements of the ARGUMENTS array, one might use the following XScript code.
...
<for param-name=”i” exclusive-limit=”${ARGUMENTS}”>
<echo message=”Argument ${i} is ${ARGUMENTS[${i}]}.”/>
</for>
...
Arguments passed in to the script as well as those passed into function are contained in the ARGV array variable (for command line arguments passed into the script, the first element is the name of the script file itself).
XScript High-level Description
In XScript, every XML element (other than the root document element) represents a single language statement. These statements may or may not themselves contain other statements depending on the element type in question. For the most part, those statements which can support inner statements are the language feature elements such as conditionals and loops, while those that cannot generally represent simple statement types like echoes, grid commands, and sleep statements. Further, in XScript, every XML elements falls into one of two categories. The first category represents the language features and these elements are always in the gsh namespace (which, recall, is the default namespace). The second category is the grid commands category. These elements are always in the geniix namespace and the name of the element must directly match a Genesis II grid command.
Grid Command Elements
The simplest form of statement in an XScript script is a grid command. Grid commands are identified by belonging to the geniix namespace. Any time an XML elements exists in this namespace, the XScript engine attempts to find a grid command with the same name as the element's local name. If it finds such a command, the statement is assumed to represent that command, otherwise an exception is thrown. Parameters (commandline arguments to the grid command) are indicated with XScript param elements described later in this document. Below we show example grid commands in the XScript language.
... <geniix:ls/> <geniix:cp> <param>--local-src</param> <param>/etc/passwd</param> <param>/home/passwd</param> </geniix:cp> ...
XScript Language Elements
The remainder of this document will present XScript language elements. For each element, a short description will be given followed by a table of all applicable element attributes (if any exist). Following this, a more detailed description will be given as well as an indication of whether or not nested statements are permitted.
echo
The echo statement is used to echo output to the console.
| Attribute Name | Required? | Description |
|---|---|---|
| message | yes | The text message to display to the console. |
The echo statement indicates that text should be printed to standard out of the scripting engine. This statement cannot contain other statements.
define
Defines a new variable and associated value.
| Attribute Name | Required? | Description |
|---|---|---|
| name | yes | The variable to define. |
| source | yes | The source or value of the variable (usually text with macros) |
| pattern | no | A regular expression to do a search and replace on the source text with (the use of this attribute requires the inclusion of the replacement attribute). |
| replacement | yes (required only if the pattern attribute is given) | A string value to replace all occurances of the pattern regular expression with |
The define statement is used to define variables (or assign values to them). This statement type cannot include any inner statements. Note that it is not required that a variable be defined before it is used.
default
The default statement is included as a short-cut for defining variables that are currently undefined.
| Attribute Name | Required? | Description |
|---|---|---|
| name | yes | The variable to define. |
| value | yes | A default value to assign to the variable if the variable is currently un-defined. |
The default statement is similar to the define statement in that it assigns a value to a property, but it differs in that the value is only assigned if the property was un-defined before the statement executed. The default statement cannot contain any sub-statements.
sleep
The sleep statement causes the XScript script to pause for a certain period of time.
| Attribute Name | Required? | Description |
|---|---|---|
| value | yes | An integral value indicating a period of time to sleep. |
| units | no | A string giving a unit type associated with the value attribute. The default is MILLISECONDS. |
The sleep statement causes the running script to sleep for a period of time indicated b the value attribute and the units attribute. The units attribute must contain a string which matches on of the enum values supported by the java.util.concurrent.TimeUnit enumeration. Valid values include DAYS, HOURS, MICROSECONDS, MILLISECONDS, MINUTES, NANOSECONDS, and SECONDS. This statement cannot have any sub-statements.
exit
The exit statement causes the running script to exit at that moment with the exit code given.
| Attribute Name | Required? | Description |
|---|---|---|
| exitcode | yes | The integer exit code with which to exit the running script. |
The exit statement causes the running script to exit with no further action. This statement cannot have any sub-statements.
param
Param statements are used to indicate a parameter to either a grid command or to another XSCript function. These statements have no attributes and the value of the parameter is indicated as the text content of that XML element (thus, param statements can have only text as their inner content, not other XScript statements).
condition
Defines a variable as a boolean value based off of conditional statements included as sub-statements of the condition.
| Attribute Name | Required? | Description |
|---|---|---|
| property | yes | The variable to assign the boolean result to |
Condition statements define a variable as having a boolean value. The value assigned to the variable is determined by the conditional expression contained within the condition statement. Only one conditional expression is permitted inside of a condition statement (though some conditional expressions such as or, and, and not may themselves contain sub-statements).
Condition statements must contain a sub-statement which results in a boolean value. These sub statements include:
- and
- or
- xor
- not
- equals
- istrue
- isfalse
- isset
- matches
- compare
and
A boolean expression that combines all boolean sub-expressions using a logical and operation. The and statement has no attributes and can contain any number of conditional sub-expressions.
or
A boolean expression that combines all boolean sub-expressions using a logical or operation. The or statement has no attributes and can contain any number of conditional sub-expressions.
xor
A boolean expression that combines all boolean sub-expressions using a logical xor operation. The xor statement has no attributes and can contain any number of conditional sub-expressions.
not
A boolean expression that negates the value of a contained conditional sub-expression. The not statement has no attributes and can contain exactly one conditional sub-expression.
equals
A boolean expression which tests whether or not two strings are equal (this statement will work for integer numbers, but only in so much as it does a string comparison of them).
| Attribute Name | Required? | Description |
|---|---|---|
| arg1 | yes | The first argument to compare |
| arg2 | yes | The second argument to compare |
| casesensitive | no | Indicates whether or not the string comparison should be case sensitive. This attribute must have a value of either true or false. The default value is true. |
The equals statement tests for string equality of two arguments. This statement cannot contain any sub-statements.
istrue
Tests whether or not a variable contains the boolean value true.
| Attribute Name | Required? | Description |
|---|---|---|
| value | yes | The name of the variable to test |
This statement is used to test whether or not a variable represents a boolean true value. These variables are usually the ones assigned to by condition statements. This statement cannot contain any sub-statements.
isfalse
Tests whether or not a variable contains the boolean value false.
| Attribute Name | Required? | Description |
|---|---|---|
| value | yes | The name of the variable to test |
This statement is used to test whether or not a variable represents a boolean false value. These variables are usually the ones assigned to by condition statements. This statement cannot contain any sub-statements.
isset
Tests whether or not a given variable has been set yet.
| Attribute Name | Required? | Description |
|---|---|---|
| property | yes | The name of the variable to test |
If the indicated variable hsa been set, then this expression returns true. Otherwise, the result is false. This statement will look for any variable of the given name, thus, scoped variables above the scope of this statement can satisfy this expression. This statement cannot contain any sub-statements.
matches
Tests whether or not a given string matches an indicated regular expression.
| Attribute Name | Required? | Description |
|---|---|---|
| string | yes | The string to test |
| pattern | yes | The regular expression to test the string against. |
Does a regular expression test against the given string. This statement cannot contain any sub-statements.
compare
The compare expression is used to compare two values against one another.
| Attribute Name | Required? | Description |
|---|---|---|
| numeric | no | A boolean attribute (true or false) that indicates whether numeric, or textual comparison is indicated. The default value is false. |
| arg1 | yes | The first argument to compare |
| arg2 | yes | The second argument to compare |
| comparison | yes | An enumerated attribute which contains one of the values lt, le, eq, ge, or gt. |
The comparison statement produces a boolean value by testing two arguments against one another. If the numeric attribute is true (the default is false), then the comparison will be a numeric comparison. Otherwise, the canonical alphabetization comparison is used. The comparison to perform is determined by the comparison attribute which has one of the following values (and associated meanings).
- lt
- true if arg1 is less than arg2
- le
- true if arg1 is less than or equal to arg2
- eq
- true if arg1 is equal to arg2
- ge
- true if arg1 is greater than or equal to arg2
- gt
- true if arg1 is greater than arg2
This statement cannot contain any sub-statements.
switch
The switch statement is used to select a block of code to run from amongst a number of choices.
| Attribute Name | Required? | Description |
|---|---|---|
| value | yes | The text to use in the switch comparison |
The XScript switch statement works very similar to the way that switch works in bash. THe value attribute gives a string value which is to be compared against a number of regular expressions. The first one that it finds that matches is run. Only two XScript statements are permitted as children of the switch statement -- case' and default. 0 or more case statements are permitted, but only 0 or 1 default statements can be included. If no case statements match, then the default (if it exists) is run.
case
Case statements occur inside of switch statements and indicate a possible match for the switch value.
| Attribute Name | Required? | Description |
|---|---|---|
| pattern | yes | Indicates a regular expression against which the outer switch value is compared. |
Case statements contain other statements that are run when the case pattern matches the outer switch value. Case statement can container 0 or more other XScript statements.
default
Default statements occur inside of switch statements and are run when no case statement matches the switchs value attribute. Default statements contain no attributes and can container 0 or more other XScript statements.
if
The if statement is used to execute code conditionally based off of a boolean property value.
| Attribute Name | Required? | Description |
|---|---|---|
| test | yes | Gives the name of an attribute (not the value) that is to be tested for a boolean value. This is often a property set by the condition statement. |
The if statement contains either one or two sub-statements that indicate which script code to run based off of the truth of the test property. If only one sub-statement is included, it must be the then statement element. If two are included, one must be then and the other must be the else sub-statement. If the test property is true, then the then statement block is executed. If the test property is not true, and if an else sub-statement exists, then the else block of script is executed.
then
This statement is included inside of an if statement and the block of code is run if and only if the test value from the if statement tested true. The then statement can contain any number of sub-statements.
else
This statement is included inside of an if statement and the block of code is run if and only if the test value from the if statement tested false. The else statement can contain any number of sub-statements.
for
The for statement permits a simple kind of iteration structure where one can iterate over a count of integers.
| Attribute Name | Required? | Description |
|---|---|---|
| param-name | yes | Gives the name of a variable that will contain the count value. |
| initial-value | no | Gives an initial integral value for the count to start with. The default value is 0. |
| increment-value | no | Gives an integral value by which the count will be increased every time through the loop. The default is 1. |
| inclusive-limit | one of inclusive-limit and exclusive-limit is required | Gives a limit (inclusive) up to which the count proceeds before the loop exits. |
| exclusive-limit | one of inclusive-limit and exclusive-limit is required | Gives a limit (exclusive) up to which the count proceeds before the loop exits. |
The for statement is a simple looping statement which executes all contained sub-statements one time each for each progression of a count variable. This statement can contain any number of sub-statements.
foreach
A specialization of the for loop, the foreach statement loops over a set of values.
| Attribute Name | Required? | Description |
|---|---|---|
| param-name | yes | Gives the name of a variable that will contain the count value. |
| source-dir | one of source-dir, source-file, or source-rns is required | Indicates a directory containing a number of entries over which the loop will progress. |
| source-file | one of source-dir, source-file, or source-rns is required | Indicates a file containing a number of lines of text over which the loop will progress. |
| source-rns | one of source-dir, source-file, or source-rns is required | Indicates an RNS directory containing a number of entries over which the loop will progress. |
| filter | no | Indicates a regular expression which will be used to filter the set of entries to loop over. |
The foreach statement permits the script to iterate over a set of entries. The entries are given either by lines in a text file (using the source-file attribute) or over entries in a local (source-dir) or a grid (source-rns) directory. If the filter attribute is given, then only entries or lines which match that regular expression are used. The foreach statement can contain any number of XScript sub-statements.
throw
Causes the XScript engine to throw a Java exception.
| Attribute Name | Required? | Description |
|---|---|---|
| class | yes | The Java exception class to throw an instance of. |
| message | yes | A string message to construct the Java exception class with. |
Throws a new exception (which has to be a valid Java exception). This statement cannot contain any other sub-statements.
try
Being a try/catch/finally block for catching exceptions thrown from sub-statements. This statement can only contain sub-statements of the block, catch, or finally type. The try statement must contain exactly one block statement, any number of catch statements, and a single optional finally statement.
When encountered, the try statement causes the block statement to be executed. If an exception is thrown which matches any of the catch statements, then the first matching catch statement is executed. Finally, if a finally statement is included, then that statement is executed after the block and any catch statements no matter what.
block
This statement is included inside of try statements and can contain any number of sub-statements. This statement is always executed inside of a try statement.
catch
The catch statement is used to catch exceptions thrown from a block of script code.
| Attribute Name | Required? | Description |
|---|---|---|
| class | yes | The Java exception class to catch. |
| property | no | A property name to hold the exception (if caught). |
| message | no | A property name that will hold the exception's text message when caught. |
When an exception is caught, the property and message attributes indicate variable names to use to store the exception and the message from the exception. The former is of limited use at this point as the language doesn't deal well with complex types, but the message can be used for printing out text. The catch statement can contain any number of sub-statements.
finally
A finally statement is guaranteed to be run at the end of every try statement no matter what happens inside the trys block or catch statements. It can contain any number of sub-statements.
function
A function statement defines a new function that can be called from other parts of the script.
| Attribute Name | Required? | Description |
|---|---|---|
| name | yes | The name to give the function. |
Functions can contain any number of sub-statements and are called using the call statement. Inside of a function, the ARGV array variable is defined to match the parameters that were used to call that function.
return
Return statements allow for early returns from a defined function. Thus, they can only be used inside of function statements.
| Attribute Name | Required? | Description |
|---|---|---|
| property | One of property, value, or included sub-statements is required | Gives the name of a property whose value is to be returned. |
| value | One of property, value, or included sub-statements is required | Gives a string value to return as the result. |
Return statements return from a function with a given value. The value is either taken from the property attribute, the value attribute, or it can be set by executing any number of contained sub-statements (the value of a set of sub-statements is the value of the last statement to execute).
call
Calls a defined function by name.
| Attribute Name | Required? | Description |
|---|---|---|
| function | yes | Indicates the name of the function to call. |
| property | no | Indicates a property or variable that will hold any results returned from the function. |
A call statement is used to call a defined function by name. This statement can only have param statements contained within as sub-statements. If the property attribute is included, then it indicates the name of a property or value that is to hold the result returned from the function after the call.
parallel
The parallel statement marks a block of code that MAY contain parallel-job statements to execute in parallel threads.
| Attribute Name | Required? | Description |
|---|---|---|
| thread-pool-size | no (default is 8) | An integer indicate how many simultaneous threads can be used to execute parallel jobs. |
A parallel statement is used to mark the beginning and end of a section of code that might be run in parallel. Parallel statements can contain any number of sub-statements. When a parallel statement start executing, a thread pool is created of the indicates size. Every time a parallel-job statement is encountered, its statements are automatically queued into the thread pool and may execute in parallel. When the parallel statement finishes, it blocks until all running or queued parallel jobs finish.
parallel-job
A parallel job statement indicates a section of script code which can execute in parallel. These statements do not have to be contained directly under parallel statements, but they have to exist somewhere within a parallel statement at some level. Parallel-job statements are automatically enqueued into the nearest (on the call stack) parallel statement block. Parallel-job statements can contain any number of sub-statements.
