Skip to content
Weaverv0.5.0

Annotations and metadata

A revision of SPEC 5.3 (annotations), 5.2 (types are values) and 5.6 (field tags): annotations, @, keep transforming what they annotate, or not, and may attach metadata to it, typed values that meta code reads; transformations, #, read a declaration’s whole description, its members and the metadata attached to each. What weft/rest and weft/inject need, neither expressible today: a generator reading the methods of a contract and what their annotations say.

Status: settled; being implemented, step by step (HISTORY 388 on): metadata on types and functions, across modules too, the methods of a description, annotations on fields, variants, parameters and a contract’s methods, the short form, transformations and their phases, aliases and the whole program, done.

  • @f(args) calls meta fn f(target, args…), which transforms the annotated function, FnDecl, or adds declarations beside a type, Type. It sees that declaration alone.
  • #C declares a conformance to contract C, whose meta fn derive(t: Type): Decls writes it, for a record or an enum.
  • A field carries tags, `json(name: "id")`, values of a type declared @tag("json"), read by f.tag(JsonTag).
  • Meta code reads a type’s name, fields, variants, contracts, annotations, doc, and of the annotated function its name, params, result and body.

What it cannot do: read a contract’s methods; annotate a method without body, a parameter, a variant or its fields; know, from a generator, what another annotation said. weft/wake wrote @needs, @default and @alias as meta functions returning their function unchanged, and re-read the source to know what they said; #Xml could not take a tag on a variant’s field.

/// What `@get` records on a method.
type Get = { path: String }
meta fn get(m: FnDecl, path: String): FnDecl = m.addMetadata(Get{path})
  • A value of any type meta code can build, a record usually: Get, Route, JsonName. It is evaluated during the expansion, as an annotation’s arguments are: literals and meta expressions, not values of the program; a lazy argument stays an Expr, which a record field of type Expr holds.
  • Attached by an annotation: target.addMetadata(v) gives the declaration with v attached, which the meta fn returns, transformed or not. An annotation may attach several values, of one type or several.
  • Compile time only. Nothing of it reaches the program unless a transformation writes it there: a generator that wants the routes at run time writes a function returning them, C.routes().

An annotation is a meta fn whose first parameter is its target, as today, with more targets:

Target Parameter Annotated
A record, an enum, a contract, a namespace Type @a type T = …, @a pub contract C {…}, @a namespace N {…}
A function, a method, with or without body FnDecl @a fn f(…), a contract’s @a fn m(self)
A field of a record or of a variant Field x: Int @a, Paperback(pages: Int @a)
A variant Variant | @a Paperback(…)
A parameter Param fn f(@a name: String)
  • It returns its target, transformed or not, metadata added or not; a Type annotation may still return Decls added beside it.

  • The short form for an annotation that only records: a type declared @annotation, its fields the annotation’s parameters.

    @annotation
    type Get = { path: String }
    @get("/packages/{name}")
    fn show(self, name: String): Package ! RestError

    @get(…) attaches Get{path: …}, its name the type’s in camelCase, @annotation(name: "…") naming it otherwise; positional arguments follow the fields’ order, labeled ones their names, defaults as in a record literal. It may target what its declaration names, @annotation(on: [.method, .function]), any by default.

  • Field tags become metadata: `json(name: "id")` is the short form of an annotation on a field, f.tag(JsonTag) and f.metadata(JsonTag) the same; @tag("json") declares such an annotation, as @annotation does. The backtick form stays.

#X on a declaration calls X’s transformation with the declaration’s description: a contract’s derive, which declares the conformance the compiler then checks, as today; or a meta fn X(t: Type, …): Decls, a transformation that declares no conformance, which # may now name.

  • The description is what meta code reads of any declaration, each part with doc, annotations and metadata(T): T?, metadataAll(T): T[]:
    • a Type: as today, and methods, those of a contract, of a namespace, or a type’s own, each a Method;
    • a Method and an FnDecl: name, params, result, errors (the types of its !), hasBody, isStatic;
    • a Param: name, type, default, expr;
    • a Field and a Variant: as today.
  • Reached through types: the description of a field’s, a parameter’s or a result’s type is that type’s, its own metadata included, whichever module declares it. #Rest reads the metadata of the types its methods take: FromRequest adopted, a body type’s #Json.
  • Order: a module’s annotations apply before any of its transformations: for each declaration, its members first, then itself, each from the annotation nearest to it outward, as today. Its transformations then apply by phase, below, each seeing the metadata and the declarations those before it produced.
  • Across modules: a module’s metadata travels in its interface, as its types do, so that a module checked alone, by module, reads the metadata of what it imports.

A transformation declares when it runs, by @phase on its meta fn:

Phase For Examples
.early what generates declarations others read an ORM’s @repository, writing an implementation and its factory
.normal, the default what writes code from a declaration #Json, #Eq, #Rest
.late what reads what others produced in the module a list of a module’s routes
.program what reads the whole program, Build.annotated #Application
@phase(.early)
meta fn repository(t: Type, entity: Type): Decls = …
  • Across the module: every .early transformation of every declaration of a module applies before every .normal one, and so on; within a phase, in the order of the declarations, then of the annotations, as written.
  • after: [Json], @phase(.normal, after: [Json]), orders a transformation after another of its phase, wherever they are written: a dependency said rather than a number chosen. A cycle of after is an error.
  • Reading what comes later is an error: a transformation reading through a description the metadata or declarations a later phase will produce, an .early one reading what a .normal one adds, is refused, rather than seeing a part.
  • Across modules nothing changes: a module imported is expanded before the module importing it, its generated declarations in its interface.
  • .program runs in the program’s root module alone, the one holding main, after every other transformation of the program: the place of what reads it whole.

@implies(M(…)) on an annotation type, an annotation declared @annotation, makes it attach M too: its own value, and an M whose fields are filled from its own fields of the same names, the rest from what @implies gives.

@annotation
@implies(Injectable(scope: .singleton))
type Service = { name: String? }

@service(name: "mail") attaches Service{name: "mail"} and Injectable{name: "mail", scope: .singleton}: Spring’s stereotypes, a library’s annotation meaning another’s. An annotation written as a meta fn does the same with addMetadata.

Build.annotated(T) gives the types of the whole program carrying a metadata of type T, and Build.annotatedFunctions(T) its functions, each a Method, whether attached directly, through an alias, or by a transformation that generated them: each with its description, in a fixed order, by module then by name, the same whether a module is checked or read from its interface.

  • The program is every module of the main package, imported or not, as wv test takes them (allModules), and every module they import: an injectable declared in a module no other imports still counts. The build loads them all when a file it reaches declares a .program transformation, @phase(.program).
  • Read in .program only, where everything else has run; elsewhere an error, the program not being expanded yet.
  • By module, the root module reads the others’ metadata from their interfaces, as their types: nothing is checked again.

weft/wake’s annotations, which only recorded and could not say so:

@annotation
type Needs = { tasks: Expr }
@annotation
type Default = { }

weft/rest’s routes, which a transformation of the contract reads:

@annotation(on: [.method])
type Get = { path: String }
#Rest("/packages")
pub contract PackagesApi {
@get("/{name}")
fn show(self, name: String): Package ! RestError
}
meta fn Rest(t: Type, prefix: String): Decls {
val routes = t.methods.filter(m => m.metadata(Get).isSome())
return quote {
// the router, the client, `routes()`, from routes
}
}
  • SPEC 5.2, 5.3 and 5.6 rewritten from this draft; the grammar takes an annotation before a parameter, a variant, and after a field’s type.
  • weft/wake’s annotations become @annotation types, and wv-wake may read them through wv expand’s metadata rather than the syntax: kept as is until then.
  • #Xml takes tags on a variant’s fields.
  • Nothing written today stops working: @f transforming a function, #C deriving a contract, backtick tags.
  • Programs of compiler/testdata for each target, each short form, each reading of metadata through a type of another module, by module and whole; errors: an annotation on a target it does not take, a metadata value that is not a meta value, a transformation reading what an annotation applied after it would attach.
  • weft/rest and weft/inject written on it.
  1. Metadata at compile time only; a transformation writes what the program needs at run time.
  2. A short form, @annotation type, for an annotation that only records.
  3. Any meta code reads the metadata of what it reaches through a description, whichever module declares it.
  4. Metadata typed, values of any type meta code builds, attached by addMetadata, read by metadata(T) and metadataAll(T).
  5. Annotations on fields, variants, parameters and methods without body, the target given by the meta fn’s first parameter.
  6. Backtick tags kept, as the short form of a field’s metadata.
  7. # naming a transformation that declares no conformance.
  8. The order: annotations of members, then of the declaration, then the transformations in the order written.
  9. Transformations ordered by phase, .early, .normal, .late, .program, declared by the transformation; across the module, the written order within a phase, after: for a dependency.
  10. .program in the root module alone, after every other transformation; #Application one of them.
  11. @implies on an annotation type, an alias attaching another’s metadata.
  12. Build.annotated(T), in .program, over every module of the main package and those they import.