This class is used to index references within the mutable state.
Attributes
- Note
-
it is undefined behaviour to use a reference in multiple different independent parsers. You should be careful to parameterise the references in shared parsers and allocate fresh ones for each "top-level" parser you will run.
- Companion
- object
- Source
- state.scala
- Graph
-
- Supertypes
Members list
Grouped members
Getters
These combinators allow for the retrieval of the stateful value of a reference, and injecting it into the parsing context. Does not modify the contents of the reference itself.
This combinator injects the value stored in this reference into a parser.
This combinator injects the value stored in this reference into a parser.
Allows for the value stored in this reference to be purely injected into the parsing context. No input is consumed in this process, and it cannot fail.
Attributes
- Returns
-
a parser that returns the value stored in this reference.
- Since
-
3.2.0
- Example
-
Get-Get Law:
r.get *> r.get == r.get r.get <~> r.get == r.get.map(x => (x, x))
- Source
- state.scala
This combinator injects the value stored in this reference into a parser after applying a function to it.
This combinator injects the value stored in this reference into a parser after applying a function to it.
Allows for the value stored in this reference to be purely injected into the parsing context but the function f
is applied first. No input is consumed in this process, and it cannot fail.
Type parameters
- B
-
the desired result type.
Value parameters
- f
-
the function used to transform the value in this reference.
Attributes
- Returns
-
the value stored in this reference applied to
f
. - Since
-
3.2.0
- Source
- state.scala
This combinator injects the value stored in this reference into a parser after applying a function obtained from a parser to it.
This combinator injects the value stored in this reference into a parser after applying a function obtained from a parser to it.
First, pf
is parsed, producing the function f
on success. Then, the value stored in this reference x
is applied to the function f
. The combinator returns f(x)
. Only pf
is allowed to consume input. If pf
fails, the combinator fails, otherwise it will succeed.
Type parameters
- B
-
the desired result type.
Value parameters
- pf
-
the parser that produces the function used to transform the value in this reference.
Attributes
- Returns
-
the value stored in this reference applied to a function generated from
pf
. - Since
-
3.2.0
- Source
- state.scala
Setters
These combinators directly update the value contained within a reference. This new value can be provided directly or sourced from a parser.
This combinator stores a new value into this reference.
This combinator stores a new value into this reference.
Without any other effect, the value x
will be placed into this reference.
Value parameters
- x
-
the value to place in the reference.
Attributes
- Since
-
4.5.0
- Example
-
Set-Get Law:
r.set(x) *> r.get == r.set(x).as(x)
Set-Set Law:
r.set(x) *> r.set(y) == r.set(y)
- Source
- state.scala
This combinator stores a new value into this reference.
This combinator stores a new value into this reference.
First, parse p
to obtain its result x
. Then store x
into this reference without any further effect. If p
fails this combinator fails.
Value parameters
- p
-
the parser that produces the value to store in the reference.
Attributes
- Since
-
4.5.0
- Example
-
Get-Set Law:
r.set(r.get) == unit
Set-Set Law:
// only when `q` does not inspect the value of `r`! r.set(p) *> r.set(q) == p *> r.set(q)
- Source
- state.scala
This combinator stores a new value into this reference.
This combinator stores a new value into this reference.
First, parse p
to obtain its result x
. Then store f(x)
into this reference without any further effect. If p
fails this combinator fails.
Equivalent to
this.set(p.map(f))
Value parameters
- f
-
a function which adapts the result of
p
so that it can fit into this reference. - p
-
the parser that produces the value to store in the reference.
Attributes
- Since
-
4.5.0
- Source
- state.scala
Modification
These combinators modify the value stored within a reference by using a function. The function used can be provided directly or sourced from a parser.
This combinator modifies the value stored in this reference with a function.
This combinator modifies the value stored in this reference with a function.
Without any other effect, get the value stored in this reference, x
, and put back f(x)
.
Equivalent to
this.set(this.gets(f))
Value parameters
- f
-
the function used to modify this reference's value.
Attributes
- Since
-
4.5.0
- Source
- state.scala
This combinator modifies the value stored in this reference with a function.
This combinator modifies the value stored in this reference with a function.
First, parse pf
to obtain its result f
. Then get the value stored in this reference, x
, and put back f(x)
. If p
fails this combinator fails.
Equivalent to
this.set(this.gets(pf))
Value parameters
- pf
-
the parser that produces the function used to transform the value in this reference.
Attributes
- Since
-
4.5.0
- Source
- state.scala
Local Modification
These combinators allow for some form of local stateful modification. This means that any changes to the reference may be reverted after the execution of the parser: this may be on the parsers success, but it could also involve the parsers failure.
This combinator rolls-back any changes to this reference made by a given parser if it fails.
This combinator rolls-back any changes to this reference made by a given parser if it fails.
First get the current value in this reference xold
. Then parse p
, if it succeeds, producing y
, then y
is returned and this reference retains its value post-p
. Otherwise, if p
failed without consuming input, xold
is placed back into this reference and this combinator fails.
This can be used in conjunction with local to make an almost unconditional state restore:
// `r`'s state is always rolled back after `p` unless it fails having consumed input.
r.rollback(r.local(x)(p))
Value parameters
- p
-
the parser to perform.
Attributes
- Returns
-
the result of the parser
p
, if any. - Since
-
3.2.0
- Source
- state.scala
This combinator changed the value stored in this reference for the duration of a given parser, resetting it afterwards.
This combinator changed the value stored in this reference for the duration of a given parser, resetting it afterwards.
First get the current value in this reference xold
, then place x
into this reference without any further effect. Then, parse p
, producing result y
on success. Finally, put xold
back into this reference and return y
. If p
fails, the whole combinator fails and the state is not restored.
Value parameters
- p
-
the parser to execute with the adjusted state.
- x
-
the value to place into this reference.
Attributes
- Returns
-
the parser that performs
p
with the modified statex
. - Since
-
4.5.0
- Example
-
Set-Set Law:
r.set(x) *> r.setDuring(y)(p) == r.set(y) *> p <* r.set(x)
- Source
- state.scala
This combinator changed the value stored in this reference for the duration of a given parser, resetting it afterwards.
This combinator changed the value stored in this reference for the duration of a given parser, resetting it afterwards.
First get the current value in this reference xold
, then parse p
to get the result x
, placing it into this reference without any further effect. Then, parse q
, producing result y
on success. Finally, put xold
back into this reference and return y
. If p
or q
fail, the whole combinator fails and the state is not restored.
Value parameters
- p
-
the parser whose return value is placed in this reference.
- q
-
the parser to execute with the adjusted state.
Attributes
- Returns
-
the parser that performs
q
with the modified state. - Since
-
4.5.0
- Source
- state.scala
This combinator changed the value stored in this reference for the duration of a given parser, resetting it afterwards.
This combinator changed the value stored in this reference for the duration of a given parser, resetting it afterwards.
First get the current value in this reference xold
, then place f(xold)
into this reference without any further effect. Then, parse p
, producing result y
on success. Finally, put xold
back into this reference and return y
. If p
fails, the whole combinator fails and the state is not restored.
Value parameters
- f
-
the function used to modify the value in this reference.
- p
-
the parser to execute with the adjusted state.
Attributes
- Returns
-
the parser that performs
p
with the modified state. - Since
-
4.5.0
- Example
-
Set-Set Law and Set-Get Law:
r.set(x) *> r.updateDuring(f)(p) == r.set(f(x)) *> p <* r.set(x)
- Source
- state.scala