macros library

Author dmx macros in Dart dartmacros.api.

A macro is a name and an expand function over a typed invocation. The worker loop dartmacros.protocol is dmxServeMacros — an author never sees a protocol frame:

final class Audit extends DmxMacro {
  @override
  String get name => 'audit';

  @override
  DmxOutput expand(DmxInvocation invocation) =>
      DmxFragment('  // ${invocation.declaration.name}\n');
}

void main() => dmxServeMacros([Audit()]);

A macro may also hand its model to a Mustache template and let dmx render it dartmacros.render — invocation.templates.render(…) reaches the very engine the catalogue's own macros use, so the two ways of authoring generated Dart are one system rather than a fork in the road.

This library is for macro authors and pulls in dart:io. Generated code and the apps that hold it use package:dmx/dmx.dart, which does not dartmacros.api.

Classes

DmxAnnotation

One annotation as the author wrote it, arguments as raw Dart source.

DmxDeclaration

The annotated declaration, as dmx's front end read it.

DmxField

One instance field of the annotated declaration.

DmxFragment

Generated members, ready for the region.

DmxGeneratedFile

One whole Dart file this expansion authors, named by the macro dartmacros.files.

DmxInvocation

Everything one expansion receives dartmacros.api.

DmxMacro

A user-defined macro: a name and a way to expand dartmacros.api.

DmxOutput

What an expansion returns: a fragment or a refusal — a value either way, never a throw dartmacros.api.

DmxRefusal

A declined declaration, in the author's terms diagnostics.

DmxTemplates

dmx's own Mustache engine, offered to the macro dartmacros.render.

Functions

dmxCamelCase(String name) → String

The Dart identifier for a foreign name: iso_code gives isoCode.

dmxPascalCase(String name) → String

The Dart type name for a foreign one: currency_detail gives CurrencyDetail.

dmxServeMacros(List<DmxMacro> macros, {String name = 'macros', String version = DmxPackage.version}) → Future<void>

Serves macros over the worker protocol until the driver closes stdin dartmacros.protocol. This is the whole of main for a macro worker.

dmxSnakeCase(String name) → String

The Dart file name for a type: CurrencyDetail gives currency_detail.

dmxWords(String name) → List<String>

The words in name, in order — the reading every casing here is built on.