Skip to content

Commit 12221e1

Browse files
committed
Improve readme and add default rules + transformers
1 parent 0094b84 commit 12221e1

3 files changed

Lines changed: 70 additions & 35 deletions

File tree

‎README.md‎

Lines changed: 44 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,44 @@ echo $declarations[0]->name->value; // "move"
3636
An invalid header throws `FFI\Parser\Exception\ParserException`, which points
3737
to 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 |

‎src/Transformer.php‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,12 @@ private static function formatTransformerRules(iterable $rules): array
6363
}
6464

6565
/**
66-
* Creates the transformer with the rules that rebuild the constructs
67-
* the grammar parses one way, whichever names are declared before them,
68-
* by the typedef names and the other names declared in the tree.
66+
* @param iterable<mixed, TransformerRuleInterface<covariant NodeInterface>> $append
67+
* @return array<array-key, TransformerRuleInterface<covariant NodeInterface>>
6968
*/
70-
public static function createDefault(): self
69+
public static function getDefaultTransformers(iterable $append = []): array
7170
{
72-
return new self([
71+
return [
7372
new TypedefCastRule(),
7473
new FunctionCallRule(),
7574
new SizeOfExpressionOperandRule(),
@@ -84,7 +83,18 @@ public static function createDefault(): self
8483
new AlignAsTypeNameOperandRule(),
8584
new GenericSelectionTypeNameOperandRule(),
8685
new BuiltinCallTypeNameOperandRule(),
87-
]);
86+
...$append,
87+
];
88+
}
89+
90+
/**
91+
* Creates the transformer with the rules that rebuild the constructs
92+
* the grammar parses one way, whichever names are declared before them,
93+
* by the typedef names and the other names declared in the tree.
94+
*/
95+
public static function createDefault(): self
96+
{
97+
return new self(self::getDefaultTransformers());
8898
}
8999

90100
/**

‎src/Validator.php‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,21 @@ private static function formatValidatorRules(iterable $rules): array
4646
};
4747
}
4848

49+
/**
50+
* @param iterable<mixed, ValidatorRuleInterface> $append
51+
* @return array<array-key, ValidatorRuleInterface>
52+
*/
53+
public static function getDefaultRules(iterable $append = []): array
54+
{
55+
return [];
56+
}
57+
4958
/**
5059
* TODO Add default rules
5160
*/
5261
public static function createDefault(): self
5362
{
54-
return new self();
63+
return new self(self::getDefaultRules());
5564
}
5665

5766
/**

0 commit comments

Comments
 (0)