NodeParameterKey

A key used when storing state within Niwen parsers.

State storage in Niwen parsers is based on a map with keys that are instances of this class. These keys are, fundamentally, a type-contextualized typed name, i.e.:

• Some name

• A type typeOf<R>() for that name

• A contextual type T that represents a type on which it's possible to "key" something that is named and typed according to the two above points.

For example, a key for the "bar" property of the following class:

data class Foo(val bar: String) {
    companion object : /* ... */
}

... would be NodeParameterKey<Foo, String>(typeOf<String>(), "bar").

Creating keys

You will generally not need to manually create keys within the Niwen parser DSL. You can create a key:

• from a KProperty1 using asKey, e.g. Foo::bar.asKey()

• with a function call using key

Key variance

Key (pun intended) to understanding the variance of R in this type is how the actual output type (from the perspective of the node) is used.

Imagine the following parser setup:

open class Food
class Strawberry

either<CharSequence> { <<----------------------------+
    // This produces a String                        | Used as input of
    expect(someToken) storeIn <result of either> >>--+
}

In plain English, expect(someToken) exposes a string that is stored, and therefore expects a NodeParameterKey<..., String>. However, we could well say "actually, I want to store the String in a CharSequence", like in the example above. This would be equivalent to passing a String value to a function that expects a CharSequence, which is valid. This is why, despite being an "output" (as in, the type of the value that the key indexes), it is an input variance, because it can (and will) be used as an input for storage purposes.

(Note, the example above is heavily simplified. The real version would use the self() and by subtype() mechanisms).