Skip to content

Commit d4b047b

Browse files
committed
(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`
1 parent a4f1f20 commit d4b047b

File tree

7 files changed

+60
-15
lines changed

7 files changed

+60
-15
lines changed

CHANGES.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,26 @@
11
## Version 10.1.0 (in progress)
22

3+
Parser Engine:
4+
5+
- (enh) Added `on:begin` callback for modes (#2261) [Josh Goebel][]
6+
- (enh) Added `on:end` callback for modes (#2261) [Josh Goebel][]
7+
- (enh) Added ability to programatically ignore begin and end matches (#2261) [Josh Goebel][]
8+
- (enh) Added `END_SAME_AS_BEGIN` mode to replace `endSameAsBegin` parser attribute (#2261) [Josh Goebel][]
9+
10+
Deprecations:
11+
12+
- (deprecation) `endSameAsBegin` is now deprecated. (#2261) [Josh Goebel][]
13+
314
Language Improvements:
415

16+
- fix(cpp) Fix highlighting of unterminated raw strings (#2261) [David Benjamin][]
517
- fix(javascript) `=>` function with nested `()` in params now works (#2502) [Josh Goebel][]
618
- fix(typescript) `=>` function with nested `()` in params now works (#2502) [Josh Goebel][]
719
- fix(yaml) Fix tags to include non-word characters (#2486) [Peter Plantinga][]
820

921
[Josh Goebel]: https://github.com/yyyc514
1022
[Peter Plantinga]: https://github.com/pplantinga
23+
[David Benjamin]: https://github.com/davidben
1124

1225

1326
## Version 10.0.1

docs/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Contents:
1313

1414
api
1515
language-guide
16-
reference
16+
mode-reference
1717
css-classes-reference
1818
style-guide
1919
plugin-api

docs/language-guide.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ For such modes ``className`` attribute should be omitted so they won't generate
186186
Mode attributes
187187
---------------
188188

189-
Other useful attributes are defined in the :doc:`mode reference </reference>`.
189+
Other useful attributes are defined in the :doc:`mode reference </mode-reference>`.
190190

191191

192192
.. _relevance:

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

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,19 @@ Regular expression starting a mode. For example a single quote for strings or tw
6262
If absent, ``begin`` defaults to a regexp that matches anything, so the mode starts immediately.
6363

6464

65+
on:begin
66+
^^^^^^^^^^^
67+
68+
**type**: callback (matchData, response)
69+
70+
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.
71+
72+
- ``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.
73+
- ``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
74+
75+
For an example of usage see ``END_SAME_AS_BEGIN`` in ``modes.js``.
76+
77+
6578
end
6679
^^^
6780

@@ -79,6 +92,19 @@ Sometimes a mode can end not by itself but implicitly with its containing (paren
7992
This is achieved with :ref:`endsWithParent <endsWithParent>` attribute.
8093

8194

95+
on:end
96+
^^^^^^^^^^^
97+
98+
**type**: callback (matchData, response)
99+
100+
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.
101+
102+
- ``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.
103+
- ``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
104+
105+
For an example of usage see ``END_SAME_AS_BEGIN`` in ``modes.js``.
106+
107+
82108
beginKeywords
83109
^^^^^^^^^^^^^^^^
84110

@@ -182,8 +208,12 @@ tell it to end the function definition after itself:
182208

183209
.. _endSameAsBegin:
184210

185-
endSameAsBegin
186-
^^^^^^^^^^^^^^
211+
endSameAsBegin (deprecated as of 10.1)
212+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
213+
214+
**Deprecated:** *This attribute has been deprecated.* You should instead use the
215+
``END_SAME_AS_BEGIN`` mode or use the ``on:begin`` and ``on:end`` attributes to
216+
build more complex paired matchers.
187217

188218
**type**: boolean
189219

src/highlight.js

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -203,9 +203,9 @@ const HLJS = function(hljs) {
203203
let matched = regex.startsWith(mode.endRe, matchPlusRemainder);
204204

205205
if (matched) {
206-
if (mode["before:end"]) {
206+
if (mode["on:end"]) {
207207
let resp = new Response(mode);
208-
mode["before:end"](match, resp);
208+
mode["on:end"](match, resp);
209209
if (resp.ignore)
210210
matched = false;
211211
}
@@ -217,7 +217,7 @@ const HLJS = function(hljs) {
217217
return mode;
218218
}
219219
}
220-
// even if before:end fires an `ignore` it's still possible
220+
// even if on:end fires an `ignore` it's still possible
221221
// that we might trigger the end node because of a parent mode
222222
if (mode.endsWithParent) {
223223
return endOfMode(mode.parent, match, matchPlusRemainder);
@@ -245,7 +245,7 @@ const HLJS = function(hljs) {
245245

246246
let resp = new Response(new_mode);
247247
// first internal before callbacks, then the public ones
248-
let beforeCallbacks = [new_mode.__beforeBegin, new_mode["before:begin"]];
248+
let beforeCallbacks = [new_mode.__beforeBegin, new_mode["on:begin"]];
249249
for (let cb of beforeCallbacks) {
250250
if (!cb) continue;
251251
cb(match, resp);
@@ -268,10 +268,10 @@ const HLJS = function(hljs) {
268268
}
269269
}
270270
mode = startNewMode(new_mode);
271-
if (mode["after:begin"]) {
272-
let resp = new Response(mode);
273-
mode["after:begin"](match, resp);
274-
}
271+
// if (mode["after:begin"]) {
272+
// let resp = new Response(mode);
273+
// mode["after:begin"](match, resp);
274+
// }
275275
return new_mode.returnBegin ? 0 : lexeme.length;
276276
}
277277

src/lib/mode_compiler.js

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,9 @@ export function compileLanguage(language) {
6161
// eslint-disable-next-line no-undefined
6262
const i = match.findIndex((el, i) => i > 0 && el !== undefined);
6363
const matchData = this.matchIndexes[i];
64-
match.splice(0, i); // // trim off the extra matches
64+
// trim off any earlier non-relevant match groups (ie, the other regex
65+
// match groups that make up the multi-matcher)
66+
match.splice(0, i);
6567

6668
return Object.assign(match, matchData);
6769
}

src/lib/modes.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ export const METHOD_GUARD = {
121121
export const END_SAME_AS_BEGIN = function(mode) {
122122
return Object.assign(mode,
123123
{
124-
'after:begin': (m, resp) => { resp.data._beginMatch = m[1]; },
125-
'before:end': (m, resp) => { if (resp.data._beginMatch !== m[1]) resp.ignoreMatch() }
124+
'on:begin': (m, resp) => { resp.data._beginMatch = m[1]; },
125+
'on:end': (m, resp) => { if (resp.data._beginMatch !== m[1]) resp.ignoreMatch() }
126126
});
127127
};

0 commit comments

Comments
 (0)