expressions

n3phele parameters are typed, and the parameter value and defaultValue fields can contain either constant values or expressions.
 
The following types are supported.

Types

  • Long
    An 64 bit signed integer. For example 3412, -7645
  • Boolean
    A logical value. It is represented as a string as either "true" or "false" and as an integer or float as "1" or "0"
  • Double
    A 64-bit double precision floating point value. For example 3.14159, 1.0E-9
  • String
    A string constant. For example "hello world". Note that if Strings are defined inside a JSON value definition it is necessary to escape the " character and enter it as \". See the example of Escaping Strings in Expressions below for more details.
  • Secret
    A string constant with contents that should be not plainly displayed or communicated. For example "dont display me"
  • List
    A vector of typed values [ "now", "is", "the", "time" ]
Expression values are implicitly coersed to match the receiving parameter type.
 

Parameter Value and DefaultValue Evaluation

 
Action parameter value or default values can be defined as either a constant or runtime expression value. These values are evaluated just prior to the start of execution of a n3phele action. The parameter value and default value fields are evaluated using the following rules:
 
  1. If the parameter starts with a \", ( or $< then it is assumed to be an expression, and will be evaluated
  2. Otherwise, it is assumed to be a constant and is automatically wrapped in quotes to convert it to a string, and then evaluated

Expression Operators

The following expression operators are supported:
 
  1. Lists: [] or [ expression ] or [ expression, expression, ... ]
  2. List Element: list[n], when [ "now", "is" ][0] is "now"
  3. Brackets: ( expression )
  4. if: logicalExpression ? expression1 : expression2
    evaluates to expression1 if logicalExpression is true, else expression2
  5. multiply: expression1 * expression2
  6. divide: expression1 / expression2
  7. modulo: expression1 % expression2
  8. add: expression1 + expression2
  9. minus: expression1 - expression2
  10. unary minus: - expression1
  11. logical equals: expression1 == expression2
  12. logical not equals: expression1 != expression2
  13. logical greater than: expression1 >  expression2
  14. logical greater than or equals: experssion1 >= expression2
  15. logical less than: expression1 < expression2
  16. logical less than or equals: expression1 <= expression2
  17. logical and: logicalExpression1 && logicalExpression2
  18. logical or: logicalExpression1 || logicalExpression2

Functions

The following functions are supported
 
  1. len(list) - returns the number of elements in the list
  2. list(string) - returns the string length
  3. regex(string, pattern, i) - returns the ith match of the regular expression pattern in string
  4. max(expression1,expression2) - returns the maximum of expression1 and expression2
  5. min(expression1, expression2) - returns the minumum of expression1 and expression2
  6. string(expression) - returns the string equivalent of the expression
  7. escape(string) - returns the string formatted with java escapes
  8. unescape(string) - returns the string with java escapes removed

Variables

Expressions can reference other parameters that exist within the context of an executing command. Variable names must commence with either an alphabetic or _ character and followed by one or more alphanumeric or _ characters.
 
  • Command parameter, such as commandParameter1, are referenced with the following syntax within the expression
    $<commandParameter1>
  • Input or output parameters, such as a parameter named stdin from the action named myCommand, are referenced with the following syntax within the expression
    $<myCommand.stdin>
  • A parameter in the current action can be referenced by its name without an additional qualifier. For example, in the action myCommand has a parameter named i, then for expressions defined in myCommand, the following are both valid:
    $<i>
    $<myCommand.i> 
 

Escaping Strings in Expressions

Expressions are defined as part of the JSON definition of parameter value and defaultValue fields of command executionParameters and of executionProfile inputParameters. For example,   
 

 On the left, we show an example of some execution parameter defaultValue expressions. In the first example, param1 is a string parameter with a default value of "now is the time". Because this is a constant string expression we don't need to enclose the string itself in quotes, as this is done automatically during the expression evaluation since the defaultValue doesnt start with a \", or a $< or a (

param2 is an example of a boolean. Because the value starts with a ( it is assumed to be an expression. Inside the expression we have an embedded string "foo". The " character is escaped and written as /" inside the json definition.

20     "executionParameters" :[ {
21        "name" : "param1",
22         "description" : "param1 is a string",
23         "type" : "String",
24         "defaultValue" : "now is the time"
25       }, 
26       {
27        "name" : "param2",
28         "description" : "param2 is a boolean",
29         "type" : "Boolean",
30         "defaultValue" : "(3+len(\"foo\")==6"
31       }]

Comments