Implement the |text| function

When called inside an action, the |text| function returns the text
matched by action's expression. It can be also called inside an
initializer or a predicate where it returns an empty string.

The |text| function will be useful mainly in cases where one needs a
structured representation of the input and simultaneously the raw text.
Until now, the only way to get the raw text in these cases was to
painfully build it from the structured representation.

Fixes GH-131.

README.md

@@ -346,6 +346,9 @@ The code inside the action can access all variables and functions defined in the
 initializer at the beginning of the grammar. Curly braces in the action code
 must be balanced.
 
+The code inside the action can also access the string matched by the expression
+using the `text` function.
+
 The code inside the action can also access the parse position at the beginning
 of the action's expression using the `offset` function. It returns a zero-based
 character index into the input string. The code can also access the line and

lib/compiler/passes/generate-code.js

@@ -404,6 +404,10 @@ module.exports = function(ast, options) {
             '        return cachedReportedPosDetails;',
             '      }',
             '      ',
+            '      function text() {',
+            '        return input.substring(reportedPos, pos);',
+            '      }',
+            '      ',
             '      function offset() {',
             '        return reportedPos;',
             '      }',

spec/generated-parser.spec.js

@@ -171,6 +171,15 @@ describe("generated parser", function() {
         expect(parser).toParse("a", 42);
       });
 
+      it("can use the |text| function", function() {
+        var parser = PEG.buildParser([
+              '{ var result = text(); }',
+              'start = "a" { return result; }'
+            ].join("\n"), options);
+
+        expect(parser).toParse("a", "");
+      });
+
       it("can use the |offset| function to get the current parse position", function() {
         var parser = PEG.buildParser([
               '{ var result = offset(); }',
@@ -273,6 +282,15 @@ describe("generated parser", function() {
         expect(parser).toParse("a", "a");
       });
 
+      it("can use the |text| function to get the text matched by the expression", function() {
+        var parser = PEG.buildParser(
+              'start = "a" "b" "c" { return text(); }',
+              options
+            );
+
+        expect(parser).toParse("abc", "abc");
+      });
+
       it("can use the |offset| function to get the current parse position", function() {
         var parser = PEG.buildParser(
               'start = "a" ("b" { return offset(); })',
@@ -443,6 +461,15 @@ describe("generated parser", function() {
         expect(parser).toParse("a", ["a", ""]);
       });
 
+      it("can use the |text| function", function() {
+        var parser = PEG.buildParser(
+              'start = "a" &{ return text() === ""; }',
+              options
+            );
+
+        expect(parser).toParse("a", ["a", ""]);
+      });
+
       it("can use the |offset| function to get the current parse position", function() {
         var parser = PEG.buildParser(
               'start = "a" &{ return offset() === 1; }',
@@ -525,6 +552,15 @@ describe("generated parser", function() {
         expect(parser).toParse("a", ["a", ""]);
       });
 
+      it("can use the |text| function", function() {
+        var parser = PEG.buildParser(
+              'start = "a" !{ return text() !== ""; }',
+              options
+            );
+
+        expect(parser).toParse("a", ["a", ""]);
+      });
+
       it("can use the |offset| function to get the current parse position", function() {
         var parser = PEG.buildParser(
               'start = "a" !{ return offset() !== 1; }',