GREL Controls

Thad Guidry edited this page Oct 8, 2015 · 9 revisions
Clone this wiki locally

Controls supported by the OpenRefine Expression Language (GREL)

There are inline controls to support branching and essentially looping. They look like 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