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.
Return all blocks tagged with #A and #B
#A
#B
#A #B
{1}(select #A #B | count)
{1}(#A #B | count)
<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.
#A { nearest}(nearest #C | text)
#B
#C nearest
#D
#C not nearest
<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.
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 | <blocks>
Return all blocks in the document.
{1}(all | count)
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.
<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: >
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)
<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: *
Return the children of blocks tagged with #A.
#A
#B
#C
#D
{3}(#A | descendants | count)
<blocks> | parent [incl] | <blocks>
Return the parent block of the input blocks. If incl
is present, include the input blocks in the output blocks.
<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.
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.
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.
<blocks> | first | <block>
Returns the first block in the input blocks.
<blocks> | last | <block>
Returns the last block in the input blocks.
<blocks> | depth <level: number> | <block>
Return input blocks that have indentation level the same as the provided level.
#A
#B
#C
{2}(all | depth 1 | count)
{3}(all | depth 0 | count)
<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.
#A
#B
#C
#D
#E
{2}(#A | children | slice 1 3 | count)
<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:
before
functionbefore
functionafter
functionafter
function<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.
BUG: Double-click broken
TODO: New styles
{1}(all | contains "BUG:" | count)
<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.
#A
#B template
[new blocks](#A | new "{}(pos) new block")
[new blocks](#A | new (#B | text | trim))
<blocks> | replace <template: string> | <blocks>
Replaces the content of the block with the string provided.
#A content
[replace](#A | replace "new content")
<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.
Sets the tail of #A to the given text and appends it to the end.
#A
=(#A | after " (this is the tail)")
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.
<blocks> | hide | <blocks>
Hides the input blocks. Returns the input blocks.
<blocks> | show | <blocks>
Shows the input blocks. Returns the input blocks.
<blocks> | toggle | <blocks>
Switches the visibility state of the input blocks. If a block is hidden it becomes visible, if visible it is hidden.
<blocks> | indent | <blocks>
Input blocks are indented by one (two spaces). This will change the tree structure of the blocks.
<blocks> | unindent | <blocks>
Input blocks are unindented by one (two spaces). This will change the tree structure of the blocks.
<blocks> | flatten | <blocks>
Removes all indentation of the input blocks. This will change the tree structure of the blocks.
<blocks> | remove
Input blocks are removed from the document.
<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.
<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.
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)
<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.
Will move the #B block to be a child of the #A block.
#B
#A
[move](#B | move (#A))
<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.
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)
<blocks> | reset | <blocks>
Reset all attributes on the input blocks. This includes all formatting as well as head and tail.
#A
[style](#A | color "red" | after " tail")
[reset](#A | reset)
now | <number>
Returns the current date and time as a UNIX timestamp.
<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.
{12 Jul 2021}(now | date "d MMM Y")
{today at 1:15 PM}(now | date "relative")
<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.
{less than a minute}(now | ago)
<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
.
Functionally same as background
but sets the text color.
<blocks> | bold | <blocks>
Input blocks become bold.
<blocks> | italic | <blocks>
Input blocks become italiced.
<blocks> | strikethrough | <blocks>
Input blocks have the strikethrough format applied.
<blocks> | underline | <blocks>
Input blocks have the underline format applied.
<blocks> | clearformat | <blocks>
Resets all format and colors of the input blocks to the default values.
<numbers> | avg | <number>
Given an input of numbers, calculate the average and output it.
<any> | count | <number>
Returns number of values given in the input. This could be any value (blocks, numbers or text).
<numbers> | sum | <number>
Given an input of numbers, calculate the sum and output it.
<blocks> | dec #tag | <blocks>
Decrement the value of a tag from the input blocks.
#A #value:5
[decrement](#A | dec #value)
Functionally the same as dec
but will increment the value by 1.
<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.
#A:9.9889
{$9.99}(#A | val #A | dollar)
<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).
#A:0.5012
{50.1%}(#A | val #A | pct 1)
<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.
#A:1.99
{2.0}(#A | val #A | fixed 1)
<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.
#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)
Functionally the same as max
but with the minimum value.
<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.
<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.
#A:1
=(return 1 | setval #A (#A))
#A:2
=(#A | setval #A (return 2))
<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 minimummax(a, b)
- return the maximumsin(x)
- return the sine of x
in radianscos(x)
- return the cosine of x
in radianstan(x)
- return the tangent of x
in radianspow(base, exponent)
- return the base taken to the power of the exponentabs(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 integerfloor(n)
- return n
rounded down to the nearest integerround(n)
- return n
rounded up or down to the nearest integersqrt(n)
- return the square root of n
#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)
<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.
<strings> | compact | <strings>
Compacts consecutive whitespace into a single space and performs trim.
this is a string #A with [button](this) text
{this is a string with text}(#A | text | compact)
<strings> | trim | <strings>
Returns the input text but with the whitespace removed from the beginning and end of the text.
text #A
{text}(#A | text | trim)
<strings> | join <glue: string> | <string>
Returns a string with all the input strings joined by the glue. Glue defaults to ,
.
#A
1
2
3
{1, 2, 3}(#A | children | text | join)
<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.
#A 1 2 3
#B 4 5 6
{6}(#A | text | numbers | sum)
{15}(#B | numbers | sum)
<strings> | wc [words/chars] | <number>
Count the words or characters in the input strings. Defaults to counting words.
#A count the words and characters
{5}(#A | text | wc) words
{31}(#A | text | wc chars) characters
<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.
#A
[add tag](#A | addtag #B once)
<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.
<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.
if <condition: nested> <then: nested> [<else: nested>]
Run a nested function as a condition and run then if true or else if false.
Value | Outcome |
---|---|
Empty string | False |
0 | False |
Empty list | False |
Else | True |
#A:2
{true}(if (#A | val #A) (return "true") (return "false"))
ifnot <condition: nested> <then: nested>
Similar to if
but runs the then nested function if the condition evaluates to false
.
<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.
#A:1
#A:2
#A:3
{2}(#A | gt #A 1 | count)
Greater than or equal. Functionally same as gt
.
Less than. Functionally same as gt
.
Less than or equal. Functionally same as gt
.
Equal. Functionally same as gt
.
Not equal. Functionally same as gt
.
<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.
#Data
Field: value
{Field: value}(#Data | key "Field" | text)
<blocks> | keyval <k: string> | <string>
Returns the value of the block which holds the key k
.
#Data
Field: value
{value}(#Data | keyval "Field")
<blocks> | keyset <k: string> <val: number/string/nested> | <blocks>
Sets the value of the block which holds the key k
to the value val
.
#Data
Field: value
[set key value](#Data | keyset "Field" "new")
<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.
#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)
<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
.
NEW
- block that has just been createdNEW_CHILD
- a child block has just been createdNEW_PARENT
- block has a different parent blockNEW_DESCENDANT
- a descendant block has just been createdREMOVED_CHILD
- a child block has been removedREMOVED_DESCENDANT
- a descendant block has just been removedCHANGE
- content of a block has changedHIDE
- block has been hiddenSHOW
- block has been shown#A
[create](#A | new "block")
=(#A | children | on NEW | addtag #new)
<blocks> | raise <event: ident> | <blocks>
Raise a custom event against input blocks.
#A
[raise](#A | raise MY_CUSTOM_EVENT)
{}(if (#A | on MY_CUSTOM_EVENT) (return "RAISED") (return "NOT RAISED"))
<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.
#A:1 A
#A:2 B
{2, 4}(#A | map (expr "#A * 2") | join)
{A, B}(#A | text | map (trim) | join)
<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.
#A
z
b
k
{b, k, z}(#A | > | sort | text | join)
{2, 1, 0}(seq 3 | sort desc | join)
seq <range: number> | <numbers>
seq <from: number> <to: number> [<step: number>] | <numbers>
Generate a sequence of numbers.
{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 <value: string/number> | <value>
Utility function to return a value.
{A}(return "A")
{1}(return 1)
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.
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 | <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.
=(expr "fail")
{expr: unrecognised expression function (fail)}(error)
<block> | scroll
Take the first input block and scroll it into view. This function can only be executed from a button action.