@@ -36,6 +36,44 @@ echo $declarations[0]->name->value; // "move"
3636An invalid header throws ` FFI\Parser\Exception\ParserException ` , which points
3737to the error in the source.
3838
39+ ### AST Transformers
40+
41+ The parser contains a set of built-in AST transformations. To use your own,
42+ pass it to the constructor:
43+
44+ ``` php
45+ // override transformers
46+ $parser = new FFI\Parser\Parser(transformers: [
47+ new MyAstTransformer(),
48+ ]);
49+
50+ // or extend existing ones
51+ $parser = new FFI\Parser\Parser(
52+ transformers: FFI\Parser\Transformer::getDefaultTransformers([
53+ new MyAstTransformer(),
54+ ]),
55+ );
56+ ```
57+
58+ ### AST Validators
59+
60+ The parser checks the AST with validators after the transformations. To use
61+ your own, pass it to the constructor:
62+
63+ ``` php
64+ // override rules
65+ $parser = new FFI\Parser\Parser(rules: [
66+ new MyValidatorRule(),
67+ ]);
68+
69+ // or extend existing ones
70+ $parser = new FFI\Parser\Parser(
71+ rules: FFI\Parser\Validator::getDefaultRules([
72+ new MyValidatorRule(),
73+ ]),
74+ );
75+ ```
76+
3977## Benchmarks
4078
4179| Name | Speed | AST Nodes | Header Size |
@@ -89,31 +127,9 @@ the ISO/IEC 9899:2024 standard).
89127
90128## Limitations
91129
92- The parser does not track typedef names, so code whose meaning depends on
93- whether ` T ` is a type is always parsed one way:
94-
95- | Code | Current AST | Expected AST | When ` T ` is |
96- | -----------------------------------------------------| -----------------------------------| ----------------------------------------------| -------------------|
97- | ` (T)-x*y ` | ` Sub(Paren(T), Mul(x, y)) ` | ` Mul(Cast(T, Minus(x)), y) ` | a typedef |
98- | ` (T)+x ` | ` Add(Paren(T), x) ` | ` Cast(T, Plus(x)) ` | a typedef |
99- | ` (T)*x ` | ` Mul(Paren(T), x) ` | ` Cast(T, Dereference(x)) ` | a typedef |
100- | ` (T)&x ` | ` BitwiseAnd(Paren(T), x) ` | ` Cast(T, AddressOf(x)) ` | a typedef |
101- | ` sizeof(T[3]) ` | ` SizeOf(Paren(Subscript(T, 3))) ` | ` SizeOfType(SizedArray(T, 3)) ` | a typedef |
102- | ` typeof(T()) ` | ` TypeOf(Call(T)) ` | ` TypeOfType(Function(T)) ` | a typedef |
103- | ` typeof(T *(U)) ` | ` TypeOf(Mul(T, Paren(U))) ` | ` TypeOfType(Function(Pointer(T), Named(U))) ` | a typedef, as ` U ` |
104- | ` sizeof(T *(U)) ` | ` SizeOf(Paren(Mul(T, Paren(U)))) ` | ` SizeOfType(Function(Pointer(T), Named(U))) ` | a typedef, as ` U ` |
105- | ` (T)(x) ` | ` Cast(T, Paren(x)) ` | ` Call(Paren(T), x) ` | a function |
106- | ` (T)(x, y) ` | ` Cast(T, Paren(Comma(x, y))) ` | ` Call(Paren(T), x, y) ` | a function |
107- | ` sizeof(T) ` | ` SizeOfType(Named(T)) ` | ` SizeOf(Paren(T)) ` | not a type |
108- | ` alignof(T) ` | ` AlignOfType(Named(T)) ` | ` AlignOf(Paren(T)) ` | not a type |
109- | ` typeof(T) ` | ` TypeOfType(Named(T)) ` | ` TypeOf(T) ` | not a type |
110- | ` alignas(T) ` | ` AlignAsType(Named(T)) ` | ` AlignAs(T) ` | not a type |
111- | ` _Generic(T, …) ` | ` Generic(T, …) ` | ` Generic(Named(T), …) ` | a typedef |
112- | ` __builtin_offsetof(T, a) ` , any ` __builtin_*(T, …) ` | ` Builtin(T, a) ` | ` Builtin(Named(T), a) ` | a typedef |
113- | ` int f(int (T)); ` | ` Parameter(int, name: T) ` | ` Parameter(Function(int, Named(T))) ` | a typedef |
114-
115- The parentheses are kept in the tree (` Paren ` ), so it can be rebuilt once the
116- typedef names are known.
117-
118- I.e. what's actually needed is a Visitor that will mutate the AST based on the
119- presence of a declaration. For now, this is a TODO :)
130+ The built-in transformations rebuild the code whose meaning depends on whether
131+ a name is a typedef, except for:
132+
133+ | Code | Current AST | Expected AST | When ` T ` is |
134+ | -------------------| ---------------------------| --------------------------------------| -------------|
135+ | ` int f(int (T)); ` | ` Parameter(int, name: T) ` | ` Parameter(Function(int, Named(T))) ` | a typedef |
0 commit comments