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)callsmeta fn f(target, args…), which transforms the annotated function,FnDecl, or adds declarations beside a type,Type. It sees that declaration alone.#Cdeclares a conformance to contract C, whosemeta fn derive(t: Type): Declswrites it, for a record or an enum.- A field carries tags,
`json(name: "id")`, values of a type declared@tag("json"), read byf.tag(JsonTag). - Meta code reads a type’s
name,fields,variants,contracts,annotations,doc, and of the annotated function itsname,params,resultandbody.
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.
Metadata
Section titled “Metadata”/// 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; alazyargument stays anExpr, which a record field of typeExprholds. - 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().
Annotations
Section titled “Annotations”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
Typeannotation may still returnDeclsadded beside it. -
The short form for an annotation that only records: a type declared
@annotation, its fields the annotation’s parameters.@annotationtype Get = { path: String }@get("/packages/{name}")fn show(self, name: String): Package ! RestError@get(…)attachesGet{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)andf.metadata(JsonTag)the same;@tag("json")declares such an annotation, as@annotationdoes. The backtick form stays.
Transformations
Section titled “Transformations”#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,annotationsandmetadata(T): T?,metadataAll(T): T[]:- a
Type: as today, andmethods, those of a contract, of a namespace, or a type’s own, each aMethod; - a
Methodand anFnDecl:name,params,result,errors(the types of its!),hasBody,isStatic; - a
Param:name,type,default,expr; - a
Fieldand aVariant: as today.
- a
- 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.
#Restreads the metadata of the types its methods take:FromRequestadopted, 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.
Phases
Section titled “Phases”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
.earlytransformation of every declaration of a module applies before every.normalone, 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 ofafteris 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
.earlyone reading what a.normalone 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.
.programruns in the program’s root module alone, the one holdingmain, after every other transformation of the program: the place of what reads it whole.
Aliases
Section titled “Aliases”@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.
The whole program
Section titled “The whole program”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 testtakes 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.programtransformation,@phase(.program). - Read in
.programonly, 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.
Examples
Section titled “Examples”weft/wake’s annotations, which only recorded and could not say so:
@annotationtype Needs = { tasks: Expr }
@annotationtype 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 }}What changes
Section titled “What changes”- 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
@annotationtypes, and wv-wake may read them throughwv expand’s metadata rather than the syntax: kept as is until then. #Xmltakes tags on a variant’s fields.- Nothing written today stops working:
@ftransforming a function,#Cderiving a contract, backtick tags.
Validation
Section titled “Validation”- 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.
Settled
Section titled “Settled”- Metadata at compile time only; a transformation writes what the program needs at run time.
- A short form,
@annotation type, for an annotation that only records. - Any meta code reads the metadata of what it reaches through a description, whichever module declares it.
- Metadata typed, values of any type meta code builds, attached by
addMetadata, read bymetadata(T)andmetadataAll(T). - Annotations on fields, variants, parameters and methods without body, the target given by the meta fn’s first parameter.
- Backtick tags kept, as the short form of a field’s metadata.
#naming a transformation that declares no conformance.- The order: annotations of members, then of the declaration, then the transformations in the order written.
- 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. .programin the root module alone, after every other transformation;#Applicationone of them.@implieson an annotation type, an alias attaching another’s metadata.Build.annotated(T), in.program, over every module of the main package and those they import.