(docs) rename to mode_reference; docs for callbacks

- I can never find this file because it's name didn't fully match.
- rename callbacks to `on:begin` and `on:end`

Author: joshgoebel

CHANGES.md

@@ -1,13 +1,26 @@
 ## Version 10.1.0 (in progress)
 
+Parser Engine:
+
+- (enh) Added `on:begin` callback for modes (#2261) [Josh Goebel][]
+- (enh) Added `on:end` callback for modes (#2261) [Josh Goebel][]
+- (enh) Added ability to programatically ignore begin and end matches (#2261) [Josh Goebel][]
+- (enh) Added `END_SAME_AS_BEGIN` mode to replace `endSameAsBegin` parser attribute (#2261) [Josh Goebel][]
+
+Deprecations:
+
+- (deprecation) `endSameAsBegin` is now deprecated. (#2261) [Josh Goebel][]
+
 Language Improvements:
 
+- fix(cpp) Fix highlighting of unterminated raw strings (#2261) [David Benjamin][]
 - fix(javascript) `=>` function with nested `()` in params now works (#2502) [Josh Goebel][]
 - fix(typescript) `=>` function with nested `()` in params now works (#2502) [Josh Goebel][]
 - fix(yaml) Fix tags to include non-word characters (#2486) [Peter Plantinga][]
 
 [Josh Goebel]: https://github.com/yyyc514
 [Peter Plantinga]: https://github.com/pplantinga
+[David Benjamin]: https://github.com/davidben
 
 
 ## Version 10.0.1

docs/index.rst

@@ -13,7 +13,7 @@ Contents:
 
    api
    language-guide
-   reference
+   mode-reference
    css-classes-reference
    style-guide
    plugin-api

docs/language-guide.rst

@@ -186,7 +186,7 @@ For such modes ``className`` attribute should be omitted so they won't generate
 Mode attributes
 ---------------
 
-Other useful attributes are defined in the :doc:`mode reference </reference>`.
+Other useful attributes are defined in the :doc:`mode reference </mode-reference>`.
 
 
 .. _relevance:

docs/reference.rst renamed to docs/mode-reference.rst

@@ -62,6 +62,19 @@ Regular expression starting a mode. For example a single quote for strings or tw
 If absent, ``begin`` defaults to a regexp that matches anything, so the mode starts immediately.
 
 
+on:begin
+^^^^^^^^^^^
+
+**type**: callback (matchData, response)
+
+This callback is triggered the moment a begin match is detected. ``matchData`` includes the typical regex match data; the full match, match groups, etc. The ``response`` object is used to tell the parser how it should handle the match. It can be also used to temporarily store data.
+
+- ``response.data`` - a simple object data store.  Can be used for building more complex rules where the end rule is dependent on the content of begin, etc.
+- ``response.ignoreMatch()`` - pretend as if this match never happened. The mode is not entered. Continues trying subsequent modes in the current mode's ``contains`` list
+
+For an example of usage see ``END_SAME_AS_BEGIN`` in ``modes.js``.
+
+
 end
 ^^^
 
@@ -79,6 +92,19 @@ Sometimes a mode can end not by itself but implicitly with its containing (paren
 This is achieved with :ref:`endsWithParent <endsWithParent>` attribute.
 
 
+on:end
+^^^^^^^^^^^
+
+**type**: callback (matchData, response)
+
+This callback is triggered the moment an end match is detected. ``matchData`` includes the typical regex match data; the full match, match groups, etc. The ``response`` object is used to tell the parser how it should handle the match. It can also be used to retrieve data stored from a `begin` callback.
+
+- ``response.data`` - a simple object data store.  Can be used for building more complex rules where the end rule is dependent on the content of begin, etc.
+- ``response.ignoreMatch()`` - pretend as if this match never happened. The mode is not entered. Continues trying subsequent modes in the current mode's ``contains`` list
+
+For an example of usage see ``END_SAME_AS_BEGIN`` in ``modes.js``.
+
+
 beginKeywords
 ^^^^^^^^^^^^^^^^
 
@@ -182,8 +208,12 @@ tell it to end the function definition after itself:
 
 .. _endSameAsBegin:
 
-endSameAsBegin
-^^^^^^^^^^^^^^
+endSameAsBegin (deprecated as of 10.1)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Deprecated:** *This attribute has been deprecated.*  You should instead use the
+``END_SAME_AS_BEGIN`` mode or use the ``on:begin`` and ``on:end`` attributes to
+build more complex paired matchers.
 
 **type**: boolean
 

src/highlight.js

@@ -203,9 +203,9 @@ const HLJS = function(hljs) {
       let matched = regex.startsWith(mode.endRe, matchPlusRemainder);
 
       if (matched) {
-        if (mode["before:end"]) {
+        if (mode["on:end"]) {
           let resp = new Response(mode);
-          mode["before:end"](match, resp);
+          mode["on:end"](match, resp);
           if (resp.ignore)
             matched = false;
         }
@@ -217,7 +217,7 @@ const HLJS = function(hljs) {
           return mode;
         }
       }
-      // even if before:end fires an `ignore` it's still possible
+      // even if on:end fires an `ignore` it's still possible
       // that we might trigger the end node because of a parent mode
       if (mode.endsWithParent) {
         return endOfMode(mode.parent, match, matchPlusRemainder);
@@ -245,7 +245,7 @@ const HLJS = function(hljs) {
 
       let resp = new Response(new_mode);
       // first internal before callbacks, then the public ones
-      let beforeCallbacks = [new_mode.__beforeBegin, new_mode["before:begin"]];
+      let beforeCallbacks = [new_mode.__beforeBegin, new_mode["on:begin"]];
       for (let cb of beforeCallbacks) {
         if (!cb) continue;
         cb(match, resp);
@@ -268,10 +268,10 @@ const HLJS = function(hljs) {
         }
       }
       mode = startNewMode(new_mode);
-      if (mode["after:begin"]) {
-        let resp = new Response(mode);
-        mode["after:begin"](match, resp);
-      }
+      // if (mode["after:begin"]) {
+      //   let resp = new Response(mode);
+      //   mode["after:begin"](match, resp);
+      // }
       return new_mode.returnBegin ? 0 : lexeme.length;
     }
 

src/lib/modes.js

@@ -121,7 +121,7 @@ export const METHOD_GUARD = {
 export const END_SAME_AS_BEGIN = function(mode) {
   return Object.assign(mode,
     {
-    'after:begin': (m, resp) => { resp.data._beginMatch = m[1]; },
-    'before:end': (m, resp) => { if (resp.data._beginMatch !== m[1]) resp.ignoreMatch() }
+    'on:begin': (m, resp) => { resp.data._beginMatch = m[1]; },
+    'on:end': (m, resp) => { if (resp.data._beginMatch !== m[1]) resp.ignoreMatch() }
     });
 };