4 Language Interface🔗ℹ

The most common way to use Qi is via interface macros in a host language such as Racket. Qi may also be used in tandem with other embedded or hosted DSLs.

4.1 Using Qi from the Host Language🔗ℹ

The core entry-point to Qi from the host language is the form ☯. In addition, other forms such as on, switch, and ~> build on top of ☯ to provide convenient syntax in specialized cases. Together, these forms represent the interface between the host language (e.g. Racket) and Qi.

4.1.1 Core🔗ℹ

This produces a value that is an ordinary function. When invoked with arguments, this function passes those arguments as inputs to the defined flow, producing its outputs as return values. A flow defined in this manner does not name its inputs, and like any function, it only produces output when it is invoked with inputs.

See also on and ~>, which are shorthands to invoke the flow with arguments immediately.

This is a way to pass inputs to a flow that is an alternative to the usual function invocation syntax (i.e. an alternative to simply invoking the flow with arguments). It may be preferable in certain cases, since the inputs are named at the beginning rather than at the end.

In the respect that it both defines as well as invokes the flow, it has the same relationship to ☯ as let has to lambda, and can be used in analogous ways.

Equivalent to ((☯ flow-expr) arg ...).

4.1.2 Threading🔗ℹ

In these docs, we’ll sometimes refer to the host language as "Racket" for convenience, but it should be understood that Qi may be used with any host language.

Note that, as there may be any number of input arguments, they must be wrapped in parentheses in order to distinguish them from the flow specification – unlike the usual threading macro where the input is simply the first argument.

As flows themselves can be nonlinear, these threading forms too support arbitrary arity changes along the way to generating the result.

In the respect that these both define as well as invoke the flow, they have the same relationship to ☯ as let has to lambda, and can be used in analogous ways.

Equivalent to ((☯ (~> flow-expr ...)) args ...).

See also: Relationship to the Threading Macro.

4.1.3 Conditionals🔗ℹ

Each of the predicate and consequent expressions is a flow, and they are each typically invoked with arg ..., so that the arguments need not be mentioned anywhere in the body of the form.

This Racket form leverages the identically-named Qi form. See Conditionals for its full syntax and behavior.

4.1.4 Lambdas🔗ℹ

These anonymous function forms may be used in cases where you need to explicitly name the arguments for some reason. Otherwise, in most cases, just use ☯ directly instead as it produces a function while avoiding the extraneous layer of bindings.

4.1.5 Definitions🔗ℹ

The following definition forms may be used in place of the usual general-purpose define form when defining flows.

The advantage of using these over the general-purpose define form is that, as they express the definition at the appropriate level of abstraction and with the attendant constraints for the type of flow, they can be more clear and more robust, minimizing boilerplate while providing guardrails against programmer error.

4.2 Using the Host Language from Qi🔗ℹ

Arbitrary host language (e.g. Racket) expressions can be used in flows in one of two core ways. This section describes these two ways and also discusses other considerations regarding use of the host language alongside Qi.

4.2.1 Using Racket Values in Qi Flows🔗ℹ

The first and most common way is to simply wrap the expression with a gen form while within a flow context. This flow generates the value of the expression.

4.2.2 Using Racket to Define Flows🔗ℹ

The second way is if you want to describe a flow using the host language instead of Qi. In this case, use the esc form. The wrapped expression in this case must evaluate to a function, since functions are the only values describable in the host language that can be treated as flows. Note that use of esc is unnecessary for function identifiers since these are usable as flows directly, and these can even be partially applied using standard application syntax, optionally with _ and __ to indicate argument placement. But you may still need esc in the specific case where the identifier collides with a Qi form.

Finally, bear in mind that if you use esc, the Qi compiler will not attempt to optimize the resulting flow. Of course, if such a flow occurs within a larger flow, other parts of that containing flow would still be optimized as usual. Yet, as escaped forms are generally not considered in optimizations, the presence of such forms may make it less likely that there would be applicable nonlocal (i.e. involving more than one flow, like phrases) optimizations.

4.2.3 Using Racket Macros as Flows🔗ℹ

Flows are expected to be functions, and so you cannot naively use a macro as a flow. But there are many ways in which you can. If you’d just like to use such a macro in a one-off manner, see Converting a Macro to a Flow for an ad hoc way to do this. But a simpler and more complete way in many cases is to first register the macro (or any number of such macros) using define-qi-foreign-syntaxes prior to use.

By doing this, you can thread multiple values through such syntaxes in the same manner as functions. The catch-all template __ isn’t supported though, since macros (unlike functions) require all the "arguments" to be supplied syntactically at compile time. So while any number of arguments may be supplied to such macros, it must be a specific rather than an arbitrary number of them, which may be indicated syntactically via _ to indicate individual expected arguments and their positions.

Note that for a foreign macro used in identifier form (such as double-me in the example above), it assumes a single argument. This is different from function identifiers where they receive as many values as may happen to be flowing at runtime. With macros, as we saw, we cannot provide them an arbitrary number of arguments. If more than one argument is anticipated, explicitly indicate them using a _ template.

Finally, as macros "registered" in this way result in the implicit creation of Qi macros corresponding to each foreign macro, if you’d like to use these forms from another module, you’ll need to provide them just like any other Qi macro, i.e. via (provide (for-space qi ...)).

4.3 Using Qi with Another DSL🔗ℹ

Qi may also be used in tandem with other DSLs in a few different ways – either directly, if the DSL is implemented simply as functions without custom syntax, or via a one-to-one macro "bridge" between the two languages (if the interface between the languages is small), or potentially by implementing the DSL itself as a Qi dialect (if the languages interact extensively).

4.3.1 Using Qi Directly🔗ℹ

If the forms of the DSL are callable, i.e. if they are functions, then you can just use Qi with them the same way as with any other function.

4.3.2 Using a Macro Bridge🔗ℹ

See Converting a Macro to a Flow.

Using the macro bridge approach, you would need to write a corresponding Qi macro for every form of your DSL that interacts with Qi (or use define-qi-foreign-syntaxes to do this for you). If this interface between the two languages is large enough, and their use together frequent enough, this approach too may prove cumbersome. In such cases, it may be best to implement the DSL itself as a dialect of Qi.

4.3.3 Writing a Qi Dialect🔗ℹ

The problem with the macro bridge approach is that all paths between the two languages must go through a level of indirection in the host language. That is, the only way for Qi and the other DSL to interact is via Racket as an everpresent intermediary.

To get around this, a final possibility to consider is to translate the DSL itself so that it’s implemented in Qi rather than Racket. That is, instead of being specified using Racket macros via e.g. define-syntax-parse-rule and define-syntax-parser, it would rather be defined using define-qi-syntax-rule and define-qi-syntax-parser so that the language expands to Qi rather than Racket (directly). This would allow your language to be used with Qi seamlessly since it would now be a dialect of Qi.

There are many kinds of languages that you could write in Qi. See Writing Languages in Qi for a view into the possibilities here, and what may be right for your language.