Reference

substitute_top_level(var, val, mod, expr)

Takes a syntax object expr and substitutes every occurence of module var for val, only if the resulting object is actually present in module mod. The mod module should correspond with a lookup of val in the caller's namespace.

@compose module Name
    [@mixin Parents, ...]
    ...
end

Creates a new composable module Name. Structs inside this module are merged with those of the same name in Parents.

@for_each(M -> M.method(), lst::Vector{Symbol})

Calls method() for each module in lst that actually implements that method. Here lst should be a vector of symbols that are all in the current module's namespace.

pass(x::CompositePass, expr)

Tries all passes in a composite pass in order, and returns with the first that succeeds (i.e. doesn't return no_match). You may create a CompositePass by adding passes with the + operator.

pass(x::Pass, expr)

Interface. An implementation of the pass function should take a Pass object and an expression (or symbol), and return no_match if the expression did not match the pattern.

You can use the given Pass object to store information about this pass, return syntax that should replace the current expression, or nothing if it should be removed.

walk(x::Pass, expr_list)

Calls MacroTools.prewalk with the given Pass. If no_match is returned, the expression stays untouched.

@spec module *name*
    *body*...
end

Create a spec. The @spec macro itself doesn't perform any operations other than creating a module and storing its own AST as const *name*.AST.

This macro is only here for teaching purposes.

eval_to_expression(mod::Module, obj)

Generic function for converting syntax data objects to expressions, where parts of expressions need to be evaluated in a given module.

Defaults to calling to_expression, dropping the mod argument.

eval_to_expression(mod::Module)

Currying version of eval_to_expression.

Get name attribute from syntax data object.

strip_syntax_version(expr)

From Julia 1.14, a module expression may carry the syntax version of the code it was parsed from as its first argument: Expr(:module, v"1.14.0", true, name, body). Whether it does depends on the project the code lives in, not on the Julia version alone. Remove the version, so that @capture patterns of the form module name_ body__ end match either way.

Generic function for converting syntax data objects to expressions.

Composite{T, R}(; kwargs...)

Construct a composite from flat keyword arguments. Each keyword goes to the part that has a field of that name.

Composite{T <: Tuple, R <: Tuple}

A value composed of parts, one per component. Properties are forwarded to the part that has a field of that name, so c.x works for any field x of any part. R is a tuple of RoleMap markers, recording which part fills each role.

RoleMap{R, i}

Marker type: role R is filled by part i of a composite.

closure(roots::Module...)

Compute all components needed by roots, in dependency order (dependencies first), each component appearing once. Roles are resolved to a component implementing them: one of the roots if any, otherwise default_implementation.

component(c::Composite, ::Val{M})
component(c::Composite, M::Module)
component(c::Composite, T::Type)

The part of c contributed by component M, the part of type T, or, if T is a role (an abstract type), the part contributed by the component that implements T. Pass a module as Val(M) for a type-stable lookup.

default_implementation(R::Type)

The component (module) used to fill role R if no component implementing R is selected explicitly.

implements(::Val{M}, R::Type)

Whether component M fills role R. Defaults to false.

map_components(f, c::Composite)

Apply f to every part of c and compose the results that aren't nothing.

record_part(M::Module, name::Symbol)

The part that component M contributes to record name: the type M.name if M defines it, otherwise nothing.

record_type(name::Symbol, roots::Module...)

The Composite type of record name, for the closure of roots. It has one part for every component that defines a type name, in dependency order.

requires(::Val{M})

The components (modules) or roles (abstract types) that component M depends on. Extend this for every component that has dependencies.

resolve(R, roots)

The component that fills requirement R. A module is a component and resolves to itself. A role resolves to the one component in roots that implements it, or else to its default_implementation.

type_parameter_names(T)

The names of the type parameters of a UnionAll type, in order.

check_declaration(x, valid, declaration, name)

Check that x, named name in declaration, is an instance of valid.

declaration(expr)

If expr is one of the declarations @mixin, @requires or @implements, return the declaration name and its arguments. Otherwise return nothing. Arguments may be separated by spaces or by commas.

field_types(struct_expr)

The declared types of the fields of a struct.

map_struct(f, expr)

Apply f to the struct definition in expr, looking through macro calls like @kwdef and docstrings. Returns expr unchanged if it doesn't define a struct.

mentioned(names, expr)

The elements of names that occur as a symbol anywhere in expr, in the order of names.

parameterize(expr, struct_names)

Rewrite the struct defined in expr (if any), so that every other struct in struct_names that is mentioned in a field type becomes a type parameter.

struct_name(expr)

The name of the struct defined by expr, or nothing.

@component module Name
    [@mixin Components...]
    [@requires Requirements...]
    [@implements Roles...]
    ...
end

Define a component module. The declarations expand into methods of ModuleMixins.Procedural:

• @mixin A, B: import A and B from the parent module (if they are plain names), and require them as components.
• @requires R: require role or component R.
• @implements R: the component implements role R.

If a field type of a struct mentions another struct S of the same module, the struct gets a type parameter S, which record_type fills with the composite of all parts of record S.

@implements Roles...

Declaration inside a @component module. See @component.

@mixin Components...

Declaration inside a @component module. See @component.

@requires Requirements...

Declaration inside a @component module. See @component.