Metaprogramming

A loaded type hands back a structured description of itself: its members with their names and declared types, modifier and visibility flags, its supertypes and the contracts it implements, and the type's own run-time identity.

Each read first resolves a name to a member, then passes an access check, then moves the value through a generic representation and an indirect call. A compiled read did the resolving once, at build time, and does none of the rest.

Two layers guard a hidden member: the per-member access check, and, where a runtime groups types into packaged units, that unit's encapsulation boundary. A refusal of the suppression request itself points at the outer one, which only the unit's author or the deployer can open.

Run-time selection sees only the runtime classes of the actual values, never the declared types at a call site, so an absent value has no type at all, several constructors can match equally, and ambiguity surfaces at startup rather than in the build.

Two axes: where a member is declared (on this type or inherited from a supertype) and how visible it is (any visibility or public only). Common lookups bundle the two, so each call answers a fixed combination rather than letting you choose.

Attached metadata is inert: something has to read it. A consumer — a build-time processor, a startup scanner, or a check at the call site — must look for that marker and act on what it says, or nothing happens.

A metadata type's declaration enumerates the declaration kinds it may be attached to - type, method, field, parameter - and attachments anywhere else are rejected. Target lists turn a misplaced marker into a build error instead of a silent no-op.

Action-at-a-distance: the call site stops describing what the call does. Behaviour now depends on a marker plus machinery the reader cannot see, so local reasoning, debugging, review and onboarding all get more expensive.

A build-time processor catches a mistake while the build runs and can fail it. A startup scanner catches it when the process boots, after the artifact already shipped. A call-site check catches it only when that path actually executes.

Declare the new member with a default value. A member without a default must be supplied at every attachment site, so adding one breaks existing uses; a defaulted member is optional and older attachments keep their meaning.

In a hand-owned file the generator never writes, attached through an extension seam the generated type exposes: a type that extends it, a hook it calls, or a wrapper around it. Generated files are build output, not source.

Mixing machine-written files into the hand-edited tree invites edits that a later re-derivation erases, and it feeds emitted code to style checks, coverage numbers and review. Emit into a separate output directory and mark every file derived.

A processor advertises up front the set of metadata markers it supports. Each round the build hands it only the declarations carrying those markers, and the processor then applies its own filter for declaration kind and shape before emitting anything.

Generated files are ordinary source: they can carry markers of their own, so the build re-runs processing over them. Each round's output becomes the next round's input, and the loop ends when a round emits no new file.

Generation decides the binding plan during the build, so startup only runs straight-line assignments. Run-time inspection computes the same plan inside the running process, so member discovery, key matching and conversion choice all land in the startup window.

Only values the expanding stage can render back as code: literals, names the emitted program can resolve, or fragments it built by quoting. A live compile-time object cannot be smuggled into run time; it has to be reconstructed.

Substitution happens before the grammar is applied, so the pasted characters are parsed together with whatever surrounds the call. The caller's operators can bind tighter than the body's, regrouping the expression into something the author never wrote.

Source positions carried on every emitted node, plus an expansion trace. Text derived from the caller's argument should point back at the call site, text the macro authored at the macro, and the trace should name the chain that produced it.

The introduced binding shadows a caller name of the same spelling, so the caller's own references - including argument text spliced into the body - resolve to the expansion's temporary instead. This is accidental capture, and it compiles cleanly.

Substitution copies the argument's expression, not its value, so the expression is evaluated once per occurrence that control flow reaches. Side effects and cost repeat, and two evaluations can disagree. Bind it once into a temporary instead.

Each configuring call returns a receiver carrying everything recorded so far, so the next call can be written straight onto it. The closing call is different: it validates the accumulated state and produces the finished result.

Each block is a piece of code the enclosing call evaluates against an object it supplies, so unqualified calls inside the block configure that object. Nesting blocks builds a tree: an inner block targets the node its enclosing call just created.

A plain API advertises itself: its members, signatures and defaults are all reachable from the call site. A notation replaces that enumerable list with vocabulary a newcomer must be told about, and has to publish it some other way.

Enclosing receivers stay in scope when an inner block opens, so a name the inner node cannot answer is looked up outward and answered by the enclosing node. The call is legal, nothing is misspelled, and the wrong node is configured.

The notation does not repay when its authors are the people who wrote it, when its whole gain is punctuation an ordinary helper would remove, when its words are a one-for-one rename of existing members, or when it has begun growing its own control flow.

Interception only runs where a call crosses from one object into another. A wrapper sees the calls made through the reference it was handed; a call the object makes on itself travels through its own self-reference and never reaches the wrapper.

Anything that is not a dynamically dispatched call on the instance: members no subtype may replace, members resolved from the declared type or with no receiver at all, direct field reads, and work the target did while it was being constructed.

In reverse of the order they were entered. Handlers nest rather than queue: each one calls inward and waits, so the handler entered last is the first to resume, and the outermost handler finishes last.

Only a stand-in generated as a subtype of that class can be substituted there; in a nominally typed language a contract-only stand-in is not of that type. The subtype needs an extensible class, overridable members and construction that is safe to repeat.

Every generated member body does the same thing: it packages a description of the member that was called together with the argument list, hands both to one handler object, and returns whatever that handler returns.