Documentation

Parser
in package

FinalYes

A parser is any function that takes a string input and returns a {@see ParseResult}. The Parser class is a wrapper around such functions. The {@see Parser::make()} static constructor takes a callable that does the actual parsing.

Usually you don't need to instantiate this class directly. Instead, build your parser from existing parsers and combinators.

At the moment, there is no Parser interface, and no Parser abstract class to extend from. This is intentional, but will be changed if we find use cases where those would be the best solutions.

The type is Parser<T>, where T is the type of the output that the parser will produce after completing successfully.

Tags
template

Table of Contents

Properties

$label  : string
$parserFunction  : mixed
$recursionStatus  : string

Methods

and()  : Parser
Combine the parser with another parser of the same type, which will cause the results to be appended.
append()  : Parser
Combine the parser with another parser of the same type, which will cause the results to be appended.
apply()  : Parser
Sequential application. Given a parser which outputs a callable, return a new parser that applies the callable on the output of the second parser.
bind()  : Parser
Create a parser that takes the output from the first parser (if successful) and feeds it to the callable. The callable must return another parser. If the first parser fails, the first parser is returned.
continueFrom()  : ParseResult
Take the remaining input from the result and parse it.
emit()  : Parser
If the parser is successful, call the $receiver function with the output of the parser. The resulting parser behaves identical to the original one. This combinator is useful for expressing side effects during the parsing process. It can be hooked into existing event publishing libraries by using $receiver as an adapter for those.
followedBy()  : Parser
Parse something, then follow by something else. Ignore the result of the first parser and return the result of the second parser.
label()  : Parser
Label a parser. When a parser fails, you'll see your label as the "expected" value. As a best practice, the labels should make sense to the person who provides the input for your parser. That's often an end user or a third party, so keep them in mind.
map()  : Parser
Map a function over the parser (which in turn maps it over the result).
notFollowedBy()  : Parser
notFollowedBy only succeeds when $second fails. It never consumes any input.
optional()  : Parser
Optionally parse something, but still succeed if the thing is not there.
or()  : Parser
Try the first parser, and failing that, try the second parser. Returns the first succeeding result, or the first failing result.
recurse()  : void
Recurse on a parser. Used in combination with {@see recursive()}. After calling this method, this parser behaves like a regular parser.
recursive()  : Parser
Create a recursive parser. Used in combination with recurse(Parser).
run()  : ParseResult
Run the parser on an input
sequence()  : Parser
Parse something, then follow by something else. Ignore the result of the first parser and return the result of the second parser.
then()  : Parser
Parse something, then follow by something else. Ignore the result of the first parser and return the result of the second parser. Alias for sequence().
thenEof()  : Parser
Make sure that the input ends after the parser has successfully completed. The output is the output of the original parser.
thenIgnore()  : Parser
Sequence two parsers, and return the output of the first one, ignore the second.
try()  : ParseResult
Try to parse the input, or throw an exception.
tryString()  : ParseResult
Try to parse a string. Alias of `try(new StringStream($string))`.
voidLeft()  : Parser
Ignore the output of the parser and return the new output instead.
__construct()  : mixed

Properties

$parserFunction

private mixed $parserFunction
Tags
psalm-var

pure-callable(Stream) : ParseResult<T> $parserF

$recursionStatus

private string $recursionStatus
Tags
psalm-var

'non-recursive'|'awaiting-recurse'|'recursion-was-setup'

Methods

and()

Combine the parser with another parser of the same type, which will cause the results to be appended.

public and(Parser $other) : Parser
APIYes
Parameters
$other : Parser
Tags
psalm-param

Parser<T|null> $other

psalm-return

Parser<T|null>

psalm-mutation-free
Return values
Parser

append()

Combine the parser with another parser of the same type, which will cause the results to be appended.

public append(Parser $other) : Parser
APIYes
Parameters
$other : Parser
Tags
psalm-param

Parser<T|null> $other

psalm-return

Parser<T|null>

psalm-mutation-free
Return values
Parser

apply()

Sequential application. Given a parser which outputs a callable, return a new parser that applies the callable on the output of the second parser.

public apply(Parser $parser) : Parser
APIYes

The first parser must be of type Parser<callable(T1):T2>. pure() can be used to wrap a callable in a Parser.

Callables with more than 1 argument need to be curried: pure(curry(fn($x, $y)))->apply($parser2)->apply($parser3)

Parameters
$parser : Parser
Tags
template
template
psalm-param

Parser<T2> $parser

psalm-return

Parser<T3>

psalm-suppress

MixedArgumentTypeCoercion

psalm-mutation-free
Return values
Parser

bind()

Create a parser that takes the output from the first parser (if successful) and feeds it to the callable. The callable must return another parser. If the first parser fails, the first parser is returned.

public bind(callable $f) : Parser
APIYes
Parameters
$f : callable
Tags
template
psalm-param

pure-callable(T) : Parser<T2> $f

psalm-return

Parser<T2>

see
bind()
psalm-mutation-free
Return values
Parser

emit()

If the parser is successful, call the $receiver function with the output of the parser. The resulting parser behaves identical to the original one. This combinator is useful for expressing side effects during the parsing process. It can be hooked into existing event publishing libraries by using $receiver as an adapter for those.

public emit(callable $receiver) : Parser
APIYes

Other use cases are logging, caching, performing an action whenever a value is matched in a long running input stream, ...

Parameters
$receiver : callable
Tags
psalm-param

callable(T): void $receiver

psalm-return

Parser<T>

Return values
Parser

followedBy()

Parse something, then follow by something else. Ignore the result of the first parser and return the result of the second parser.

public followedBy(Parser $second) : Parser
APIYes
Parameters
$second : Parser
Tags
template
psalm-param

Parser<T2> $second

psalm-return

Parser<T2>

see
sequence()
psalm-mutation-free
Return values
Parser

label()

Label a parser. When a parser fails, you'll see your label as the "expected" value. As a best practice, the labels should make sense to the person who provides the input for your parser. That's often an end user or a third party, so keep them in mind.

public label(string $label) : Parser
APIYes
Parameters
$label : string
Tags
psalm-return

Parser<T>

psalm-mutation-free
Return values
Parser

map()

Map a function over the parser (which in turn maps it over the result).

public map(callable $transform) : Parser
APIYes
Parameters
$transform : callable
Tags
template
psalm-param

pure-callable(T) : T2 $transform

psalm-return

Parser<T2>

psalm-mutation-free
Return values
Parser

notFollowedBy()

notFollowedBy only succeeds when $second fails. It never consumes any input.

public notFollowedBy(Parser $second) : Parser
APIYes

Example:

string("print") will also match "printXYZ"

string("print")->notFollowedBy(alphaNumChar())) will match "print something" but not "printXYZ something"

Parameters
$second : Parser
Tags
psalm-param

Parser<T2> $parser

psalm-return

Parser<T>

see
notFollowedBy()
template
psalm-mutation-free
Return values
Parser

optional()

Optionally parse something, but still succeed if the thing is not there.

public optional() : Parser
APIYes
Tags
psalm-return

Parser<T|null>

see
optional()
psalm-mutation-free
Return values
Parser

or()

Try the first parser, and failing that, try the second parser. Returns the first succeeding result, or the first failing result.

public or(Parser $other) : Parser
APIYes

Caveat: The order matters! string('http')->or(string('https')

Parameters
$other : Parser
Tags
psalm-param

Parser<T> $other

psalm-return

Parser<T>

psalm-mutation-free
Return values
Parser

recurse()

Recurse on a parser. Used in combination with {@see recursive()}. After calling this method, this parser behaves like a regular parser.

public recurse(Parser $parser) : void
APIYes
Parameters
$parser : Parser
Tags
psalm-param

Parser $parser

recursive()

Create a recursive parser. Used in combination with recurse(Parser).

public static recursive() : Parser
APIYes
Tags
see
recursive()
psalm-return

Parser

psalm-pure
Return values
Parser

sequence()

Parse something, then follow by something else. Ignore the result of the first parser and return the result of the second parser.

public sequence(Parser $second) : Parser
APIYes
Parameters
$second : Parser
Tags
template
psalm-param

Parser<T2> $second

psalm-return

Parser<T2>

see
sequence()
psalm-mutation-free
Return values
Parser

then()

Parse something, then follow by something else. Ignore the result of the first parser and return the result of the second parser. Alias for sequence().

public then(Parser $second) : Parser
APIYes
Parameters
$second : Parser
Tags
template
psalm-param

Parser<T2> $second

psalm-return

Parser<T2>

see
sequence()
psalm-mutation-free
Return values
Parser

thenEof()

Make sure that the input ends after the parser has successfully completed. The output is the output of the original parser.

public thenEof() : Parser
APIYes

Also useful in unit tests to make sure a parser doesn't consume more than you intended.

Alias for $parser->thenIgnore(eof()).

Tags
psalm-return

Parser<T>

psalm-mutation-free
Return values
Parser

thenIgnore()

Sequence two parsers, and return the output of the first one, ignore the second.

public thenIgnore(Parser $other) : Parser
APIYes
Parameters
$other : Parser
Tags
psalm-mutation-free
Return values
Parser

tryString()

Try to parse a string. Alias of `try(new StringStream($string))`.

public tryString(string $input) : ParseResult
APIYes
Parameters
$input : string
Tags
TODO

Try should fail when it doesn't consume the whole input.

psalm-param

string $input

psalm-return

ParseResult<T>

throws
ParserHasFailed
Return values
ParseResult

voidLeft()

Ignore the output of the parser and return the new output instead.

public voidLeft(mixed $output) : Parser

@TODO needs test

Parameters
$output : mixed
Tags
template
psalm-param

T2 $output

psalm-return

Parser<T2>

psalm-mutation-free
Return values
Parser

__construct()

private __construct(callable $parserFunction, string $recursionStatus, string $label) : mixed
Parameters
$parserFunction : callable
$recursionStatus : string
$label : string
Tags
psalm-param

pure-callable(Stream) : ParseResult<T> $parserFunction

psalm-param

'non-recursive'|'awaiting-recurse'|'recursion-was-setup' $recursionStatus

psalm-pure
psalm-suppress

ImpureVariable


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results