Documentation

combinators.php

This file is part of the Parsica library.

Copyright (c) 2020 Mathias Verraes mathias@verraes.net

For the full copyright and license information, please view the LICENSE file that was distributed with this source code.

Table of Contents

Functions

identity()  : Parser
Identity parser, returns the Parser as is.
pure()  : Parser
A parser that will have the argument as its output, no matter what the input was. It doesn't consume any input.
optional()  : Parser
Optionally parse something, but still succeed if the thing is not there
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.
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.
sequence()  : Parser
Parse something, then follow by something else. Ignore the result of the first parser and return the result of the second parser.
keepFirst()  : Parser
Sequence two parsers, and return the output of the first one.
keepSecond()  : Parser
Sequence two parsers, and return the output of the second one.
either()  : Parser
Either parse the first thing or the second thing
append()  : Parser
Combine the parser with another parser of the same type, which will cause the results to be appended.
assemble()  : Parser
Append all the passed parsers.
collect()  : Parser
Parse into an array that consists of the results of all parsers.
any()  : Parser
Tries each parser one by one, returning the result of the first one that succeeds.
choice()  : Parser
Tries each parser one by one, returning the result of the first one that succeeds.
atLeastOne()  : Parser
One or more repetitions of Parser, with the outputs appended.
zeroOrMore()  : Parser
Zero or more repetitions of Parser, with the outputs appended.
repeat()  : Parser
Parse something exactly n times
repeatList()  : Parser
Parse something exactly n times and return as an array
some()  : Parser
Parse something one or more times, and output an array of the successful outputs.
many()  : Parser
Parse something zero or more times, and output an array of the successful outputs.
between()  : Parser
Parse $open, followed by $middle, followed by $close, and return the result of $middle. Useful for eg. "(value)".
sepBy()  : Parser
Parses zero or more occurrences of $parser, separated by $separator. Returns a list of values.
sepBy1()  : Parser
Parses one or more occurrences of $parser, separated by $separator. Returns a list of values.
sepBy2()  : Parser
Parses 2 or more occurrences of $parser, separated by $separator. Returns a list of values.
notFollowedBy()  : Parser
notFollowedBy only succeeds when $parser fails. It never consumes any input.
map()  : Parser
Map a function over the parser (which in turn maps it over the result).
lookAhead()  : Parser
If $parser succeeds (either consuming input or not), lookAhead behaves like $parser succeeded without consuming anything. If $parser fails, lookAhead has no effect, i.e. it will fail to consume input if $parser fails consuming input.

Functions

identity()

Identity parser, returns the Parser as is.

identity(Parser $parser) : Parser
Parameters
$parser : Parser
Tags
psalm-param

Parser<T> $parser

psalm-return

Parser<T>

template
psalm-pure
Return values
Parser

pure()

A parser that will have the argument as its output, no matter what the input was. It doesn't consume any input.

pure(mixed $output) : Parser
Parameters
$output : mixed
Tags
psalm-param

T $output

psalm-return

Parser<T>

template
psalm-pure
Return values
Parser

optional()

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

optional(Parser $parser) : Parser
Parameters
$parser : Parser
Tags
psalm-param

Parser<T> $parser

psalm-return

Parser<T|null>

template
psalm-pure
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.

bind(Parser $parser, callable $f) : Parser

This is a monadic bind aka flatmap.

Parameters
$parser : Parser
$f : callable
Tags
psalm-param

Parser<T1> $parser

psalm-param

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

psalm-return

Parser<T2>

template
template
psalm-pure
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.

apply(Parser $parser1, Parser $parser2) : Parser

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
$parser1 : Parser
$parser2 : Parser
Tags
template
template
psalm-param

Parser<pure-callable(T1):T2> $parser1

psalm-param

Parser<T1> $parser2

psalm-return

Parser<T2>

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.

sequence(Parser $first, Parser $second) : Parser
Parameters
$first : Parser
$second : Parser
Tags
psalm-param

Parser<T1> $first

psalm-param

Parser<T2> $second

psalm-return

Parser<T2>

template
template
see
Parser::sequence()
psalm-pure
Return values
Parser

keepFirst()

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

keepFirst(Parser $first, Parser $second) : Parser
Parameters
$first : Parser
$second : Parser
Tags
template
template
psalm-param

Parser<T1> $first

psalm-param

Parser<T2> $second

psalm-return

Parser<T1>

psalm-pure
Return values
Parser

keepSecond()

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

keepSecond(Parser $first, Parser $second) : Parser
Parameters
$first : Parser
$second : Parser
Tags
template
template
psalm-param

Parser<T1> $first

psalm-param

Parser<T2> $second

psalm-return

Parser<T2>

psalm-pure
Return values
Parser

either()

Either parse the first thing or the second thing

either(Parser $first, Parser $second) : Parser
Parameters
$first : Parser
$second : Parser
Tags
psalm-param

Parser<T1> $first

psalm-param

Parser<T2> $second

psalm-return

Parser<T1|T2>

see
Parser::or()
template
template
psalm-pure
Return values
Parser

append()

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

append(Parser $left, Parser $right) : Parser
Parameters
$left : Parser
$right : Parser
Tags
psalm-param

Parser<T|null> $left

psalm-param

Parser<T|null> $right

psalm-return

Parser<T|null>

template
psalm-pure
Return values
Parser

assemble()

Append all the passed parsers.

assemble(Parser ...$parsers) : Parser
Parameters
$parsers : Parser
Tags
psalm-param

list<Parser<T|null>> $parsers

psalm-return

Parser<T|null>

template
psalm-suppress

MixedReturnStatement

psalm-suppress

MixedInferredReturnType

psalm-pure
Return values
Parser

collect()

Parse into an array that consists of the results of all parsers.

collect(Parser ...$parsers) : Parser
Parameters
$parsers : Parser
Tags
psalm-param

list<Parser> $parsers

psalm-return

Parser

psalm-pure
Return values
Parser

any()

Tries each parser one by one, returning the result of the first one that succeeds.

any(Parser ...$parsers) : Parser
Parameters
$parsers : Parser
Tags
no-named-arguments
psalm-param

non-empty-list<Parser> $parsers

psalm-return

Parser

psalm-pure
Return values
Parser

choice()

Tries each parser one by one, returning the result of the first one that succeeds.

choice(Parser ...$parsers) : Parser

Alias for any()

Parameters
$parsers : Parser
Tags
no-named-arguments
psalm-param

non-empty-list<Parser> $parsers

psalm-return

Parser

psalm-pure
Return values
Parser

atLeastOne()

One or more repetitions of Parser, with the outputs appended.

atLeastOne(Parser $parser) : Parser
Parameters
$parser : Parser
Tags
psalm-param

Parser<T> $parser

psalm-return

Parser<T>

template
psalm-suppress

MixedArgumentTypeCoercion

psalm-pure
Return values
Parser

zeroOrMore()

Zero or more repetitions of Parser, with the outputs appended.

zeroOrMore(Parser $parser) : Parser
Parameters
$parser : Parser
Tags
TODO

Untested

psalm-param

Parser<T> $parser

psalm-return

Parser<T>

template
psalm-suppress

MixedArgumentTypeCoercion

psalm-pure
Return values
Parser

repeat()

Parse something exactly n times

repeat(int $n, Parser $parser) : Parser
Parameters
$n : int
$parser : Parser
Tags
template
psalm-param

Parser<T> $parser

psalm-return

Parser<T>

psalm-pure
Return values
Parser

repeatList()

Parse something exactly n times and return as an array

repeatList(int $n, Parser $parser) : Parser
Parameters
$n : int
$parser : Parser
Tags
TODO

This doesn't feel very elegant.

template
psalm-param

positive-int $n

psalm-param

Parser<T> $parser

psalm-return

Parser<list<T>>

psalm-pure
Return values
Parser

some()

Parse something one or more times, and output an array of the successful outputs.

some(Parser $parser) : Parser
Parameters
$parser : Parser
Tags
template
psalm-param

Parser<T> $parser

psalm-return

Parser<list<T>>

psalm-pure
Return values
Parser

many()

Parse something zero or more times, and output an array of the successful outputs.

many(Parser $parser) : Parser
Parameters
$parser : Parser
Tags
template
psalm-param

Parser<T> $parser

psalm-return

Parser<list<T>>

psalm-pure
Return values
Parser

between()

Parse $open, followed by $middle, followed by $close, and return the result of $middle. Useful for eg. "(value)".

between(Parser $open, Parser $close, Parser $middle) : Parser
Parameters
$open : Parser
$close : Parser
$middle : Parser
Tags
template
template
template
psalm-param

Parser<TO> $open

psalm-param

Parser<TC> $close

psalm-param

Parser<TM> $middle

psalm-return

Parser<TM>

psalm-pure
Return values
Parser

sepBy()

Parses zero or more occurrences of $parser, separated by $separator. Returns a list of values.

sepBy(Parser $separator, Parser $parser) : Parser

The sepBy parser always succeed, even if it doesn't find anything. Use sepBy1() if you want it to find at least one value.

Parameters
$separator : Parser
$parser : Parser
Tags
template
template
psalm-param

Parser<TSeparator> $separator

psalm-param

Parser<T> $parser

psalm-return

Parser<list<T>>

psalm-pure
Return values
Parser

sepBy1()

Parses one or more occurrences of $parser, separated by $separator. Returns a list of values.

sepBy1(Parser $separator, Parser $parser) : Parser
Parameters
$separator : Parser
$parser : Parser
Tags
template
template
psalm-param

Parser<TS> $separator

psalm-param

Parser<T> $parser

psalm-return

Parser<list<T>>

psalm-suppress

MissingClosureReturnType

psalm-pure
Return values
Parser

sepBy2()

Parses 2 or more occurrences of $parser, separated by $separator. Returns a list of values.

sepBy2(Parser $separator, Parser $parser) : Parser
Parameters
$separator : Parser
$parser : Parser
Tags
template
template
psalm-param

Parser<TS> $separator

psalm-param

Parser<T> $parser

psalm-return

Parser<list<T>>

psalm-suppress

MissingClosureReturnType

psalm-pure
Return values
Parser

notFollowedBy()

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

notFollowedBy(Parser $parser) : Parser

Example:

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

keepFirst(string("print"), notFollowedBy(alphaNumChar())) will match "print something" but not "printXYZ something"

Parameters
$parser : Parser
Tags
template
psalm-param

Parser<T> $parser

psalm-return

Parser<T>

see
Parser::notFollowedBy()
psalm-pure
Return values
Parser

map()

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

map(Parser $parser, callable $transform) : Parser
Parameters
$parser : Parser
$transform : callable
Tags
template
template
psalm-param

pure-callable(T1) : T2 $transform

psalm-return

Parser<T2>

psalm-pure
Return values
Parser

lookAhead()

If $parser succeeds (either consuming input or not), lookAhead behaves like $parser succeeded without consuming anything. If $parser fails, lookAhead has no effect, i.e. it will fail to consume input if $parser fails consuming input.

lookAhead(Parser $parser) : Parser
Parameters
$parser : Parser
Tags
template
psalm-param

Parser<T> $parser

psalm-return

Parser<T>

psalm-pure
Return values
Parser 

        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results