Class CharParser<T>

Namespace

Farkle

Assembly

Farkle.dll

Provides the base class of Farkle's default parsers.

public abstract class CharParser<T> : IParser<char, T>, IServiceProvider

Type Parameters

T

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

Inheritance

object

CharParser<T>

Implements

IParser<char, T>

IServiceProvider

Extension Methods

ParserExtensions.ParseAsync<T>(IParser<char, T>, TextReader, CancellationToken)

ParserExtensions.ParseFileAsync<T>(IParser<char, T>, string, CancellationToken)

ParserExtensions.ParseFile<T>(IParser<char, T>, string)

ParserExtensions.Parse<T>(IParser<char, T>, TextReader)

ParserExtensions.Parse<T>(IParser<char, T>, string)

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

Remarks

This class is the replacement of the RuntimeFarkle class of Farkle 6. It extends IParser<TChar, T> with features like swapping the parser's Tokenizer<TChar> and ISemanticProvider<TChar, T>, getting the parser's Grammar and representing parsers that will always fail because of problems with the grammar.

CharParser<T>s are immutable, stateless and thread-safe. Methods that customize them return new instances.

Unlike IParser<TChar, T>, CharParser<T> cannot be inherited by user code.

Properties

IsFailing

Whether the CharParser<T> will always fail because of problems with the grammar.

public bool IsFailing { get; }

Property Value

bool

Remarks

The error can be retrieved by parsing an empty string.

If the problem is in the grammar's lexical analysis tables, the parser can be fixed by changing the tokenizer.

Methods

GetGrammar()

Gets the Grammar used by the CharParser<T>.

public Grammar GetGrammar()

Returns

Grammar

GetService(Type)

Implements GetService(Type).

public object? GetService(Type serviceType)

Parameters

serviceType Type

Returns

object

Remarks

The following services are always provided by CharParser<T>:

• IGrammarProvider

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

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

public abstract void Run(ref ParserInputReader<char> input, ref ParserCompletionState<T> completionState)

Parameters

input ParserInputReader<char>

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

ToSyntaxChecker()

Converts a CharParser<T> to a syntax checker.

public CharParser<object?> ToSyntaxChecker()

Returns

CharParser<object>

See Also

CreateSyntaxChecker(Grammar)

ToSyntaxChecker<TNew>()

Converts a CharParser<T> to a syntax checker with a user-defined return type.

public CharParser<TNew?> ToSyntaxChecker<TNew>() where TNew : class?

Returns

CharParser<TNew>

Type Parameters

TNew

See Also

CreateSyntaxChecker<T>(Grammar)

WithSemanticProvider<TNew>(ISemanticProvider<char, TNew>)

Changes the semantic provider of the CharParser<T> to an ISemanticProvider<TChar, T>.

public CharParser<TNew> WithSemanticProvider<TNew>(ISemanticProvider<char, TNew> semanticProvider)

Parameters

semanticProvider ISemanticProvider<char, TNew>

The semantic provider of the new parser.

Returns

CharParser<TNew>

A CharParser<T> that returns TNew on success and has semanticProvider as its semantic provider.

Type Parameters

TNew

The result type of the new parser.

Exceptions

ArgumentNullException

semanticProvider is null.

WithSemanticProvider<TNew>(Func<IGrammarProvider, ISemanticProvider<char, TNew>>)

Changes the semantic provider of the CharParser<T> to an ISemanticProvider<TChar, T> that depends on the parser's grammar.

public CharParser<TNew> WithSemanticProvider<TNew>(Func<IGrammarProvider, ISemanticProvider<char, TNew>> semanticProviderFactory)

Parameters

semanticProviderFactory Func<IGrammarProvider, ISemanticProvider<char, TNew>>

A delegate that accepts an IGrammarProvider and returns a semantic provider.

Returns

CharParser<TNew>

A CharParser<T> that returns TNew on success and has the result of semanticProviderFactory as its semantic provider.

Type Parameters

TNew

The result type of the new parser.

Remarks

In certain failing parsers, semanticProviderFactory will not be called.

Exceptions

ArgumentNullException

semanticProviderFactory is null.

WithTokenizer(Tokenizer<char>)

Changes the tokenizer of the CharParser<T> to a Tokenizer<TChar>.

public CharParser<T> WithTokenizer(Tokenizer<char> tokenizer)

Parameters

tokenizer Tokenizer<char>

The tokenizer of the new parser.

Returns

CharParser<T>

A CharParser<T> with tokenizer as its tokenizer.

Remarks

In certain failing parsers, this method will have no effect and return this.

Exceptions

ArgumentNullException

tokenizer is null.

WithTokenizer(Func<IGrammarProvider, Tokenizer<char>>)

Changes the tokenizer of the CharParser<T> to a Tokenizer<TChar> that depends on a grammar.

public CharParser<T> WithTokenizer(Func<IGrammarProvider, Tokenizer<char>> tokenizerFactory)

Parameters

tokenizerFactory Func<IGrammarProvider, Tokenizer<char>>

A delegate that accepts an IGrammarProvider and returns a tokenizer.

Returns

CharParser<T>

A CharParser<T> with the result of tokenizerFactory as its tokenizer.

Remarks

In certain failing parsers this method will have no effect and return this.

Exceptions

ArgumentNullException

tokenizerFactory is null.

WithTokenizerChain(params ChainedTokenizerComponent<char>[])

Changes the tokenizer of the CharParser<T> to a chained tokenizer to be built from a sequence of ChainedTokenizerComponent<TChar>s.

public CharParser<T> WithTokenizerChain(params ChainedTokenizerComponent<char>[] components)

Parameters

components ChainedTokenizerComponent<char>[]

The sequence of chained tokenizer components.

Returns

CharParser<T>

Remarks

In certain failing parsers this method will have no effect and return this.

Exceptions

ArgumentException

components is empty.

WithTokenizerChain(params ReadOnlySpan<ChainedTokenizerComponent<char>>)

Changes the tokenizer of the CharParser<T> to a chained tokenizer to be built from a sequence of ChainedTokenizerComponent<TChar>s.

public CharParser<T> WithTokenizerChain(params ReadOnlySpan<ChainedTokenizerComponent<char>> components)

Parameters

components ReadOnlySpan<ChainedTokenizerComponent<char>>

The sequence of chained tokenizer components.

Returns

CharParser<T>

Remarks

In certain failing parsers this method will have no effect and return this.

Exceptions

ArgumentException

components is empty.