5 The Qi Language🔗ℹ

The core syntax of the Qi language. These forms may be used in any flow. Flows may be specified in Racket via the language interface.

5.1 Basic🔗ℹ

Note that literals are transparently wrapped with gen during expansion and don’t need to be explicitly wrapped.

gen generalizes const in the same way that values generalizes identity.

Also see Using Racket Values in Qi Flows.

When used in parametrized form with a presupplied flo, this flow accepts any number of inputs, where the first is expected to be the list to be unraveled. In this form, the flow separates the list into its component values and passes each through flo along with the remaining input values.

△ and ▽ often allow you to use functions directly where you might otherwise need to use an indirection like apply or list.

△ and ▽ often allow you to use functions directly where you might otherwise need to use an indirection like apply or list.

Also see Using Racket to Define Flows.

We typically describe flows using Qi, while esc allows us to describe a flow using the host language. In either case, the flow simply operates on runtime inputs. In some cases, though, we need to generate a flow as a value to be used later, for instance, when the flow is parametrized by inputs not available until runtime. clos allows us to define and produce such a flow using Qi.

Without clos, we could still accomplish this by using esc and producing a function value (i.e. a lambda) as the result of the function we define – but this would mean that we must employ the host language to describe the flow rather than Qi.

When used within a threading form (i.e. ~> or ~>>), clos incorporates the pre-supplied input in accordance with the threading direction at the site of its definition.

See Converting a Function to a Closure in the field guide for more tips on using closures.

5.2 Predicates🔗ℹ

5.3 Boolean Algebra🔗ℹ

Note that the symbol form uses Unicode 0x2225 corresponding to LaTeX’s \parallel. We do not use the easier-to-type || symbol (that was formerly used here in older versions of Qi) as that is treated as the empty symbol by Racket’s reader, which could cause problems in some cases.

5.4 Routing🔗ℹ

~> "threads" the arguments in the leading position, while ~>> threads them in the trailing position. Argument positions may also be explicitly indicated via a template, either individually or en masse.

In the common case of 1 × 1 flos (i.e. where the flows each accept one input and produce one output), the number of outputs will be the same as the number of inputs, but as flows can be nonlinear, this is not necessarily the case in general.

When used in identifier form simply as ==, it behaves identically to ><.

See also the field guide entry on the relationship between bindings and nonlinearity.

When used in identifier form simply as fanout, it treats the first input as N, and the remaining inputs as the values to be fanned out.

In the context of a loop, this is a typical way to do "structural recursion" on flows (see "pare"), and in this respect it is the values analogue to car and cdr for lists.

When used in identifier form simply as group, it treats the first three inputs as number, selection-flo and remainder-flo, respectively, and the remaining as the data inputs to be acted upon.

When used in identifier form simply as sieve, it treats the first three inputs as condition-flo, selection-flo and remainder-flo, respectively, and the remaining as the data inputs to be acted upon.

5.5 Conditionals🔗ℹ

when is shorthand for (if condition-flo consequent-flo ⏚) and unless is shorthand for (if condition-flo ⏚ alternative-flo).

Typically, each of the component flows – conditions and consequents both – receives all of the original inputs to the switch. This can be changed by using a divert clause, which takes two flow arguments, the first of whose outputs go to all of the condition flows, and the second of whose outputs go to all of the consequent flows. This can be useful in cases where multiple values flow, but only some of them are predicated upon, and others (or all of them) inform the actions to be taken. Using (divert _ _) is equivalent to not using it. % is a symbolic alias for divert – parse it visually not as the percentage sign, but as a convenient way to depict a "floodgate" diverting values down different channels.

When the => form is used in a consequent flow, the consequent receives N + 1 inputs, where the first input is the result of the predicate flow, and the remaining N inputs are the a priori inputs to the consequent flow (which are typically the original inputs to the switch, unless modulated with a divert clause). This form is analogous to the => symbol when used in a cond. Note that while switch can direct any number of values, we can unambiguously channel the result of the predicate to the first input of the consequent here because it is guaranteed to be a single value (otherwise it wouldn’t be a predicate).

If none of the conditions are met, this flow produces the input values, unchanged, except if a divert clause is specified, in which case it produces the input values transformed under consequent-gate-flow. If you need a specific value such as (void) or would prefer to output no values, indicate this explicitly via e.g. [else void] or [else ⏚].

5.6 Loops🔗ℹ

If unspecified, condition-flo defaults to #t, combine-flo defaults to _, and return-flo defaults to ⏚.

When used in identifier form simply as loop, this behaves the same as the fully qualified version, except that the flows parametrizing the loop are expected as the initial four inputs (in the same order), and the data inputs being acted upon are expected to follow.

If used as (feedback flo), the first input to the feedback block will be expected to be N and will not be "fed back" with the rest of the inputs. If flo is not specified, then it will be expected as the first input, with the remaining inputs being treated as the inputs being acted upon. If used in identifier form simply as feedback, it treats the first two inputs as N and flo, respectively, and both are expected. The remaining inputs are treated as the data inputs being acted upon.

For practical advice on using feedback, see Effectively Using Feedback Loops in the field guide.

5.7 Exceptions🔗ℹ

5.8 Higher-order Flows🔗ℹ

If used in identifier form simply as ><, it treats the first input as flo.

If used in identifier form simply as pass, it treats the first input as condition-flo and the remaining inputs as the values to be filtered.

flo processes one input value at a time. It receives the current input value in the first position, followed by the accumulated values, and may generate any number of output values. These output values are fed back as accumulated values for the next iteration if input values remain to be processed; otherwise, they are produced as the output of the flow.

init-flo is expected to be a flow that will generate the initial values for the fold, and will be invoked with no inputs for this purpose at runtime. It is done this way to support having multiple initial values or no initial values, rather than specifically one. Specifying init-flo is optional; if it isn’t provided, flo itself is invoked with no arguments to obtain the init value, to borrow a convention from the Clojure language.

Use (ε side-effect-flo) to just perform a side effect without modifying the input, equivalent to (-< (~> side-effect-flo ⏚) _).

Remember that, as the side-effect flow is based on a tee junction, it must handle as many inputs as the main flow. For instance, if you were to use displayln as the side-effect, it wouldn’t work if more than one value were flowing, and you’d get an inscrutable error resembling:

; displayln: contract violation

;   expected: output-port?

;   given: 1

;   argument position: 2nd

;   other arguments...:

;    1

As displayln expects a single input, you’d need to use (>< displayln) for this side-effect in general.

If you are interested in using effect to debug a flow, see the section on Debugging in the field guide for more strategies.

5.9 Binding🔗ℹ

5.9.1 Variable Scope🔗ℹ

We will use (gen v) as an example of a flow referencing a binding, to illustrate variable scope.

In general, bindings are scoped to the outermost threading form, and may be referenced downstream.

> (~> (5) (as v) (gen v))

5

> (~> (5) (-< (~> sqr (as v))               _) (gen v))

25

A tee junction binds downstream flows in a containing threading form, with later tines shadowing earlier tines.

> (~> () (-< (~> 5 (as v))              (~> 6 (as v))) (gen v))

6

A relay binds downstream flows in a containing threading form, with later tines shadowing earlier tines.

> (~> (5 6)       (== (as v)           (as v))       (gen v))

6

In an if conditional form, variables bound in the condition bind the consequent and alternative flows, and do not bind downstream flows.

> (on ("Ferdinand")     (if (-< (~> string-titlecase (as name))             (string-suffix? "cat"))         (gen name)         (gen (~a name " the Cat"))))

"Ferdinand the Cat"

Analogously, in a switch, variables bound in each condition bind the corresponding consequent flow.

> (switch ("Ferdinand the cat")     [(-< (~> string-titlecase (as name))          (string-suffix? "cat")) (gen name)]     [else "dog"])

"Ferdinand The Cat"

As switch compiles to if, technically, earlier conditions bind all later switch clauses (and are shadowed by them), but this is considered an incidental implementation detail. Like if, switch bindings are unavailable downstream.

5.10 Identifiers🔗ℹ

Identifiers in a flow context are interpreted as variables whose values are expected to be functions. In other words, any named function may be used directly as a flow.

More precisely, for instance, add1 in a flow context is equivalent to (esc add1).

5.11 Literals🔗ℹ

Literals and quoted values (including syntax-quoted values) in a flow context are interpreted as flows generating them. That is, for instance, 5 in a flow context is equivalent to (gen 5).

5.12 Templates and Partial Application🔗ℹ

A parenthesized expression that isn’t one of the Qi forms is treated as partial function application, where the syntactically-indicated arguments are pre-supplied to yield a partially applied function that is applied to the input values at runtime.

Usually, the _ symbol indicates the trivial or identity flow, simply passing the inputs through unchanged. Within a partial application, however, the underscore indicates argument positions. If the expression includes a double underscore, __, then it is treated as a blanket template such that the runtime arguments (however many there may be) are passed starting at the position indicated by the placeholder. Another type of template is indicated by using one or more single underscores. In this case, a specific number of runtime arguments are expected (corresponding to the number of blanks indicated by underscores). Note that this could even include the function to be applied, if that position is templatized. This more fine-grained template is powered under the hood by Fancy App: Scala-Style Magic Lambdas.