ClarioScript Guide

ClarioScript may feel familiar to users with experience in other scripting languages. There are a few special elements (e.g. Attribute references) which require special syntax. This guide covers the syntax and the core elements available when authoring ClarioScript.

Attribute Names

Attribute names may only consist of the following characters: A-Z, a-z, 0-9, ‘-‘, and ‘_’.

GoodName, good_name, good123, good-name

Attribute Types

Types are single characters S, D, or N corresponding to String, Date, Number.

For new attributes, if type is not specified, the attribute type will try to be determined. If type cannot be determined, it will be assigned the type Any (*) and result in a syntax error.

Attributes

Attributes on the incoming stream can be expressed with:

<name>     Simple form for most attributes like:
           attr1, my-attr, undefinedAttr, a123

[<name>]   Required when attribute name is all-numeric or begins/ends with a dash
           [123], [-abc], [abc-]

Example:

myExpression:N = attr1 - [-attrWithDash]

Expression References

In most Clario nodes defined expressions can be referenced in another expression. Expression references use the syntax:

@<name>    Simple form for referencing an expression
@[<name>]  Required when referenced expression name is all-numeric or begins/ends with a dash

Example:

// expr1: return the absolute value of incoming attribute "attr1"
expr1:N = abs(attr1)

// expr2: return expression "expr1" squared
expr2:N = @expr1 * @expr1

Circular references are not valid:

expr1:N = @expr2 + 1
expr2:N = @expr1

Function Calls

Clario provides a large set of built-in functions for creating useful expressions. Use the Expression Builder to explore the available functions:

<function name>(<arg 1>, <arg 2>, ...<arg n>)

Example:

abs(123), condition([attr1]=={mycode}, 1, 0), daysBetween('2012-09-24','1969-09-24')

Incomplete functions are allowed to be saved, although the workflow will not be valid:

abs(), condition(,,)

User Defined Functions

User functions can be defined at the project level and used throughout Clario.

Calling a user-defined function has the same syntax as calling a built-in function.

Template String Fields

Many Clario nodes (Read File, Write File, Spreadsheet, etc) contain special configuration fields that allow parts of the string to be marked with an expression to be resolved at run time.

Any user-defined function that takes zero arguments is eligible for string templating:

Example:

Given user-defined functions:

:FUNCTION asOfDate() = '2019-12-31'
:FUNCTION asOfDateNextQuarter() = endOfMonth(asOfDate(), 3)
:FUNCTION addYears(d,years) = addMonths($d, $years * 12)

A file name can be templated by inserting an existing zero-argument function between {}:

"DataFile_{asOfDate}-to-{asOfDateNextQuarter}.csv"

So that at runtime the string evaluates to:

"DataFile_2019-12-31-to-2019-03-31.csv

Note: The function “addYears(d,years)” cannot be used in a string template because it requires arguments.

Operators

+,-,/,*          // Numeric only operators
==,!=,<,>,<=,>=  // Comparison operators
AND, OR          // Logical operators
()               // Parenthetical grouping

Example:

condition([attr] >= 0 OR [attr] < 1000, 5 * ([attr]+3), 0)

Constants

Strings, Numbers, Dates, and Null

Strings:

"Hello", "JAN",       // String literals are double quoted.
"\"Hi\", said Jim"    // Double quotes are escaped with a back slash.
"\\"                  // Back slashes are escaped with a double back slash.

Numbers:

123, 55.90, 999.0394845

Dates: Date are defined by single quotes and an ISO format:

'YYYY-MM-DD'
'YYYY-MM-DD HH:MM:SS' OR 'YYYY-MM-DDTHH:MM:SS'

Example:

'2012-09-24'            // Short date
'2040-12-31 14:22:02'   // Date time with space separator
'2040-12-31T14:22:02'   // Date time with optional ISO “T” separator

Null:

mydef1:N= condition([attr1] == ?, 1, 0) // Nulls are a question mark

Comments

Anything after a double forward slash is ignored by the script compiler:

// This is a comment and is saved with expression "fn1"
fn1:S="a string"
//
// Another multi-line comment saved with expression "fn2"
//
fn2:N=123
// This comment won't be retained because it doesn't come before an expression.

Note: Expression comments are retained with the expression they precede.