XSCRIPT LANGUAGE REFERENCE

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.

Attributes

Attribute NameRequired?Description
messageyesThe 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.

Attributes

Attribute NameRequired?Description
nameyesThe variable to define.
sourceyesThe source or value of the variable (usually text with macros)
patternnoA 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).
replacementyes (required only if the pattern attribute is given)A string value to replace all occurrences 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.

Attributes

Attribute NameRequired?Description
|nameyesThe variable to define.
valueyesA 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.

Attributes

Attribute NameRequired?Description
valueyesAn integral value indicating a period of time to sleep.
unitsnoA 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.

Attributes

Attribute NameRequired?Description
exitcodeyesThe 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.

Attributes

Attribute NameRequired?Description
propertyyesThe 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).

Attributes

Attribute NameRequired?Description
arg1yesThe first argument to compare
arg2yesThe second argument to compare
casesensitivenoIndicates 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.

Attributes

Attribute NameRequired?Description
valueyesThe 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.

Attributes

Attribute NameRequired?Description
valueyesThe 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.

Attributes

Attribute NameRequired?Description
propertyyesThe name of the variable to test

If the indicated variable has 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.

Attributes

Attribute NameRequired?Description
stringyesThe string to test
patternyesThe 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.

Attributes

Attribute NameRequired?Description
numericnoA boolean attribute (true or false) that indicates whether numeric, or textual comparison is indicated. The default value is false.
arg1yesThe first argument to compare
arg2yesThe second argument to compare
comparisonyesAn 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.

Attributes

Attribute NameRequired?Description
valueyesThe 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.

Attributes

Attribute NameRequired?Description
patternyesIndicates 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.

Attributes

Attribute NameRequired?Description
testyesGives 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.

Attributes

Attribute NameRequired?Description
param-nameyesGives the name of a variable that will contain the count value.
initial-valuenoGives an initial integral value for the count to start with. The default value is 0.
increment-valuenoGives an integral value by which the count will be increased every time through the loop. The default is 1.
inclusive-limitone of inclusive-limit and exclusive-limit is requiredGives a limit (inclusive) up to which the count proceeds before the loop exits.
exclusive-limitone of inclusive-limit and exclusive-limit is requiredGives 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.

Attributes

Attribute NameRequired?Description
param-nameyesGives the name of a variable that will contain the count value.
source-dirone of source-dir, source-file, or source-rns is requiredIndicates a directory containing a number of entries over which the loop will progress.
source-fileone of source-dir, source-file, or source-rns is requiredIndicates a file containing a number of lines of text over which the loop will progress.
source-rnsone of source-dir, source-file, or source-rns is requiredIndicates an RNS directory containing a number of entries over which the loop will progress.
filternoIndicates 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.

Attributes

Attribute NameRequired?Description
classyesThe Java exception class to throw an instance of.
messageyesA 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.

Attributes

Attribute NameRequired?Description
classyesThe Java exception class to catch.
propertynoA property name to hold the exception (if caught).
messagenoA 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.

Attributes

Attribute NameRequired?Description
nameyesThe 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.

Attributes

Attribute NameRequired?Description
propertyOne of property, value, or included sub-statements is requiredGives the name of a property whose value is to be returned.
valueOne of property, value, or included sub-statements is requiredGives 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.

Attributes

Attribute NameRequired?Description
functionyesIndicates the name of the function to call.
propertynoIndicates 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.

Attributes

Attribute NameRequired?Description
thread-pool-sizeno (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.