From 85eaf3b2fcebbb84ca4d80f9f5134a43bdb19c62 Mon Sep 17 00:00:00 2001
From: Josh Goebel <me@joshgoebel.com>
Date: Mon, 27 Apr 2020 13:54:55 -0400
Subject: [PATCH] update naming and docs

---
 docs/mode-reference.rst | 16 ++++++++++++----
 src/highlight.js        | 16 ++++++++--------
 src/lib/modes.js        |  4 ++--
 3 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/docs/mode-reference.rst b/docs/mode-reference.rst
index 1c73854e5a..a60400d536 100644
--- a/docs/mode-reference.rst
+++ b/docs/mode-reference.rst
@@ -62,7 +62,7 @@ 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.
 
 
-after:begin
+on:begin
 ^^^^^^^^^^^
 
 **type**: callback (matchData, response)
@@ -72,6 +72,8 @@ This callback is triggered the moment a begin match is detected. ``matchData`` i
 - ``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
 ^^^
@@ -90,7 +92,7 @@ Sometimes a mode can end not by itself but implicitly with its containing (paren
 This is achieved with :ref:`endsWithParent <endsWithParent>` attribute.
 
 
-before:end
+on:end
 ^^^^^^^^^^^
 
 **type**: callback (matchData, response)
@@ -100,6 +102,8 @@ This callback is triggered the moment an end match is detected. ``matchData`` in
 - ``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
 ^^^^^^^^^^^^^^^^
@@ -204,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
 
diff --git a/src/highlight.js b/src/highlight.js
index ca3a3d8b6a..d60330fba5 100644
--- a/src/highlight.js
+++ b/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;
     }
 
diff --git a/src/lib/modes.js b/src/lib/modes.js
index 55eabb8e67..8acb8f0e51 100644
--- a/src/lib/modes.js
+++ b/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() }
     });
 };