V:4.1.4/Karajan:System Library

From Java CoG Kit

< V:4.1.4

Jump to: navigation, search

Files: sys.k, sys.xml

The system library contains general purpose elements that help implement the most common tasks in Karajan.

Flow Control Elements

sys:sequential

sys:sequential()

Executes all arguments in sequence.

sys:parallel

sys:parallel()

Executes all arguments in parallel.

sys:unsynchronized

sys:unsynchronized()

Asynchronously executes all arguments in sequence. Does not return any value. If return values from asynchronous computations is required, use either future or futureIterator

sys:choice

sys:choice()

Executes arguments in succession. Terminates when one of the arguments completes successfully. If an argument fails, the next argument will have access to the following variables:

element: Contains a reference to the element that caused the initial failure.
error: A textual message detailing the error that occurred
trace: A textual representation of the Karajan stack trace.
exception: Available if a Java exception caused the failure.

If no argument completes successfully choice will fail with the last failure encountered.

Choice exhibits a transactional behavior when it comes to return values. All single values and all channels are buffered until one argument completes successfully. If that happens then choice returns the buffered values. If an argument fails, all the buffered values produced by that argument are discarded.

sys:catch

sys:catch(match)

Catch will match the error variable against the regular expression in match. If successful, it will execute the rest of its arguments, otherwise it will fail with the last failure encountered. Catch can be used with choice to selectively handle specific failures:

choice(
  ...
  catch(".*File not found.*"
    print("File not found")
  )
  catch(".*Connection refused.*"
    print("Connection refused")
  )
)

sys:guard

sys:guard()

Guard expects two sub-elements. It will execute the first, then the second, even if the first one fails. In other words, the second sub-element will always be executed. If the first element failed, after executing the second element, guard will also fail. If the second element fails, guard will fail with the same error, regardless of whether the first element failed or not. Guard can be used to implement clean-up actions, in a fashion similar to try/finally from C++, Java or Python:

set(myhost, "sunny.mcs.anl.gov")
transfer(srcfile="a", desthost=myhost)
guard(
  sequential(
    execute(executable="/usr/bin/hammer", arguments="a", host=myhost,    
      provider="gt2")
  )   
  sequential(
    //always clean up
    file:remove(name="a", host=myhost, provider="gridftp")
  )
)

sys:race

sys:race()

Aliases: parallelChoice

Can be used to race a number of arguments. Race will execute all its arguments in parallel, buffer their return values, and wait for the first one that completes. It will then return all the values that the winner generated. If an any argument fails before any other argument completes, then race will fail.

Race is similar in behavior to the discriminator workflow pattern.

sys:for

sys:for(name, in)

Can be used to iterate sequentially across a range of values. The name argument is an identifier that indicates the name of the variable that will be set to the successive values of the in argument, which Karajan will try to convert to an iterator before beginning the iteration process.

After evaluating name and in, for will proceed and evaluate the rest of the arguments repeatedly, while setting the variable indicated by the name argument to each value produced by the iterator (in).

Example:

equals(
  list(
    for(i, range(1, 5), i)
  )
  list(1, 2, 3, 4, 5)
)

will return true

sys:parallelFor

sys:parallelFor(name, in)

Will behave in a similar way to for with the exception that iterations will occur in parallel. Each iteration will occur in a separate scope. Therefore variables set in one of the iterations will not be visible in the others (which is also the case with for). Each scope will have the variable indicated by the name argument set to one of the values obtained from the in argument.

sys:while

sys:while(condition)

Will repeatedly execute its arguments in sequence until a value of false is received on the condition channel. A convenience element that returns a boolean argument on the condition channel is condition (or ?). While will check for a condition every time an argument completes. It is therefore possible to exit the loop after the termination of any of the arguments.

Example:

list(
  while(
    1, 2, 3, ?(false)
  )
)

list(
  while(
    1, ?(false), 2, 3
  )
)

list(
  while(
    ?(false), 1, 2, 3
  )
)

list(
  while(
    sequential(
      ?(false)
      0 
      /* zero will make it to the list
       * because while will only do the check
       * after sequential() completes
       */
    )
    1, 2, 3
  )
)

will return the following lists:

[1,2,3]
[1]
[]
[0]

Or, in XML:

<list>
  <while>
    <number>1</number>
    <number>2</number>
    <number>3</number>
    <condition>
      <false/>
    </condition>
  </while>
</list>

<list>
  <while>
    <number>1</number>
    <condition>
      <false/>
    </condition>
    <number>2</number>
    <number>3</number>
  </while>
</list>

<list>
  <while>
    <condition>
      <false/>
    </condition>
    <number>1</number>
    <number>2</number>
    <number>3</number>
  </while>
</list>

<list>
  <while>
     <sequential>
       <condition>
         <false/>
       </condition>
       <number>0</number>
     </sequential>
     <number>1</number>
     <number>2</number>
     <number>3</number>
   </while>
</list>

sys:condition

sys:condition(value)

Aliases: ?

Evaluates the value argument and returns its value on the condition channel.

sys:break

sys:break()

Can be used to break out of a while loop. By contrast with using the condition channel, break will immediately exit the loop, no matter how deep the nesting level. It does that by generating a failure, which is intercepted by the enclosing while.

sys:continue

sys:continue()

Can be used to skip the evaluation of the remaining arguments in an iteration in a while loop and jump to the next iteration. Similar to break, continue achieves its purpose by generating a failure which is intercepted by while.

sys:if

sys:if()

Executes its elements using the following scheme:

start with k = 0
evaluate element 2 * k;
if element 2 * k is the last element, then return its return values and complete
if no value is element by argument 2 * k, fail
if value returned by element 2*k is true then evaluates element 2*k+1 returning its return values, and completes
if value returned by element 2 * k is false then continue with k = k + 1

Informally:

if(
  <condition> <then>
  [<condition2> <then2>
  [<condition3> <then3>
  ...]]
  [<else>]
)

<condition>, <then>, and <else> can be any elements. However, each <condition>, <then>, and <else> must be only one element (possibly with multiple child elements). For convenience and clarity then and else can be used.

sys:then

sys:then()

Aliases: else

Then and else are the same as sequential, but can be used to make constructs using if more intuitive:

if(
  a == 1 
    then(print("a is 1"))
  a == 2
    then(print("a is 2"))
  else(print("a is not 1 nor 2"))
)

<if>
  <equals>
    <number>1</number>
    <variable>a</variable>
  </equals>
  <then>
    <print message = "a is 1"/>
  </then>
  <equals>
    <number>2</number>
    <variable>a</variable>
  </equals>
  <then>
    <print message = "a is 2"/>
  </then>
  <else>
    <print message = "a is not 1 nor 2"/>
  </else>
</if>

sys:exclusive

sys:exclusive()

Defines a mutual exclusion block. It guarantees that at any give time, within a given execution, only one instance of this (lexically) exclusive element is executing.

Elements Dealing with Variables and Arguments

sys:set

sys:set(names, ...)

Sets a variable or more to a value (or more). Set tries to interpret the first argument as an identifier or a list of identifiers. If the first argument is an identifier, it is treated as being a list with one identifier. Set expects the number of arguments on the default channel to be the same as the number of identifiers. It is important that a quoted list be used to specify the list of identifiers in order to avoid evaluating the variables that the identifiers represent:

set(a, 1)
set([a], 1)
set([a, b, c], 1, 2, 3)

Differences in XML:

The XML variant of the set element uses a slightly different set of arguments. If a single variable is assigned, the name argument can be used. If multiple variables are assigned, the names argument must be used. As opposed to the native syntax, the names argument can be a string of comma separated identifiers which will be tokenized by set

<set name="a" value="1"/>
<set names="a, b, c">
  <number>1</number>
  <number>2</number>
  <number>3</number>
</set>

sys:default

sys:default(name, value)

Assigns a value to a variable if no binding of that variable can be accessed within the current scope. If an accessible variable with the indicated name is already defined, then the assignment does not take place:

default(a, 1)
//a is assigned the value 1
set(b, 2)
default(b, 3)
//b is not assigned the value of 3 because
//b is already accessible within the current scope

sys:maybe

sys:maybe()

Evaluates its arguments. If the evaluation completes successfully, it returns all the arguments. If the evaluation fails at any point, maybe completes without returning anything. In particular, maybe can be used in extending existing elements with optional arguments:

element(one, [a, b, optional(c, d)]
  print("a = {a}", "b = {b}", maybe("c = {c}"), maybe("d = {d}"))
)

element(two, [a, b, optional(c, d)]
  one(a = a, b = b, maybe(c = c), maybe(d = d))
)

sys:global

sys:global(name, value)

Sets a global variable. A global variable is a variable that has a global scope, and thus can be accessed from anywhere within the program. While the use of global variables is discouraged, it can prove useful to create constant-like definitions.

Differences in XML:

The XML variant of global uses the same arguments as the XML variant of the set element.

sys:...()

Aliases: vargs

Can be used inside an element definition to return all arguments received on the default channel.

Differences in XML:

In the XML syntax the vargs alias must be used, because “...” is not a valid XML element name.

channel:to

channel:to(name, ...)

Returns all arguments received on the default channel on the specified channel.

channel:from

channel:from(name, <varies>)

Returns all arguments received on the specified channel on the default channel.

channel:close

channel:close(name)

Closes a channel. All iterations that are active on that channel and waiting for values will complete.

channel:fork

channel:fork(name, count)

Splits a channel into a number of identical channels and returns these channels. All values written to the initial channel will be available in all the forked channels. Reading from the original channel will cause inconsistencies and should not be done. When the original channel is closed, all the forked channels will also be closed.

sys:isDefined

sys:isDefined(name)

Determines whether a variable is accessible within the current scope. Returns true if it is; false otherwise.

sys:quoted

sys:quoted(name)

Returns an identifier without evaluating the variable it might point to.

sys:discard

sys:discard(...)

Sometimes only the side-effect of an element is needed, while ignoring the return values of the element. Discard will evaluate its arguments, but avoid returning anything on the default channel.

sys:future

sys:future(...)

Evaluates the arguments asynchronously. Returns a future representing the first return value generated by the arguments. All other arguments received on the default channel are ignored.

sys:futureIterator

sys:futureIterator(...)

Evaluates its arguments asynchronously. Returns a future iterator representing all values received on the default channel. The particular aspect of a future iterator is that it can only be iterated over once. Every time a value is used from a future iterator, that value is removed. If access to the iterator values is needed more than once, a list can safely be created with the values. However, the process of creating the list will force synchronization with the thread that produced the values since the iterator is only closed when that thread completes.

sys:each

sys:each(items)

Returns all elements in items as separate values. It is roughly equivalent to the following:

for(i, items, i)

Element Definition Elements

sys:element

sys:element(name, arguments)

Allows the definition of an element. Evaluates the name and arguments arguments. It expects the name argument to be an identifier, and arguments to be a list of identifiers. The scope of the definition is the same as the scope of a variable that could be defined instead of the element. The arguments are a list of mandatory arguments. Optional arguments can also be specified using the optional element. If the element accepts arguments on the default channel, the ... identifier can be used in the argument list. Other channels can be specified using the channel element. The rest of the arguments are not evaluated when the definition takes place, but will be evaluated whenever the element is invoked.

The following example defines an element foo, which takes no arguments, and prints ’foo’ on the console:

element(foo, []
  print("foo")
)

foo()

In the following example, foo takes two arguments and prints them both on the screen:

element(foo, [one, two]
  print(one)
  print(two)
)

foo(1, 2)

Arguments on the default channel can be accessed using the ... identifier:

element(foo, [one, ...]
  print(one)
  for(i, ...
    print(i)
  )
)

foo("one", 1, 2, 3, 4)

Other channels can be used in a similar way:

element(foo, [one, ..., channel(channelOne)]
  print(one)
  for(i, ..., print(i))
  for(i, channelOne, print(i))
)

foo("one", 1, 2, 3, 4, to(channelOne, 5, 6, 7, 8))

Optional arguments can be assigned a default value using default:

element(foo, [one, optional(two)]
  default(two, 2)
  print(one)
  print(two)
)

foo("one")
foo("one", two = "two")

Element can also be used to define anonymous elements. If the first argument evaluates to a list of identifiers instead of an identifier, element considers that an anonymous element was instead desired, defines the element, and returns the definition, which can later be used through executeElement:

set(foo,
  element([]
    print("Foo")
  )
)

executeElement(foo)

Each definition of an element keeps a reference to the environment that was used at the time of the definition. When evaluated, elements in the body of the definition will be resolved by first searching in the local scope (eventually for elements defined by the execution of the body of this element) and, if not found, in the environment that was used at the time of the definition. In the following example, the result will be the printing of the string "a":

element(foo, []
  element(a, [], print("a"))
  //return an anonymous element
  element([]
    a() //this is the a() defined above
  )
)

set(b, foo())
element(a, [], print("b"))
executeElement(b)

This behaviour is particularly important when import and export are used.

Differences in XML:

The arguments list is a string of comma separated identifiers.

The XML version of element uses a different set of arguments. If an element accepts arguments on the default channel, the vargs="true" attribute must be used. The arguments received on the default channel will then be available in the body of the definition through the vargs identifier.

Optional arguments are indicated using the optargs attribute. The value must be a comma separated list of identifiers.

In a similar way, the channels are specified using a comma separated list of identifiers and the channels attribute.

<element name = "foo" arguments = "one" vargs = "true" channels = "channelOne">
  <print message = "{one}"/>
  <for name = "i" in = "{vargs}">
    <print message = "{i}"/>
  </for>
  <for name = "i" in = "{channelOne}">
    <print message = "{i}"/>
  </for>
</element>

<foo one = "one">
  <number>1</number>
  <number>2</number>
  <number>3</number>
  <number>4</number>
  <to name="channelOne">
    <number>5</number>
    <number>6</number>
    <number>7</number>
    <number>8</number>
  </to>
</foo>

<element name ="foo" arguments = "one" optargs = "two">
  <default name = "two" value = "2"/>
  <print message = "{one}"/>
  <print message = "{two}"/>
</element>
 
<foo one = "one"/>
<foo one = "one" two = "two"/>

sys:parallelElement

sys:parallelElement(name, arguments)

Like element, parallelElement also defines an element. However, elements defined using parallelElement will evaluate their arguments in parallel with their bodies. All single value arguments will automatically be futures, and all channels will automatically be future iterators. ParallelElement can be used to define elements that process their arguments asynchronously.

parallelElement(consumer, [...]
  for(i, ..., print("Received {i}")
)

element(producer, []
  for(i, range(0, 100)
    i
    print("Sent {i}")
    wait(delay = 100)
  )
)

consumer(producer())

Differences in XML:

The differences for the XML syntax from element also apply to parallelElement

<parallelElement name = "consumer" vargs = "true">
  <for name = "i" in = "{vargs}">
    <print message = "Received {i}"/>
  </for>
</parallelElement>

<element name = "producer">
  <for name = "i">
    <range from = "0" to = "100"/>
    <variable>i</variable>
    <print message = "Sent {i}"/>
    <wait delay = "100"/>
  </for>
</element>

<consumer>
  <producer/>
</consumer>

sys:channel

sys:channel(...)

Used to specify channel arguments for an element. Quotes all arguments, such that identifiers are not evaluated. Returns values that can be interpreted by element and parallelElement as representing channels.

sys:optional

sys:optional(...)

Allows the specification of optional arguments for element definitions. Quotes all arguments and returns values that can be interpreted by element and parallelElement as representing optional arguments.

sys:self

sys:self()

Self can be used to build recursive anonymous elements:

set(f 
  element([x]
    if(x == 0 1 x*self(x - 1))
  )
)

print(executeElement(f, 6))

Service Interaction Elements

sys:remote

sys:remote(host)

Uses the Karajan:Service that runs on the specified host to evaluate the rest of the arguments. The element supports forwarding of the variable environment to the remote service ^[1], and returning values from the service. Therefore the following code will work as expected:

set(a, 1)
set(b
  remote("https://somehost:1984", a+1)
)
print(b) //will print 2

A consequence is that if print is used remotely, the actual output is going to be automatically and transparently forwarded (since it is merely a return value on a particular channel) to the execution instance that initiated the remote execution.

It is also possible to use this feature recursively, such that a remote code snippet in turn delegates part of the execution to other services.

Please note that the code inside remote might reference entities that are sensitive to the actual location of the execution. In particular, the meaning of “localhost” if used with execute or transfer will not refer to the machine where the execution originated.

Element resolution is performed separately when a script is submitted to a service. In other words, import-ed files on the client side will be re-imported on the service side, if and only if they are system libraries. If imports refer to user-defined libraries not part of the system libraries, the code defining the libraries will be forwarded to the service, thus enabling the use of client-side user-defined elements on the remote side. Similarly, in-line user defined elements are also available for use on the remote side:

element(foo, [], print("Foo"))
remote("https://somehost:1984"
  foo()
)

List Manipulation Elements

list:list

list:list(*items, ...)

Constructs a list from values received on the default channel.

Alternatively the *items argument can be used to specify a a string with comma separated list of items. This may be particularly convenient with the XML syntax.

list:append

list:append(list, *items, ...)

Appends all values received on the default channel to the list indicated by the list argument. Does not return anything.

Alternatively, the *items argument could be used with a string of comma separated items.

list:prepend

list:prepend(list, ...)

Works like append with the exception that values are added to the beginning of the list. The order of the values in the list will be the reverse of the order in which they are received by prepend:

set(l, list(4, 5, 6))
prepend(l, 1, 2, 3)
print(l)

will print [3, 2, 1, 4, 5, 6]

list:join

list:join(...)

Concatenates all lists received on the default channel and returns the resulting list.

list:size

list:size(list)

Returns the size of the list indicated by the list argument.

list:first

list:first(list)

Returns the first element in a list.

list:last

list:last(list)

Returns the last element in a list.

list:butFirst

list:butFirst(list)

Returns a list composed of all but the first element in the specified list.

list:butLast

list:butLast(list)

Returns a list containing all elements but the last from the specified list.

list:isEmpty

list:isEmpty(list)

Tests whether a list is empty. Returns true if the list is empty, and false otherwise.

Map Elements

map:map

map:map(...)

Returns a map with the entries received on the default channel. See entry.

map:entry

map:entry(key, value)

Allows the specification of an entry that can be used with map to construct a map.

map:put

map:put(map, ...)

Adds the entries received on the default channel to the specified map. Existing entries with the same key are replaced. Does not return any value.

map:delete

map:delete(map, key)

Deletes the entry with the specified key from a map. Does not return a value.

map:get

map:get(map, key)

Returns the value corresponding to the specified key from a map.

map:size

map:size(map)

Returns the size of the map (the number of entries in the map).

map:contains

map:contains(map, key)

Tests whether the map contains an entry with the specified key.

Logic Elements

Logic elements do not at this time use shortcut evaluation. They always evaluate all their arguments.

sys:and

sys:and(...)

Aliases: &

Returns the boolean and value of the arguments received on the default channel.

sys:or

sys:or(...)

Aliases: |

Returns the boolean or value of the arguments received on the default channel.

sys:not

sys:not(value)

Returns the boolean negation of the value in the value argument.

sys:equals

sys:equals(value1, value2)

Aliases: ==

Tests for the equality of two values. Makes a deep comparison of the arguments.

sys:true

sys:true()

Returns true.

sys:false

sys:false()

Returns false.

Numeric Elements

math:sum

math:sum(...)

Aliases: +

Returns the sum of all the values received on the default channel.

math:product

math:product(...)

Aliases: *

Returns the product of all the values received on the default channel.

math:subtraction

math:subtraction(from, value)

Aliases: -

Returns the difference between the value specified by the from argument and the value indicated by the value argument.

math:quotient

math:quotient(divisor, dividend)

Aliases: /

Divides divisor by dividend and returns the resulting value.

math:remainder

math:remainder(divisor , dividend)

Aliases: %

Returns the remainder of the division of divisor and dividend

math:square

math:square(value)

Returns the square of a number.

math:sqrt

math:sqrt(value)

Returns the square root of a number.

math:equalsNumeric

math:equalsNumeric(value1, value2)

Makes a numeric comparison of the values specified by the two arguments. A numeric comparison will try to convert string values to numbers before the comparison is performed. Like equals, equalsNumeric performs a deep comparison.

equalsNumeric(1, "1") //true
equalsNumeric("2", "2.0") //true
equals("2", 2) //false
equalsNumeric([1, 2, "3"], ["1", "2", 3]) //true

<equalsNumeric value1 = "1">
  <number>1</number>
</equalsNumeric> 
<equalsNumeric value1 = "2" value2 = "2.0"/> 
<equals value1 = "2">
  <number>2</number>
</equals> 
<equalsNumeric>
  <list items = "1, 2, 3"/>
  <list>
    <number>1</number>
    <number>2</number>
    <string>3</string>
  </list>
</equalsNumeric>

math:greaterThan

math:greaterThan(value1, value2)

Aliases: >

Returns true if value1 is strictly larger than value2

math:lessThan

math:lessThan(value1, value2)

Aliases: <

Returns true if value1 is strictly less than value2

math:greaterOrEqual

math:greaterOrEqual(value1, value2)

Aliases: >=

Returns true if value1 is larger than or equal to value2

math:lessOrEqual

math:lessOrEqual(value1, value2)

Aliases: <=

Returns true if value2 is less than or equal to value2

math:min

math:min(...)

Returns the minimum of all numeric values on the default channel.

math:max

math:max(...)

Returns the maximum of all numeric values on the default channel.

math:int

math:int(value)

Returns the integer part of the argument, where “integer part” is to be understood in the mathematical sense (also equivalent to the floor function).

math:ln

math:ln(value)

Returns the natural logarithm of the value argument.

math:exp

math:exp(value)

Returns e raised to the power of value.

math:random

math:random()

Returns a pseudo-random number in the interval [0,1) with a uniform distribution ^[2].

Error Handling Elements

sys:ignoreErrors

sys:ignoreErrors(*match)

Executes its arguments returning any values as they are received. If any of the arguments fails, the failure will be matched against the regular expression in *match if present (otherwise it will be treated as .*) ^[3]. If the match is successful, then the error will be ignored and the next argument will be executed. If the match fails, the error will be propagated.

sys:restartOnError

sys:restartOnError(match, times)

Evaluates its arguments in sequence. If a failure matching the regular expression in match occurs ^[3], all arguments will be re-evaluated for a maximum of times indicated by the times argument.

sys:generateError

sys:generateError(error, *exception)

Allows the generation of an error. The message of the error is taken from the error argument. *Exception is used in the current implementation to pass a Java exception to be attached to the error.

sys:onError

sys:onError(match)

OnError allows the definition of a custom error handler. Handlers defined with onError are valid for anything executed within the scope of the parent of onError. Multiple handlers can be defined within the same scope.

Whenever an error occurs within the scope of an error handler, the error will be matched against error handlers starting with the inner-most handlers and ending with the outer-most handlers. If a handler matches, it is invoked. When a handler is invoked it will evaluate all its arguments except for match in sequence. The execution takes place in the context of the failing element. The following variables are defined automatically to be used by the body of the error handler:

element: The element that caused the error. If the error is corrected by the handler, the execution of the element can be re-started using executeElement.
error: The message of the error that occurred.
trace: A textual representation of the Karajan stack trace.
exception: In the current implementation exception can either contain a Java exception or the message “No exception available”.

Error handlers are not re-entrant. If an unhandled error occurs within the body of the handler, the handler will fail immediately.

String Elements

str:concat

str:concat(...)

Concatenates all arguments received on ... and returns the resulting string value.

str:split

str:split(string, separator)

Returns a list obtained by splitting string in tokens separated by separator. The separator will not be part of the tokens.

str:strip

str:strip(value)

Strips all leading and trailing whitespace characters from value.

str:matches

str:matches(string, regexp)

Returns true if string matches the regular expression specified by regexp, and false otherwise.

str:nl

str:nl()

Returns the new-line separator.

str:chr

str:chr(code)

Returns the character whose code is represented by code.

Miscellaneous Elements

sys:print

sys:print(message, *nl)

Returns the value in the message argument on the stdout channel. If the *nl argument is not present or set to true, it appends a new line character to the message argument before returning it. The project (root element) automatically prints all argument received on the stdout channel on the console.

sys:echo

sys:echo(message, *nl, *stream)

Immediately prints the value in the message argument to the console. If the *nl argument is not present or set to true, it also prints a new line character. If the *stream argument is present, echo instead tries to print the message on the specified output stream.

The difference between print and echo is that print does not rely on a side-effect to print values. Therefore the evaluation of print cannot be distinguished from returning the value generated by print.

It is recommended that print be used instead of echo if possible.

sys:checkpoint(*file, *automatic, *interval, *timestamped, *now)

sys:checkpoint

Allows the configuration of checkpointing. If the *now arguments is present and set to true, creates a checkpoint of the state at the time of the evaluation of checkpoint, and writes it to the file indicated by the *file argument.

The *automatic argument, if set to true, indicates that automatic checkpoints should be created at the interval specified by the *interval argument (in seconds). If the *timestamped argument is also present and set to true, the file names in which the checkpoint is saved will have a date and time appended in the YYYYMMDDhhmm format.

sys:wait

sys:wait(*delay, *until)

When evaluated waits the number of milliseconds specified by the *delay argument or until the date in the *until argument before completing.

sys:time

sys:time()

Evaluates all arguments and returns the total time elapsed, in milliseconds.

set(t
  time(
    execute(executable="/bin/wait", arguments="10", ...)
  )
)

print("Job done in ", t/1000, " seconds.")

sys:file:execute

sys:file:execute(file)

Aliases: executeFile

Parses and executes a file. The difference between import and file:execute is that file:execute always parses and executes the file when evaluated, unlike import which only parses the file once. File:execute can therefore be used to execute files which change over time, or to execute different files based on a certain context.

sys:executeElement

sys:executeElement(element, args, ...)

Executes an element optionally passing the single value arguments indicated by the args argument, and the ... on the default channel. Args must be a map in which the keys are argument names and the values are argument values. It is also possible to pass named arguments directly using the named form. However, this does not allow passing of arguments named element or args.

If args is not present, ... will be mapped to named arguments according to the rules in Argument Mapping

sys:elementList

sys:elementList()

Returns a list containing the arguments to elementList but in non-evaluated form. The elements in the resulting list can then be evaluated using executeElement

sys:cacheOn

sys:cacheOn(value)

Caches all return values of the rest of its arguments based on the value of the value argument. Subsequent evaluations of this element in which the value argument will have the same value will not re-evaluate the rest of the arguments, but return the cached values instead. The cache is bound to this static instance of the cacheOn element. In other words, if another cacheOn element exists, it will not use the values cached by this element, irrespective of the value of the value argument.

Caching is not guaranteed. It is a mechanism that could help improve performance, but it should not be relied on to guarantee that certain elements are only evaluated once. Also, elements that rely on side-effects to perform their function will not be able to perform those functions if their cached valued is used. Echo will, for example, not do anything if cached. However, print will, because it does not rely on a side-effect to print values to the console.

sys:numberFormat

sys:numberFormat(pattern, value)

Allows the formatting of a decimal number. The pattern argument indicates the pattern to be used for formatting (as used by the java.text.DecimalFormat class). The value argument holds the decimal value that is to be formatted.

In short, the following characters can be used in patterns:

#: Digit; zero not shown
0: Digit; zero is shown
.: Decimal separator
,: Grouping separator
E: Scientific notation separator

sys:file

sys:file:contains(file, value)

Aliases: contains

File:contains determines whether a file contains a specific sequence of characters. The file argument points to the file to be checked, while the value argument specifies the value to be searched.

sys:uid

sys:uid(*prefix, *suffix)

Returns a string with a unique ID. The *prefix and *suffix arguments can be used to specify a prefix and a suffix respectively. In the current implementation, the uniqueness of the returned string is relative to the instance of the interpreter.

sys:file

sys:file:read(name)

Aliases: readFile

File:read reads the contents of a file, pointed to by the name argument. This is intended for short text files that may possibly hold things like error messages or exit codes. The file is completely read into memory; therefore this element would not be suitable for manipulation of large files.

sys:file

sys:file:write(name, *append, ...)

File:write writes all arguments received on the default channel to the file with the given name. The file is truncated first, unless the *append argument is true. When the element terminates, either successfully or not, the file is closed.

sys:outputStream

sys:outputStream(type, *file)

Returns an output stream which can be used for writing values to. The type argument can be one of “stdout”, “stderr”, or “file”. If the type is “file”, the *file argument must be present and indicate a valid file name.

sys:closeStream

sys:closeStream(stream)

Closes a stream opened with outputStream.

sys:sort

sys:sort(*descending, ...)

Returns all arguments in sorted order. The values are sorted in ascending order, unless the *descending argument is set to true.

sys:dot

sys:dot(...)

Returns the "dot product" of all the arguments, which are expected to be some form of vectors (lists or channels). Dot returns the result asynchronously if any its arguments is a channel that is not closed. The returned values are lists with a value extracted from each of the vectors.

sys:cross

sys:cross(...)

Returns the "cross product" of its vector arguments. Each value returned is a list with a value from each vector. Cross does not work asynchronously.

sys:stats

sys:stats(*asmap)

If *asmap is false then it returns a string summarizing information such as the amount of used and free memory, the number of CPUs, and the current number of active threads. If the *asmap argument is set to true, it returns the information as a map with the following keys:

memused
heapsize
heapmax
cpucount
threadcount

sys:filter

sys:filter(*regexp, *invert, ...)

Filters arguments based on a regular expression, specified by *regexp. If *invert is true, matches will be inverted (values that do not match are returned).

If only one argument is received on the default channel, and that argument is a list, a list is returned with the values of the argument filtered.

If more than one argument is received on the default channel, each argument will be matched against *regexp.

sys:info

sys:info(*prefix, *name)

Prints information (such as name and arguments) about elements. If the *prefix argument is present, it will print information about all elements currently defined within that namespace prefix. If the *name arguments is present it will only print information about the element with the given name. If none of the two possible arguments are present, info will print information about all currently defined elements (within the scope of info).

Notes

1. At the time of this writing, futures are not properly forwarded if unbound at the time of the remote invocation, possibly causing errors or the remote execution to hang indefinitely.

2. The uniform distribution relies in the current implementation on the properties of the Java Math.random() function

3. Please note that ".*" may not match multiline strings because by default as "." will not match line terminators. To disable this behavior and force "." to match characters including newlines, you can add the "(?s)" directive (e.g. "(?s).*")

V:4.1.4/Karajan:System Library

From Java CoG Kit

Contents

Flow Control Elements

sys:sequential

sys:parallel

sys:unsynchronized

sys:choice

sys:catch

sys:guard

sys:race

sys:for

sys:parallelFor

sys:while

sys:condition

sys:break

sys:continue

sys:if

sys:then

sys:exclusive

Elements Dealing with Variables and Arguments

sys:set

sys:default

sys:maybe

sys:global

channel:to

channel:from

channel:close

channel:fork

sys:isDefined

sys:quoted

sys:discard

sys:future

sys:futureIterator

sys:each

Element Definition Elements

sys:element

sys:parallelElement

sys:channel

sys:optional

sys:self

Service Interaction Elements

sys:remote

List Manipulation Elements

list:list

list:append

list:prepend

list:join

list:size

list:first

list:last

list:butFirst

list:butLast

list:isEmpty

Map Elements

map:map

map:entry

map:put

map:delete

map:get

map:size

map:contains

Logic Elements

sys:and

sys:or

sys:not

sys:equals

sys:true

sys:false

Numeric Elements

math:sum

math:product

math:subtraction

math:quotient

math:remainder

math:square

math:sqrt

math:equalsNumeric

math:greaterThan

math:lessThan