2 Zuo Base Language🔗ℹ

The zuo language is Zuo’s default language. It’s meant to be familiar to Racket programmers, and the description here leans heavily on comparisons and the Racket documentation, for now. Zuo forms and functions tend use traditional Racket names, even when a different choice might be made in a fresh design, and even when the Zuo construct is not exactly the same. Filesystem operations, however, tend to use the names of Unix programs, which are much shorter than Racket’s long names.

The zuo/base language includes most of the bindings from zuo, but not the ones from zuo/cmdline, zuo/build, zuo/shell, zuo/thread, zuo/glob, or zuo/config.

When using module->hash on zuo/base, zuo, or a module implemented with one of those languages, the resulting hash table includes 'dynamic-require mapped to the dynamic-require function. Getting dynamic-require that way provides a path from the primitive Zuo kernel module protocol to zuo/base module exports.

Changed in version 1.2: Added the 'dynamic-require key for zuo and related languages.

2.1 Syntax and Evaluation Model🔗ℹ

A zuo module consists of a sequence of definitions (e.g., define), macro definitions (e.g., define-syntax), imports (e.g., require), exports (e.g., provide), and expressions (e.g., 5). Loading the module first expands it, and then evaluates it. A module is loaded only once, so if a module is demanded more than once, the result of the first load is used.

The expansion process expands macro uses, loads imported modules, and evaluates macro definitions as such forms are encountered for the module body. Expansion creates a binding for each definition as encountered, but does not expand or evaluate the definition, yet. Expansion of definitions and expressions is deferred until all forms in the module body have been processed. Some expression forms have local definition contexts, which can include further imports and macro definitions, so expansion at those points nests the same two-step process as used for the module body.

Evaluation of a module evaluates its definitions and expressions (some of which may have been introduced by macro expansion) in order. Definitions bind mutually recursively within the enclosing module or definition context, and referencing a defined variable before its evaluation is an error. The value of each expression in a module body is printed using alert compiled with ~v.

A module’s provided variables and macros are made available to other modules that import it. Variables and macros that are not provided are completely inaccessible outside of the module.

There are no phases in the sense of Racket. When zuo macro expansion encounters an import, it makes all of the imported module’s exports immediately available for use in macro implementations, both variables and macros. For example, an imported macro might be used both to implement a macro body and in nearby run-time code or even run-time code generated by the macro’s expansion. The absence of a phase separation is related to the way that each module is evaluated only once, and it’s made workable in part by the absence of mutable data structures in Zuo, and in part because there is no support for compiling a zuo module and saving it separate from its instantiation in a Zuo process or saved image.

Zuo macros consume a representation of syntax that uses plain pairs, numbers, strings, etc., but with an identifier syntax object potentially in place of a symbol. Even for symbols, using a syntax object is optional; by using quote-syntax to create a syntax object, a macro can generate a term with identifiers bound at the macro’s definition site, instead of a use site’s, but the macro expander does not impose or automate that binding. See quote-syntax for more information.

2.2 Binding and Control Forms🔗ℹ

A zuo syntactic form is either a definition form or an expression form. Expressions can appear in definition contexts, but not vice versa. In descriptions of syntactic forms body ...+ refers to a context that allows definition forms, but the last form in the expansion of the definition context must be an expression form.

2.2.1 Expression Forms🔗ℹ

A Zuo module’s representation starts with plain pairs and symbols, a macro procedure can receive terms containing plain symbols, and it can return a term with plain symbols. A symbol non-hygienically acquires a scope at the point where its binding is resolved or where it creates a binding.

A scope corresponds to a particular binding context. It can be a module context, an internal definition context, or a binding site for an expression form like the formals of a lambda or the right-hand side of a letrec.

An identifier syntax object created by quote-syntax closes over a binding at the point where it is created, closing over the enclosing module scope if the identifier is not (yet) bound. The closure does not change if the identifier is nested in a later quote-syntax form. Identifiers that are introduced by macros are not automatically given a scope or otherwise distinguished from identifiers that appeared as input to a macro, and a plain symbol is implicitly coerced to a syntax object only at the point where it binds or where its binding is resolved as a reference.

There is no quasisyntax, unsyntax, or unsyntax-splicing analog, since quasiquote, unquote, and unquote-splicing are already convenient enough for most purposes. To generate a fresh symbol for the output of a macro expansion, use string->uninterned-symbol.

2.2.2 Definition Forms🔗ℹ

If expr produces a context-consumer wrapper, then when id is used for a macro invocation, the wrapped procedure receives three arguments: the macro use as syntax, a function that acts like free-identifier=?, and either #f or an inferred-name string. (In racket, free-identifier=? and syntax-local-name are implicitly parameterized over the context of a macro invocation. Explicitly providing a comparison procedure and name string to a macro implementation, instead, avoids the implicit parameterization.)

See quote-syntax for more information about the representation of syntax that a macro function consumes and produces.

A submodule becomes a procedure of zero arguments that is a mapped from the symbol form of id in the enclosing module’s representation as a hash table (see Zuo Module Protocol). Calling the procedure evaluates the defn-or-expr content of the submodule, where expression results are printed and the procedure’s result is (void).

When Zuo loads a starting module (see Building and Running Zuo), it checks for a main submodule and runs it if one is found.

2.3 Booleans🔗ℹ

Zuo booleans are written #t or #true and #f or #false. Any value other than #f counts as true for conditionals.

2.4 Numbers🔗ℹ

A Zuo number corresponds to a 64-bit two’s complement representation with modular arithmetic (i.e., wraparound on overflow). It is always written in decimal form with a leading - for negative numbers.

Changed in version 1.9: Added remainder and changed modulo to match Racket.

2.5 Pairs and Lists🔗ℹ

Zuo pairs and lists work the same as in Racket with the same textual representation.

2.6 Strings🔗ℹ

Zuo strings are sequences of bytes.

See also file-sha256 and sha256-length.

2.7 Symbols🔗ℹ

Zuo symbols are interned by the reader, where two interned symbols are eq? when they have the same string content. An uninterned symbol is eq? only to itself. Zuo symbols are the only kind of value that can be used as a key for a Zuo hash table.

The textual representation of symbols does not include escapes for special character, unlike the way | works in Racket. Symbols with those characters will print in a way that cannot be read back into Zuo.

2.8 Hash Tables (Persistent Maps)🔗ℹ

Zuo hash tables do not actually have anything to do with hashing, but they’re called that for similarity to Racket. A hash table maps symbols to other values, and updating a hash table produces a new hash table (which, internally, may share with the original).

Hash tables print in a way analogous to Racket, but there is no reader support to convert the textual form back into a hash table value.

Besides being constrained to symbol keys, there are two additional differences:

• the third argument to hash-ref, when supplied, is always used as a value to return if a key is missing, as opposed to a failure thunk; and

• the hash-keys function returns interned keys sorted alphabetically.

2.9 Procedures🔗ℹ

2.10 Paths🔗ℹ

A path string is a string that is not empty and contains no null bytes.

The result path depends on whether base and path are relative or absolute:

• If both are relative, the result is always a relative path. If base starts with ".." elements that are not matched by path, then elements are drawn from (hash-ref (runtime-env) 'dir).

• If both are absolute, the result is absolute if base and path do not share a root element, otherwise the result is relative.

• If path is absolute and base is relative, path is returned as-is. The intent of this mode is to preserve the “absoluteness” of path in a setting that otherwise works in terms of relative paths.

• If base is absolute and path is relative, path is converted to absolute via path->complete-path, and the result is as when both are absolute (so, the result may still be absolute).

(lambda args

(apply build-path (cons (path-only (quote-module-path))

args)))

If the argument to the function is an absolute path, however, the enclosing module’s directory is ignored, and the function acts simply like build-path.

2.11 Opaque Records🔗ℹ

2.12 Variables🔗ℹ

A variable is a value with a name that contains another value. The contained value is initially undefined, and attempting to access the contained value before it’s set results in an error where the variable’s name is used in the error message. A variable’s contained value can be set only once.

2.13 Modules and Evaluation🔗ℹ

A module path is a path string or a symbol, where a symbol must contain only the letters A-Z, a-z, 0-9, -, +, _, or /. Furthermore, / in a symbol module path cannot be at the start, end, or adjacent to another /.

2.14 Void🔗ℹ

2.15 Reading and Writing Objects🔗ℹ

See also Zuo S-Expression Reader.

Unlike uninterned symbols in racket, Zuo uninterned symbols format in print and write styles with #<symbol:...>. Opaque objects, handles, and variables print with #<:...> notation in all styles.