Reimplement offset() and add range()

Author: felix9

CHANGELOG.md

@@ -63,6 +63,11 @@ Released: TBD
   especially if your plugin replaces both `generateBytecode` as `generateJs` passes.
 
   [@Mingun](https://github.com/peggyjs/peggy/pull/117)
+- Parsers now can use two new functions to get location information:
+  `offset()` and `range()`. Use them if you don't need the whole
+  location information, because it could be expensive to compute.
+  That two functions always very efficient (back-ported pegjs/pegjs#528).
+  [@felix9 and @Mingun](https://github.com/peggyjs/peggy/pull/145)
 
 ### Bug fixes
 

README.md

@@ -539,6 +539,12 @@ available to them.
 - `location()` returns an object with the information about the parse position.
   Refer to [the corresponding section](#locations) for the details.
 
+- `range()` is similar to `location()`, but returns an object with offsets only.
+  Refer to [the "Locations" section](#locations) for the details.
+
+- `offset()` returns only the start offset, i.e. `location().start.offset`.
+  Refer to [the "Locations" section](#locations) for the details.
+
 - `text()` returns the source text between `start` and `end` (which will be `""` for
   predicates). Instead of using that function as a return value for the rule consider
   using the [`$` operator](#-expression-2).
@@ -709,6 +715,24 @@ For the per-parse initializer, the location is the start of the input, i.e.
 The line number is incremented each time the parser finds an end of line
 sequence in the input.
 
+Line and column are somewhat expensive to compute, so if you just need the
+offset, there's also a function `offset()` that returns just the start offset,
+and a function `range()` that returns the object:
+
+```javascript
+{
+  source: options.grammarSource,
+  start: 23,
+  end: 25
+}
+```
+
+(i.e. difference from the `location()` result only in type of `start` and `end`
+properties, which contain just an offset instead of the `Location` object.)
+
+All notes about values for `location()` object is also applicable to the `range()`
+and `offset()` calls.
+
 Currently, Peggy only works with the [Basic Multilingual Plane (BMP)][BMP] of
 Unicode. This means that all offsets are measured in UTF-16 code units. If you
 try to parse characters outside this Plane (for example, emoji, or any

docs/documentation.html

@@ -657,6 +657,12 @@ <h3 id="action-execution-environment">Action Execution Environment</h3>
   <li><p><code>location()</code> returns an object with the information about the parse position.
   Refer to <a href="#locations">the corresponding section</a> for the details.</p>
   </li>
+  <li><p><code>range()</code> is similar to <code>location()</code>, but returns an object with offsets only.
+  Refer to <a href="#locations">the &quot;Locations&quot; section</a> for the details.</p>
+  </li>
+  <li><p><code>offset()</code> returns only the start offset, i.e. <code>location().start.offset</code>.
+  Refer to <a href="#locations">the &quot;Locations&quot; section</a> for the details.</p>
+  </li>
   <li><p><code>text()</code> returns the source text between <code>start</code> and <code>end</code> (which will be <code>&quot;&quot;</code> for
   predicates). Instead of using that function as a return value for the rule consider
   using the <a href="#-expression-2"><code>$</code> operator</a>.</p>
@@ -799,6 +805,24 @@ <h2 id="locations">Locations</h2>
 <p>The line number is incremented each time the parser finds an end of line sequence in
   the input.</p>
 
+<p>Line and column are somewhat expensive to compute, so if you just need the
+offset, there's also a function <code>offset()</code> that returns just the start offset,
+and a function <code>range()</code> that returns the object:</p>
+
+<pre><code class="language-javascript">
+{
+  source: options.grammarSource,
+  start: 23,
+  end: 25
+}
+</code></pre>
+
+<p>(i.e. difference from the <code>location()</code> result only in type of <code>start</code> and <code>end</code>
+properties, which contain just an offset instead of the <code>Location</code> object.)</p>
+
+<p>All notes about values for <code>location()</code> object is also applicable to the <code>range()</code>
+and <code>offset()</code> calls.</p>
+
 <p>Currently, Peggy only works with the <a href="https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane">Basic Multilingual Plane (BMP)</a> of Unicode.
 This means that all offsets are measured in UTF-16 code units. If you
 try to parse characters outside this Plane (for example, emoji, or any

lib/compiler/passes/generate-js.js

@@ -857,6 +857,18 @@ function generateJS(ast, options) {
       "    return input.substring(peg$savedPos, peg$currPos);",
       "  }",
       "",
+      "  function offset() {",
+      "    return peg$savedPos;",
+      "  }",
+      "",
+      "  function range() {",
+      "    return {",
+      "      source: peg$source,",
+      "      start: peg$savedPos,",
+      "      end: peg$currPos",
+      "    };",
+      "  }",
+      "",
       "  function location() {",
       "    return peg$computeLocation(peg$savedPos, peg$currPos);",
       "  }",

lib/parser.js

@@ -584,6 +584,28 @@ describe("generated parser behavior", function() {
             end: { offset: 3, line: 2, column: 1 }
           });
         });
+
+        it("|offset| returns current start offset", function() {
+          const parser = peg.generate([
+            "start = [0-9]+ @mark",
+            "mark = 'xx' { return offset(); }"
+          ].join("\n"), options);
+
+          expect(parser).to.parse("0123456xx", 7);
+        });
+
+        it("|range| returns current range", function() {
+          const parser = peg.generate([
+            "start = [0-9]+ @mark",
+            "mark = 'xx' { return range(); }"
+          ].join("\n"), options);
+
+          expect(parser).to.parse("0123456xx", {
+            source: undefined,
+            start: 7,
+            end: 9
+          });
+        });
       });
     });