Functions Reference

Selectors

select

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

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

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

Return all blocks in the document.

Example

{1}(all | count)

this

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

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

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

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

siblings

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)

next

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)

prev

Same as next but returns previous siblings.

first

Returns the first block in the input blocks.

last

Returns the last block in the input blocks.

depth

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

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

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:

contains

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

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

Replaces the content of the block with the string provided.

Example

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

after

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

Hides the input blocks. Returns the input blocks.

show

Shows the input blocks. Returns the input blocks.

toggle

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

indent

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

unindent

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

flatten

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

remove

Input blocks are removed from the document.

duplicate

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

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

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

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

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

Returns the current date and time as a UNIX timestamp.

date

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

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

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

Input blocks become bold.

italic

Input blocks become italiced.

strikethrough

Input blocks have the strikethrough format applied.

underline

Input blocks have the underline format applied.

clearformat

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

Number

avg

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

count

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

sum

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

dec

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

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

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

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

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

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

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

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

#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

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

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

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

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

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

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

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

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

toggletag

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

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

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

gt

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

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

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

Example

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

keyset

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

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

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

Example

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

raise

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

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

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

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

Utility function to return a value.

Example

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

plugin

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

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

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