9 Enforestation API🔗ℹ

9.1 Name Roots🔗ℹ

The transformer procedure proc takes an introducer funciton and a syntax list of terms and returns two values: a new head identifier or operator, and a syntax list of remaining terms. The introducer function corresponds to the space that is otherwise used to lookup identifiers, which the transformer procedure might take into account.

9.2 Operators🔗ℹ

The precs list is an association list from identifiers to 'stronger, 'weaker, 'same, 'same-on-left, or 'same-on-right, indicating that the operator’s precedence is stronger than, weaker than, or the same as (when on the indicated side of) the associated identifier; 'default can be used instead of an identifier to specify a default relationship.

The protocol is either 'macro for macro protocol or 'auto for automatic protocol.

The proc transformer procedure depends on the mode (prefix or infix) as well as the protocol for its arguments and results.

This structure type should not be used directly. Instead, use its subtypes prefix-operator and infix-operator.

If the protocol is 'auto, proc takes two arguments: a parsed right-hand form and the operator name, and returns a further parsed form.

If the protocol is 'macro, proc takes two arguments: a parsed left-hand form and a syntax list of terms consisting of all remaining terms (including the operator term) in the enclosing group, and returns two values: a parsed form, and a syntax list of remaining terms.

If the protocol is 'auto, proc takes three arguments: a parsed left-hand form, a parsed right-hand form, and the operator name, and returns a further parsed form.

9.3 Parameterized Enforestation🔗ℹ

The enforest-step name (defaulting to a fresh name) is bound to an enforest-step function that continues an enforestation. It takes two arguments: a syntax list of all remaining terms in a group and the current operator, and returns two values: a parsed form and a syntax list of remaining terms (starting with an infix operator that has lower precedence than the input operator).

The syntax-class name (defaulting to a fresh name) is bound to a syntax class (see define-syntax-class) that matches and enforests a group shrubbery representation. A match has a parsed attribute for the enforestation result.

The relative-precedence name, if present, is bound to a function that compares the precedence of two operators. The function takes four arguments: 'infix or 'prefix for the left operator’s mode, the left operator’s identifier, 'infix or 'prefix for the right operator’s mode, and the right operator’s identifier. The result is either 'stronger (left takes precedence), 'weaker (right takes precedence), or an error result: #f (no precedence relation), 'inconsistent-prec (inconsistent precedence), 'inconsistent-assoc (inconsistent associativity), 'same (same precedence but non-associativity), 'same-on-left (same precedence but on the wrong side), 'unbound (one of the operators is unbound).

The prefix-more-syntax-class and infix-more-syntax-class names (defaulting to fresh names) are bound to syntax classes that take an operator-name argument, and match and enforest a group that’s intended to represent the tail of a group. The enforestation is based on the precedence and associatvity of the given operator. A match has a parsed attribute for the enforestation result and a tail attribute for the remaining terms in a group.

The desc (defaulting to "form") and operator-desc (defaulting to "operator") strings are used in error reporting to refer to a form or an operator for a form.

The in-space function (defaulting to the identity function) takes an identifier syntax object and adds a space scope if the enforesting context uses a space.

The prefix-operator-ref (defaulting to prefix-operator-ref) and infix-operator-ref (defaulting to infix-operator-ref) functions take a compile-time value and extract an instance of prefix-operator or infix-operator, respectively, if the value has one suitable for the context, returning #f otherwise. Normally, these functions use structure-property accessors.

The name-path-op symbol (defaulting to '|.|) is an operator name that is (symbolically) recognized after a name-root identifier for hierarhical name references.

The name-root-ref function (defaulting to name-root-ref) takes a compile-time value and extracts an instance of name-root. The compile-time value is resolved from an identifier that is followed by an operator recognized by name-path-op.

The check-result function (defaulting to a function that checks whether its first argument is a syntax object, returning it as-is if so, raising an exception otherwise) takes an enforestation result and checks whether the result is suitable for the context. It should either raise an exception for earlier detection of errors or return its first argument (possibly adjusted). A second argument to the function is the procedure that produced the result, which can be used for error reporting (e.g., through object-name).

The make-identifier-form function (defaulting to the identity function) takes an identifier an produces a suitable parsed form. If a context does not have a meaning for unbound identifiers, a syntax error can be reported.

The make-operator-form function, if non-#f, takes an operator and produces a suitable parsed form. Absence or #f means that an error is reported for an unbound operator in an expression position.

The juxtapose-implicit-name symbol (defaulting to '#%juxtapose as described in Implicit Operators) is the name for the implicit infix operator between two immediately adjacent expressions.

The select-implicit-prefix function (defaulting to a function that selects implicit prefix operators as described in Implicit Operators) takes a term within a group that is not an operator and does not follow an infix operator. The result should be two values: a symbol as the name for the implicit prefix operator and a syntax object whose lexical context is added to the symbol to look up the operator binding.

The select-implicit-infix function (defaulting to a function that selects implicit infix operators as described in Implicit Operators) takes a term within a group that is not an operator and follows a parsed term. The result should be two values: a symbol as the name for the implicit infix operator and a syntax object whose lexical context is added to the symbol to look up the operator binding.

9.4 Prefix Transformers🔗ℹ

The desc string (defaulting to "form") is used in error reporting to refer to a form.

The transformer-ref function (defaulting to transformer-ref) takes a compile-time value and extracts an instance of transformer, if the value has one suitable for the context, returning #f otherwise. Normally, this function uses a structure-property accessor.

See define-enforest for the meanings of desc, name-path-op, name-root-ref, and check-result.