Macros#

A macro gives a title to reusable expression syntax. Expansion replaces a call with its template before compilation. The expanded expression follows the expression type and cost rules.

{
  "#_ada": {
    "name": "Ada",
    "role": "engineer",
    "age": 36
  },
  "#_bob": {
    "name": "Bob",
    "role": "engineer",
    "age": 41,
    "mentor": {
      "#link": "#_ada"
    }
  },
  "#_cy": {
    "name": "Cy",
    "role": "designer",
    "age": 29
  }
}

Define a macro#

A macro document has ordered params and an expands template. An optional description explains its purpose. A stored definition has a title. The native macro builder also accepts an authored definition without saving it.

{
  "description": "Multiply an amount by a rate.",
  "params": [
    "amount",
    "rate"
  ],
  "expands": [
    "*",
    {
      "insert": "amount"
    },
    {
      "insert": "rate"
    }
  ]
}

Parameter names are plain text. Each name must differ from the other names. A name cannot be empty or contain whitespace. A macro cannot have a built-in operator's title. Definition validation rejects unknown fields, missing required fields and invalid markers.

Call a macro#

A call has the title first, then one argument for each declared parameter.

[
  "pricing/apply-rate",
  "?subtotal",
  0.2
]

20.0

Expansion produces [* ?subtotal 0.2]. The variable remains a caller input. Expansion rejects an invalid argument count.

[
  "pricing/apply-rate",
  100.0
]

Insert and spread#

An insertion marker is a map with one member. {insert name} replaces the marker with one argument tree. {spread name} inserts each item of a list argument into the surrounding list.

{
  "params": [
    "values"
  ],
  "expands": [
    "+",
    {
      "spread": "values"
    }
  ]
}

[
  "sum-all",
  [
    1,
    2,
    3,
    4
  ]
]

10

The expansion is [+ 1 2 3 4]. A spread marker needs a surrounding list and a list argument. An insertion preserves a list or map as one argument tree.

Compose macros#

A template can call another macro. Expansion resolves nested calls before the compiler validates operators and types. Expansion rejects direct and indirect cycles.

{
  "params": [
    "value",
    "floor"
  ],
  "expands": [
    ">=",
    {
      "insert": "value"
    },
    {
      "insert": "floor"
    }
  ]
}

{
  "params": [
    "value"
  ],
  "expands": [
    "and",
    [
      "at-least",
      {
        "insert": "value"
      },
      18
    ],
    [
      "<",
      {
        "insert": "value"
      },
      65
    ]
  ]
}

[
  "working-age",
  36
]

true

quote stops macro expansion inside its values. The expression evaluator still rejects quote. Syntax preserved during expansion is not necessarily executable.

Use macros in queries#

A query expands macros in expression positions, including predicates, derivations, computed columns, grouping filters, ordering and projection. Ordinary fact values remain data.

{
  "find": [
    "?name"
  ],
  "where": [
    [
      "?person",
      "age",
      "?age"
    ],
    [
      "?person",
      "name",
      "?name"
    ],
    [
      "working-age",
      "?age"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

A mutation uses the same expansion rules in its selection query.

Current and pinned definitions#

An unpinned call uses the current title mapping. Each accepted update records a mapping revision. A pin names that mapping revision, rather than the macro entity or its definition revision.

This update changes working-age to require an age of at least 40.

{
  "params": [
    "value"
  ],
  "expands": [
    "and",
    [
      ">=",
      {
        "insert": "value"
      },
      40
    ],
    [
      "<",
      {
        "insert": "value"
      },
      65
    ]
  ]
}

[
  "working-age",
  36
]

false

The first recorded mapping revision of working-age is 13 in this fresh fixture. Read the actual revision from the saved definition in your database. A pinned call keeps that earlier rule.

[
  {
    "title": "working-age",
    "mappingRevision": 13
  },
  36
]

true

A query can pin all calls of a title with its definitions member. Expansion consumes that metadata before query compilation.

{
  "definitions": {
    "working-age": 13
  },
  "find": [
    "?name"
  ],
  "where": [
    [
      "?person",
      "age",
      "?age"
    ],
    [
      "?person",
      "name",
      "?name"
    ],
    [
      "working-age",
      "?age"
    ]
  ],
  "orderBy": [
    "?name"
  ]
}

[
  {
    "name": "Ada"
  },
  {
    "name": "Bob"
  },
  {
    "name": "Cy"
  }
]

Expansion rejects an unknown mapping revision. It does not select the current rule.

Run it#

build macro · expand macro.