5 The Qi Language🔗

The syntax and semantics of the Qi language. Qi flows may be described using these forms and embedded into Racket using the language interface.

5.1 Syntax🔗

The syntax of a language is most economically and clearly expressed using a grammar, in the form of "nonterminal" symbols along with production rules expressing the syntax that is entailed in positions marked by those symbols. We may thus take the single starting symbol in such a grammar to formally designate the entire syntax of the language.

The symbol expr is typically used in this sense to indicate a Racket nonterminal position in the syntax, i.e., a position that expects a Racket expression. Analogously, we use the identifier floe (pronounced "flow-e," for "flow expression") to refer to the Qi nonterminal, i.e., a position expecting Qi syntax.

floe is not to be confused with flow. The relationship between the two is one of syntax and semantics, that is, the meaning of a floe is a flow.

The full surface syntax of Qi is given below. Note that this expands to a smaller core language before being compiled to Racket. Additionally, Qi’s syntax (i.e., floe) may be extended by writing Qi Macros. In particular, the list-oriented forms (not included here) may be added via (require qi/list).

5.2 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 given multiple input lists, this resembles the standard "zip" operation in functional programming languages. Specifically: combine corresponding members of each input list using flo, producing these results directly as values. If no flo is specified, default to values, so that the behavior is to simply separate all input lists into values, in order of appearance, by index. A common choice of flo here is list, yielding the usual "zip."

If the input lists aren’t all of the same size, the operation is truncated when the shortest list is exhausted.

In the common case where flo is 1 × 1 (i.e., where it accepts one input and produces one output), and where the input lists are all of the same size, the number of outputs will be the same as the length of each input list. But as flows can produce any number of values, this is not necessarily the case in general.

△ 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.

That is, this lambda is a Qi form that expands to a use of Racket’s lambda form, providing a shorthand for a common way to describe a flow using Racket.

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.3 Predicates🔗

5.4 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.5 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.6 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.7 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.8 Exceptions🔗

5.9 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.