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}, {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 attributes 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, "key c" = ValueC, ...]

There is no ordering to the keys or values in keyed lists, but you can still access individual elements using the syntax 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:

Anonymous 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.

Regular expressions are a very powerful feature of Text Blaze.

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.

Extracting structured data with regular expressions

The following examples assume your computer's clipboard contains the following text. You should copy this text to your clipboard and then reload this page for the examples below to work.

Name: John Smith
Age: 32
ID: RFS4215

To extract the name from this text, we could use the following regular expressions:

Let's walk through these three examples one-by-one:

• Full Name: We extract the full name with the regular expression "Name: (.+)". What this says is match "Name: " then any character ("." -- called a "wildcard" -- means match any character, except a line break) one or more times ("+" means repeat whatever preceded it one or more times). The parenthesis around "(.+)", means the extraction should return that part of the match (while matching but not returning the "Name: ").
• First Name: This is much like the full name match except with two differences. The first difference is we add a "?" after the plus. Without the question mark, ".+" means match as many characters as possible (this is called "greedy" matching). With the question mark, ".+?" means match as few characters as possible (this is called non-greedy matching). With the final space, this regular expression translates to: "Match 'Name: ' followed by one or more characters (but as few of those characters possible), and then finally a space".
• Last Name: The ".+? (.+)" means match one or more characters (again as few as possible), then a space, then again match another group of one or more characters. The first part corresponds to the first name and the second part to the last name. Since we only have parenthesis around the second part, just the contents of this second part (the last name) are returned from the function.

Now let's write a regular expression to get the user's age. Here we show a couple different approaches:

In these examples we show that there are many different ways to write a regular expression that give you the same result. We highlight two differences between these methods.

The first difference is between "." vs "\d" vs "[0-9]". These are three different ways to define what characters we want to match.

• "." means match any character except a new line.
• "\d" means match any digit. There are many types of special backslash symbols in regular expressions that match certain types of characters. "\w" means match any word character, "\s" means match any whitespace (spaces or tabs), "\W" means match any non-word character, and "\D" means match any non-digit character.
• "[0-9]" means match any digit between 0 and 9. You could use "[5-9]" if you only wanted to match the numbers 5, 6, 7, 8, and 9. You can also use "[a-z]" to match the letters of the alphabet.

Generally when matching an age we would use one of the second two approaches. Using ".", might incorrectly cause our regular expression to match on non-numeric values like letters or punctuation.

The second difference is "+" vs "*". As we saw above, "+" means match one or more instances of the preceding character. "*" is very similar, except it means match 0 or more instances of the preceding character. In this example, ".*" would return an empty string if there was no age specified, while ".+" would throw an error as it requires at least one character to be there.

Now let's write a regular expression to get the user's ID. We'll show two equivalent examples for this:

Let's assume the ID is always an alphanumeric sequence of three word characters followed by 3 to 5 numbers. Remember that "\w" means match a single word character and "\d" means match a single digit.

In this example we introduce two new concepts:

• We saw above that when a question mark follows a "." or a "+", the question mark converts the matching from greedy to non-greedy. However, when it follows any other character, like it does here, the question mark indicates that the preceding character is optional. So the first regular expression says, match three word characters ("\w\w\w") followed by three digits ("\d\d\d") followed by two optional digits ("\d?\d?").
• The "{3,3}" means match three of the preceding character and "{3,5}" means match between three and five of the preceding character. So the second regular expression says to match exactly three word characters ("\w{3,3}") followed by three to five digits ("\d{3,5}").

Handling badly formatted data

Occasionally, you will try to use a regular expression on data that is incorrectly formatted so that the regular expression does not correctly match the data. For instance, imagine the following data was given to you:

Name:
Age: 32
ID: RFS4215

This data is missing the name. If we use our regular expressions above to try to process this we will get a "No match found" error in our snippet when they try to extract the name. Sometimes that is what we want, but other times, we will want to just insert some fallback value when the match fails.

There are two basic ways to handle these cases. The first uses the catch() function. The catch() function evaluates its first argument and returns it. However, if an error occurs when it is evaluating its first argument, it will return the second as a fallback. Here is a quick example:

Let's try to use catch() in an email snippet with a regular expression:

This example will start with "Dear John" when we copy the correctly formatted data from the start of this section, but will start with "Dear Customer" when we copy the incorrectly formatted data.

Another way we can achieve the same thing is with an {if} command and the testregex() function.

We hope that this was a helpful introduction to regular expressions. They are an incredibly powerful tool but can also be complicated to use. If you ever run into issues with a particularly confusing one, we recommend you visit https://regexr.com/. It is a great site that will visualize the regular expression and its results for you.

Special characters in regular expressions

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