combinator
This object contains the two main debug combinators, attachDebugger and attachWithFrontend.
Attributes
- Since
-
4.5.0
- Source
- combinator.scala
- Graph
-
- Supertypes
- Self type
-
combinator.type
Members list
Type members
Classlikes
Dot accessor versions of the combinators.
Types
Shorthand representation of a pair of a tree extraction function and a debugged parser.
Shorthand representation of a pair of a tree extraction function and a debugged parser.
Attributes
- Source
- combinator.scala
Value members
Concrete methods
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.
Type parameters
- A
-
Output type of original parser.
Value parameters
- 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.
Attributes
- Returns
-
A pair of the finalised tree, and the instrumented parser.
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Type parameters
- A
-
Output type of original parser.
Value parameters
- parser
-
The parser to debug.
Attributes
- Returns
-
A pair of the finalised tree, and the instrumented parser.
- See also
-
The other overload of this method (attachDebugger) has more information on how this attachment works.
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Attributes
- Returns
-
Generator closure for debugged versions of the input parser.
- See also
-
attachDebugger for more information, or attachWithFrontend for a version that also accepts a parsley.debugger.frontend.DebugFrontend.
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Attributes
- Returns
-
Generator closure for debugged versions of the input parser.
- See also
-
The other overload of this method (attachDebugger) has more information on its usage.
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Attributes
- Returns
-
Generator closure for frontend-debugged versions of the input parser.
- See also
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Attributes
- Returns
-
Generator closure for frontend-debugged versions of the input parser.
- See also
-
The other overload of this method (attachDebugger) has more information on its usage.
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Type parameters
- A
-
Output type of parser.
Value parameters
- frontend
-
The frontend instance to render with.
- 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.
Attributes
- Returns
-
A modified parser which will ask the frontend to process the produced debug tree after a call to Parsley.parse is made.
- 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).
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Type parameters
- A
-
Output type of parser.
Value parameters
- frontend
-
The frontend instance to render with.
- parser
-
The parser to debug.
Attributes
- Returns
-
A modified parser which will ask the frontend to process the produced debug tree after a call to Parsley.parse is made.
- See also
-
The other overload of this method (attachDebugger) has more information on its usage.
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Attributes
- See also
-
attachWithFrontend for more information.
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Attributes
- See also
-
The other overload of this method (attachWithImplicitFrontend) has more information on its usage.
- Note
-
Do not run a parser through this combinator multiple times.
- Source
- combinator.scala
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.
Attributes
- Source
- combinator.scala
Implicits
Implicits
Dot accessor versions of the combinators.