Interface IParser<TChar, T>

Namespace

Farkle.Parser

Assembly

Farkle.dll

Encapsulates the logic of converting sequences of characters into meaningful objects.

public interface IParser<TChar, T> : IServiceProvider

Type Parameters

TChar

The type of characters that are parsed. Usually it is char or byte (not supported by Farkle's built-in parsers).

T

The type of objects the parser produces in case of success.

Inherited Members

IServiceProvider.GetService(Type)

Extension Methods

ParserExtensions.Parse<TChar, T>(IParser<TChar, T>, ReadOnlySpan<TChar>)

Remarks

This is the base interface for Farkle's parser API and encapsulates the lexical, syntactical and semantic analysis stages. It supports high-performance parsing of text from either a contiguous buffer or from streaming input.

IParser<TChar, T> is the lowest-level parser API of Farkle. Higher-level APIs exist in the form of ParserExtensions and ParserStateContext<TChar, T>.

Objects implementing IParser<TChar, T> must be stateless and thread-safe. To provide additional functionality, IParser<TChar, T> inherits from the IServiceProvider interface.

Methods

Run(ref ParserInputReader<TChar>, ref ParserCompletionState<T>)

Moves forward a parsing operation by parsing a block of characters.

void Run(ref ParserInputReader<TChar> input, ref ParserCompletionState<T> completionState)

Parameters

input ParserInputReader<TChar>

Used to access the characters and the operation's ParserState.

completionState ParserCompletionState<T>

Used to set that the operation has completed.

Remarks

This method must be invoked after reading new characters from the input source. To determine how many characters in the buffer should be kept, compare the TotalCharactersConsumed before and after running the parser.

After a result has been set to completionState the parsing operation has completed and the parser should not run again with the same parameters.

For compatibility with Farkle's higher-level parsing APIs, running a parser whose input's IsFinalBlock property is set to true should set a result to completionState. Custom parsers can support deviating from this behavior, but must do it in an opt-in fashion.

While using this method to parse a single contiguous buffer is simple, directly using it to parse streaming input is non-trivial and requires manually managing the character buffer. Parsing streaming input is best done by using ParserExtensions or a ParserStateContext<TChar, T>.

See Also

ParserExtensions

ParserStateContext