@define

Defines a template: a new construct whose uses expand to the Chalk written in its body.

@defineDirectiveExplained in Modularity
On this page

#Attributes

nodeRequiredImplicit
The new construct's name, written as the implicit value: @define:card. It may not be a library construct's name or alias.
Can be written as shorthand: @define:value

#Allowed content

Body { }The template — the Chalk that replaces each use, with {{param}} splices and {{body}}/{{detail}} for the use’s own sections

#Examples

@define:swatch{
    square(x: 0; y: 0; radius: 1; colour: {{colour}})
}(
    colour: !colour(default: blue)
)

graph{
    swatch(colour: red)
}
@define:finding{
    note{
        {{body}}
    }
}

finding{Richness scales as roughly the cube root of area.}
@define:reading{
    point(x: {{at}}; y: {{value}}; label: {{name}})
}(
    at:    !number(required; implicit)
    value: !number(required)
    name:  !string(default: —)
)

graph{
    reading:2(value: 4.1; name: Baltra)
}

#Notes

  • Each attribute is declared name: !type(…), the brackets written even when empty; required, default, implicit and aliases inside them describe the attribute, everything else refines the type.
  • body and detail declare the use's {…} and […] with a content policy — !all(), !none(), !children(…), !inline(…) or !literal() — and default to body: !all() and detail: !none().
  • A value is parsed by its attribute's type where the use is written: node tile: attribute x: abc is not a valid number.
  • An id written in the template is private to each use; one spelled through an attribute, square#{{name}}, is the caller's.
  • An entry whose key starts with _ is an export, read without the underscore as #id.name on a use with an id.
  • A template is known after its @define, inside the construct that holds it; declaring the name again replaces it.
  • A use takes no preset:, and the constructs it expands to are checked where they land.
  • A @define with no body is refused: @define: requires a {template} body.
  • A name that is not an identifier is refused: 2tag is not a valid node identifier.
  • A library construct's name is refused: curve is already a library node (canonical name or alias).
  • A type written without brackets is refused: !number on x needs a declaration group — write !number() even when it is empty.
  • An unknown type is refused: attribute v on node tag references unknown type boolean.
  • A refinement on a named type is refused: paint is a named type on v and cannot be refined further (min).
  • A refinement the base type does not have is refused: number does not define a refinement required (it defines: class, min, max).
  • An attribute both required and defaulted is refused: attribute v on node tag cannot be both required and defaulted.
  • A default the type cannot parse is refused: default for attribute v on node tag is invalid: abc is not a valid number.
  • A facet written twice is refused: default is written twice on v — and across a union's branches, declares default on more than one variant.
  • Two implicit attributes are refused: implicit is declared on both a and b — a node has at most one head : slot.
  • An alias that clashes with another attribute is refused: alias n collides with another attribute.
  • An attribute named preset is refused: preset cannot be an attribute name.
  • Union branches that accept the same text are refused: branches string and number accept the same text.
  • fields on a record is refused: fields is not written in a declaration group.
  • A section given a value type is refused: !string(…) is not a content policy on node rule.
  • An export that reads a later entry is refused: _area refers to side, which is declared after it.
  • A use that leaves out a required attribute is refused: required attribute v is missing.
  • A use with a section the template does not accept is refused: node card does not allow detail content.
  • A section of constructs spliced inside a line is refused: {{body}} holds constructs — … declare it a value.
  • A template that reaches itself as it expands is refused: circular define expansion.

Last updated