pegjs/spec/api/pegjs-api.spec.js

"use strict";

let chai = require("chai");
let peg = require("../../lib/peg");
let sinon = require("sinon");

let expect = chai.expect;

describe("PEG.js API", function() {
  describe("generate", function() {
    it("generates a parser", function() {
      let parser = peg.generate("start = 'a'");

      expect(typeof parser).to.equal("object");
      expect(parser.parse("a")).to.equal("a");
    });

    it("throws an exception on syntax error", function() {
      expect(() => { peg.generate("start = @"); }).to.throw();
    });

    it("throws an exception on semantic error", function() {
      expect(() => { peg.generate("start = undefined"); }).to.throw();
    });

    describe("allowed start rules", function() {
      let grammar = [
        "a = 'x'",
        "b = 'x'",
        "c = 'x'"
      ].join("\n");

      // The |allowedStartRules| option is implemented separately for each
      // optimization mode, so we need to test it in both.

      describe("when optimizing for parsing speed", function() {
        describe("when |allowedStartRules| is not set", function() {
          it("generated parser can start only from the first rule", function() {
            let parser = peg.generate(grammar, { optimize: "speed" });

            expect(parser.parse("x", { startRule: "a" })).to.equal("x");
            expect(() => { parser.parse("x", { startRule: "b" }); }).to.throw();
            expect(() => { parser.parse("x", { startRule: "c" }); }).to.throw();
          });
        });

        describe("when |allowedStartRules| is set", function() {
          it("generated parser can start only from specified rules", function() {
            let parser = peg.generate(grammar, {
              optimize: "speed",
              allowedStartRules: ["b", "c"]
            });

            expect(() => { parser.parse("x", { startRule: "a" }); }).to.throw();
            expect(parser.parse("x", { startRule: "b" })).to.equal("x");
            expect(parser.parse("x", { startRule: "c" })).to.equal("x");
          });
        });
      });

      describe("when optimizing for code size", function() {
        describe("when |allowedStartRules| is not set", function() {
          it("generated parser can start only from the first rule", function() {
            let parser = peg.generate(grammar, { optimize: "size" });

            expect(parser.parse("x", { startRule: "a" })).to.equal("x");
            expect(() => { parser.parse("x", { startRule: "b" }); }).to.throw();
            expect(() => { parser.parse("x", { startRule: "c" }); }).to.throw();
          });
        });

        describe("when |allowedStartRules| is set", function() {
          it("generated parser can start only from specified rules", function() {
            let parser = peg.generate(grammar, {
              optimize: "size",
              allowedStartRules: ["b", "c"]
            });

            expect(() => { parser.parse("x", { startRule: "a" }); }).to.throw();
            expect(parser.parse("x", { startRule: "b" })).to.equal("x");
            expect(parser.parse("x", { startRule: "c" })).to.equal("x");
          });
        });
      });
    });

    describe("intermediate results caching", function() {
      let grammar = [
        "{ var n = 0; }",
        "start = (a 'b') / (a 'c') { return n; }",
        "a = 'a' { n++; }"
      ].join("\n");

      describe("when |cache| is not set", function() {
        it("generated parser doesn't cache intermediate parse results", function() {
          let parser = peg.generate(grammar);

          expect(parser.parse("ac")).to.equal(2);
        });
      });

      describe("when |cache| is set to |false|", function() {
        it("generated parser doesn't cache intermediate parse results", function() {
          let parser = peg.generate(grammar, { cache: false });

          expect(parser.parse("ac")).to.equal(2);
        });
      });

      describe("when |cache| is set to |true|", function() {
        it("generated parser caches intermediate parse results", function() {
          let parser = peg.generate(grammar, { cache: true });

          expect(parser.parse("ac")).to.equal(1);
        });
      });
    });

    describe("tracing", function() {
      let grammar = "start = 'a'";

      describe("when |trace| is not set", function() {
        it("generated parser doesn't trace", function() {
          let parser = peg.generate(grammar);
          let tracer = { trace: sinon.spy() };

          parser.parse("a", { tracer: tracer });

          expect(tracer.trace.called).to.equal(false);
        });
      });

      describe("when |trace| is set to |false|", function() {
        it("generated parser doesn't trace", function() {
          let parser = peg.generate(grammar, { trace: false });
          let tracer = { trace: sinon.spy() };

          parser.parse("a", { tracer: tracer });

          expect(tracer.trace.called).to.equal(false);
        });
      });

      describe("when |trace| is set to |true|", function() {
        it("generated parser traces", function() {
          let parser = peg.generate(grammar, { trace: true });
          let tracer = { trace: sinon.spy() };

          parser.parse("a", { tracer: tracer });

          expect(tracer.trace.called).to.equal(true);
        });
      });
    });

    // The |optimize| option isn't tested because there is no meaningful way to
    // write the specs without turning this into a performance test.

    describe("output", function() {
      let grammar = "start = 'a'";

      describe("when |output| is not set", function() {
        it("returns generated parser object", function() {
          let parser = peg.generate(grammar);

          expect(typeof parser).to.equal("object");
          expect(parser.parse("a")).to.equal("a");
        });
      });

      describe("when |output| is set to |\"parser\"|", function() {
        it("returns generated parser object", function() {
          let parser = peg.generate(grammar, { output: "parser" });

          expect(typeof parser).to.equal("object");
          expect(parser.parse("a")).to.equal("a");
        });
      });

      describe("when |output| is set to |\"source\"|", function() {
        it("returns generated parser source code", function() {
          let source = peg.generate(grammar, { output: "source" });

          expect(typeof source).to.equal("string");
          expect(eval(source).parse("a")).to.equal("a");
        });
      });
    });

    // The |format|, |exportVars|, and |dependencies| options are not tested
    // becasue there is no meaningful way to thest their effects without turning
    // this into an integration test.

    // The |plugins| option is tested in plugin API specs.

    it("accepts custom options", function() {
      peg.generate("start = 'a'", { foo: 42 });
    });
  });
});