GREL-Controls.md

Controls supported by the General Refine Expression Language (GREL)

There are inline controls to support branching and essentially looping. They look like GREL Functions, but unlike functions, their arguments don't all get evaluated down to value before they get run. A control can decide which part of the code to execute and can affect the environment bindings. Functions, on the other hand, can't do either. Each control decides which of their arguments to evaluate to value, and how.

if(expression o, expression eTrue, expression eFalse)

Expression o is evaluated to a value. If that value is true, then expression eTrue is evaluated and the result is the value of the whole if expression.

Examples:

expression	result
if("internationalization".length() > 10, "big string", "small string")	big string
if(mod(37, 2) == 0, "even", "odd")	odd

with(expression o, variable v, expression e)

Evaluates expression o and binds its value to variable name v. Then evaluates expression e and returns that result.

expression	result
with("european union".split(" "), a, a.length())	2
with("european union".split(" "), a, forEach(a, v, v.length()))	[8, 5]
with("european union".split(" "), a, forEach(a, v, v.length()).sum() / a.length())	6.5

filter(expression a, variable v, expression test)

Evaluates expression a to an array. Then for each array element, binds its value to variable name v, evaluates expression test which should return a boolean. If the boolean is true, pushes v onto the result array.

expression	result
filter([3, 4, 8, 7, 9], v, mod(v, 2) == 1)	[3, 7, 9]

forEach(expression a, variable v, expression e)

Evaluates expression a to an array. Then for each array element, binds its value to variable name v, evaluates expression e, and pushes the result onto the result array.

expression	result
forEach([3, 4, 8, 7, 9], v, mod(v, 2))	[1, 0, 0, 1, 1]

forEachIndex(expression a, variable i, variable v, expression e)

Evaluates expression a to an array. Then for each array element, binds its index to variable i and its value to variable name v, evaluates expression e, and pushes the result onto the result array.

expression	result
forEachIndex(["anne", "ben", "cindy"], i, v, (i + 1) + ". " + v).join(", ")	1. anne, 2. ben, 3. cindy

forRange(number from, number to, number step, variable v, expression e)

Iterates over the variable v starting at from, incrementing by step each time while less than to. At each iteration, evaluates expression e, and pushes the result onto the result array.

forNonBlank(expression o, variable v, expression eNonBlank, expression eBlank)

Evaluates expression o. If it is non-blank, binds its value to variable name v, evaluates expression eNonBlank and returns the result. Otherwise (if o evaluates to blank), evaluates expression eBlank and returns that result instead.

Unlike other GREL functions beginning with 'for', forNonBlank is not an iterative function. forNonBlank essentially offers a shorter syntax to achieving the same outcome by using the 'isNonBlank' function within an 'if' statement.

isBlank, isNonBlank, isNull, isNotNull, isNumeric, isError

isX(e) : evaluates expression e and returns whether its value is X.

Examples:

expression	result
isBlank("abc")	false
isNonBlank("abc")	true
isNull("abc")	false
isNumeric(2)	true
isError(1)	false
isError("abc")	false
isError(1 / 0)	true

Remember that these are controls and not functions. So you can not use the e.isX() syntax.