Pipe - misonou/waterpipe GitHub Wiki

Advanced manipulations can be done through pipe and pipe function.

A pipe consists of a list of arguments separated by spaces:

{{input? function args* ...}}

While a pipe function accepts the previous evaluated value (a.k.a. input), reads arguments from the pipe and then returns a new value.

{{array}} ➜ [1,2,3,4]
{{array length}} ➜ 4
{{array.0 * 10}} ➜ 10
{{string upper padstart /}} ➜ /FOO

There are three possible roles for an argument in a pipe:

1. Input value
2. Pipe function
3. Argument to pipe function

which can be one of the following forms:

	Evaluated	Constant	Inferred	Lambda
Syntax	$arg	"arg"	arg	[ ... ]
Input value (first argument)	✓	✓	✓ (See note)	✓
Pipe function			✓
Argument to pipe function	✓	✓	✓	✓

Evaluated and constant arguments are pretty simple that the former are always evaluated as an object path while the latter are always as is.

However, both mode cannot be used to resolve pipe functions.

{{value "add" 2}} ➜
{{value $add 2}} ➜

The following precendence take places if it represents argument to pipe function:

1. Numbers, booleans, undefined and null are always as constants
2. Evaluated value if it is an accepted object path (see note below)
3. Constant string value

{{value}} ➜ 3
{{value * 2}} ➜ 6
{{value * value}} ➜ 9
{{value * invalidPath}} ➜

Note: Unless pipe functions are declared as variadic (see Variadic functions) which can operate advanced pipe operations, if the input value is a primitive value, only object paths that evaluate to primitive values are accepted.

{{string}} ➜ object
{{object}} ➜ {}

{{string == object}} ➜ true
{{string == "object"}} ➜ true
{{string == $object}} ➜ false

A lambda argument is denoted by an open bracket ([) argument, through coming segments until a balanced close bracket (]) argument.

Almost in all circumstances pipe functions accept lambda as arguments unless otherwise specified.

{{values}} ➜ [1,2,3,4]
{{values where [ even ]}} ➜ [2,4]
{{values map [ + 1 ]}} ➜ [2,3,4,5]

Lambda can be nested.

{{? [ any [ even ] ] yes no}} ➜ yes

The backslash character (\) is used for escaping in arguments.

It escapes the next whitespace character in inferred arguments; or escapes the next double-quote character in constant arguments:

{{&print Single\ argument}} ➜ Single argument
{{&print "\"Single argument\""}} ➜ "Single argument"