A simple expression language for templating constructs. The main function, evaluate, takes an expression as a string and a Positron::Environment object, and evaluates the two. The result is a scalar value.

The grammar is basically built up of the following rules. The exact grammar is available as a package variable $Positron::Expression::grammar; this is a string which could be fed to Parse::RecDescent starting at the token expression.

However, the Parse::RecDescent path has been replaced with a version using plain regular expressions, so the string is no longer the direct definition of the grammar.

A single, non-deliminated word is looked up in the environment; that value is returned. This may be undef if the environment does not contain such a key.

Words follow the rules for identifiers in most C-like languages (and Perl), in that they may start with a letter or an underscore, and contain only letters or underscores. Currently, only ASCII letters are supported; this will hopefully change in the future.

Subselects allow you to to select a part of something else, like getting the value for a given key in a hash, or an indexed entry in a list, or call a method on an object etc. In Positron::Expression, these are denoted with a dot, ., hence the alternative name "dotted expression". Subselects can be chained.

Arrays are indexed by appending an integer to the variable or expression holding the array. Like Perl, indices start with 0, and negative indices count from the back. The form $<expression> can be used to take any expression that evaluates to an integer as an index.

Hashes are indexed by appending a key, an identifier or string, to the variable or expression holding the hash. Most keys in practice will fit the form of an identifier as above (letters, digits, underscores). If not, a quoted string can be used. The form $<expression> can again be used to take any expression that evaluates to a string as the key.

The ?, : and ! operands stand for "and", "or" and "not", respectively. This terminology, while a bit obscure, is the mirror of Python's a and b or c ternary operator replacement. In practice, this allows for some common use cases:

The ! operator has a higher precedence than ? or :, binding closer. It reverses the "truth" of the expression it precedes.

Note: unlike pure Perl, a reference to an empty array or an empty hash counts as false! In Perl, it would be true because all references are true, barring overloading; only non-reference empty arrays and hashes are false. Positron's use is closer related to the Perl usages of if ( $@list ) than if ( $list ), and is typically what you mean.

The : operator is a short-circuiting || or or equivalent. If the left hand side is true, it is returned, otherwise the right hand side is returned. It is chainable, left associative, and has the same precedence as ?.

The most common use case is to provide a chain of fallback values, selecting the first fitting (i.e. true) one.

Evaluates the expression in $string with the Positron::Environment$env. The result is always a scalar value, which may be a plain scalar or a reference. For example, the expression x with the environment { x => [1] } will evaluate to a reference to an array with one element.

Parses the string in the first argument, and returns an abstract parse tree. The exact form of the tree is not important, it is usually a structure made of nested array references. The important part is that it contains no blessed references, only strings, numbers, arrays and hashes (that is, references to those).

This makes it easy to serialize the tree, for distributed caching or persistant storage, if parsing time is critical.

In Perl, empty lists and hashes count as false. The only way for Positron::Environment to contain lists and hashes is as array or hash references. However, these count as true in Perl, even if they reference an empty array or hash.

To aid decisions in templates, the function true returns a false value for references to empty arrays or hashes, and a true value for non-empty ones. Other values, such as plain scalars, blessed references, subroutine references or undef, are returned verbatim. Their truth values are therefore up to Perl (a reference blessed into a package with an overloaded bool method may still return false, for example).