object combinator
This object contains the two main debug combinators, attachDebugger and attachWithFrontend.
- Source
- combinator.scala
- Since
4.5.0
- Alphabetic
- By Inheritance
- combinator
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Type Members
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
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def attachDebugger[A](parser: Parsley[A]): DebuggedPair[A]
Attaches a debugger to a parser.
Attaches a debugger to a parser.
This assumes the default rules of converting only lambdas and closures into strings when storing in the output debug tree.
- A
Output type of original parser.
- parser
The parser to debug.
- returns
A pair of the finalised tree, and the instrumented parser.
- Note
Do not run a parser through this combinator multiple times.
- See also
The other overload of this method (attachDebugger) has more information on how this attachment works.
- def attachDebugger[A](parser: Parsley[A], toStringRules: Seq[(Any) => Boolean]): DebuggedPair[A]
Attaches a debugger to a parser, returning a reference to the debug tree produced by the parser's parse tree formed as it runs.
Attaches a debugger to a parser, returning a reference to the debug tree produced by the parser's parse tree formed as it runs.
Ideally, this is called on the highest level parser that you want to debug, as this combinator will traverse downwards in the parser tree and attach debuggers to all the child parsers. As a consequence of this, it is not really recommended to include debugged parsers as lower-level parsers within your main parser, and rather to isolate their testing.
Before running the parser, it may be advised to see if the current platform's implementation of the debugger supports parsley.debugger.util.Collector (via parsley.debugger.util.Collector.isSupported), which allows you to input an object or class instance containing parsers, in order to analyse it via reflection to assign the names given to the parser fields / methods in that object to disambiguate the parser names in the tree in a much easier manner. Otherwise, you may want to attach explicit names to your parsers using named to achieve the same effect manually.
Without either of those name sources, parsers will simply appear as prettified versions of their internal class names.
After instrumentation, you would run the instrumented parser first, then after the parser finishes running on ONE input ideally, you would run the debug tree generator function in order to acquire the debug tree.
This tree can then be introspected manually in a (runtime) debugger, or passed over to one of the frontends in parsley.debugger.frontend in one of the extra companion libraries for this debugger.
It is recommended that you save the debug trees somewhere should you want to re-use the same debugged parser, or if you want to use the same debugged parser as a child parser on multiple parts of your main parser, make sure you use attachReusable , as re-use of the same debugged parser across multiple parent parsers will cause the different parse trees to incorrectly merge in an undefined manner.
A small warning: debugging an already debugged parser (via attachDebugger and friends) is an undefined behaviour.
See attachWithFrontend to automate the tree processing after parsing.
- A
Output type of original parser.
- parser
The parser to debug.
- toStringRules
If a parser's result matches any of the predicates in this sequence, it will get turned into a string before storing in the debug tree. This is usually for memory-usage optimisation. By default, all function-like objects will be converted into strings, as closures are expensive to store.
- returns
A pair of the finalised tree, and the instrumented parser.
- Note
Do not run a parser through this combinator multiple times.
- def attachReusable[A](parser: Parsley[A]): () => DebuggedPair[A]
Create a closure that freshly attaches a debugger to a parser every time it is called.
Create a closure that freshly attaches a debugger to a parser every time it is called. This is used for creating debugged parsers that can be used as children to multiple parent parsers, as using the same debugged parser as a child to multiple parsers is unsafe.
This assumes the default rules of converting only lambdas and closures into strings when storing in the output debug tree.
- returns
Generator closure for debugged versions of the input parser.
- Note
Do not run a parser through this combinator multiple times.
- See also
The other overload of this method (attachDebugger) has more information on its usage.
- def attachReusable[A](parser: Parsley[A], toStringRules: Seq[(Any) => Boolean]): () => DebuggedPair[A]
Create a closure that freshly attaches a debugger to a parser every time it is called.
Create a closure that freshly attaches a debugger to a parser every time it is called. This is used for creating debugged parsers that can be used as children to multiple parent parsers, as using the same debugged parser as a child to multiple parsers is unsafe.
- returns
Generator closure for debugged versions of the input parser.
- Note
Do not run a parser through this combinator multiple times.
- See also
attachDebugger for more information, or attachWithFrontend for a version that also accepts a parsley.debugger.frontend.DebugFrontend.
- def attachReusableWithFrontend[A](parser: Parsley[A], frontend: () => DebugFrontend): () => Parsley[A]
Create a closure that freshly attaches a debugger and a tree-processing frontend to a parser every time it is called.
Create a closure that freshly attaches a debugger and a tree-processing frontend to a parser every time it is called.
This assumes the default rules of converting only lambdas and closures into strings when storing in the output debug tree.
- returns
Generator closure for frontend-debugged versions of the input parser.
- Note
Do not run a parser through this combinator multiple times.
- See also
The other overload of this method (attachDebugger) has more information on its usage.
- def attachReusableWithFrontend[A](parser: Parsley[A], frontend: () => DebugFrontend, toStringRules: Seq[(Any) => Boolean]): () => Parsley[A]
Create a closure that freshly attaches a debugger and a tree-processing frontend to a parser every time it is called.
Create a closure that freshly attaches a debugger and a tree-processing frontend to a parser every time it is called.
- returns
Generator closure for frontend-debugged versions of the input parser.
- Note
Do not run a parser through this combinator multiple times.
- See also
- def attachWithFrontend[A](parser: Parsley[A], frontend: DebugFrontend): Parsley[A]
Attach a debugger and an explicitly-available frontend in which the debug tree should be processed with.
Attach a debugger and an explicitly-available frontend in which the debug tree should be processed with. This frontend will also be called automatically with any debug trees produced by the parser.
This assumes the default rules of converting only lambdas and closures into strings when storing in the output debug tree.
- A
Output type of parser.
- parser
The parser to debug.
- frontend
The frontend instance to render with.
- returns
A modified parser which will ask the frontend to process the produced debug tree after a call to Parsley.parse is made.
- Note
Do not run a parser through this combinator multiple times.
- See also
The other overload of this method (attachDebugger) has more information on its usage.
- def attachWithFrontend[A](parser: Parsley[A], frontend: DebugFrontend, toStringRules: Seq[(Any) => Boolean]): Parsley[A]
Attach a debugger and an explicitly-available frontend in which the debug tree should be proessed with.
Attach a debugger and an explicitly-available frontend in which the debug tree should be proessed with.
You would normally obtain a parsley.debugger.frontend.DebugFrontend frontend from its respective package as either a static object or an instance object depending on whether the renderer stores state. In the latter case, it is better to regenerate the frontend with every new debugged parser. The frontend can be reusable (i.e. inherits from parsley.debugger.frontend.ReusableFrontend) or single-use (i.e. inherits from parsley.debugger.frontend.SingleUseFrontend).
The instrumented parser will automatically call the frontend to render the debug tree, so it may be recommended that you only use this with smaller parsers as large parsers may cause large amounts of memory to be used for processing the tree.
- A
Output type of parser.
- parser
The parser to debug.
- frontend
The frontend instance to render with.
- toStringRules
If a parser's result matches any of the predicates in this sequence, it will get turned into a string before storing in the debug tree. This is usually for memory-usage optimisation. By default, all function-like objects will be converted into strings, as closures are expensive to store.
- returns
A modified parser which will ask the frontend to process the produced debug tree after a call to Parsley.parse is made.
- Note
Do not run a parser through this combinator multiple times.
- See also
attachDebugger for more information on how attachment works and things you may want to do before using this debug combinator, as well as some warnings on what not to do when using this debugger (such as regarding re-use of debugged parsers).
- def attachWithImplicitFrontend[A](parser: Parsley[A])(implicit frontend: DebugFrontend): Parsley[A]
Attach a debugger and an implicitly-available frontend in which the debug tree should be processed with.
Attach a debugger and an implicitly-available frontend in which the debug tree should be processed with.
This assumes the default rules of converting only lambdas and closures into strings when storing in the output debug tree.
- Note
Do not run a parser through this combinator multiple times.
- See also
The other overload of this method (attachWithImplicitFrontend) has more information on its usage.
- def attachWithImplicitFrontend[A](parser: Parsley[A], toStringRules: Seq[(Any) => Boolean] = defaultRules)(implicit frontend: DebugFrontend): Parsley[A]
Attach a debugger and an implicitly-available frontend in which the debug tree should be processed with.
Attach a debugger and an implicitly-available frontend in which the debug tree should be processed with.
- Note
Do not run a parser through this combinator multiple times.
- See also
attachWithFrontend for more information.
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native()
- final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable])
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- def named[A](parser: Parsley[A], name: String): Parsley[A]
Attach a name to a parser, for display within the debugger output.
Attach a name to a parser, for display within the debugger output. Names assigned here have a higher precedence than names collected with parsley.debugger.util.Collector.
Renaming the same parser multiple times simply overwrites its name to the most latest rename.
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()