uk.co.strangeskies.text.parsing

Interface Parser<T>

Type Parameters:

T - the type of the object created by successful application of the Parser to a piece of text

All Known Subinterfaces:

AbstractParser<T>

All Known Implementing Classes:

AppendingParser, ChoiceParser, DateTimeParser, JoiningParser, ParserProxy, PrependingParser, RegexParser

public interface Parser<T>

A simple text parser, composable by way of fluent and type-safe API. This class is intended for fairly simple use-cases.

Usage should be intuitive enough for users familiar with context free grammars, where a Parser instance represents a single symbol, and all production rules on that symbol. Parser instances should be immutable.

By this interpretation, production rules for new symbols can be derived by appending and prepending text, or other symbols, to existing symbols. Multiple production rules can effectively be created for a new symbol by "piping" production rules through orElse(Parser) and orElse(Supplier).

For the sake of simplicity, all parsers are composed and evaluated greedily from left to right, unless otherwise noted.

Parsing is one way. Composition should be dealt with by other means, as it is expected to be a far simpler process in itself but support would add a significant amount of complexity to this API.

Field Summary

Fields

Modifier and Type	Field and Description
static Parser<java.lang.String>	MATCHING_ALL Parser for matching a whole string.

Method Summary

Modifier and Type	Method and Description
default <U> Parser<T>	append(Parser<U> parser, java.util.function.BiConsumer<T,U> incorporate) Derive a new Parser instance from the receiving instance.
default Parser<T>	append(java.lang.String pattern) Derive a new Parser instance from the receiving instance.
default Parser<T>	append(java.lang.String pattern, java.util.function.BiConsumer<T,java.lang.String> incorporate) Derive a new Parser instance from the receiving instance.
<U,V> Parser<V>	appendTransform(Parser<U> parser, java.util.function.BiFunction<T,U,? extends V> incorporate) Derive a new Parser instance from the receiving instance.
<U> Parser<U>	appendTransform(java.lang.String pattern, java.util.function.BiFunction<T,java.lang.String,? extends U> incorporate) Derive a new Parser instance from the receiving instance.
static <T> Parser<T>	from(java.util.function.Supplier<T> supplier) Create a trivial parser matching an empty piece of text and returning a supplied object.
static <T> Parser<java.util.List<T>>	list(Parser<T> element, java.lang.String delimiter) Convenience method to create a Parser which accepts a list of text items, delimited by the given string, which are each parsable according to the given parser.
static <T> Parser<java.util.List<T>>	list(Parser<T> element, java.lang.String delimiter, int minimum) Convenience method to create a Parser which accepts a list of text items, delimited by the given string, which are each parsable according to the given parser.
static Parser<java.lang.String>	matching(java.lang.String regex) Create a trivial parser matching a piece of text to a regular expression and then returning that text unmodified.
static Parser<java.lang.String>	matchingAll()
static <T> Parser<T>	matchingAll(java.util.function.Function<java.lang.String,T> transformation)
Parser<T>	orElse(Parser<? extends T> onFailure) Derive a new Parser instance from the receiving instance.
Parser<T>	orElse(java.util.function.Supplier<? extends T> onFailure) Derive a new Parser instance from the receiving instance.
default Parser<T>	orElse(T onFailure) Derive a new Parser instance from the receiving instance.
T	parse(java.lang.String literal) Parse the given literal according to this parser.
ParseResult<T>	parseSubstring(ParseState currentState) Parse the substring at the given parse state according to this parser.
default <U> Parser<T>	prepend(Parser<U> parser, java.util.function.BiConsumer<T,U> incorporate) Derive a new Parser instance from the receiving instance.
default Parser<T>	prepend(java.lang.String pattern) Derive a new Parser instance from the receiving instance.
default Parser<T>	prepend(java.lang.String pattern, java.util.function.BiConsumer<T,java.lang.String> incorporate) Derive a new Parser instance from the receiving instance.
<U,V> Parser<V>	prependTransform(Parser<U> parser, java.util.function.BiFunction<T,U,? extends V> incorporate) Derive a new Parser instance from the receiving instance.
<U> Parser<U>	prependTransform(java.lang.String pattern, java.util.function.BiFunction<T,java.lang.String,? extends U> incorporate) Derive a new Parser instance from the receiving instance.
static <T> Parser<T>	proxy(java.util.function.Supplier<Parser<T>> parser) Create a proxy of a parser supplied at a future time.
<U> Parser<U>	transform(java.util.function.Function<? super T,? extends U> transform) Derive a new Parser instance from the receiving instance.
default <U> Parser<T>	tryAppend(Parser<U> parser, java.util.function.BiConsumer<T,U> incorporate) Derive a new Parser instance from the receiving instance.
<U> Parser<T>	tryAppendTransform(Parser<U> parser, java.util.function.BiFunction<T,U,? extends T> incorporate) Derive a new Parser instance from the receiving instance.
default <U> Parser<T>	tryPrepend(Parser<U> parser, java.util.function.BiConsumer<T,U> incorporate) Derive a new Parser instance from the receiving instance.
<U> Parser<T>	tryPrependTransform(Parser<U> parser, java.util.function.BiFunction<T,U,? extends T> incorporate) Derive a new Parser instance from the receiving instance.

Field Detail

MATCHING_ALL

static final Parser<java.lang.String> MATCHING_ALL

Parser for matching a whole string.

Method Detail

list

static <T> Parser<java.util.List<T>> list(Parser<T> element,
                                          java.lang.String delimiter)

Convenience method to create a Parser which accepts a list of text items, delimited by the given string, which are each parsable according to the given parser.

Type Parameters:

T - The type of the objects to be parsed as elements of the list.

Parameters:

element - The parser responsible for parsing the elements of the list.

delimiter - The string delimiter between parsable text items in the list. This may be set to an empty string.

Returns:

A newly derived Parser which will accept a String representation of a list of items, and parse it into a List instance containing objects parsed from its elements.

list

static <T> Parser<java.util.List<T>> list(Parser<T> element,
                                          java.lang.String delimiter,
                                          int minimum)

Convenience method to create a Parser which accepts a list of text items, delimited by the given string, which are each parsable according to the given parser.

Type Parameters:

T - The type of the objects to be parsed as elements of the list.

Parameters:

element - The parser responsible for parsing the elements of the list.

delimiter - The string delimiter between parsable text items in the list. This may be set to an empty string.

minimum - The minimum length of the list to be parsed.

Returns:

A newly derived Parser which will accept a String representation of a list of items, and parse it into a List instance containing objects parsed from its elements.

matching

static Parser<java.lang.String> matching(java.lang.String regex)

Create a trivial parser matching a piece of text to a regular expression and then returning that text unmodified.

Parameters:

regex - The regular expression matcher

Returns:

A new Parser instance to match the regular expression

matchingAll

static Parser<java.lang.String> matchingAll()

Returns:

a parser for matching a whole string

matchingAll

static <T> Parser<T> matchingAll(java.util.function.Function<java.lang.String,T> transformation)

Parameters:

transformation - a transformation to apply to the string

Returns:

a parser for matching a whole string

from

static <T> Parser<T> from(java.util.function.Supplier<T> supplier)

Create a trivial parser matching an empty piece of text and returning a supplied object.

Type Parameters:

T - The type of the object to supply

Parameters:

supplier - The object to supply when matching an empty piece of text

Returns:

A new Parser instance to supply the given object

proxy

static <T> Parser<T> proxy(java.util.function.Supplier<Parser<T>> parser)

Create a proxy of a parser supplied at a future time.

The supplier will only be invoked at the time of parsing, meaning this method can be used to build self-mentioning parsers. At this time, the parser returned by this method will behave in an identical manner to the supplier parser.

Type Parameters:

T - the type of the object to supply

Parameters:

parser - the supplier of a parser

Returns:

a new Parser instance to proxy the supplied parser

transform

<U> Parser<U> transform(java.util.function.Function<? super T,? extends U> transform)

Derive a new Parser instance from the receiving instance.

The new parser will match the same text as the given parser, but the object parsed will be transformed by the given Function.

Type Parameters:

U - the type of the object of the new parser, post-transformation

Parameters:

transform - the transformation to apply to the object given by application of this parser

Returns:

a new Parser instance which applies the given transformation

orElse

default Parser<T> orElse(T onFailure)

Derive a new Parser instance from the receiving instance.

The new parser will attempt to match a piece of text in the same manner as the receiving parser. If the attempt fails, the text matched, or partially matched, by the original attempt will remain unconsumed, and the parser will instead return the given value.

Parameters:

onFailure - the object the new parser should return if application of the original parser fails

Returns:

a new Parser instance which includes the given failure guard

orElse

Parser<T> orElse(java.util.function.Supplier<? extends T> onFailure)

Derive a new Parser instance from the receiving instance.

The new parser will attempt to match a piece of text in the same manner as the receiving parser. If the attempt fails, the text matched, or partially matched, by the original attempt will remain unconsumed, and the parser will instead return a value from the given supplier.

Parameters:

onFailure - The supplier for the object the new parser should return if application of the original parser fails

Returns:

A new Parser instance which includes the given failure guard

orElse

Parser<T> orElse(Parser<? extends T> onFailure)

Derive a new Parser instance from the receiving instance.

The new parser will attempt to match a piece of text in the same manner as the receiving parser. If the attempt fails, the text matched, or partially matched, by the original attempt will remain unconsumed, then an attempt will be made to instead apply the given parser.

Parameters:

onFailure - The parser which should be applied if and when application of the original parser fails

Returns:

A new Parser instance which includes the given failure guard

append

default Parser<T> append(java.lang.String pattern)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the receiving parser, then match the start of any subsequent text according to the given pattern.

The appended pattern contains no parsable data, and will not change the parsed object upon matching.

Parameters:

pattern - A pattern matching the text which should immediately follow from the text matched by this parser

Returns:

A new Parser instance which also matches against the appended text pattern

appendTransform

<U> Parser<U> appendTransform(java.lang.String pattern,
                              java.util.function.BiFunction<T,java.lang.String,? extends U> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the receiving parser, then match the start of any subsequent text according to the given pattern.

Upon success, the text matched by the appended pattern will be transformed, along with the result of applying the receiving parser, into a new result according to the given function.

Type Parameters:

U - The type of the new parse result

Parameters:

pattern - A pattern matching the text which should immediately follow from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the appended text, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended text pattern

append

default Parser<T> append(java.lang.String pattern,
                         java.util.function.BiConsumer<T,java.lang.String> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the receiving parser, then match the start of any subsequent text according to the given pattern.

Upon success, the text matched by the appended pattern will be consumed, along with the result of applying the receiving parser, allowing the text to inform mutation of the parse result's state.

Parameters:

pattern - A pattern matching the text which should immediately follow from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the appended text, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended text pattern

prepend

default Parser<T> prepend(java.lang.String pattern)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the given pattern, then match the start of any subsequent text according to the receiving parser.

The appended pattern contains no parsable data, and will not change the parsed object upon matching.

Parameters:

pattern - A pattern matching the text which should immediately follow from the text matched by this parser

Returns:

A new Parser instance which also matches against the appended text pattern

prependTransform

<U> Parser<U> prependTransform(java.lang.String pattern,
                               java.util.function.BiFunction<T,java.lang.String,? extends U> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the given pattern, then match the start of any subsequent text according to the receiving parser.

Upon success, the text matched by the appended pattern will be transformed, along with the result of applying the receiving parser, into a new result according to the given function.

Type Parameters:

U - The type of the new parse result

Parameters:

pattern - A pattern matching the text which should immediately precede the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the prepending text, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the prepended text pattern

prepend

default Parser<T> prepend(java.lang.String pattern,
                          java.util.function.BiConsumer<T,java.lang.String> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the given pattern, then match the start of any subsequent text according to the receiving parser.

Upon success, the text matched by the prepended pattern will be consumed, along with the result of applying the receiving parser, allowing the text to inform mutation of the parse result's state.

Parameters:

pattern - A pattern matching the text which should immediately precede the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the prepended text, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the prepended text pattern

appendTransform

<U,V> Parser<V> appendTransform(Parser<U> parser,
                                java.util.function.BiFunction<T,U,? extends V> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the receiving parser, then match the start of any subsequent text according to the given parser.

Upon success, the result of applying the appended parser will be transformed, along with the result of applying the receiving parser, into a new result according to the given function.

Type Parameters:

U - The type of the parse result of the appended parser

V - The type of the new parse result

Parameters:

parser - A parser matching the text immediately following from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the result of parsing the appended parser, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended parser

append

default <U> Parser<T> append(Parser<U> parser,
                             java.util.function.BiConsumer<T,U> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the receiving parser, then match the start of any subsequent text according to the given parser.

Upon success, the result of applying the appended parser will be consumed, along with the result of applying the receiving parser, allowing the text to inform mutation of the parse result's state.

Type Parameters:

U - The type of the parse result of the appended parser

Parameters:

parser - A parser matching the text immediately following from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the result of parsing the appended parser, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended parser

tryAppendTransform

<U> Parser<T> tryAppendTransform(Parser<U> parser,
                                 java.util.function.BiFunction<T,U,? extends T> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the receiving parser, then attempt to match the start of any subsequent text according to the given parser. If the second step - of matching the remaining text with the given parser - fails, then the result of applying the receiving parser alone will be returned.

If application of the appended parser also succeeds, the result of applying the appended parser will be transformed, along with the result of applying the receiving parser, into a new result according to the given function.

Type Parameters:

U - The type of the parse result of the appended parser

Parameters:

parser - A parser matching the text immediately following from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the result of parsing the appended parser, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended parser

tryAppend

default <U> Parser<T> tryAppend(Parser<U> parser,
                                java.util.function.BiConsumer<T,U> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the receiving parser, then attempt to match the start of any subsequent text according to the given parser. If the second step - of matching the remaining text with the given parser - fails, then the result of applying the receiving parser alone will be returned.

If application of the appended parser also succeeds, the result of applying the appended parser will be incorporated with the result of applying the receiving parser, and the result of the receiving parser will then be returned.

Type Parameters:

U - The type of the parse result of the appended parser

Parameters:

parser - A parser matching the text immediately following from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the result of parsing the appended parser, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended parser

prependTransform

<U,V> Parser<V> prependTransform(Parser<U> parser,
                                 java.util.function.BiFunction<T,U,? extends V> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the given parser, then match the start of any subsequent text according to the receiving parser.

Upon success, the result of applying the prepended parser will be transformed, along with the result of applying the receiving parser, into a new result according to the given function.

Type Parameters:

U - The type of the parse result of the appended parser

V - The type of the new parse result

Parameters:

parser - A parser matching the text immediately preceding the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the result of parsing the appended parser, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended parser

prepend

default <U> Parser<T> prepend(Parser<U> parser,
                              java.util.function.BiConsumer<T,U> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the given parser, then match the start of any subsequent text according to the receiving parser.

Upon success, the result of applying the prepended parser will be consumed, along with the result of applying the receiving parser, allowing the text to inform mutation of the parse result's state.

Type Parameters:

U - The type of the parse result of the appended parser

Parameters:

parser - A parser matching the text immediately following from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the result of parsing the appended parser, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended parser

tryPrependTransform

<U> Parser<T> tryPrependTransform(Parser<U> parser,
                                  java.util.function.BiFunction<T,U,? extends T> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the given parser, then attempt to match the start of any subsequent text according to the receiving parser. If the first step - of matching the remaining text with the given parser - fails, then the result of applying the receiving parser alone will be returned.

If application of the prepended parser also succeeds, the result of applying the prepended parser will be transformed, along with the result of applying the receiving parser, into a new result according to the given function.

Type Parameters:

U - The type of the parse result of the appended parser

Parameters:

parser - A parser matching the text immediately following from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the result of parsing the appended parser, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended parser

tryPrepend

default <U> Parser<T> tryPrepend(Parser<U> parser,
                                 java.util.function.BiConsumer<T,U> incorporate)

Derive a new Parser instance from the receiving instance.

The new parser will first match the start of the text according to the given parser, then attempt to match the start of any subsequent text according to the receiving parser. If the first step - of matching the remaining text with the given parser - fails, then the result of applying the receiving parser alone will be returned.

If application of the prepended parser also succeeds, the result of applying the prepended parser will be incorporated with the result of applying the receiving parser, and the result of the receiving parser will then be returned.

Type Parameters:

U - The type of the parse result of the appended parser

Parameters:

parser - A parser matching the text immediately following from the text matched by this parser

incorporate - A function taking the result of parsing the receiving parser and the result of parsing the appended parser, and transforming them into a new parse result

Returns:

A new Parser instance which also matches against the appended parser

parse

T parse(java.lang.String literal)

Parse the given literal according to this parser.

Parameters:

literal - the string literal to parse

Returns:

the object result of parsing

parseSubstring

ParseResult<T> parseSubstring(ParseState currentState)

Parse the substring at the given parse state according to this parser.

Parameters:

currentState - the current parse state over a string literal

Returns:

the object result of parsing