Extending
Grammar
The spec of a definition is the grammar
of the line after @tagname, built by the methods of Spec:
| Method | Grammar | Matches |
|---|---|---|
Spec::literal('static') |
"static" |
an exact word or symbol |
Spec::rule(TypeCombinator::NAME) |
<Type> |
what the combinator reads |
Spec::sequence($a, $b) |
a b |
every rule, one after another |
Spec::oneOf($a, $b) |
( a | b ) |
the first rule that applies |
Spec::maybe($a) |
[ a ] |
the rule or nothing |
Spec::repeat($a) |
[ a ... ] |
the rule, any number of times |
// "@param" <Type> <Variable> [ <Description> ]Spec::sequence( Spec::rule(TypeCombinator::NAME, 'type'), Spec::rule(VariableCombinator::NAME, 'variable'), Spec::maybe( Spec::rule(DescriptionCombinator::NAME, 'description'), ),)Spec::repeat($rule, times: 1) requires at least one match (a ...). The third
argument of Spec::rule() is the name of the rule in the printed grammar:
Spec::rule(IntegerCombinator::NAME, 'amount', 'Amount') is <Amount>.
Captures
Section titled “Captures”The second argument of Spec::rule() and Spec::literal() is an alias: the
key of the matched value in the TagPayload given to create() of the
definition. A rule without an alias has to match, but its value is not kept.
$result->get('type'); // the value, throws when not captured$result->find('description'); // the value or null$result->getAll('issue'); // every value of a repeated aliasAn alias may repeat, such as the issues of
@suppress:
// "@suppress" <IssueName> [ "," <IssueName> ... ] [ <Description> ]Spec::sequence( Spec::rule(IssueNameCombinator::NAME, 'issue'), Spec::repeat( Spec::sequence( Spec::literal(','), Spec::rule(IssueNameCombinator::NAME, 'issue'), ), ), Spec::maybe( Spec::rule(DescriptionCombinator::NAME, 'description'), ),)
// @suppress PhanUnusedVariable, PhanTypeMismatch$result->getAll('issue'); // ['PhanUnusedVariable', 'PhanTypeMismatch']