Functions Reference

Selectors

select

select #tags | <blocks>

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

#A
#B
#A #B
{1}(select #A #B | count)
{1}(#A #B | count)

nearest

<blocks> | nearest #tag | <blocks>

Return the first block that contains the provided tag nearest to the input block. The traversal will search through descendants first, then parents, and finally the first block to match from the start of the document.

Example

#A { nearest}(nearest #C | text)
  #B
    #C nearest
  #D
#C not nearest

not

<blocks> | not #tags | <blocks>
<blocks> | not <query: nested> | <blocks>

Return input blocks that do not have tags. If nested then it returns input blocks that are not returned from the nested command.

Example

Return blocks tagged with #A but exclude those tagged with #B.

#A
#A #B
{1}(select #A | not #B | count)

Return blocks tagged with #A but exclude this block.

#A
#A {1}(select #A | not (this) | count)

all

all | <blocks>

Return all blocks in the document.

Example

{1}(all | count)

this

this | <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

<blocks> | children [incl] | <blocks>

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

Alias: >

Example

Return the children of blocks tagged with #A.

#A
  #B
  #C
{2}(#A | children | count)

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

#A
  #B
  #C
{3}(#A | > incl | count)

descendants

<blocks> | descendants [incl] | <blocks>

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

Alias: *

Example

Return the children of blocks tagged with #A.

#A
  #B
    #C
  #D
{3}(#A | descendants | count)

parent

<blocks> | parent [incl] | <blocks>

Return the parent block of the input blocks. If incl is present, include the input blocks in the output blocks.

siblings

<blocks> | siblings [incl] | <blocks>

Return the siblings of the input blocks but not including the input block. If incl is present, the input block will be returned in the output blocks.

Example

Returns the blocks Y and Z.

#A
  #B
  #C
  #D
{2}(#B | siblings | count)

<blocks> | next [all] | <blocks>
<blocks> | next [<limit: number>] | <blocks>

Return the next sibling of the input blocks. If all is present, return all the next siblings. If limit is present, return no more than that number of siblings. If no argument is present, a limit of 1 will be default.

Example

Returns the block X.

#A
  #B
  #C
  #D
  #E
{2}(#B | next 2 | count)
{3}(#B | next all | count)

Same as next but returns previous siblings.

first

<blocks> | first | <block>

Returns the first block in the input blocks.

last

<blocks> | last | <block>

Returns the last block in the input blocks.

depth

<blocks> | depth <level: number> | <block>

Return input blocks that have indentation level the same as the provided level.

Example

#A
  #B
  #C
{2}(all | depth 1 | count)
{3}(all | depth 0 | count)

slice

<blocks> | slice <from: number> [<to: number>] | <blocks>

Returns a slice of the input blocks given a start and end index. If only one argument is present, it will start from that index to the end. Negative values will wrap around, so a value of -1 represents the last block.

Example

#A
  #B
  #C
  #D
  #E
{2}(#A | children | slice 1 3 | count)

filter

<blocks> | filter #tag | <blocks>
<blocks> | filter <filter> | <blocks>

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:

visible - blocks that are visible
hidden - blocks that are hidden
empty - blocks with no text
notempty - blocks that have text
plaintext - blocks that have text only (no features like buttons, tags, immediates)
feature - blocks that have features (buttons, tags, immediates)
haschildren - blocks with children
nochildren - blocks with no children
hascolor - blocks with a color set
nocolor - blocks with no color set
hasbackground - blocks with a background set
nobackground - blocks with no background set
hashead - blocks that has head content from the before function
nohead - blocks that has no head content from the before function
hastail - blocks that has tail content from the after function
notail - blocks that has no tail content from the after function

contains

<blocks> | contains <search: string> [i] | <blocks>

Return blocks from input blocks that contain the search string. If i is present, the search will be case-insensitive.

Example

BUG: Double-click broken
TODO: New styles
{1}(all | contains "BUG:" | count)

Blocks

new

<blocks> | new <template: string> | <new blocks>
<blocks> | new <template: nested> | <new blocks>

Creates new blocks as children of the input blocks and returns the newly created blocks. The content of the block will be either the string passed in or the output of a nested function.

Example

#A
#B template
[new blocks](#A | new "{}(pos) new block")
[new blocks](#A | new (#B | text | trim))

replace

<blocks> | replace <template: string> | <blocks>

Replaces the content of the block with the string provided.

Example

#A content
[replace](#A | replace "new content")

after

<blocks> | after <tail: string> [once] | <blocks>

Sets the tail of the input blocks to the given string. This will also append the text to the end of the block. If once is present, will only set the tail if the block doesn’t already have one. 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

Same as after but 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

<blocks> | hide | <blocks>

Hides the input blocks. Returns the input blocks.

show

<blocks> | show | <blocks>

Shows the input blocks. Returns the input blocks.

toggle

<blocks> | toggle | <blocks>

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

indent

<blocks> | indent | <blocks>

Input blocks are indented by one (two spaces). This will change the tree structure of the blocks.

unindent

<blocks> | unindent | <blocks>

Input blocks are unindented by one (two spaces). This will change the tree structure of the blocks.

flatten

<blocks> | flatten | <blocks>

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

remove

<blocks> | remove

Input blocks are removed from the document.

duplicate

<blocks> | duplicate | <new blocks>

Creates a clone of the input blocks and their descendants and places it 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.

reorder

<blocks> | reorder | <blocks>
<blocks> | reorder <key: nested> [asc/desc] | <blocks>

Sort and rearrange the immediate children of the input blocks in place. If a nested function is present it will be used as the sort key otherwise the text of the block will be used.

Example

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

#A
  #B:1
  #B:2
=(#A | reorder (val #B) desc)

move

<blocks> | move <destination: nested> | <blocks>

Moves the input blocks and its descendants to be a child of the block returned by the nested function. If the destination block already has children it will be moved to be the last child. The destination function may only use selector functions and the first block returned will be the destination.

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
[move](#B | move (#A))

pos

<blocks> | pos | <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)

reset

<blocks> | reset | <blocks>

Reset all attributes on the input blocks. This includes all formatting as well as head and tail.

Example

#A
[style](#A | color "red" | after " tail")
[reset](#A | reset)

Date

now

now | <number>

Returns the current date and time as a UNIX timestamp.

date

<number> | date <format: string> | <string>

Formats the number passed into the input as a date and time string using the format string. Refer to the date-fns library format function for how to format the dates. If "relative" is used as the format string, the formatRelative function will be used.

Example

{12 Jul 2021}(now | date "d MMM Y")
{today at 1:15 PM}(now | date "relative")

ago

<number> | ago | <string>

Format the number from input as a date and outputs text that represents how long ago from now, e.g. about 2 hours. Refer to the date-fns library formatDistance function.

Example

{less than a minute}(now | ago)

Formatting

background

<blocks> | background <color: string> | <blocks>

Sets the background color of the input blocks. The color string can either be hexadecimal RGB or an alias from this color table. Once a background color is set it can only be unset with clearformat or reset.

color

Functionally same as background but sets the text color.

bold

<blocks> | bold | <blocks>

Input blocks become bold.

italic

<blocks> | italic | <blocks>

Input blocks become italiced.

strikethrough

<blocks> | strikethrough | <blocks>

Input blocks have the strikethrough format applied.

underline

<blocks> | underline | <blocks>

Input blocks have the underline format applied.

clearformat

<blocks> | clearformat | <blocks>

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

Number

avg

<numbers> | avg | <number>

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

count

<any> | count | <number>

Returns number of values given in the input. This could be any value (blocks, numbers or text).

sum

<numbers> | sum | <number>

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

dec

<blocks> | dec #tag | <blocks>

Decrement the value of a tag from the input blocks.

Example

#A #value:5
[decrement](#A | dec #value)

inc

Functionally the same as dec but will increment the value by 1.

dollar

<number> | dollar | <string>

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

Example

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

pct

<number> | pct [<decimal: number>] | <string>

Given a number will return a string with the number formatted as a percentage value. Number will be multiplied by 100 and rounded to the decimal place provided (defaults to no decimals).

Example

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

fixed

<number> | fixed <decimal: number> | <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

<blocks> | max #tag | <block>
<numbers> | max | <number>

When blocks are input, return the block with the highest value of the tag present. When numbers are input, return the largest number.

Example

#A
  a #value:3
  b #value:1
  c #value:2
{a }(#A | children | max #value | text)

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

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

min

Functionally the same as max but with the minimum value.

val

<blocks> | val #tag | <number>
<blocks> | val #tag all | <numbers>

Return the value of the tag provided from the input blocks. If a block has multiple of the target tag, the indentifier all must be used to extract all values otherwise the first tag value will be returned.

setval

<blocks> | setval #tag <value: nested> | <blocks>
<blocks> | setval #tag <value: number> | <blocks>
<number> | setval #tag <target: nested> | <number>
<number> | setval #tag | <number>

Sets the value of a tag. When the input is blocks, the nested function should return a number to set as the value. When the input is a number, the nested function should select the blocks.

Example

#A:1
=(return 1 | setval #A (#A))

#A:2
=(#A | setval #A (return 2))

expr

<numbers> | expr <string> | <numbers>
<blocks> | expr <string> | <numbers>

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:

min(a, b) - return the minimum
max(a, b) - return the maximum
sin(x) - return the sine of x in radians
cos(x) - return the cosine of x in radians
tan(x) - return the tangent of x in radians
pow(base, exponent) - return the base taken to the power of the exponent
abs(n) - return the absolute value of n
random() - return a random number between 0.0 (inclusive) and 1.0 (exclusive)
ceil(n) - return n rounded up to the nearest integer
floor(n) - return n rounded down to the nearest integer
round(n) - return n rounded up or down to the nearest integer
sqrt(n) - return the square root of n

Example

#A
  a #tag:1
  b #tag:2
  c #tag:3
{2, 4, 6}(#A | > | expr "#tag * 2" | join)
{1, 4, 9}(#A | > | val #tag | expr "pow(#x, 2)" | join)

String

text

<blocks> | text [all] | <strings>

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

<strings> | compact | <strings>

Compacts consecutive whitespace into a single space and performs trim.

Example

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

trim

<strings> | trim | <strings>

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

Example

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

join

<strings> | join <glue: string> | <string>

Returns a string with all the input strings joined by the glue. Glue defaults to ,.

Example

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

numbers

<strings> | numbers | <numbers>
<blocks> | numbers | <numbers>

Extracts numbers from the input strings or blocks. Multiple numbers could be found and returned from a single string.

Example

#A 1 2 3
#B 4 5 6
{6}(#A | text | numbers | sum)
{15}(#B | numbers | sum)

wc

<strings> | wc [words/chars] | <number>

Count the words or characters in the input strings. Defaults to counting words.

Example

#A count the words and characters
{5}(#A | text | wc) words
{31}(#A | text | wc chars) characters

Tag

addtag

<blocks> | addtag #tag [once] | <blocks>

Adds the provided tag to the input blocks. Will append the tag to the end of the block. If once is present, the tag won’t be added if the block already has it.

Example

#A
[add tag](#A | addtag #B once)

removetag

<blocks> | removetag #tag [all] | <blocks>

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

toggletag

<blocks> | toggletag #tag | <blocks>

Toggle tag will remove 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.

Logic

if

if <condition: nested> <then: nested> [<else: nested>]

Run a nested function as a condition and run then if true or else if false.

Truthy table

Value	Outcome
Empty string	False
0	False
Empty list	False
Else	True

Example

#A:2
{true}(if (#A | val #A) (return "true") (return "false"))

ifnot

ifnot <condition: nested> <then: nested>

Similar to if but runs the then nested function if the condition evaluates to false.

gt

<blocks> | gt <a: number/tag/nested> <b: number/tag/nested> | <blocks>

Return input blocks where a is greater than b. These values can be represented by either a number, tag or a nested function.

Example

#A:1
#A:2
#A:3
{2}(#A | gt #A 1 | count)

gte

Greater than or equal. Functionally same as gt.

lt

Less than. Functionally same as gt.

lte

Less than or equal. Functionally same as gt.

eq

Equal. Functionally same as gt.

neq

Not equal. Functionally same as gt.

Keyval

key

<blocks> | key <k: string> | <block>

Returns the block which holds the key k. This will only look at the direct children of the input blocks.

Example

#Data
  Field: value
{Field: value}(#Data | key "Field" | text)

keyval

<blocks> | keyval <k: string> | <string>

Returns the value of the block which holds the key k.

Example

#Data
  Field: value
{value}(#Data | keyval "Field")

keyset

<blocks> | keyset <k: string> <val: number/string/nested> | <blocks>

Sets the value of the block which holds the key k to the value val.

Example

#Data
  Field: value
[set key value](#Data | keyset "Field" "new")

where

<blocks> | where <k: string> [gt/gte/lt/lte/eq/neq] <val: string/number> | <blocks>
<blocks> | where <k: string> [min/max] | <blocks>

Return the blocks where a child block value matches the query.

Example

#items
  item 1
    price: 2.8
  item 2
    price: 4.1
{item 2}(#items | > | where "price" max | text)
{2.8}(#items | > | where "price" lt 3 | keyval "price" | numbers | dollar)

Events

on

<blocks> | on <event: ident> | <blocks>

Events can be raised against blocks when the document structure changes such as a new block. This function will return blocks where the event has been raised. The event will live as long as one execution cycle. Custom events can be raised using the function raise.

Events

NEW - block that has just been created
NEW_CHILD - a child block has just been created
NEW_PARENT - block has a different parent block
NEW_DESCENDANT - a descendant block has just been created
REMOVED_CHILD - a child block has been removed
REMOVED_DESCENDANT - a descendant block has just been removed
CHANGE - content of a block has changed
HIDE - block has been hidden
SHOW - block has been shown

Example

#A
[create](#A | new "block")
=(#A | children | on NEW | addtag #new)

raise

<blocks> | raise <event: ident> | <blocks>

Raise a custom event against input blocks.

Example

#A
[raise](#A | raise MY_CUSTOM_EVENT)
{}(if (#A | on MY_CUSTOM_EVENT) (return "RAISED") (return "NOT RAISED"))

Utility

map

<any> | map <fn: nested> | <nested output>

Iterate over the input and run the nested function with each item as the input. The output will be a flattened list of all the output from the nested functions.

Example

#A:1 A
#A:2 B
{2, 4}(#A | map (expr "#A * 2") | join)
{A, B}(#A | text | map (trim) | join)

sort

<blocks> | sort [<key: nested>] [asc/desc] | <blocks>
<numbers> | sort [asc/desc] | <numbers>
<strings> | sort [asc/desc] | <strings>

Return the sorted input items. If the input is blocks then a nested function can be used as the sort key otherwise it will be sorted alphanumerically. The sort order defaults to ascending.

Example

#A
  z
  b
  k
{b, k, z}(#A | > | sort | text | join)

{2, 1, 0}(seq  3 | sort desc | join)

seq

seq <range: number> | <numbers>
seq <from: number> <to: number> [<step: number>] | <numbers>

Generate a sequence of numbers.

Example

{0, 1, 2, 3, 4}(seq 5 | join)
{1, 3, 5, 7, 9, 11}(seq 1 12 2 | join)
{2, 1, 0, -1, -2}(seq 2 -3 -1 | join)

return

return <value: string/number> | <value>

Utility function to return a value.

Example

{A}(return "A")
{1}(return 1)

plugin

plugin <src: string>

Load an external JavaScript file once and only once. This allows for adding more functions to use in actions.

Plugin script should use window.registerFunction to allow actions to run functions defined in the plugin script. registerFunction takes two arguments, the name of the function and the JavaScript function that will be called when it is used in an action.

Example

Plugin script (upper.js).

registerFunction("upper", function (stdin, args) {
   return stdin.map(s => s.toUpperCase());
});

Using the script and the new function in a document.

=(plugin "https://qworp.com/assets/plugins/upper.js")
{A}(return "a" | upper)

error

error | <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

<block> | scroll

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