Expressions

Expressions are the dynamic heart of Stencil. Expressions are used in outputs, macros and functions alike. Understanding expressions is key to harnessing the full power of any template language, Stencil included.

Stencil is an untyped language. As such types never have to be provided by the author and when using objects it will do its best to coerce it to the correct type.

Literals

Stencil has support for basic literals like numbers and strings as well as support for advanced literals like lists, maps and ranges.

Booleans

Booleans are provided with the usual true and false keywords

		x = true;
		y = false;

Numbers

Number are specified in Java syntax

		x = 1 		$* integer *$
		x = 1.0		$* double *$

In certain cases (when interacting with the API) you may need to specify an exact type of integer or floating point value. You can use suffixes to achieve this

s = short integer, i = integer, l = long integer, f = float, d = double

		x = 1s 		$* short integer *$
		x = 1l 		$* long integer *$
		x = 3.0f 	$* float *$

Strings

Strings are enclosed in single or double quotes. They are equivalent.

		'This is a string'
		"So is this!"

Lists

Lists are created by enclosing expressions in square brackets. They can contain any type of object

		[1,2,3,'four']

Maps

Maps are created by enclosing entries (name = expression) in square brackets. They can contain any type of object

		[one=1,two=2,three=3]

In cases where the name needs to be something other than an identifier you can use a string literal

		['item-one'=1,'item-two'=2]

Ranges

Ranges are sets of numbers. They are useful in a number of situations including when needing to iterate a set of numbers (and you can't or don't want to type out the entire set).
Ranges are specified as an inclusive..exclusive set. Meaning the ending value is not included.

		[1..4] == [1,2,3,5]
		[5+5..5+10] == [10,11,12,13,14]

Operators

Expressions are used to calculate values and they offer a number of operators to do that. Stencil provides all the familiar operators provided by static languages like Java as well as a number of convenient operators that make life easier while evaluating templates.

While all of Stencils operators are listed below. The less common, and more interesting, ones are listed first.

Navigation

Like most languages Stencil uses the '.' operator to access properties of objects.

		item.name
		item.name.length

Safe Navigation

Stencil also supports the safe navigation operator using '?.' syntax. This means that if a null is encountered null is returned and any other navigation is ignored.

		item.name
		item.name.length

Array Navigation

Array navigation is supported through the standard '[]' operator. It can also be used to access maps and object with property names that are invalid identifiers.

		item[0]
		item['some-value']

Conditionals

Ternary ( x ? y : z )

The ternary operator selects one of 2 values based on a condition

		value ? 'true' : 'false'

Elvis ( x ?: z )

A variant of the ternary operator. The Elvis operator selects the value of a variable or if the value if null or false it selects a default.

		value ?: 'false'

Select ( x ? z )

A variant of the ternary operator. The Select operator selects a value if the condition is true or null if it is false

		value ? 'true'

Concatenation

String Concatentation (+)

When the '+' operator is applied to strings, or a string and any other type, the result is the two values concatenated as strings.

		3 + ' Kings' == '3 Kings'

List Concatentation (+)

When the '+' operator is applied to lists, or a list and any other type, the result is the values are treated as lists and joined to create a single list

		[3] + ['Kings'] == [3, 'Kings']
		3 + ['Kings'] 	== [3, 'Kings']

Basics

Mathematical (+ - / * %)

Stencil has support for the all basic and advanced mathematical operators.

Equality (== != < <= > >=)

Stencil has support for the all standard equality operators.

		1 == 1
		2 != 1

Typing (isa instanceof)

Stencil supports testing if an object is a type with the 'isa' operator. Java folks can use the familiar alternative of 'instanceof' (they do the same thing).

		x isa [] 			$* test if x is a list *$
		x instanceof []

Identical (=== !==)

While the equality operators test if two values are equal. The identical operator tests if two objects are exactly the same object. API Note: The basic identity operator calls the Java Object.equals method while this operator performs an object identity test (aka == in Java).

		(x === x) == true
		(x !== x) == false

Logical (&& ||)

Supports the standard 'logical and' (&&) and 'logical or' (||) operators

		true && false == false
		true || false == true

Logical Negation (!)

Logical negates inverts a boolean value

		!false = true
		!true = false

Bitwise (& | ^ ~)

Stencil has support for the standard bitwise operators

Bit Shifting (<< >>)

Stencil supports bit shifting operators

		1 << 1 == 2
		2 >> 1 == 1