Expressions

Expressions¶

Seqtool can evaluate mathematical expressions, but also supports more complex programming code; thanks to the tiny integrated JavaScript engine (QuickJS). This allows for solving problems that would normally require writing a custom script (which would often run slower).

Another important use case for expressions is the powerful filter command.

A comprehensive JavaScript language overview can be found on this Mozilla site.

Usage¶

Expressions are always written in curly brackets: { expression }. They can be used at any place where variables/functions are allowed.

Exception: filtering expressions don't need braces

Strings + numbers¶

JavaScript has a special behavior when it comes to adding strings + numbers:

"a" + 1 just concatenates the two, producing the string "a1". Things become confusing if numbers are stored as strings: "1" + 2 gives "12" instead of just 3.

In seqtool, many variables/functions are (respectively return) text/strings. Examples for numeric variables are seqhash, seq_num as well as all sequence statistics variables. The exact type can be found by typing st <command> --help-vars:

Variable help example

TODO: add type to var reference

Functions for header attribute and metadata access are the most prone to this issue. The functions attr(name) and meta(column) always return text, since seqtool doesn't know or check whether the given text is a number or not. Consequently, attr("name") + 1 will just concatenate 1 to the attribute value instead of adding the numbers.

Solution: Convert to numeric with the num function: num(attr("name")) + 1. Num works like parseFloat(), but stops with an error if the given string is not a number.

String function arguments¶

A peculiarity of seqtool functions are unquoted string arguments. These are allowed in a non-expression context in order to prevent users from having to use both single and double quotes. Example:

st sort 'attr(a)' input.fasta

As soon as an expression is used, arguments need to be quoted, otherwise the a is interpreted as a variable:

st sort 'num(attr("a")) + num(attr("b"))' input.fasta

Initialization¶

(TODO: explain --js-init...)

Regular expressions¶

Using the regular expression /literal/ syntax is not possible, since seqtool has its own script parsing routine, which cannot handle such complex cases. Use the RegExp class instead, e.g.: desc.match(new RegExp("xy\d+")).