Class GrammarBuilderExtensions

Namespace

Farkle.Builder

Assembly

Farkle.dll

Contains extension methods that to set configuration options on IGrammarBuilder and IGrammarBuilder<T>.

public static class GrammarBuilderExtensions

Inheritance

object

GrammarBuilderExtensions

Remarks

These methods do not modify the object they are called on. Instead, they return a new object with the requested configuration option changed.

Because these methods apply to the entire grammar, they must be called on the topmost symbol of the grammar, and after the methods on GrammarSymbolExtensions. Failure to do so will result in compile errors.

Methods

AddBlockComment(IGrammarBuilder, string, string)

Adds a comment to the grammar that starts and ends with specific sequences of characters.

public static IGrammarBuilder AddBlockComment(this IGrammarBuilder builder, string start, string end)

Parameters

builder IGrammarBuilder

The grammar builder.

start string

The sequence of characters that starts the comment.

end string

The sequence of characters that ends the comment.

Returns

IGrammarBuilder

AddBlockComment<T>(IGrammarBuilder<T>, string, string)

Adds a comment to the grammar that starts and ends with specific sequences of characters.

public static IGrammarBuilder<T> AddBlockComment<T>(this IGrammarBuilder<T> builder, string start, string end)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

start string

The sequence of characters that starts the comment.

end string

The sequence of characters that ends the comment.

Returns

IGrammarBuilder<T>

Type Parameters

T

AddLineComment(IGrammarBuilder, string)

Adds a comment to the grammar that starts with a specific sequence of characters and ends at the end of a line or the end of the input.

public static IGrammarBuilder AddLineComment(this IGrammarBuilder builder, string start)

Parameters

builder IGrammarBuilder

The grammar builder.

start string

The sequence of characters that starts the comment.

Returns

IGrammarBuilder

AddLineComment<T>(IGrammarBuilder<T>, string)

Adds a comment to the grammar that starts with a specific sequence of characters and ends at the end of a line or the end of the input.

public static IGrammarBuilder<T> AddLineComment<T>(this IGrammarBuilder<T> builder, string start)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

start string

The sequence of characters that starts the comment.

Returns

IGrammarBuilder<T>

Type Parameters

T

AddNoiseSymbol(IGrammarBuilder, string, Regex)

Adds a noise symbol to the grammar that will be ignored if it is encountered in the input.

public static IGrammarBuilder AddNoiseSymbol(this IGrammarBuilder builder, string name, Regex regex)

Parameters

builder IGrammarBuilder

The grammar builder.

name string

The name of the noise symbol. Used for diagnostics and documentation purposes only.

regex Regex

The regular expression that matches the noise symbol.

Returns

IGrammarBuilder

AddNoiseSymbol<T>(IGrammarBuilder<T>, string, Regex)

Adds a noise symbol to the grammar that will be ignored if it is encountered in the input.

public static IGrammarBuilder<T> AddNoiseSymbol<T>(this IGrammarBuilder<T> builder, string name, Regex regex)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

name string

The name of the noise symbol. Used for diagnostics and documentation purposes only.

regex Regex

The regular expression that matches the noise symbol.

Returns

IGrammarBuilder<T>

Type Parameters

T

AutoWhitespace(IGrammarBuilder, bool)

Changes whether whitespace is automatically ignored in the grammar.

public static IGrammarBuilder AutoWhitespace(this IGrammarBuilder builder, bool value)

Parameters

builder IGrammarBuilder

The grammar builder.

value bool

Whether to automatically ignore whitespace in the grammar.

Returns

IGrammarBuilder

Remarks

This option is set to true by default. Whitespace is defined as the characters '\t', '\n', '\r', and ' '.

AutoWhitespace<T>(IGrammarBuilder<T>, bool)

Changes whether whitespace is automatically ignored in the grammar.

public static IGrammarBuilder<T> AutoWhitespace<T>(this IGrammarBuilder<T> builder, bool value)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

value bool

Whether to automatically ignore whitespace in the grammar.

Returns

IGrammarBuilder<T>

Type Parameters

T

Remarks

This option is set to true by default. Whitespace is defined as the characters '\t', '\n', '\r', and ' '.

BuildSyntaxCheck(IGrammarBuilder, BuilderArtifacts, BuilderOptions?)

Builds multiple artifacts from the given untyped IGrammarBuilder.

public static BuilderResult<object?> BuildSyntaxCheck(this IGrammarBuilder builder, BuilderArtifacts artifacts, BuilderOptions? options = null)

Parameters

builder IGrammarBuilder

The grammar to build.

artifacts BuilderArtifacts

The set of artifacts to build.

options BuilderOptions

Used to customize the building process. Optional.

Returns

BuilderResult<object>

A BuilderResult<T> object with the properties of the requested artifacts populated.

Remarks

The builder will reuse resources to build the requested artifacts where applicable.

Additional artifacts may be built beyond the ones requested, if they are dependencies of the requested artifacts. For example, if CharParser is requested, the builder will also build TokenizerOnChar, SemanticProviderOnChar.

If requested, the builder will create a syntax-checking parser and semantic provider that will not execute any semantic actions and produce null semantic values on success.

BuildSyntaxCheck(IGrammarBuilder, BuilderOptions?)

Creates a syntax-checking CharParser<T> from the given IGrammarBuilder<T>.

public static CharParser<object?> BuildSyntaxCheck(this IGrammarBuilder builder, BuilderOptions? options = null)

Parameters

builder IGrammarBuilder

The grammar to build.

options BuilderOptions

Used to customize the building process. Optional.

Returns

CharParser<object>

A CharParser<T> object that can be used to parse text, and will always return null on success.

Remarks

If building the grammar failed, the parser's IsFailing property will be true. Detailed error information can be obtained by trying to parse any text, and casting the result's Error property to IReadOnlyList<T> of type BuilderDiagnostic.

BuildSyntaxCheck<T>(IGrammarBuilder, BuilderArtifacts, BuilderOptions?)

Builds multiple artifacts from the given untyped IGrammarBuilder.

public static BuilderResult<T?> BuildSyntaxCheck<T>(this IGrammarBuilder builder, BuilderArtifacts artifacts, BuilderOptions? options = null) where T : class?

Parameters

builder IGrammarBuilder

The grammar to build.

artifacts BuilderArtifacts

The set of artifacts to build.

options BuilderOptions

Used to customize the building process. Optional.

Returns

BuilderResult<T>

A BuilderResult<T> object with the properties of the requested artifacts populated.

Type Parameters

T

The supposed return type of the parser and the semantic provider. Must be a reference type.

Remarks

The builder will reuse resources to build the requested artifacts where applicable.

Additional artifacts may be built beyond the ones requested, if they are dependencies of the requested artifacts. For example, if CharParser is requested, the builder will also build TokenizerOnChar, SemanticProviderOnChar.

If requested, the builder will create a syntax-checking parser and semantic provider that will not execute any semantic actions and produce null semantic values on success.

BuildSyntaxCheck<T>(IGrammarBuilder, BuilderOptions?)

Creates a syntax-checking CharParser<T> from the given IGrammarBuilder<T>.

public static CharParser<T?> BuildSyntaxCheck<T>(this IGrammarBuilder builder, BuilderOptions? options = null) where T : class?

Parameters

builder IGrammarBuilder

The grammar to build.

options BuilderOptions

Used to customize the building process. Optional.

Returns

CharParser<T>

A CharParser<T> object that can be used to parse text, and will always return null on success.

Type Parameters

T

The supposed return type of the parser. Must be a reference type.

Remarks

If building the grammar failed, the parser's IsFailing property will be true. Detailed error information can be obtained by trying to parse any text, and casting the result's Error property to IReadOnlyList<T> of type BuilderDiagnostic.

Build<T>(IGrammarBuilder<T>, BuilderArtifacts, BuilderOptions?)

Builds multiple artifacts from the given IGrammarBuilder<T>.

public static BuilderResult<T> Build<T>(this IGrammarBuilder<T> builder, BuilderArtifacts artifacts, BuilderOptions? options = null)

Parameters

builder IGrammarBuilder<T>

The grammar to build.

artifacts BuilderArtifacts

The set of artifacts to build.

options BuilderOptions

Used to customize the building process. Optional.

Returns

BuilderResult<T>

A BuilderResult<T> object with the properties of the requested artifacts populated.

Type Parameters

T

The type of objects the parser will produce in case of success.

Remarks

The builder will reuse resources to build the requested artifacts where applicable.

Additional artifacts may be built beyond the ones requested, if they are dependencies of the requested artifacts. For example, if CharParser is requested, the builder will also build TokenizerOnChar, SemanticProviderOnChar.

Build<T>(IGrammarBuilder<T>, BuilderOptions?)

Creates a CharParser<T> from the given IGrammarBuilder<T>.

public static CharParser<T> Build<T>(this IGrammarBuilder<T> builder, BuilderOptions? options = null)

Parameters

builder IGrammarBuilder<T>

The grammar to build.

options BuilderOptions

Used to customize the building process. Optional.

Returns

CharParser<T>

A CharParser<T> object that can be used to parse text. If building the grammar failed, the parser's IsFailing property will be true. Detailed error information can be obtained by trying to parse any text, and casting the result's Error property to IReadOnlyList<T> of type BuilderDiagnostic.

Type Parameters

T

The return type of the parser or semantic provider.

CaseSensitive(IGrammarBuilder, CaseSensitivity)

Changes the case sensitivity option of a grammar. This overload accepts a CaseSensitivity value for more flexibility.

public static IGrammarBuilder CaseSensitive(this IGrammarBuilder builder, CaseSensitivity value)

Parameters

builder IGrammarBuilder

The grammar builder.

value CaseSensitivity

The case sensitivity option for the grammar.

Returns

IGrammarBuilder

CaseSensitive(IGrammarBuilder, bool)

Changes the case sensitivity option of a grammar. This overload accepts a bool value for convenience and compatibility.

public static IGrammarBuilder CaseSensitive(this IGrammarBuilder builder, bool value = true)

Parameters

builder IGrammarBuilder

The grammar builder.

value bool

Whether the grammar will be case sensitive or not.

Returns

IGrammarBuilder

CaseSensitive<T>(IGrammarBuilder<T>, CaseSensitivity)

Changes the case sensitivity option of a grammar. This overload accepts a CaseSensitivity value for more flexibility.

public static IGrammarBuilder<T> CaseSensitive<T>(this IGrammarBuilder<T> builder, CaseSensitivity value)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

value CaseSensitivity

The case sensitivity option for the grammar.

Returns

IGrammarBuilder<T>

Type Parameters

T

CaseSensitive<T>(IGrammarBuilder<T>, bool)

Changes the case sensitivity option of a grammar. This overload accepts a bool value for convenience and compatibility.

public static IGrammarBuilder<T> CaseSensitive<T>(this IGrammarBuilder<T> builder, bool value = true)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

value bool

Whether the grammar will be case sensitive or not.

Returns

IGrammarBuilder<T>

Type Parameters

T

Cast(IGrammarBuilder)

Changes the type of IGrammarBuilder to a generic IGrammarBuilder<T> of type object, forcing it to return a value.

public static IGrammarBuilder<object?> Cast(this IGrammarBuilder builder)

Parameters

builder IGrammarBuilder

The grammar builder.

Returns

IGrammarBuilder<object>

An IGrammarBuilder<T> that returns the object builder would return. If builder had been created with the untyped API, the returned object will be null.

NewLineIsNoisy(IGrammarBuilder, bool)

Changes whether to ignore unexpected occurrences of NewLine symbols in the grammar.

public static IGrammarBuilder NewLineIsNoisy(this IGrammarBuilder builder, bool value)

Parameters

builder IGrammarBuilder

The grammar builder.

value bool

Whether to ignore unexpected new lines in the grammar.

Returns

IGrammarBuilder

Remarks

In versions of Farkle prior to 7 this option did not exist and the behavior was always equivalent to false. Since Farkle 7 the option's default value was changed to be equal to the option set in AutoWhitespace(IGrammarBuilder, bool). The reason for this change is that the previous behavior was unintuitive and rarely useful.

If the grammar does not contain a NewLine symbol, this option has no effect.

NewLineIsNoisy<T>(IGrammarBuilder<T>, bool)

Changes whether whitespace is automatically ignored in the grammar.

public static IGrammarBuilder<T> NewLineIsNoisy<T>(this IGrammarBuilder<T> builder, bool value)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

value bool

Whether to automatically ignore whitespace in the grammar.

Returns

IGrammarBuilder<T>

Type Parameters

T

Remarks

This option is set to true by default. Whitespace is defined as the characters '\t', '\n', '\r', and ' '.

WithGrammarName(IGrammarBuilder, string)

Changes the name of the grammar.

public static IGrammarBuilder WithGrammarName(this IGrammarBuilder builder, string value)

Parameters

builder IGrammarBuilder

The grammar builder.

value string

The new name of the grammar.

Returns

IGrammarBuilder

Remarks

This value is used only for diagnostic and documentation purposes. Its default value is equal to the Name of the grammar's start symbol.

See Also

Name

Name

WithGrammarName<T>(IGrammarBuilder<T>, string)

Changes the name of the grammar.

public static IGrammarBuilder<T> WithGrammarName<T>(this IGrammarBuilder<T> builder, string value)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

value string

The new name of the grammar.

Returns

IGrammarBuilder<T>

Type Parameters

T

Remarks

This value is used only for diagnostic and documentation purposes. Its default value is equal to the Name of the grammar's start symbol.

See Also

Name

Name

WithOperatorScope(IGrammarBuilder, params AssociativityGroup[])

Changes the OperatorScope used to resolve parser conflicts in the grammar.

public static IGrammarBuilder WithOperatorScope(this IGrammarBuilder builder, params AssociativityGroup[] associativityGroups)

Parameters

builder IGrammarBuilder

The grammar builder.

associativityGroups AssociativityGroup[]

The AssociativityGroups that will comprise the scope, in ascending order of precedence.

Returns

IGrammarBuilder

WithOperatorScope(IGrammarBuilder, params OperatorScope)

Changes the OperatorScope used to resolve parser conflicts in the grammar.

public static IGrammarBuilder WithOperatorScope(this IGrammarBuilder builder, params OperatorScope value)

Parameters

builder IGrammarBuilder

The grammar builder.

value OperatorScope

The OperatorScope to use in the grammar.

Returns

IGrammarBuilder

Remarks

In versions of Farkle prior to 7 this option could be applied to individual symbols and still had effect on the entire grammar. Since Farkle 7 a grammar may only have one operator scope. The reason for this change is that the previous behavior had limited utility and lots of edge cases that were difficult to define and handle.

WithOperatorScope<T>(IGrammarBuilder<T>, params AssociativityGroup[])

Changes the OperatorScope used to resolve parser conflicts in the grammar.

public static IGrammarBuilder<T> WithOperatorScope<T>(this IGrammarBuilder<T> builder, params AssociativityGroup[] associativityGroups)

Parameters

builder IGrammarBuilder<T>

The grammar builder.

associativityGroups AssociativityGroup[]

The AssociativityGroups that will comprise the scope, in ascending order of precedence.

Returns

IGrammarBuilder<T>

Type Parameters

T

WithOperatorScope<T>(IGrammarBuilder<T>, params OperatorScope)

public static IGrammarBuilder<T> WithOperatorScope<T>(this IGrammarBuilder<T> builder, params OperatorScope value)

Parameters

builder IGrammarBuilder<T>

value OperatorScope

Returns

IGrammarBuilder<T>

Type Parameters

T