final class ParsingRun[+T] extends AnyRef
Models an in-progress parsing run; contains all the mutable state that may be necessary during the parse, in order to avoid the individual parsers needing to perform their own allocations and instantiations, and greatly improving performance
There are a few patterns that let us program with these mutable variables in a sort-of-pure-functional way:
- If a parser that wishes to ignore changes to a field within their child parsers, a common pattern is to save the value of the field before the wrapped parser runs, and then re-set the field. e.g. this can be used to backtrack index after a lookahead parser finishes
- If a parser wants to read the value of the field "returned" by multiple child parsers, make sure to read the field into a local variable after each child parser is complete to make sure the value you want from an earlier child isn't stomped over by a later child
In general, for a parser to "return" a value in a mutable field, it is sufficient to simply set the value of that field before returning. It is the parent-parser's responsibility to make sure it reads out the value of the field to a local variable before running another child parser that will over-write the mutable field
- Alphabetic
- By Inheritance
- ParsingRun
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Instance Constructors
-
new
ParsingRun(input: ParserInput, startIndex: Int, originalParser: (ParsingRun[_]) ⇒ ParsingRun[_], traceIndex: Int, instrument: Instrument, failureAggregate: List[Lazy[String]], shortParserMsg: Lazy[String], lastFailureMsg: Lazy[String], failureStack: List[(String, Int)], earliestAggregate: Int, isSuccess: Boolean, logDepth: Int, index: Int, cut: Boolean, successValue: Any, verboseFailures: Boolean, noDropBuffer: Boolean)
- input
The input to the parsing run, as a ParserInput.
- startIndex
Where the parse initially started, so as to allow
.result.traced
to re-create it with tracing enabled.- originalParser
The original parsing function we used to start this run, so as to allow
.result.traced
to re-create it with tracing enabled.- traceIndex
The index we wish to trace if tracing is enabled, else -1. Used to find failure messages to aggregate into
failureAggregate
- instrument
Callbacks that can be injected before/after every
P(...)
parser.- failureAggregate
When tracing is enabled, this collects up all the upper-most failures that happen at traceIndex (in Lazy wrappers) so they can be shown to the user at end-of-parse as suggestions for what could make the parse succeed. For terminal parsers like LiteralStr, it just aggregate's the string representation. For composite parsers like
a ~ b
or!a
which may fail at traceIndex even without any of their wrapped terminal parsers failing there, it makes use of the shortParserMsg as the string representation of the composite parser.- shortParserMsg
When tracing is enabled, this contains string representation of the last parser to run. Since parsers aren't really objects, we piece together the string in the parser body and return store it here, and an enclosing parser may fetch it back out to help build its own string representation. Stored in a Lazy wrapper to avoid paying the string-construction cost unless truly necessary; in exchange we pay a small cost constructing the chain of functions that can be invoked to create the string
- failureStack
The stack of named
P(...)
parsers in effect when the failure occured; only constructed when tracing is enabled viatraceIndex != -1
- earliestAggregate
Lets backtracking parsers keep track on-failure of where the earliest actually-aggregated terminal failure within the backtracked parse happened. This is necessary to provide a high-level error message based on shortParserMsg if no low-level error message based on a terminal parser was recorded at the right index
- isSuccess
Whether or not the parse is currently successful
- logDepth
How many nested
.log
calls are currently surrounding us. Used to nicely indent the log output so you can see which parsers are nested within which other parsers; -1 means logging is disabled- index
The current index of the parse
- cut
Has the current parse been prevented from backtracking? This field starts as
true
at top-level, since there is nowhere to backtrack to. Upon entering a parser that can backtrack, such as|
or.?
or.rep
, it is set tofalse
, and re-set totrue
upon encountering a./
or~/
cut operator that prevents backtracking.- successValue
The currently returned success value
- verboseFailures
Whether or not we are currently collecting lastFailureMsgs; defaults to false, unless traceIndex is set OR we are inside a LogByNameOps.log call which necessitates tracing in order to print out failure traces during logging
- noDropBuffer
Flag that prevents the parser from dropping earlier input. Used for the
.!
capture operator that needs the input around to return as a string, theNoCut
operator that forces backtracking (regardless of internal cuts), or whitespace consumption which implicitly backtracks if the parser on the RHS of the whitespace fails or consumes 0 characters. The value for this field is lexically scoped, but it is up to the individual parser method implementations to set the values and remember to un-set it to the previous value after they finish. Forgetting to re-set it to the previous value can cause strange behavior or crashes.
Value Members
-
final
def
!=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
final
def
##(): Int
- Definition Classes
- AnyRef → Any
-
final
def
==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- def aggregateMsg(f: Lazy[String]): Unit
-
def
aggregateMsgPostBacktrack(startAggregate: Int, f: Lazy[String]): Unit
Special case of aggregateMsg which ignores isSuccess status and only performs aggregation if the failureAggregate has not already changed from when it was recorded as
startAggregate
.Special case of aggregateMsg which ignores isSuccess status and only performs aggregation if the failureAggregate has not already changed from when it was recorded as
startAggregate
. This allows any failures aggregated by the child parsers to take priority if present, but if not present then the outer less-specific failure can then be aggregated -
final
def
asInstanceOf[T0]: T0
- Definition Classes
- Any
- def augmentFailure(index: Int, cut: Boolean): ParsingRun[Nothing]
- def augmentFailure(index: Int): ParsingRun[Nothing]
- def checkForDrop(): Boolean
-
def
clone(): AnyRef
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @native() @throws( ... )
- var cut: Boolean
- var earliestAggregate: Int
-
final
def
eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
def
equals(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- var failureAggregate: List[Lazy[String]]
- var failureStack: List[(String, Int)]
-
def
finalize(): Unit
- Attributes
- protected[java.lang]
- Definition Classes
- AnyRef
- Annotations
- @throws( classOf[java.lang.Throwable] )
- def freshFailure(startPos: Int): ParsingRun[Nothing]
- def freshFailure(): ParsingRun[Nothing]
- def freshSuccess[V](value: V, index: Int, cut: Boolean): ParsingRun[V]
- def freshSuccess[V](value: V, cut: Boolean): ParsingRun[V]
- def freshSuccess[V](value: V, index: Int): ParsingRun[V]
- def freshSuccess[V](value: V): ParsingRun[V]
-
final
def
getClass(): Class[_]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
-
def
hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- var index: Int
- val input: ParserInput
- val instrument: Instrument
-
final
def
isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- var isSuccess: Boolean
- var lastFailureMsg: Lazy[String]
- var logDepth: Int
-
final
def
ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- var noDropBuffer: Boolean
-
final
def
notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
-
final
def
notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- val originalParser: (ParsingRun[_]) ⇒ ParsingRun[_]
- def setMsg(f: Lazy[String]): Unit
- var shortParserMsg: Lazy[String]
- val startIndex: Int
- var successValue: Any
-
final
def
synchronized[T0](arg0: ⇒ T0): T0
- Definition Classes
- AnyRef
-
def
toString(): String
- Definition Classes
- AnyRef → Any
- val traceIndex: Int
- var verboseFailures: Boolean
-
final
def
wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws( ... )
-
final
def
wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @native() @throws( ... )