3 Xsmith Reference🔗ℹ

3.1 Stability🔗ℹ

Xsmith does not currently promise API stability between versions.

3.2 Auto-Generated attributes and choice-methods🔗ℹ

Many attributes and choice-methods are auto-generated by Xsmith:

attributes

• 'xsmith_is-hole?

  Accepts no arguments other than the node to call it on. Returns #t when called on a hole node, otherwise returns #f.

  Example:

  ; Within the context of a choice method, this will return #t

  (att-value 'xsmith_is-hole? (current-hole))

• 'xsmith_render-node

  Accepts no arguments other than the node to call it on. Defined by the render-node-info property.

  Example:

  (add-property

  my-spec-component

  render-node-info

  ; assuming we're outputting for a lispy language

  [AdditionExpression (λ (n) `(+ ,(att-value 'xsmith_render-node (ast-child 'l n))

  ,(att-value 'xsmith_render-node (ast-child 'r n))))])

• 'xsmith_find-descendants

  Accepts the node to call it on, then a predicate. Returns a list of all descendant nodes that satisfy the predicate.

  Example:

  ; This will return a list of all addition and subtraction nodes.

  ; It will not return any nodes that are subtypes, though!

  (att-value 'xsmith_find-descendants ast-node (λ (n) (member (ast-node-type n)

  '(AdditionExpression

  SubtractionExpression))))

• 'xsmith_find-a-descendant

  Accepts the node to call it on, then a predicate. Like 'xsmith_find-descendants, but it only returns one. If no descendant matching the predicate is found, it returns #f. It is mostly useful if you just want to know if there is any descendant matching a type, such as to determine whether to do an analysis based on the presence or absence of some feature.

• 'xsmith_binding Accepts the node to call it on and optionally a boolean require-binder-or-reference flag (defaults to #t). If the given node is a reference, as determined by the reference-info property, then the reference is resolved and a binding object is returned. If the given node is a binder, as determined by the binder-info property, then its binding object is returned. For any other node, #f is returned when require-binder-or-reference is false, otherwise an error is raised.

  Example:

  ; This raises an exception if `n` is not a binder or reference.

  (att-value 'xsmith_binding n)

  ; If `n` is not a binder or a reference, return #f.

  (att-value 'xsmith_binding n #f)

  The main use of this is to do analyses where you need to look up the declaration node that a reference refers to. The binding? object returned by this function contains a reference to the binder node. When resolving references, the scope graph model is used.

• 'xsmith_ast-depth

  Accepts the node it is called on, and no other arguments. Returns the tree depth at that node. Determined by depth-increase.

  Example:

  (att-value 'xsmith_ast-depth n)

  Related: xsmith-max-depth

• 'xsmith_type This attribute takes no arguments (besides a RACR node) and returns the type (type?) of that node. Note that the type of the node may be a not-yet-concretized type variable.

  (att-value 'xsmith_type n)

choice-methods

• 'xsmith_get-reference! This is a choice method that can be used when creating a reference node. It uses reference-choice-info to choose a reference. The default value of reference-choice-info will cause a fresh appropriate definition to be lifted if none exists. If no reference can be made (due to a non-default reference-choice-info), #f will be returned. Otherwise, it returns a binding? of the reference, which you can use binding-name on.

  Example:

  (att-value 'xsmith_type (current-hole)) ; -> (fresh-type-variable int bool)

  ; This will return the name of a variable in scope

  ; that has type int or type bool.

  ; It may make a new definition node to do that.

  (define name (binding-name (send this xsmith_get-reference!)))

  Note that the reference is choosing one of the possible types (via concretize-type). Probably you are using this in a fresh method to initialize a node. So you will want to put that name in the node.

  Generally you don’t need to do this manually, however. Nodes with the reference-info property marked will automatically have their name fields initialized, and nodes with the binder-info property marked will automatically have their name and type fields initialized.

• 'xsmith_get-reference-for-child! This is a choice method that can be used when creating reference nodes for children during the fresh rule. It takes two additional parameters:

  • type: settled-type? - the type you want the reference to be. Note that it must be a settled type. If you want this type to be based somehow on the type of the node in question, use force-type-exploration-for-node! so the node’s type will be maximally concretely computed before you concretize it.

  • write-reference?: boolean? - whether the reference will be used as a write reference.

  It returns a binding? of the reference or #f if none can be made (due to a non-default reference-choice-info).

  Example:

  ; This will return the name of a variable in scope

  ; with type int for a write reference

  (define name (binding-name (send this xsmith_get-reference-for-child! int #t)))

  Like xsmith_get-reference!, it may cause a new definition to be lifted. Only use the result for children of the current-hole.

Node type names, attribute names, and choice-method names are just symbols, so they are not hygienic. The names of symbols used or defined by the xsmith library start with xsmith or _xsmith, so don’t tread on those namespaces.

3.3 Forms for Defining a Grammar and Its Attributes🔗ℹ

The fuzzer name defaults to the name of the first spec component provided. The command-line function is named the id passed to #:command-line-name, defaulting to <fuzzer-name>-command-line with <fuzzer-name> replaced appropriately. The command-line function takes no arguments and parses current-command-line-arguments.

#:comment-wrap takes a list of strings which contain info about the generated program, such as the command line used to generate it, the #:fuzzer-name, the #:fuzzer-version, and the random seed number. It should return a string representing those lines commented out. Such as the following, assuming the # character is the line-comment character in your language:

(λ (lines)

(string-join

(map (λ (x) (format "# ~a" x)) lines)

"\n"))

fuzzer-version takes a string describing the version of the current fuzzer, used in automatically-generated output.

#:format-render is a function which takes the output of your render-node-info property as input and should return a string representing the program (perhaps by use of a pretty-printing function). If your render-node-info property produces a string already, you will not need to specify the #:format-render argument.

The #:default-max-depth sets the “max” tree depth generated. It’s a bit of a fib – there are situations where Xsmith will allow deeper generation, but they are limited. See xsmith-max-depth. Similarly the #:default-type-max-depth sets the maximum depth that will be used for type concretization. In other words, when a type variable is concretized it will only choose base types past that depth. However, deeper types can still be made through other means.

The #:type-thunks argument should be a list or thunk that returns a list of thunks that return a type. I.e. (listof (-> type?)) or (-> (listof (-> type?))). However, #f may be returned instead of a thunk or instead of a type to filter out a given type in some situations.

The #:features argument takes a list of lists containing a feature name (as an identifier) and a default value (as a boolean), and optionally a list of documentation strings. Each feature will be included in the command-line options as --with-<feature-name>. Documentation strings will be displayed in the --help text, one per line. The values of these features is available via xsmith-feature-enabled?.

#:extra-parameters is a list of specifications for extra custom command line parameters. Each list contains an identifier to be used as the name of the parameter (e.g. for use in the command-line interface), a documentation string, a parameter, and a normalization function (or #f). The normalization function should take the string given on the command line and convert it to the value that is actually parameterized during program generation. The following example defines a --max-widgets parameter with a default of 3:

(define widget-parameter

(make-parameter 3))

...

(define-xsmith-interface-functions

...

#:extra-parameters ([max-widgets

"The maximum number of widgets"

widget-parameter

string->number]))

Various attributes are automatically defined within the spec, see Auto-Generated attributes and choice-methods.

Properties (defined with define-property) are used to derive more RACR attributes as well as Xsmith choice-methods, and extra properties can be used in your fuzzer by adding them with #:properties. Each property may have a transformer function that alters other properties, attributes, or choice-methods. All properties referenced within a spec-component are used to generate attributes and choice-methods, as well as any properties specified in the maybe-properties list. Unless values for that property have also been specified within a spec component, properties in the #:properties list will only be able to generate rules based on the default value for the property. Note that any property that has a value attached to a node in the grammar will be run, but if you have defined custom properties that don’t have values attached you may need to add the properties to this list. In other words, if you have a property that defines an attribute on the default node without attaching a value to any node, you need to add it here or the attribute won’t actually be added.

Names in the grammar productions are limited to alphabetic characters, but there could be additional restrictions. In particular:

• node-name (and hence parent-name and type-name if provided) must begin with an uppercase letter. E.g., LiteralInt

• If type-name is provided, then the field name name/type-id has no other restrictions. E.g., sideEs

• If type-name is not provided and the field name name/type-id is a type, then name/type-id must follow the restriction for node name. I.e., it must begin with an uppercase letter.

• If type-name is not provided and the field name name/type-id is not a type (i.e., it is a terminal), then name/type-id must consist of only lowercase letters. E.g., value

Due to the alphabetic character limitation, kebab-style or snake_style names are invalid. Depending on the restriction, you may want to use alllowercase, camelCase, or PascalCase style names.

node-name will be the name of the grammar production in RACR. parent-name is either the name of the parent grammar production or #f.

Fields are then specified. Each nonterminal inherits all fields of its parent nodes. A field has a name, a type, an optional kleene star, and an optional initialization expression. The type of each field is the name of the nonterminal that it must be or #f for fields that may contain arbitrary Racket values. A field name may be the same as the type, in which case the type does not need to be specified. If a type is not specified and the name does not match the name of a nonterminal, then the type #f is used. If the optional kleene star is supplied, the field will be a list field. If a kleene star is provided for a non-false type, the name and type must be specified separately.

The init-expr for each field specifies a default value for the field. When a node is generated, each init-expr is evaluated unless a non-default value is supplied to the generating function. If no init-expr is supplied, the following defaults are used:

• For false types, #f.

• For nonterminal types, a hole node of the appropriate type.

• For fields with a kleene star, an empty list.

For nodes with a kleene star, init-expr may return a list or a number. If a number is provided, the default value is a list of that many of the non-kleene-star default value.

The example defines a piece of a grammar that includes some kinds of expressions. When a LiteralInt expression is generated, it’s v field will be populated with a random number. Since the random expression is evaluated for each fresh LiteralInt, they will (probably) receive different values for v. When an AditionExpression node is generated, it will be populated with an Expression hole node for each of its left and right fields. When a fresh SumExpression is generated, its addends field will be populated with a list of zero to four Expression hole nodes.

Xsmith creates a choice object class for each node type in the specification grammar, following the same class hierarchy that AST nodes themselves do. Choice objects are created every time Xsmith fills in a hole node. One choice object is created for every node type that is legal to use in filling the hole. Choice objects are then filtered according to the choice-filters-to-apply property, and then the choice-weight property of the remaining choice objects is used to determine the probability of choosing each one. When a choice object is selected, its fresh property is used to generate a new AST node of its type. If all choices are eliminated, an exception is raised with a message stating which filter step invalidated each potential choice.

Choice-methods are methods on the choice objects. Some choice-methods are used by choice-filters-to-apply to filter choices. Other choice-methods may be used by those filters or in the body of the fresh property as helper methods. While most information about the AST and the current choice are probably computed using attributes, information about choosing a specific node type to fill in an abstract hole (such as an expression hole which may be filled with many different types of expressions) are computed using choice-methods.

Choice-methods are methods in Racket’s class system and therefore have the this macro available for use in their bodies to access other methods (e.g. with the send macro). Choice-methods also have the current-hole macro available within their body so that they can query attributes of the RACR AST being elaborated (e.g. with att-value to access attributes and ast-parent to inspect other nodes in the AST).

Since choice-methods are methods in Racket’s class system, they must be defined with a literal lambda (with no parameter for the implicit this argument). If a method needs to modify state (such as to cache the computation of available references of the appropriate type), I would normally recommend the “let-over-lambda” pattern, but that is not allowed in this case. To make up for this, I recommend using make-weak-hasheq to hold the state, using the this object as a key.

Since property transformers are macros that may accept arbitrary domain-specific syntax, the grammar of prop-value varies for each property.

Elsewhere it raises a syntax error.

This function is essentially used by add-to-grammar as the default value for grammar fields with nonterminal types that lack an init-expr.

Outside of a spec component context, it raises a syntax error.

Note that the fresh node is initially created unattached to the rest of the program tree. This means that any nodes whose fresh implementation needs to inspect the tree may fail. In particular, reference nodes can only lift bindings when attached to the tree, and will probably fail if created with make-fresh-node.

3.4 Custom Properties🔗ℹ

Properties are used to create domain-specific languages or terse declarative syntax for specifying attributes and choice-methods. Custom properties are probably only useful for shared infrastructure for multiple languages (perhaps with the exception of define-non-inheriting-rule-property).

Properties can have a transformer function that produce attributes, choice-methods, or other property values. Property transformers can read the values set for the property by add-property, and optionally the values of other properties as well. Not all properties must have a transformer – some properties may just be a single place to store information that is used by (multiple) other properties.

The transformer function accepts a dictionary mapping grammar node names (as symbols) to the syntax objects from the right-hand-side of add-property uses for each property that it reads. The transformer function must return a list of dictionaries mapping grammar node names (as symbols) to syntax objects for the properties, attributes, and choice-methods that it writes.

Property transformers are run during define-xsmith-interface-functions in an order determined by the read/write dependencies among the properties. Appending goes before rewriting, which goes before reading.

If a property appends (using the #:appends keyword) to a property or rule, its return dictionary will be appended to the existing dictionary for that property/rule. This allows a property or rule to be specified in part by the property that appends and in part by another property or the user. If an appended rule (or property that disallows multiple values) ends up with two values for any node, an error is raised.

If a property rewrites (using the #:rewrites keyword) to a property or rule, its return dictionary replaces any previous dictionary for that property/rule. Rewriting a property also automatically implies reading that property. A property or rule may only be rewritten by one property transformer.

The syntax object value for a property can be anything, since property transformers define the grammar and semantics of properties.

The syntax object value for attributes and choice-methods should be a syntax object specifying a function (i.e. a lambda). attributes may be any syntax that evaluates to a function (so you may return an identifier that references a function or an expression that computes a function such as let-over-lambda), but choice-method syntax is provided to Racket’s class macro, which requires literal lambda forms.

Dictionaries may or may not contain an entry for each nonterminal in the grammar. A dictionary may even be empty.

In addition to nonterminals, each dictionary may include a mapping for the value #f, which will define a default value used for the (super secret) parent node that define-xsmith-interface-functions defines. If nothing is specified for #f, attributes and choice-methods will have a default which errors, providing a helpful error message.

If the #:allow-duplicates? argument is supplied and is #t, then add-property may be used more than once for the property for the same node, and the syntax object in the dictionary for the property will be a syntax list of the syntax objects specified in the various add-property calls. But by default only one use of add-property is allowed per property per node type, and the syntax object in the dict is the single syntax object from the one call.

Here is a simple example that basically desugars straight to an attribute with a default:

(define-property strict-child-order?

#:appends (attribute xsmith_strict-child-order?)

#:transformer

(λ (this-prop-info)

(define xsmith_strict-child-order?-info

(hash-set

(for/hash ([(n v) (in-dict this-prop-info)])

(values n (syntax-parse v [b:boolean #'(λ (n) b)])))

#f #'(λ (n) #f)))

(list xsmith_strict-child-order?-info)))

For more realistic examples of properties, see the file private/core-properties.rkt in the Xsmith implementation. Generally they are big, hairy macros.

Defines a property that generates an attribute or choice-method according to rule-type. The optional #:default value will be associated with the implicit #f node (and thus be inherited by other nodes unless overrided). The default is given as literal syntax (i.e., no hash-quote or syntax form needed). The optional transformer should be a syntax parser, or in other words, it must be a function from a syntax object to a syntax object. The default transformer is the identity function, meaning the rule is written verbatim. Note that using the default transformer means there is little reason to use a property, since you can just use add-attribute or add-choice-method directly instead.

By default the name of the generated attribute or choice-method is the same as the name of the property, but this may be overrided by providing #:rule-name.

rule-type must be either attribute or choice-method.

rule-name defaults to property-name, but you can make it give the rule a different name than the property.

default-expr is the default value of the property. Any nonterminal that does not have a different value specified gets this one. Note that the default is required, not optional, despite being a keyword argument.

transformer-func is an optional transformer to transform the value. It is not called with a dictionary like the transformers of define-property, but rather it receives each value individually. This allows a small amount of sugar. Note that the value supplied as the default-expr is also transformed by the transformer-func when it is supplied. When no transformer-func is supplied, values are passed through literally.

Normally B would inherit a method from A when none was specified for it. But in this case it inherits the default (#f). When a user tries (att-value 'some-bool-flag <node-of-type-B>) it will return #f, not #t.

3.5 Refiners🔗ℹ

Xsmith supports iterative refinement, which is a technique that allows for the modification of an existing AST. There are no default refiners, and their use is entirely optional. You might use a refiner to handle simplifications due to a post-generation analysis, such as using native mathematical operations instead of a specialized library when it has been proven that such operations will not produce unsafe results.

Refiners can have an order imposed on them if so desired. You can specify the #:follows parameter, which accepts either a refiner name or a list of refiner names. All refiners will be sorted based on these #:follows declarations, and executed in the order determined.

If you want to predicate the execution of a refiner itself, you can use the #:refiner-predicate parameter. This parameter accepts a single function that, if given, will be run prior to attempting to run the refiner at all. If it returns anything other than #f, the refiner will be run. The function should be a thunk (i.e., it should accept zero arguments). This is useful if you wish to have a refiner toggled on or off by a command-line argument.

Additionally, you may wish to have some predicate shared among all clauses of a refiner. The #:global-predicate parameter allows for this. Similar to #:refiner-predicate, #:global-predicate accepts a single predicate function as argument. This function will be prepended to the list of functions for each clause.

The refiner-clauses are similar to those used by the add-property (and similar) functions. One key difference with refiners is that there is always a #f clause given. (The default implementation of this clause if omitted by the user is [(λ (n) #f)], which means the refiner has no effect for any node which does not have a matching clause defined.) The predicate defined by #:global-predicate (if present) will not ever be applied to the #f clause. This means that if you want its functionality to be applied to nodes which do not have matching clauses, you will need to use it in a custom #f clause.

(define-spec-component arith)

(add-to-grammar

arith

; ...

[ArithOrVal #f ()]  ; This simplifies choices for generation.

[Val ArithOrVal ([v = (random -100 100)])]  ; Integer values on the specified

; interval (-100, 100).

[ArithOp ArithOrVal ([lhs : ArithOrVal]    ; Arithmetic operations have a

[rhs : ArithOrVal])]  ; left-hand side and a right-hand

; side, which can be either a value

; or another arithmetic operation.

[AddOp ArithOp ()]  ; +

[SubOp ArithOp ()]  ; -

[MulOp ArithOp ()]  ; *

[DivOp ArithOp ()]  ; /

[ModOp ArithOp ()]  ; %

; ...)

; ... (more code here)

(define-refiner

arith

make-even

; This refiner makes all literal integer values into even values by

; incrementing them by 1. The `#:refiner-predicate` parameter says that it

; will only be run when the `make-even` feature is enabled. This does

; require the make-even feature to be defined in the `define-xsmith-interface-functions`

; macro.

#:refiner-predicate (λ () (xsmith-feature-enabled? 'make-even))

[Val [(λ (n) (odd? (ast-child 'v n)))

(λ (n) (make-replacement-node

'Val

n

(hash 'v (+ 1 (ast-child 'v n)))))]])

(define-refiner

arith

replace-rhs-val-with-zero

; The `replace-rhs-val-with-zero` refiner looks at the right-hand side of

; every ArithOp to see if it's a Val. If it is, its internal value will

; be replaced with 0.

#:global-predicate (λ (n) (node-subtype? (ast-child 'rhs n) 'Val))

[ArithOp [(make-replacement-node

(node-type n)

n

(hash 'rhs (make-fresh-node

'Val

(hash 'v 0))))]])

(define-refiner

arith

prevent-divide-by-zero

; To prevent divide-by-zero errors, this refiner looks for generated

; DivOps and checks whether their right-hand side is a 0. If it is, it

; is replaced with a 13.

#:follows replace-rhs-val-with-zero

#:refiner-predicate (λ () (xsmith-feature-enabled? 'prevent-divide-by-zero))

[DivOp [(λ (n) (node-subtype? (ast-child 'rhs n) 'Val))

(λ (n) (eq? 0 (ast-child 'v (ast-child 'rhs n))))

(λ (n) (make-replacement-node

'DivOp

n

(hash 'rhs (make-fresh-node

'Val

(hash 'v 13)))))]])

; ... (more code here)

(define-xsmith-interface-functions

[arith]

; ... (other options specified here as needed)

#:features ([make-even #f]

[prevent-divide-by-zero #t]))

A new-node-type must be given, which is a symbol corresponding to a node type in the grammar. Then, original-node is the node which is being replaced. The new node will completely take the place of the old node; there will no longer be any references to original-node in the AST. Additionally, all children of the original-node will be copied to the new node except those replaced by the children hash. This is simply a hash of child names to values, just like in make-fresh-node.

(define-refiner

my-spec-component

replace-plus-with-minus

[PlusOp [(λ (n) (make-replacement-node 'MinusOp n))]])

Note that make-replacement-node should only be used in the bodies of refiner functions! If a replacement is made but the refiner fails for some other reason (i.e., it returns #f), the replacement will be undone.

3.6 Scope Graph Functions🔗ℹ

This section describes the API to the Scope Graph model of binding.

Notably this is returned by the attribute xsmith_binding.

The ast-node field is the grammar node containing the definition of name. The def-or-param field is there to distinguish names that are bound as function parameters vs names that are bound as (local or global) definitions.

Probably all you need to do with this, though, is get the name field and stuff it in the name field of your definition nodes in the fresh method.

When the xsmith_binding attribute is used or when Xsmith searches for a valid reference with xsmith_get-reference, this regexp determines valid scope-graph resolution paths. The path elements (reference, parent, import, definition) are turned into characters (r, p, i, and d respectively). If the path from reference to definition matches this regexp, it is valid. If two definitions have the same name and paths from a reference to both definitions are valid, the definition that is in scope for the reference is determined by current-path-greater-than.

Because Xsmith doesn’t currently support import elements at all, modifying this regexp is somewhat of a moot point.

By default the comparator walks down the paths, comparing each element. A path is greater than another if its first differing element is greater. From least to greatest, path elements are 'reference, 'parent, 'import, 'declaration.

For most languages you probably don’t need to fuss with this.

3.7 Core Properties🔗ℹ

These properties are available for specification on Xsmith grammars. Many of them define or modify the behavior of core functionality, such as fresh modifying how fresh program nodes are instantiated, or type-info defining a language’s type rules.

Many are optional, but for any language at all you probably need to use type-info and may-be-generated. Additionally, for any language with variables you need binder-info and reference-info. Next, the fresh property will likely become necessary for a few fields that Xsmith can’t infer. Then the most important of the truly optional properties is likely choice-weight.

If may-be-generated is false, the node is not added to the list of possibile choices to replace an appropriate AST hole. It is useful to set it to false for abstract node types or for specialized node types that are meant to be swapped in only after a full tree is generated, such as by a later analysis to determine validity of an unsafe operation. This property is NOT inherited by subclasses.

The property is two armed. The first arm specifies the type(s) that a node can inhabit, and its value is unify!-ed with the node’s type during type checking. The second arm specifies a relationship between a parent node and its children. Children nodes are allowed to be subtypes of the type specified by their parent, so a node’s type is subtype-unify!-ed with the type specified by its parent during type checking.

The first part is the type (or partially-constrained type variable) that the given node can inhabit. The expression given is evaluated fresh every time a node is type checked or considered for generation. When determining the type of a node, this value is unify!-ed with this value.

Additionally, the expression for a node’s type constraint may be a function that takes the node and returns a type instead of a type directly. However, the function may be passed a hole node that does not yet have properly populated fields and that may be a supertype of the node type you are defining the constraint for. So if you use a function here, you need to check the node with (att-value 'xsmith_is-hole? node)

The second part is a function that takes a node, its type, and must return a dictionary mapping its children nodes to types. The dictionary keys may be the node objects of the node’s children OR the symbol of the field name the child inhabits. The values in the hash may be types or functions from node to type. For kleene-star children, if they are all supposed to have the same type, it is convenient to use the field name as the key. However, if a kleene-star child needs a different type for each element of the list, you should use the nodes themselves as keys or use a function as dictionary value.

If the typing function makes any decisions about the type of the parent node when deciding the type of the child nodes, the decision needs to be reflected by either some unification with the child node types, construction/deconstruction using the parent type, or by saving the decision in the parent node and unifying with it in future passes. Here’s an example of a subtly broken type rule:

(add-to-grammar

my-spec-component

[Convert Expression (Expression)])

(add-property

my-spec-component

type-info

[Convert [(fresh-type-variable int float)

(λ (n t)

(cond

; Don't do this.

[(can-unify? t int) (hash 'Expression float)]

[(can-unify? t float) (hash 'Expression int)]))]])

This example uses the input type to determine an output type, and in fact makes a decision about what the input type is. But this decision isn’t saved. The problem is that t could be a concrete int, a concrete float, or it could be a type variable that could be unified with either! In the first two cases this type rule is fine, but in the third case it will effectively decide that the type is an int, and generate a float child expression. Because it doesn’t unify and save this decision, generation in another branch of code could then unify the variable with float, which would then cause a type error when this type function is re-run.

Note that the complexity of the Convert example arises because the input type has a relationship with the output type that can’t be expressed in terms of a construction, decomposition, or unification of types.

Acceptable values for this property are expressions which produce a dict? object, or expressions which produce a function of type (-> dict? dict?). Keys of the dictionary must be field names of the node being generated. The values in the dictionary are used to fill node fields of the appropriate name. Any field whose name is not in the dictionary will be filled by evaluating the default init-expr defined in the grammar (via add-to-grammar).

This is useful for fields that must be determined together. For example, a function call needs the function name and the number of arguments to be chosen together rather than independently.

As with all choice-methods, this and current-hole are available for use in expressions, which you may want to do for e.g. accessing available bindings or mutable information connected to the choice object.

If the result is a procedure instead of a dictionary, that procedure must accept and return a dictionary. It is called with a dictionary that is empty unless the node being created is the result of lifting a definition. In that case it will have the appropriate name and type fields with the name and type chosen by the lifting mechanism. In the case of lifting a definition, the name and type fields in the return dictionary are ignored. This procedure option is allowed because your fresh expression may need access to the name or type to determine the values of other fields. If a definition node only has a name and type field then a fresh property is unnecessary when lifting, and if lifting is the only way you generate definitions then fresh properties or initializers for definition nodes are unnecessary.

If the value for a field (i.e. values inside the result dictionary) is a procedure, it will be called with 0 arguments. This allows the fresh property to provide a default value that is not evaluated when make-fresh-node is called with an appropriate value.

The expression provided as the choice weight will be evaluated in the context of a method call, so this and current-hole are available.

Choice weights should be positive integer values. The default weight is 10 unless set explicitly. Alternatively, you can specify a function that takes the node (i.e. the current hole) and returns a weight.

The property accepts an expression which much evaluate to a function of one argument (the RACR AST node) which returns an integer for the depth increase. The default is (λ (n) 1). This property is NOT inherited by subclasses.

This is useful to allow node re-use. For example, the body of an if or for statement might be a block and have the same semantics, but you might want a block inside an if to only be considered a depth increase of 1, not 2.

If you have types that don’t have atomic constructors, you need to set wont-over-deepen to true for its basic constructor. The easiest example of this is functions – lambda nodes have at least one interior expression, and thus are not automatically recognized to be atomic values that can be used at maximum tree depth. If xsmith gets into a position where it needs a function type but it’s already at max depth and lambda is not marked #t for wont-over-deepen, xsmith with likely crash.

In other words, this is a property that lets xsmith fudge on its xsmith-max-depth settings, but you need it sometimes.

Note that for a basic definition with default name fields, the property need only contain an empty list to mark that the node is in fact a binder.

• The identifier read or the identifier write, indicating whether the reference reads or writes the variable

• (Optional) #:name-field: The name of the field that stores the reference name (as an identifier). Defaults to name.

• (Optionaly) #:unifies: Accepts the name of a field that the type checker unifies with respect to. The default value, #t, unifies the node itself instead of one of its fields. Use #f to disable automated unification for this node. (If you disable unification, you should implement your own manually!)

  If you give a field for the unification target, that field’s type rule must NOT depend on the parent node’s type. Essentially, the #:unifies argument is meant for writes to any type in a node that itself has type void.

See Lifting.

The function must return one of the options, the symbol 'lift to lift a fresh definition, or #f. If it returns #f, then you can’t have a reference there, in which case you need to be sure you have other non-reference nodes available to fulfill that type. The default doesn’t ever return #f. The default value biases towards choosing parameters over definitions and lexically closer bindings over far ones.

You can give different values to different nodes, but a default on #f is probably good enough?

Each of 'serial, 'parallel, and 'recursive allow all non-binder children to see the bindings provided by all binder children, and differ only in how the right-hand side of the binder nodes see the binders. The 'serial/all flag is like 'serial, but each node can only see bindings in nodes declared before them in the grammar spec. The 'serial/all flag is useful for creating nodes whose non-binder children see different subsets of the binder nodes.

If the property is not specified, 'serial is assumed and used as a default.

Setting this property is unnecessary, but using it allows more liberal use of references, mutation, and io effects.

The property takes a list of either the identifier read or the identifier write, then an expression for the key for the kind of mutable container. The key can be anything, but it needs to be eq? for each access of the same container type and not eq? for accesses to different container types. E.g., you could use the type constructor, or just a symbol for the name of the type.