Lexikalische Analyse

Jede Folge von Bezeichnerzeichen, gefolgt von einem Ausrufezeichen (Exklamationszeichen, britisch), wird als `MACRO_NAME` tokenisiert.

Anweisungsform

macro_stmt = MACRO_NAME testlist [ "import" NAME ] [ "as"  NAME ] [ ":" NEWLINE suite ]

Ausdrucksform

macro_expr = MACRO_NAME "(" testlist ")"

Auflösung von Mehrdeutigkeiten

Die Anweisungsform eines Makros hat Vorrang, so dass der Code `macro_name!(x)` als Makro-Anweisung und nicht als Ausdrucksanweisung, die einen Makro-Ausdruck enthält, geparst wird.

Kompilierung

Beim Auftreten eines `macro` während der Übersetzung in Bytecode sucht der Codegenerator nach dem für das Makro registrierten Makro-Prozessor und übergibt den AST, der an der Wurzel des Makros liegt, an die Prozessorfunktion. Der zurückgegebene AST wird dann für den ursprünglichen Baum eingesetzt.

Bei Makros mit mehreren Namen werden mehrere Bäume an den Makro-Prozessor übergeben, aber nur einer wird zurückgegeben und eingesetzt, wodurch der umschließende Block von Anweisungen gekürzt wird.

Dieser Prozess kann wiederholt werden, damit Makros AST-Knoten zurückgeben können, die andere Makros enthalten.

Der Compiler sucht erst dann nach einem Makro-Prozessor, wenn dieses Makro erreicht ist, so dass innere Makros keine registrierten Prozessoren benötigen. Beispielsweise muss in einem `switch`-Makro für die `case`- und `default`-Makros kein Prozessor registriert sein, da sie vom `switch`-Prozessor eliminiert würden.

Um die Definition von Makros zum Importieren zu ermöglichen, sind die Makros `import!` und `from!` vordefiniert. Sie unterstützen die folgende Syntax

"import!" dotted_name "as" name

"from!" dotted_name "import" name [ "as" name ]

Das `import!`-Makro führt einen Import zur Kompilierzeit von `dotted_name` durch, um den Makro-Prozessor zu finden, und registriert ihn dann unter `name` für den aktuell kompilierten Geltungsbereich.

Das `from!`-Makro führt einen Import zur Kompilierzeit von `dotted_name.name` durch, um den Makro-Prozessor zu finden, und registriert ihn dann unter `name` (unter Verwendung von `name` nach `as`, falls vorhanden) für den aktuell kompilierten Geltungsbereich.

Beachten Sie, dass `import!` und `from!`, da sie das Makro nur für den Geltungsbereich definieren, in dem der Import vorhanden ist, alle Verwendungen eines Makros durch einen expliziten `import!`- oder `from!`-Befehl vorangestellt werden müssen, um die Klarheit zu verbessern.

Zum Beispiel, um das Makro „compile“ aus „my.compiler“ zu importieren

from! my.compiler import compile

Definition von Makro-Prozessoren

Ein Makro-Prozessor wird durch ein Vierertupel definiert, bestehend aus `(func, kind, version, additional_names)`.

• `func` muss aufrufbar sein, der `len(additional_names)+1` Argumente entgegennimmt, von denen alle abstrakte Syntaxbäume sind, und einen einzelnen abstrakten Syntaxbaum zurückgibt.
• `kind` muss eine der folgenden sein:
  • `macros.STMT_MACRO`: Ein Anweisungs-Makro, bei dem der Körper des Makros eingerückt ist. Dies ist die einzige Form, die zusätzliche Namen haben darf.
  • `macros.SIBLING_MACRO`: Ein Anweisungs-Makro, bei dem der Körper des Makros die nächste Anweisung im selben Block ist. Die folgende Anweisung wird als Körper in das Makro verschoben.
  • `macros.EXPR_MACRO`: Ein Ausdrucks-Makro.
• `version` wird verwendet, um Versionen von Makros zu verfolgen, damit generierte Bytecodes korrekt zwischengespeichert werden können. Es muss eine Ganzzahl sein.
• `additional_names` sind die Namen der zusätzlichen Teile des Makros und müssen ein Tupel von Zeichenketten sein.

# (func, _ast.STMT_MACRO, VERSION, ())
stmt_macro!:
    multi_statement_body

# (func, _ast.SIBLING_MACRO, VERSION, ())
sibling_macro!
single_statement_body

# (func, _ast.EXPR_MACRO, VERSION, ())
x = expr_macro!(...)

# (func, _ast.STMT_MACRO, VERSION, ("subsequent_macro_part",))
multi_part_macro!:
    multi_statement_body
subsequent_macro_part!:
    multi_statement_body

Der Compiler prüft, ob die verwendete Syntax mit der deklarierten Art übereinstimmt.

Zur Bequemlichkeit wird der Dekorator `macro_processor` im Modul `macros` bereitgestellt, um eine Funktion als Makro-Prozessor zu kennzeichnen.

def macro_processor(kind, version, *additional_names):
    def deco(func):
        return func, kind, version, additional_names
    return deco

Dies kann zur Deklaration von Makro-Prozessoren verwendet werden, zum Beispiel

@macros.macro_processor(macros.STMT_MACRO, 1_08)
def switch(astnode):
    ...

AST-Erweiterungen

Zwei neue AST-Knoten werden benötigt, um Makros auszudrücken: `macro_stmt` und `macro_expr`.

class macro_stmt(_ast.stmt):
    _fields = "name", "args", "importname", "asname", "body"

class macro_expr(_ast.expr):
    _fields = "name", "args"

Darüber hinaus benötigen Makro-Prozessoren ein Mittel, um Ablaufsteuerung oder seitenwirksamen Code auszudrücken, der einen Wert erzeugt. Ein neuer AST-Knoten namens `stmt_expr` wird hinzugefügt, der eine Anweisung und einen Ausdruck kombiniert. Dieser neue AST-Knoten ist eine Unterklasse von `expr`, enthält aber eine Anweisung, um Nebeneffekte zu ermöglichen. Er wird in Bytecode übersetzt, indem die Anweisung kompiliert und dann der Wert kompiliert wird.

class stmt_expr(_ast.expr):
    _fields = "stmt", "value"

Hygiene und Debugging

Makro-Prozessoren müssen oft neue Variablen erstellen. Diese Variablen müssen so benannt werden, dass sie den ursprünglichen Code und andere Makros nicht kontaminieren. Es werden keine Regeln für die Benennung erzwungen, aber um die Hygiene zu gewährleisten und das Debugging zu erleichtern, wird das folgende Benennungsschema empfohlen:

• Alle generierten Variablennamen sollten mit einem `$` beginnen.
• Rein künstliche Variablennamen sollten mit `$$mname` beginnen, wobei `mname` der Name des Makros ist.
• Variablen, die von echten Variablen abgeleitet sind, sollten mit `$vname` beginnen, wobei `vname` der Name der Variablen ist.
• Alle Variablennamen sollten die Zeilennummer und den Spaltenoffset enthalten, getrennt durch einen Unterstrich.

Beispiele

• Rein generierter Name: `$$macro_17_0`
• Von einer Variable abgeleiteter Name für ein Ausdrucks-Makro: `$var_12_5`

Zur Kompilierzeit geprüfte Datenstrukturen

Es ist üblich, Tabellen von Daten in Python als große Wörterbücher zu kodieren. Diese können jedoch schwer zu pflegen und fehleranfällig sein. Makros ermöglichen es, solche Daten in einem besser lesbaren Format zu schreiben. Zur Kompilierzeit können die Daten dann überprüft und in ein effizientes Format umgewandelt werden.

Nehmen wir zum Beispiel an, wir haben zwei Wörterbuch-Literale, die Codes zu Namen und umgekehrt zuordnen. Dies ist fehleranfällig, da die Wörterbücher doppelte Schlüssel haben können oder eine Tabelle nicht die Umkehrung der anderen ist. Ein Makro könnte die beiden Zuordnungen aus einer einzigen Tabelle generieren und gleichzeitig überprüfen, ob keine Duplikate vorhanden sind.

color_to_code = {
    "red": 1,
    "blue": 2,
    "green": 3,
}

code_to_color = {
    1: "red",
    2: "blue",
    3: "yellow", # error
}

würde zu

bijection! color_to_code, code_to_color:
    "red" = 1
    "blue" = 2
    "green" = 3

Domänenspezifische Erweiterungen

Wo ich Makros als wirklich wertvoll erachte, sind spezifische Domänen, nicht allgemeine Sprachfunktionen.

Zum Beispiel Parser. Hier ist ein Teil einer Parser-Definition für Python, die Makros verwendet.

choice! single_input:
    NEWLINE
    simple_stmt
    sequence!:
        compound_stmt
        NEWLINE

Compiler

Laufzeitcompiler wie `numba` müssen den Python-Quellcode wiederherstellen oder versuchen, den Bytecode zu analysieren. Für sie wäre es einfacher und zuverlässiger, den AST direkt zu erhalten.

from! my.jit.library import jit

jit!
def func():
    ...

Abgleich symbolischer Ausdrücke

Beim Abgleich von etwas, das Syntax repräsentiert, wie z. B. einem Python `ast`-Knoten oder einem `sympy`-Ausdruck, ist es praktisch, gegen die tatsächliche Syntax abzugleichen und nicht gegen die sie darstellende Datenstruktur. Zum Beispiel könnte ein Taschenrechner mithilfe eines domänenspezifischen Makros zum Abgleichen von Syntax implementiert werden.

from! ast_matcher import match

def calculate(node):
    if isinstance(node, Num):
        return node.n
    match! node:
        case! a + b:
            return calculate(a) + calculate(b)
        case! a - b:
            return calculate(a) - calculate(b)
        case! a * b:
            return calculate(a) * calculate(b)
        case! a / b:
            return calculate(a) / calculate(b)

was übersetzt werden könnte in

def calculate(node):
    if isinstance(node, Num):
        return node.n
    $$match_4_0 = node
    if isinstance($$match_4_0, _ast.Add):
        a, b = $$match_4_0.left, $$match_4_0.right
        return calculate(a) + calculate(b)
    elif isinstance($$match_4_0, _ast.Sub):
        a, b = $$match_4_0.left, $$match_4_0.right
        return calculate(a) - calculate(b)
    elif isinstance($$match_4_0, _ast.Mul):
        a, b = $$match_4_0.left, $$match_4_0.right
        return calculate(a) * calculate(b)
    elif isinstance($$match_4_0, _ast.Div):
        a, b = $$match_4_0.left, $$match_4_0.right
        return calculate(a) / calculate(b)

Nullkostengrenzen und Anmerkungen

Annotationen, entweder als Dekoratoren oder als PEP 3107-Funktionsannotationen, haben Laufzeitkosten, auch wenn sie nur als Marker für Prüfer oder als Dokumentation dienen.

@do_nothing_marker
def foo(...):
    ...

kann durch das Nullkosten-Makro ersetzt werden

do_nothing_marker!:
def foo(...):
    ...

Prototyping von Spracherweiterungen

Obwohl Makros für domänenspezifische Erweiterungen am wertvollsten wären, ist es möglich, mögliche Spracherweiterungen mithilfe von Makros zu demonstrieren.

try_!:
    body
finally!:
    closing

try:
    body
except:
    closing
else:
    closing

with! open(filename) as fd:
    return fd.read()

with! open!(filename) as fd:
    return fd.read()

Makro-Definitionsmakros

Sprachen, die syntaktische Makros haben, stellen normalerweise ein Makro zur Definition von Makros bereit. Dieser PEP tut dies absichtlich nicht, da noch nicht klar ist, wie ein gutes Design aussehen würde, und wir der Community erlauben wollen, ihre eigenen Makros zu definieren.

Eine mögliche Form könnte sein

macro_def! name:
    input:
        ... # input pattern, defining meta-variables
    output:
        ... # output pattern, using meta-variables