seb35 / pegjs-syntactic-actions Goto Github PK

View Code? Open in Web Editor NEW

2.0 2.0 0.0 106 KB

A PEG.js plugin to replace default actions and obtain syntactic trees

License: MIT License

JavaScript 100.00%

pegjs pegjs-plugin

pegjs-syntactic-actions's Introduction

pegjs-syntactic-actions

This PEG.js plugin removes all actions in a grammar and adds to rules actions returning text and location.

As a result:

any potential bug in actions is removed, making the grammar strictly syntactic;
the resulting tree documents captured rules.

When writing complex grammars, it can be useful to first debug syntactic aspects of the grammar with this plugin, then execute the default actions.

Example

import pegjs from "pegjs";
import SyntacticActionsPlugin from "pegjs-syntactic-actions";

const parser = pegjs.generate(
  `
    rule = "a"+ ( b / c )+
    b = "b" { return bug; }
    c = "c"
  `,
  {
    plugins: [ new SyntacticActionsPlugin() ]
  }
);

console.log( parser.parse( "aabc" ) );

returns:

{
  "rule": "rule",
  "text": "aabc",
  "start": 0,
  "end": 4,
  "children": [
    [
      "a",
      "a"
    ],
    [
      {
        "rule": "b",
        "text": "b",
        "start": 2,
        "end": 3,
        "children": "b"
      },
      {
        "rule": "c",
        "text": "c",
        "start": 3,
        "end": 4,
        "children": "c"
      }
    ]
  ]
}

Although it would have returned an error without the plugin:

undefined:148
        peg$c4 = function() { return bug; },
                              ^

ReferenceError: bug is not defined

Usage

Installation

npm install pegjs-syntactic-actions

Use

In the second argument options of pegjs.generate, add the main object

{
  plugins: [ new SyntacticActionsPlugin() ]
}

Options

It can be given an argument options in the constructor. Currently only one is supported:

ignoredRules: array of rules names to be completely ignored (these rules will keep their original actions).

For instance:

{
  plugins: [ new SyntacticActionsPlugin( { ignoredRules: [ "rule1" ] } ) ]
}

Documentation

A JSON schema is included in the docs directory, documenting the output of the parser modified by this plugin. Obviously, if there are ignored rules, these rules can detract the validity of the JSON schema.

pegjs-syntactic-actions's People

Contributors

Stargazers

Watchers

pegjs-syntactic-actions's Issues

Under some circumstances some actions could remain

In the PEG.js AST, in situations where a node { "type": "labeled" } is immediately followed by a node { "type": "action" }, the former node is removed but the later remains, and if the action is triggered some JS variables declared by a label could be missing, returning a ReferenceError in strict mode.

OutOfMemoryException

Not sure what I'm doing wrong, but replacing your example grammar with one from https://www.npmjs.com/package/pegjs-otf results in OutOfMemory when executing parser.parse("hello world")

var grammar = `
sample = _ 

_ "blank"
    = (co / ws)*

co "comment"
    = "//" (![\\r\\n] .)*
    / "/*" (!"*/" .)* "*/"

ws "whitespaces"
    = [ \\t\\r\\n]+
`

Format of the Position keys

Current state

In the initial (current) version of this plug-in, the position of each substring is encoded in the keys start and end with type int, alongside with the other keys about the capture (rule, text, and children, see JSON schema):

{
  rule: "rule-name",
  text: "captured text",
  start: 0,
  end: 13,
  children: []
}

Proposed changes

I wonder about changing this into one of these two forms:

{
  rule: "rule-name",
  text: "captured text",
  start: { line: 1, column: 1, offset: 0 },
  end: { line: 1, column: 14, offset: 13 },
  children: []
}

{
  rule: "rule-name",
  text: "captured text",
  position: {
    start: { line: 1, column: 1, offset: 0 },
    end: { line: 1, column: 14, offset: 13 }
  },
  children: []
}

The second one is more popular: used in PEG.js itself in the location() function (although without specific reference to the key name position) and in unist.

Adding line and column will probably be easier in most use cases – it was not my original use case because my grammar dealt only with single-line texts. An additional detail is: should the plug-in let the user choose their output format for the position? Some users could not need full details, more verbose and sometimes not useful.

I would appreciate if users of this plug-in give their opinion about this. This issue will stay open for multiple months before – perhaps – a change will happen.

Implement peggyjs support

pegjs does not seem to be actively maintained anymore and even the official website is not accessible anymore.

Recently I have decided to switch to a maintained alternative and I picked up peggyjs which is a maintained fork of pegjs (see pegjs/pegjs#675).

I have tried to use this plugin in conjunction with peggyjs and the transition was smoothless. However:

this plugin lists pegjs as a peer and dev dependency, which results in pegjs to be included in my node_modules;
the plugin does not officially support peggyjs although it is compatible with it.

I wonder if it would make sense to update the plugin and support peggyjs instead of pegjs or at least make the dependencies optional.