What are expressions?

Expressions are how you describe calculations for Elara to perform.

For example, if you want to add x and y, you can write the expression Add(x, y). If you wrote x + y in your EDK project, the addition will be performed by JavaScript on your computer. The expression Add(x, y) is an instruction to Elara to perform the addition on the platform at run time. Expressions are normally evaluated as a part of a larger task, such as a pipeline.

The East expression langauge

Once again consider Microsoft Excel for an analogy. Formulae in Excel are written in Excel's expression language. You can enter expressions like =A1 + B1, =SUM(A1:A10) or =IF(A1, B1 + B2, C3) into cells, and Excel will evaluate the expressions as necessary using the input data.

Expressions in Elara are similar to this. The expression language used by Elara is a simple programming language designed for Elara called "East". You can write expressions directly in your EDK project using syntax like Add(a, b). With East expressions, you can perform calculations and transform complex data however you wish. This tutorial focuses on basic operations like adding and comparing numbers.

How do you write expressions?

When developing solutions with the EDK, expressions are required by builders like PipelineBuilder wherever user-defined calculations are expected. In the previous module you saw that the .transform method on PipelineBuilder accepts an expression to define the transformation. Here you will learn how to write an expression in such locations.

Expressions can be used in lots of places

Pipeline operations are not the only place where you can define Expressions. There are many places in where an expression can be used to evaluate a value. You will learn more about these locations in later lessons.

East functions

The EDK exports Add and around 100 other East functions for you to build your logic with. Expressions are built syntactically out of these East functions in your template code. Ultimately all expressions are composed of just these "built-in" functions.

The full set of East functions isn't covered here, but you should know there are some really basic ones for arithmetic.

East function	Description	Example usage	Result
`Add`	Addition, a + b	`Add(6, 2)`	`8`
`Subtract`	Subtraction, a − b	`Subtract(6, 2)`	`4`
`Multiply`	Multiplication, a × b	`Multiply(6, 2)`	`12`
`Divide`	Division, a ÷ b	`Divide(6, 2)`	`3`

You can also compare values to one another.

East function	Description	Example usage	Result
`Equal`	Determine if two values are equal	`Equal(1, 2)`	`false`
`NotEqual`	Determine if two values are not equal	`NotEqual(1, 2)`	`true`
`Less`	Determine if the first value is less than the second	`Less(1, 2)`	`true`
`LessEqual`	Determine if the first value is less than or equal to the second	`LessEqual(1, 2)`	`true`
`Greater`	Determine if the first value is greater than the second	`Greater(1, 2)`	`false`
`GreaterEqual`	Determine if the first value is greater than or equal to the second	`GreaterEqual(1, 2)`	`false`

As you continue to learn Elara, you will become familiar with a wider range of fundamental expessions.

Expressions can be nested inside each other

Expressions can be nested inside of each other, like Add(x, Multiply(y, z)) for x + (y * z). When an expression is evaluated, the sub-expressions are evaluated first and those values are used to evaluate the parent expression. So first we multiply the values y and z, before we are able to add x with the result.

Expressions have data types

Each expression has well defined type. Types are automatically propagated through expressions. If we add two integers, then we know the result is an integer.

And the EDK knows, for example, that you cannot add integers and strings. If you write Add(integer, string) for some integer-typed integer and some string-typed string, you will encounter errors. You will recieve live feedback about this directly in VS Code as TypeScript will fail to type-check. Furthermore, the EDK will refuse to build your template.

Expressions are built from variables

So far it hasn't be discussed how run-time data actually enters your expressions. Like most programming languages, values are assigned to named variables. Typically these variables are "injected" into your expressions by a builder like PipelineBuilder.

This is because expressions define only part of larger computer program, such as an entire pipeline task. The pipeline task needs to load input datastreams and execute a series of operations. Each operation might require evaluating one or more expressions. When the result of the expression is required, the pipeline executor will provide the values of the input variables to the expression and evaluate it.

Expressions you enter in the EDK may look somewhat like this:

(x) => Multiply(x, 2n);

Here we have an expression of a single variable x. In the above, the value x has TypeScript type Variable<IntegerType>. Its type will be automatically inferred and you can inspect the type of the variable by hovering over it in VS Code.

In other places in the EDK the list of available variables is more dynamic. There may be many variables of different names and types. In these cases a collection containing all the variables is injected like so:

(vars) => Add(vars.x, vars.y);

The vars (or "variables") object is a record of the variables. Each variable, such vars.x, has TypeScript type Variable<T> where T is the data type of the variable. In the above the TypeScript type of vars might be:

vars satisfies {
  x: Variable<IntegerType>;
  y: Variable<IntegerType>;
  z: Variable<StringType>;
};

So the variables "in scope" for this expression are the integers x and y, and the string z.

In East, it is possible to create your own variables with Let. You won't need to use Let in this module, but it is good to know it is there.

Expressions can contain constant values

In certain places it is valid to enter a constant JavaScript value directly into your expressions. For example you may write Add(x, 1n) to add one to the variable x.

In more complex situations you might find that directly entering values does not work. This is because sometimes it can be ambiguous what is intended, or TypeScript can't handle the complexity. In such cases it is necessary to wrap the value in the Const East function, which holds the value inside. We can write Add(x, Const(1n)). In fact Elara always uses this form internally – Add(x, 1n) is just convenient shorthand syntax.

Expressions can contain branching logic

You can express arbitrary logic with expressions. The IfElse expression allows you to perform different calculations depending on data. Depending on whether a predicate is true or false, it will evaluate one of two branches of code.

IfElse(GreaterThan(2, 1), Add(1, 2), Multiply(2, 3));

If you are an Excel user, you may recognise some syntactic similarity with Excel's IF expression, which might look like =IF(2 > 1, 1 + 2, 2 * 3). Alternatively, the same expression in JavaScript would be written with ? like 2 > 1 ? 1 + 2 : 2 * 3 (note that the if statement in JavaScript is not an expression as it does not produce a value).

Next steps

Now that you understand the fundamental principles of expressions, continue to the next tutorial to define an expression in a pipeline operation.