Skip to content

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>.

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 alias

An 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']