Expectation

abstract class Expectation<T, in R>(val stateCallback: StateCallback<T, R, *>? = null)

General class for an expectation.

Expectations are the core of the parsing algorithms used by Niwen Parser, and a way to express what we expect the chain of tokens to look like in order to be parsed into an abstract syntax tree.

Each node of the tree is described as a list of expectations over a chain of token. In other words, constructing a node is as simple as just checking if the list of expectations matches the chain of tokens.

Recognizing tokens is not just about expectations: we also need to store the matched value of some expectations. Take a string for example:

"Hello World!"

While the quotation marks (") are not useful for the abstract syntax tree (the fact that this is a string will be represented by having a node type specific to string values), the content of the string is very important. Therefore, expectations also know where their matched value should be stored through the storeValueIn property. This stored value can then be retrieved through the TypeDescription's arguments and are passed using the make function in the ParserNodeDeclaration.

If storeValueIn is null, that means that:

  • this expectation cannot store value (it does not "emit" anything, like the either construct which just executes branches and picks the first result), or

  • this expectation can store values but we do not want to store it for this expectation

Parser algorithms assume that expectations always expect some tokens to be present (e.g. if we run out of tokens, we fail immediately instead of letting the expectation crash). If the expectation can handle situations where there are not enough tokens, then it should implement the HandlesTokenDrought marker interface.

Parameters

T

Type this expectation is run in.

R

Result this expectation will produce. For explanations on the variance of this type, see NodeParameterKey

Inheritors

Constructors

Link copied to clipboard
constructor(stateCallback: StateCallback<T, R, *>? = null)

Functions

Link copied to clipboard
abstract fun matches(context: ParsingContext, index: Int): ExpectationResult<T>

Check if this expectation matches the given context at the given index among the context's tokens list.

Properties

Link copied to clipboard
val stateCallback: StateCallback<T, R, *>? = null

The name of the argument where the result of this expectation should be stored, or null if the matched value of this expectation should not or cannot be stored.

Link copied to clipboard
abstract val title: String

Title of this expectation. This should be a shortened description of what this expectation is. For example, an expectation for a node could have the title expect(SomeNode). If possible and legible, this title should be similar to the DSL expression for creating the expectation