Formula Reference

The Blaze Formula Language makes it possible to use formulas and calculations as part of your snippets. This enables dynamic and conditional snippet content. The Blaze Formula Language is used in the {=} (Formula Command), {if} and {repeat} commands.

Supported Operators

The Blaze Formula Language supports many operators for manipulating numbers, comparing values, and working with strings and boolean (yes/no) values.

Supported Functions

Text Blaze supports a variety of functions in formulas.

Escaping Special Characters

Certain characters have special meaning in Text Blaze commands and strings. For instance, the ; character is used to separate settings in commands. In formula strings, the " character is used to signal the start and end of the string.

To use these special characters in their normal form you can "escape" them by placing a single backslash (\) before them.

For example:

{="this is a \" character"}

will print:

this is a " character

The rules for escaping special characters are slightly different within commands and strings. The following table summarizes these rules:

Additional common escapes may be added to Text Blaze in the future, so you should be explicit with your backslashes and not accidentally rely on the behaviors in the third row of this table.

Lists

Lists are special data structures in the sense that they contain other pieces of data. There are two types of lists in Text Blaze: ordered lists and keyed lists.

Ordered Lists

Ordered lists (also called arrays), are a sequential set of zero or more values. Their syntax is as follows:

[Value1, Value2, Value3, ...]

Since there is a distinct order to the elements, you can access a specific element by its index using the syntax list[index]. The first element in the list has index 1, the second index 2 and so on. For example:

Ordered lists are especially useful when processing multiple items of some type.

Keyed Lists

Keyed lists are a set of key/value mappings. Their syntax is as follows:

["key a" = ValueA, "key b" = ValueB, ...]

There is no ordering to the keys or values in keyed lists, but you can still access individual elements using the syntax list["key"] or list.key. For example:

Keyed lists are particularly useful when processing data. Keys are case-sensitive.

If the key is not quoted when defining a list, it is a treated as a form variable and the value of the variable is used as the key value. The following example illustrates this:

List Comprehensions

Text Blaze has powerful methods for manipulating lists: including filter(), map(), and reduce().

Sometimes though, it can be easier to use a powerful Text Blaze feature called list comprehensions if you need to transform a list. List comprehensions carry our an operation across each element of a list.

Imagine you wanted to square each element of an ordered list. The following example shows how to do that with both the map() function and a list comprehension:

Both work and are almost exactly the same length, but many people find the list comprehension version easier to read.

You can also include an optional if block in your list comprehensions, items will only included when it evaluates to yes. Imagine we only wanted to include items who were larger than 20:

List comprehensions can also iterate across keyed lists and can create keyed lists. The following shows the examples of the different possible combinations:

Text Blaze has two special delimiters you can use that join the items together using natural language concatenation: "BLAZE_AND" and "BLAZE_OR". These can be particularly useful in the formatter function for the {formmenu} command.

For example:

Functions

An anonymous function is like a regular function except it does not have a name. The syntax for anonymous functions is:

(arg1, arg2, ...) -> doSomething(arg1, arg2, ...)

The parenthesis around the arguments can be omitted if you have exactly one argument:

arg -> doSomething(arg)

Some built-in functions and commands use anonymous functions. For instance, the sort() function for lists takes an anonymous function to define the sorting order to use. The following example shows the use of anonymous functions with the sort() function to sort the same array four different ways:

Using anonymous functions, you can define whatever sorting method you want.

You can also call anonymous functions directly in your formulas. For example:

A common use case for anonymous functions is manipulating lists. The filter(), map() and reduce() built-in functions are three functions for operating across a list that leverage anonymous functions.

Regular Expressions

A regular expression pattern is composed of simple characters, such as "abc", or a combination of simple and special characters, such as "ab*c" or "Chapter (\d+)\.\d*". The last example includes parentheses which can be used to extract specific parts of the regex using the extractregex() function.

This section is adapted from this MDN Page by Mozilla Contributors and licensed under CC-BY-SA license.

Text Blaze provides the extractregex() and testregex() functions to leverage regular expressions.

Using simple patterns

Simple patterns are constructed of characters for which you want to find a direct match. For example, the pattern "abc" matches character combinations in strings only when exactly the characters 'abc' occur together and in that order. Such a match would succeed in the strings "Hi, do you know your abc's?" and "The latest airplane designs evolved from slabcraft." In both cases the match is with the substring 'abc'. There is no match in the string 'Grab crab' because while it contains the substring 'ab c', it does not contain the exact substring 'abc'.

Using special characters

When the search for a match requires something more than a direct match, such as finding one or more b's, or finding white space, the pattern includes special characters. For example, the pattern "ab*c" matches any character combination in which a single 'a' is followed by zero or more 'b's (* means 0 or more occurrences of the preceding item) and then immediately followed by 'c'. In the string "cbbabbbbcdebc," the pattern matches the substring 'abbbbc'.

The table at the end of this section provides a complete list and description of the special characters that can be used in regular expressions.

Special characters in regular expressions

Table of special characters that can be used in regular expressions: