The Scala Expression Language

Contents

Introduction

• Parse numerical user input in an expressive matter, e.g allow "1/16" or "1/2**4" instead of the rather meaningless number "0.0625"
• Parse configuration files that may contain interdependencies between different settings. Such dependencies may be expressed by variables.
  E.g. assume some XML content: <DefX>x = 1</DefX> ... <Param1> x + 1 </Param1> ... <Param2> x + 2 </Param2>
  
• Allow configuration files to contain formulas, e.g. for sequence generation or data checks like this:
  <Generator> defined(x) ? x += PI / 16 : x = 0; sin(x) </Generator>
<Check> x GT 0 AND x LT 100 </Check>
  

Sel is not intended to be used for high performance math calculations. Those should probably be written in some native language anyway.

This document describes the Sel syntax itself. To get information about integration into Java or other JVM languages, please consult the See API documentation which may be found here.

1. An input string is parsed into a node tree. The parser will return the root node of produced tree, if there were no parsing errors. Otherwise a RuntimeException will be thrown.
2. The node tree is evaluated to yield some kind of result. If a problem occurs during this step, the evaluator will either produce an error result or throw a RuntimeException, depending on the evaluation method.

See provides a number of convenience methods to combine both steps into one and to enforce a certain result type, e.g. boolean or double.

As Sel is a formally complete programming language, the halting problem applies. This means it is possible to provide input which causes evaluation to take infinite time. This may not be a major problems for most applications, but there can be situations where it matters. Therefore, See provides an alternate parser that rejects all constructs which may cause infinite loops. In practice, this means that variable support has to be dropped, because even the evaluation of a variable may lead to endless recursion. To create a See context with this alternate parser use "See.createConst()". As a side effect, a node returned by the alternate parser is guaranteed to evaluate in constant time and will always yield the same result, independent of the context that is used for evaluation. There is no point in using the alternate parser for performance reasons. The difference in parsing speed is neglectible.

General Syntax

Data Types

• Value types may act as regular operands. They can be created using some kind of literal form and may be converted into a reparsable string representaion.
  
• Nonvalue types are the the result of some evaluation step that does not yield a regular value. Values of such types cannot be created explicitly.
  

Value types

Bool

String

Regex

Int

Real

BigInt

BigReal

Symbol

Nonvalue types

Function

Anonymous

Any

Null

Container types

Vector

Map

Table

Assoc

Value Equality

Variables

Scoping rules

_x = y = 1;
{
    _x = y = z = 2;
}
_x; // 1 unchanged
y; // 2 changed within inner scope
z; // Unresolved eval error: z is only defined within inner scope

Unary Operators

Binary Operators

Built-In Functions

Type conversion functions

bool(x)

Converts its arguments into Bool values.
Possible for any value type.
Return type: Bool

str(x)

Converts its arguments into a reparsable string.
Possible for any value type
Return type: String

regex(x)

Converts its arguments into a regular expression.
Possible for any value type.
Return type: Regex

int(x)

Converts its arguments into Int values. Real values are rounded down.
Possible for any numeric type and reparsable string.
Return type: Int, may be truncated

real(x)

Converts its arguments into Real values.
Possible for any numeric type and reparsable string.
Return type: Real, may be truncated

bigint(x)

Converts its arguments into BigInt values.
Possible for any numeric type and reparsable string.
Return type: BigInt

bigreal(x)

Converts its arguments into BigReal values.
Possible for any numeric type and reparsable string.
Return type: BigReal

round(x)

Converts its arguments into integer type of same precision, rounding to nearest.
Possible for any numeric type and reparsable string.
Return type: Int or BigInt

floor(x)

Converts its arguments into integer type of same precision, rounding down.
Possible for any numeric type and reparsable string.
Return type: Int or BigInt

ceil(x)

Converts its arguments into integer type of same precision, rounding up.
Possible for any numeric type and reparsable string.
Return type: Int or BigInt

Container Construction

vector(x1, ... xn)

Generates a vector.
In general, using this function is redundant, because the form (x1, ... xn) will yield a vector anyway, but it may be useful to create a vector with exactly one element.
Return type: Vector of arguments

map(x1, ... xn)

Generates a Map.
In most cases, arguments will be associations, but a scalar values are also allowed.
It is even possible that all arguments are scalars. Although this sounds rather pointless at first, such a map will make sense when used in combination with set operations described below.
Return type: Map of arguments

table(x1, ... xn)

Generates a Table.
In general, arguments will be associations, but any kind of number is also a valid argument.
Return type: Table of arguments

Basic Mathematics

abs(x)

Calculates the absolute value of its argument.
Arguments may be any numerical types or vectors composed of such.
Return type: Same as argument

cos(x)

Calculates cosine of its argument.
Return type: Real

sin(x)

Calculates sine of its argument.
Return type: Real

tan(x)

Calculates tangent of its argument.
Return type: Real

acos(x)

Calculates inverse cosine of its argument.
Return type: Real

asin(x)

Calculates inverse sine of its argument.
Return type: Real

atan(x)

Calculates inverse tangent of its argument.
Return type: Real

sqrt(x)

Calculates square root of its argument.
Return type: Real

log(x)

Calculates natural logarithm of its argument.
Return type: Real

log10(x)

Calculates logarithm base ten of its argument.
Return type: Real

Vector reducing functions

max(x)

Returns the maximum of all arguments.
Return type: Same as argument

min(x)

Returns the minimum of all arguments.
Return type: Same as argument

sum(x)

Calculates the sum of all arguments.
Return type: Same as argument

prod(x)

Calculates the product of all arguments.
Return type: Same as argument

mean(x)

Calculates the arithmetic mean of all arguments.
Return type: Same as argument

fold(init, op, v)

Folds a vector into as scalar using function 'op'.
Folding is done from left to right. 'init' is used as initial value.
So the function sum(x) could also be written as fold(0, add, x), where 'add' is somewhere defined as add(x,y) := {x + y}
Return type: Some kind of scalar.

Misc. functions

len(x)

Returns the length of a vector or string argument.
All other input types will return 1.
Return type: Int (always scalar)

pad(x, l, v)

Produces a vector of constant length l from input vector x.
If l is smaller than len(x), the rightmost elements are discarded.
If l is larger than len(x), the produced vector will be padded with v.
Return type: Vector

rep(l, v)

Produces a vector of constant length l with elements initialized to v.
Return type: Vector

rnd(x)

Produces a random number between 0 and argument (exclusive).
BigReal result may be larger than x!
Return type: Same as argument

sort(v)

Sorts vector elements in ascending order.
This function is only guaranteed to work if all entries are comparable and share the same type. Otherwise an error may be raised or the resulting vector will remain partially unsorted.
Return type: Vector

unique(v)

Removes duplicate elements from vector.
Uses weak equality to identify duplicate entries.
Return type: Vector

distinct(v)

Removes duplicate elements from vector.
Uses strong equality to identify duplicate entries.
Return type: Vector

zip(v1, v2, ...)

Zips vectors into one, containing tuples of adjacent elements. If vectors are of different length, the shortest one will determine result size.
It is also possible to call this function with a single argument, that is a multi-dimensional vector. For dimension 2, the result wll have rows and columns exchanged and the relation zip(zip(v)) == v holds.
Return type: Vector

Set Operations

Although Sel does not provide an explicit set type, it contains operations that let you treat vectors and maps as such.
The preferred type to use for sets is the map. Therefore, if neither operand of a set operation is map or vector, a map will be produced, possibly an empty one. Operations will just affect the key sets. The associated values are ignored and remain unchanged.
A vector may form a multi-set, which means it can contain multiple instances of the same value.

Operation result depends on operands. If the left operand is either a map or a vector, so will be the result. Otherwise the right operand determines the result type.
A scalar combined with a map will produce an association to itself, which means key and value are the same,
e.g. map(1 -> 2) @| 3 yields map(1 -> 2, 3 -> 3).

• Union
  The result will contain the union set of both operands.
  If both operands are vectors, this is basically the same as concatenation. Otherwise, a regular union operation is performed.
  E.g.(1,2,3,3) @| (1,3,3,4) yields (1,2,3,3,1,3,3,4), while (1,2,3,3) @| 3 yields (1,2,3,3).
  If the left operand is a map, any overlapping entries will take associations from the right.
  
• Intersection
  The result will contain the intersection set of both operands, which may be empty.
  If both operands are vectors, the result contains any elements that occur in both operands, e.g. (1,2,3,3,3) @& (1,3,3,4) yields (1,3,3).
  For map operands, the values of the left side take precedence.
  
• Difference
  This operator is asymmetric. All elements occurring within the right operand will be removed from the left one, which may leave an empty set.
  If the right operand is a scalar, all equal elements will be removed, otherwise only so many as the right side contains, e.g. (1,2,3,3,3) @^ (1,3,3,4) yields (2,3), while (1,2,3,3,3) @^ 3 yields (1,2)
  
• Containment
  The operators @? and @?? yield true, if the right operand is found at least once within the left operand. @? performs a weak, @?? performs a strong equality check. Even if the weak test succeds for a given value, it is not guaranteed that a map subscript will succeed.

Flow Control

Conditional operator

x > 0 ? 1 : x < 0 ? -1 : 0

Loop operator

y = 1; x > 0 ?? x -= 1; y *= 1 : 0

x = 1; 
y = x ? 0 : 1; 
z = y * 10;		// Probably causes eval failure, because y is undefined! 

x = 1; 
y = (x ? 0 : 1); 
z = y * 10;		// Works as expected now 

Return operator

x = -1;
  y = {
    x <= 0 ?= 0;
    log10(x);     // not executed
  };              // will end up here
10 * y;
// not here!

Error (or assert) operator

x = 0;
   {
       y = 10 * {
           x > 0 ?! "Undefined ln() operand";
           log10(x);    // not executed
        };
        y += 5       // not executed
    }!               // error catched here
        0            // result returned in case of error
    }

Pattern matching operator

• At first, the selector expression is evaluated.
• Then, alternatives are tried from left to right.
• If any pattern matches the selector, the operator yields its result and the remaining alternatives are ignored.
• If no pattern matches at all, an evaluation error is raised.

• The '?' acts as default pattern. It matches any selector and should therefore be used only within the last alternative.
• If the pattern is a Regex, the selector is forced into a string and a full regex match will cause the pattern to fit.
• If the pattern is a typename, the selector must fit this type.
• If the pattern is any other constant, it will be compared against the selector, using the == operator. If that returns true, the pattern fits.
• If the pattern is a variable that refers to a function, it will be called using the selector as argument. The return value is then forced into a Bool and fits, if true.
• Any other variable is compared against the selector, using the == operator. If that returns true, the pattern fits.
• Finally, if the pattern is some other kind of expression, it will be evaluated and the result is forced into a Bool. In such a case, it is assumed that the expression contains a reference to $, which will be set to the selector value.
  This isn't enforced, however. If the pattern expression doesn't mention $, it will in fact be independent of the selector, so the operator degradates into a short form of if() elseif() elseif() ...

pred(x) := { 10 < x < 100 };
a = 101;
x = 20;
y = x ?~   "abc"  -> 0x41L :
           '\d+\*a' -> a * int($~~~'(\d*).'@1) :
           111    -> 112 :
           a      -> a + 1:
           $ < 0  -> $ + 1:
           pred   -> 2 * $:
           Number -> bigint($) :
           ?      -> 0L ; // note semicolon after last alternative!

Functions

f(x, y) := { x + 2 * y };
f(10, 20) // yields 40

f = (x, y) => { x + 2 * y };
f(10, 20) // same as above

f = { _1 + 2 * _2 };
f(10, 20) // again same as above

{ 2 * _4 } // is equivalent to (_1, _2, _3, _4) => { 2 * _4 }

{ _ + _ } // is equivalent to (a, b) => { a + b } in Scala
          // but (a) => { a + a } in Sel

{ _ + _2 } // Won't work
(x) => { x + _2} // Illegal

Java Reflection

f = "java.io.File":>new("somefile");
(f:>exists() ? f:>delete(); 1 : 0);
"java.lang.System":>out!:>println("Hello"); 

// or, if you want to do that more than once:
sout = "java.lang.System":>out!;
sout:>println("Hello"); 
sout:>println("world"); 

fstr = "java.lang.String":>format("%04x, %.2f", (10, 1.5)); 
sout:>println(fstr); // prints "000a, 1.50"

Keywords

and = 1;
xor = 2;
or = 3;
if = and or xor xor and or not or and and or xor;