pegjs-backtrace
v0.2.1
Published
A debug backtrace module for PEG.js.
Downloads
51,202
Readme
pegjs-backtrace
A tracer module for PEG.js which generates a visual backtrace tree.
This module also supports normal tracing output. See showTrace option for detail.
Example
The following example grammar recognizes arithmetic expressions like 2*(3+4)
.
start = additive
additive = multiplicative plus additive / multiplicative
multiplicative = primary mult multiplicative / primary
primary = integer / "(" additive ")"
integer = digits:[0-9]+
plus = "+"
mult = "*"
If you give the 2*(3/4)
which the grammar does not recognize, pegjs-backtrace shows backtrace tree from the maximum failure positions to the start rule as follows.
Install
npm install pegjs-backtrace
Usage
pegjs-backtrace is implemented as a Tracer. When calling the parse
function, pass the pegjs-backtrace instance to the tracer
option.
Then, after parser fails, you can obtain the backtrace string from getBacktraceString()
.
var Parser = require('./parser'); // parser generated by pegjs --trace
var Tracer = require('pegjs-backtrace');
var text = '2*(3/4)';
var tracer = new Tracer(text); // input text is required.
try {
Parser.parse(text, { tracer:tracer });
} catch(e) {
console.log(tracer.getBacktraceString());
}
Note that --trace
option is required to generated parser.js with pegjs command. If the option is not supplied, tracer feature is disabled.
Options
When creating pegjs-backtrace instance, you can provide some options as follows.
var Tracer = require('pegjs-backtrace');
var tracer = new Tracer(text,{
parent: null,
hiddenPaths: [],
useColor: true,
showTrace: false,
maxSourceLines: 6,
maxPathLength: 72,
matchesNode: function(node, options) { return true; },
output: console.log,
});
parent
This option specifies a parent Tracer instance. Once the option is given, the parent's trace
method is also called during parsing. The default value is null
.
var Parser = require('./parser');
var Tracer = require('pegjs-backtrace');
var tracer = new Tracer(text,{
parent: new Parser.DefaultTracer(),
});
useColor
If true, the output is colored with ANSI escape sequence. Otherwise no escape sequence is used. The default value is true
.
showSource
If true, quoted source are shown on the trace nodes. Otherwise source is suppressed. The default value is true
.
maxSourceLines
The maximum number of lines shown as the quoted source on each trace node. The default value is 6
.
showTrace
If true, trace log is printed while parsing. The default value is false
.
showFullPath
If the options is true, the rule path is shown instead of the rule name. The default value is false
.
maxPathLength
The limit length of the displaying path name. When the path length exeeds to the limit, the path is truncated.
hiddenPaths
This option specifies path patterns to hide. Any node that matches one of these patterns will be hidden from the trace log.
Note that this option works only with trace log, not for backtrace. The default value is []
.
var Tracer = require('pegjs-backtrace');
var tracer = new Tracer(text,{
hiddenPaths:["integer", "primary/.*"]
});
The type of the pattern must be string
or RegExp
. Even the pattern is string
, it may also contain RegExp meta characters.
The /
character can be used to represent the hierarchcal path of grammar rules. If the pattern is string like "FOO"
, it is treated as the regular expression /(^|\/)FOO(\/|$)/
.
matchesNode
Custom filtering of nodes printed by the graph.
Two parameters are passed, node
and options
.
The node
object is an internal representation which may be subject to changes.
The options
are the options passed to getParseTreeString()
or
getBacktraceString()
.
{ backtrace: false }
is passed when calling getParseTreeString()
.
{ backtrace: true }
is apssed when calling getBacktraceString()
.
{
// example of showing only fail nodes when
matchesNode: function(node) {
if (node.type === "rule.fail") {
return true;
} else {
return false;
}
}
}
output
Sets the output destination for the backtrace. The default is console.log
.
Limitation
The cursor symbol ^
may points the wrong position if the prefix of the source line contains East Asian full-width Characters.
The generating tree is based on the observable trace events from the pegjs parser. Any local failure inside a grammar rule is ignored. For example, if parser fails while
reading "+"
character in the following additive
rule, we can observe the event that additive
fails but cannot get any information of "+"
fails.
additive = multiplicative "+" additive / multiplicative
If you would like to see the event on "+"
failure, the "+"
should be an explicit rule like:
plus = "+"
additive = multiplicative plus additive / multiplicative