Formula Reference

The Blaze Formula Language makes it possible to use formulas and calculations as part of your snippets.

This enables dynamic snippet content.

The Blaze Formula Language is used in the {=} (Formula Command), {if} and {repeat} commands.

There's a lot of functionality built-in to help you truly make snippets your own.

This page will cover everything you need to know about the Blaze Formula Language and includes a variety of examples.

Supported Values

The Blaze Formula Language supports five types of values:

1. Numbers (e.g. 12, 3.75, or -10)
2. Booleans (yes or no)
3. Text Strings (e.g "abc" or "this is a string")
4. Lists (e.g. [1, 2, "three", yes])
5. Functions (e.g. (x) -> x * 2)

Throughout this documentation page, you'll learn that the Blaze Formula Language primarily consists of working with and manipulating these core supported values.

Text Blaze will convert between these different types as needed. For example, let's look at the max() function which takes two or more numbers and returns the largest one of them. If you pass a string to the max() function, it will attempt to convert the string to a number automatically. For example, max(2, "3", 1) would return the number 3.

You'll learn about those, but before that, we'll review a very important concept within your snippets: Creating Variables.

Creating Variables

Text Blaze allows you to create variables to reference values in your snippets. There are several ways to create variables in your snippets:

1. The {=} (Formula Command) command provides an assignment mode that allows you to create a variable.
2. Forms commands allows you to use the name setting to explicitly give a form value a variable name.

Variable names are case-insenstive, so "address" and "Address" refer to the same thing. Regular variable names start with a letter which is followed by any combination of letters, numbers and underscores. You can create variable names that include spaces or other special characters, however you must enclose those variable names in back ticks ` when referencing them in your formulas.

Creating variables and saving data becomes important as you use the various features of the Blaze Formula Language.

Lists

Lists are a value type that can hold more than one value at a time. They are wrapped in brackets ([]) with each value being separated by a comma (,).

There are two types of lists in Text Blaze: ordered lists and keyed lists.

Ordered Lists

Ordered lists are a set of one or more values.

For example, ["Hi"] or ["Hi", "Hello", ...]. A list can also be empty and contain no values (e.g. []).

A list can contain values of any type (e.g. [1, 2, "three", yes]), but the most common use case is multiple values of the same type (e.g. ["Katie", "John", "Greg"]).

Accessing Items In Ordered Lists

Since there is a distinct order to the items in the list, you can access a specific item by its index using the syntax list[index].

An index is the position of the element in the list. 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 a specific type.

Keyed Lists

Keyed lists, the second type of list, are a set of key-value pairings. Their syntax is as follows:

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

Keys are case-sensitive.

Also, unlike ordered lists, there is no ordering to the keys or values in keyed lists.

Accessing Items In Keyed Lists

You can access individual elements using the syntax list.key. For example:

The "." syntax to reference a value in a keyed list doesn't work when the key has spaces or other special characters in it.

To access values in this case you can use the ["key a"] syntax. You can also use this syntax to reference values that don't contain any spaces or special characters, similar to the "." syntax (e.g. ["color"]).

While this syntax may look similar to the way values are referenced in ordered lists, notice how a string is used instead of a number because you're not referencing a position in the list.

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

Later on this documentation page, you'll learn about a variety of useful built-in functions that work on lists.

Functions

A function is similar to a built-in function except it does not have a name.

The syntax for a function is:

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

A function is treated as a value in Text Blaze. This means three things:

1. Built-in functions can take functions as an argument, just like a Number, Text String, or any other value.
2. Some command settings can receive a function as a value.
3. You can assign a function to a variable using the {=} (Formula Command) command's assignment mode.

Function as an argument

The filter() function, which allows you to filter a list takes a function to define the filtering to use. The function must return a Boolean.

The following example shows the use of functions with the filter() built-in function to filter the same ordered list in three different ways:

Using a function as the argument, you can define whatever filtering method you want. Also, notice how it's possible to use built-in functions in your functions.

Functions as command settings

A function can be used as a command setting's value. For example, {formmenu} has a setting called itemformatter that allows you to format the individual values of the menu items before snippet insertion.

Visit the {formmenu} command to learn more about its functionality.

Assign a function to a variable

Using the {=} (Formula Command)'s assignment mode, it's possible to assign a function to a variable.

Here's an example for squaring a number:

Notice how in the example above, we're creating a function and using other built-in functions within it. Functions allow you to combine operators, built-in functions, and even other functions inside of them.

Finally, we're saving that whole function to a variable and naming it squared. Now it's possible to use this variable anywhere else in your snippet.

You can also call functions directly in the {=} (Formula Command) command by using parenthesis () and passing your arguments directly.

For example:

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

Supported Operators

The Blaze Formula Language supports many operators for working with the various supported values. You can manipulate numbers, compare values, work with strings, and handle boolean (yes/no) values.

Text Blaze will convert between these when suitable in formulas. If you try to use types in a way that is not supported (e.g. 12 + yes or "abc" * 2) an error will be shown.

Math Operators

Text Blaze provides you with a few general Math operators for working with numbers.

Comparison Operators

Comparison operators are very useful for comparing two values. The final result will always resolve into a Boolean (yes/no) value. You'll use these a lot when creating conditions for the {if} command.

String Operators

Text Blaze provides you with one operator, the & operator, to help you concatenate strings together.

Text Blaze provides you with plenty of string built-in functions to work with strings further.

Logical Operators

These operators are very useful for working with Boolean (yes/no) values.

Built-in Functions

Besides operators that allow you to work with the various Text Blaze supported values, you also get access to built-in functions.

A built-in function is a contained piece of functionality designed to perform a particular task.

Text Blaze supports a variety of these built-in functions for you to use in your snippets.

Math Functions

Trigonometric Functions

Similar to the Math functions these built-in functions are designed to help you work with trigonometry.

All of these functions take a single number as an argument and return a single number.

Some of Text Blaze's trigonometric functions are approximate. Due to the numerical approaches to determine their values, there may be extremely small errors in their output (in the 10th decimal place or beyond).

For example, instead of equalling exactly 0, cos(90) could instead return 0.00000000000000006123.

Because of this, you may need to round results from these functions when formatting them for output with the round() function.

For example, you can do round(cos(90)) to get 0.

Statistical Functions

Similar to the Math functions and Trigonometric functions these built-in functions are designed to help you work with statistics.

Error Functions

There are often times when errors will appear in your snippets.

For example, if a form isn't validated or a function returns no value. To help you deal with these scenarios, Text Blaze provides you with two different error built-in functions.

Text String Functions

Text Blaze provides you with built-in string functions to help you work with Text Strings.

Regular Expression Functions

Regular Expressions are a very powerful tool to help you create search patterns.

Supported flags

In all the above regex functions, flags is an optional argument. It can be set to a string containing any of these characters:

1. When the ignore case flag ("i") is set, the search will be case-insensitive.
2. When the multi-line flag ("s") is set, the "." special character will match multiple lines.
3. The global flag ("g") is only supported in replaceregex. When it is set, the search will replace all matches instead of only the first match.

Here's an example using the multi-line and ignore-case flags ("is"):

Date Time Functions

These functions do calculations based on date and times. Other than datetimeparse, these functions require the date to be in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. datetimeparse can be used to convert a date to that format.

List Functions

These functions work on both ordered lists and keyed lists.

The output of these functions depends on which function you choose. Some functions return lists, others a Boolean (yes/no) value, or a number.

Ordered List Functions

The following functions only work on ordered lists.

Keyed List Functions

The following only work on Text Blaze's keyed lists.

Information Functions

The following functions all return a Boolean (yes/no) value. They're especially useful when used in combination with the {if} command.

Data Encoding Functions

These are very helpful functions to help with encoding. The urlencode() and urldecode() functions in particular are very useful when working with the {link} and {image} commands.

JSON Functions

There's a useful function built into Text Blaze that will help you work with JSON. This is very useful if you already have JSON and need this data available in your snippet.

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.

Special Delimiters

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:

List Comprehensions

Text Blaze has powerful built-in functions for transforming 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 out 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 be included when it evaluates to yes. Imagine we only wanted to include items who were larger than 20:

List Comprehensions with Keyed Lists

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

Multi-line formulas

Text Blaze supports multi-line formulas with code blocks.

Variable scopes

In general, all variables in Text Blaze are part of one global scope. There are a few exceptions to this. In these exceptions local scopes are created that have access to the global scope variables but may contain additional variables that are not in the global scope:

1. The {repeat} command, creates a separate local scope for each iteration of the repeat]. This allows you to create form fields within repeat's that are independent of one another. You can use the {repeat} command's locals setting to access these local variables in your global scope.
2. User defined functions will create a local scope with any parameters passed to the function.
3. Code blocks can create variables local to the code block using the var statement.

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 you with a variety of regular expression built-in functions for you to leverage regular expressions with.

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

The following table is a list of special characters that can be used in regular expressions:

More Regular Expression Examples

Let's build out a snippet to extract an email address.

Here's what's happening:

\w+@ is matching all word characters prior to the @ symbol. [.\w]+\b is matching as many periods and word characters as it can, up until a word boundary (meaning a punctuation mark followed by a space).

Here are some further clarifications of the special characters being used:

The period character (.) has a special meaning in regex (see the list provided above). If you want RegEx to interpret the period character literally, you need to precede it with a backslash.

The square brackets mean "any combination of the included".

The \b represents the word boundary.

Of course, this is just the tip of the iceberg with RegEx.

We're always improving the Text Blaze documentation to make things more clear for you.

Next Steps

• If you still have questions you can always post on our community. We're here to help!
• Go through our examples to see various commands and the formula language in use.
• Watch our YouTube videos for examples on using the Blaze Formula language and various commands.