parsley
5.0.0-M2
API
Generated with
parsley/parsley/state/Ref

Ref

parsley.state.Ref
See theRef companion object
class Ref[A]

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
class Object
trait Matchable
class Any

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.

def get: Parsley[A]

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
def gets[B](f: A => B): Parsley[B]

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
def gets[B](pf: Parsley[A => B]): Parsley[B]

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.

def set(x: A): Parsley[Unit]

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
def set(p: Parsley[A]): Parsley[Unit]

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
def sets[B](p: Parsley[B], f: B => A): Parsley[Unit]

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.

def update(f: A => A): Parsley[Unit]

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
def update(pf: Parsley[A => A]): Parsley[Unit]

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.

def rollback[B](p: Parsley[B]): Parsley[B]

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
def setDuring[B](x: A)(p: Parsley[B]): Parsley[B]

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 state x.

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
def setDuring[B](p: Parsley[A])(q: => Parsley[B]): Parsley[B]

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
def updateDuring[B](f: A => A)(p: Parsley[B]): Parsley[B]

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
Generated with