Functions Reference

Selector

select <tags> In: None. Out: <block>

Return all blocks that contain the given tags. When multiple tags are provided, all tags must be present for a block to be returned. If a function begins with a tag, this function will be invoked.

Example

Return all blocks tagged with #A and #B

=(select #A #B)

not <tags> In: <block>. Out: <block>

Functions similar to select though the blocks found will be excluded from the input.

Example

Return all blocks tagged with #A and #B but exclude those tagged with #C.

=(select #A #B | not #C)

all In: None. Out: <block>

Return all blocks in the document.

this In: None. Out: <block>

Return the block from where the function is being executed. If an action does not begin with a selector, this is implicitly added and executed first.

children [incl] In: <block>. Out: <block>

Return the immediate children of the blocks passed into the input. If incl is present in the argument, the original parent block is included in the output.

Example

Return the children of blocks tagged with #A.

=(#A | children)

Return the block and children of the blocks tagged with #A.

=(#A | children incl)

descendants [incl] In: <block>. Out: <block>

Return all the children of the input blocks. Where children will only return the immediate next level children, descendants will return the entire tree of children.

parent [incl] In: <block>. Out: <block>

Return the parent block of the input block(s).

siblings In: <block>. Out: <block>

Return the siblings of the input block(s) but not including the input block.

Example

Returns the blocks Y and Z.

X
    #A
    Y
    Z

=(#A | siblings)

next [<limit: number> | all] In: <block>. Out: <block>

Return the next sibling of the input blocks.

Example

Returns the block X.

#A
X
Y

=(#A | next)

prev [<limit: number> | all] In: <block>. Out: <block>

Functionally the same as next but returns previous siblings.

first In: <block>. Out: <block>

Returns the very first block in the input blocks.

last In: <block>. Out: <block>

Returns the last block in the input blocks.

slice <from: number> <to: number> In: <block>. Out: <block>

Returns a subset of the input blocks given a start and end index. If only one argument is present, it will use it as the from index.

Example

Returns X and Y blocks.

#A
    W
    X
    Y
    Z

=(#A | children | slice 1 3)

filter <tag | fn> In: <block>. Out: <block>

Returns input blocks that pass a filter test. If a tag is used as the first argument then only blocks with the given tag will be returned. The available special filters are:

Blocks

after <tail: string> [once] In: <block>. Out: <In>

Sets the tail of the input blocks to the given string. This will also append the text to the end of the block. Returns the input blocks.

Example

Sets the tail of #A to the given text and appends it to the end.

#A

=(#A | after " (this is the tail)")

before <head: string> [once] In: <block>. Out: <In>

Functionally the same as after. Sets the head of the input blocks to the given string. This will also prepend the text to the start of the block. Returns the input blocks.

hide In: <block>. Out: <In>

Hides the input blocks. If already hidden this will have no effect.

show In: <block>. Out: <In>

Input blocks become visible. If already visible this will have no effect.

toggle In: <block>. Out: <In>

Switches the visibility state of the input blocks. If a block is hidden it becomes visible, if visible it is hidden.

indent In: <block>. Out: <In>

Input blocks are indented by a single tab. This will change the tree structure of the blocks.

unindent In: <block>. Out: <In>

Input blocks are unindented by a single tab. This will change the tree structure of the blocks.

flatten In: <block>. Out: <In>

Removes all indentation of the input blocks. This will change the tree structure of the blocks.

remove In: <block>. Out: None

Input blocks are removed from the document. This function returns nothing.

duplicate In: <block>. Out: <new block>

Creates a copy of the input blocks immediately after the original. Returns the newly created input blocks. The copied block will inherit the same properties such as head, tail, visibility state and styles.

sort <sortkey: tag | alpha> [asc|desc] In: <block>. Out: <In>

Will sort and rearrange the immediate children of the input blocks in place. If a tag is present, the sorter will look at the value of the tag. If this option is not used or the indentifier alpha is present, the sorter will sort alphabetically based on the text. If no direction is specified it will sort in ascending order.

Example

Will sort the children of #A by the value of #t in descending order (largest to smallest).

#A
    a #t:4
        a.a
    b #t:2
    c #t:5
    d #t:1

=(#A | sort #t desc)

move <destination: subcommand> In: <block>. Out: <block>

Moves the input blocks and all the subtree of blocks to be a child of the block returned by the subcommand. If the destination block already has children it will be moved to be the last child. The destination subcommand may only use selector functions and will use the first block in the output.

This function will always change the document even if the input blocks are already children of the destination block. Therefore it's recommended not to run move in an immediate action.

Example

Will move the #B block to be a child of the #A block.

#B
#A

=(#B | move `#A`)

pos In: None. Out: <number>

Returns the position of the current block where the function is executed. The position represents a zero-based index of where the blocks sits relative to its parent.

Example

The #A tag is at position 0 relative to the root of the document. It's children a, b and c are 0, 1 and 2 respectively as that is the position relative to the parent #A.

#A {0}(pos)
    a {0}(pos)
    b {1}(pos)
    c {2}(pos)

Date

now In: None. Out: <number>

Returns the current date and time as a UNIX timestamp.

Formatting

background <color: string> In: <block>. Out: <In>

Sets the background color of the input blocks. Once a background color is set it can only be unset with clearformat.

color <color: string> In: <block>. Out: <In>

Sets the text color of the input blocks. Once a background color is set it can only be unset with clearformat.

bold In: <block>. Out: <In>

Input blocks have the bold format applied.

italic In: <block>. Out: <In>

Input blocks have the italic format applied.

strikethrough In: <block>. Out: <In>

Input blocks have the strikethrough format applied.

underline In: <block>. Out: <In>

Input blocks have the underline format applied.

clearformat In: <block>. Out: <In>

Resets all format and colors of the input blocks to the default values.

Number

avg In: <number>. Out: <number>

Given an input of numbers, calculate the average and output it.

count In: <any>. Out: <number>

Returns number of values given in the input. This could be blocks, numbers or strings.

sum In: <number>. Out: <number>

Given an input of numbers, calculate the sum and output it.

dec <target: tag> In: <block>. Out: <In>

Decrement the value of a tag from the input blocks.

Example

Will decrement the value of the tag #value until stopped.

#A #value:5
=(#A | dec #value)

inc <target: tag> In: <block>. Out: <In>

Functionally the same as dec but instead will add 1.

dollar In: <number>. Out: <string>

Given a number will return a string with the number formatted as a dollar value. If more than one number is input, it will use the first value.

Example

#A:9.9889

{$9.99}(#A | val #A | dollar)

pct [<decimal: number>] In: <number>. Out: <string>

Given a number will return a string with the number formatted as a percentage value. If more than one number is input, it will use the first value.

Example

#A:0.5012

{50.1%}(#A | val #A | pct 1)

fixed [<decimal: number>] In: <number>. Out: <string>

Given a number will return a string with the number fixed to a decimal place. If more than one number is input, it will use the first value.

Example

#A:1.99

{2.0}(#A | val #A | fixed 1)

max <target: tag> In: <block|number>. Out: <block|number>

There are two ways to use the max functions. It can be used to return the input block with the highest value of a given tag. It can also be used to return the highest value given input numbers.

Example 1

Given the input blocks, returns the block with the highest value in the tag #value and set the color to red.

#A
    a #value:3
    b #value:1
    c #value:2

=(#A | children | max #value | color "red")

Example 2

Given the input blocks, extract the value of the tag #value and return the maximum.

#A
    a #value:3
    b #value:1
    c #value:2

{3}(#A | children | val #value | max)

min <target: tag> In: <block|number>. Out: <block|number>

Functionally the same as min but looking for the lowest value.

val <target: tag> [all] In: <block>. Out: <number>

Given input blocks, extract the value of the tag provided. If a block has multiple of the target tag, the indentifier all must be used to extract both values rather than just the first value.

setval <target: tag> <destination: subcommand> In: <number>. Out: <In>

Given an input number, set the value of a tag. The tag to set should be the first argument, the block that contains the tag should be the second argument as returned by the subcommand.

Example

Return the number 2, pass it into setval then set the tag of #value for the blocks tagged with #A.

#A #value

=(expr "2" | setval #value `#A`)

expr <expression: string> In: <number|block>. Out: <number>

Will execute the expression in the string. Tag values can be used in the expression for calculation. If blocks are the input, it will execute the expression per block and use the tags of said block in the expression. If a number is the input, it be used in an expression with a special tag #x.

Extracting the value of a tag has many moving parts. First it will try to find the tag in the current block, then it will look up the tree for the tag in any parents, then it will look down the tree in any children. If the tag is still not found it will search the entire document and use the first occurance.

There are a set of common mathematical functions available:

Example

Select the children of #A, extract the value of #v and multiply by 2.

#A
    a #v:1
    b #v:3
    c #v:2

{2, 6, 4}(#A | children | expr "#v * 2" | join)

String

text In: <block>. Out: <string>

Return the text of the input blocks removing all features including tags, buttons, immediates and textboxes. When the indentifier all is present, no features will be removed and the raw text will be returned.

compact In: <string>. Out: <string>

Compacts consecutive whitespace into a single space and performs trim.

Example

Select the block tagged with #A, return the text (without the tag), then collapse the whitespace.

this    is   a    string #A with   text
{this is a string with text}(#A | text | compact)

trim In: <string>. Out: <string>

Returns the input text but with the whitespace removed from the beginning and end of the text.

Example

The block #A has two spaces at the beginning and end. These will be removed by trim.

  text #A  
{text}(#A | text | trim)

join <separator: string> In: <number | string>. Out: <string>

Returns a string with all the inputs joined by a separator.

Example

Select the block tagged with #A, select its children and extract the text. This is joined by the default separator and returned. Notice the tab character before each item. This can be removed by using trim after extracting the text.

#A
    1
    2
    3
{   1,  2,  3}(#A | children | text | join)

Tag

addtag <tag> [once] In: <block>. Out: <In>

Adds the provided tag to the input blocks. Will append the tag to the end of the block. If only is present, this will have no change if one is already present. Otherwise multiple tags can be added.

Example

#A
=(#A | addtag #B once)

removetag <tag> [all] In: <block>. Out: <In>

Removes the provided tag from the input blocks. This will remove the first occurence of the tag unless the all identifier is present.

toggletag <tag> In: <block>. Out: <In>

Toggle tag will removed the provided tag if present on the input block. It will add it to the end of the block if it is not present. Toggle tag will remove all occurances of the tag that are present on the block.

Misc.

error In: None. Out: <string>

If at any point an error is made in an action, the error string is saved and can be viewed by using this function. This will always return the last error that has happened.

Example

=(expr "fail")
{expr: unrecognised expression function (fail)}(error)

scroll In: <block>. Out: None

Take the first input block and scroll it into view. This function can only be executed from a button action.