diff --git a/CHANGES.md b/CHANGES.md index 2cf4ad9ace..1c43201f65 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,6 +4,7 @@ Parser Engine: - (parser) Adds `keywords.$pattern` key to grammar definitions (#2519) [Josh Goebel][] - (parser) Adds SHEBANG utility mode [Josh Goebel][] +- (parser) Adds `registerAlias` method (#2540) [Taufik Nurrohman][] - (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][] diff --git a/docs/api.rst b/docs/api.rst index deb6f496c2..a219bfa9ea 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -5,7 +5,7 @@ Highlight.js exports a few functions as methods of the ``hljs`` object. ``highlight(languageName, code, ignore_illegals, continuation)`` ---------------------------------------------------------- +---------------------------------------------------------------- Core highlighting function. Accepts a language name, or an alias, and a string with the code to highlight. @@ -32,7 +32,7 @@ Returns an object with the following properties: ``highlightAuto(code, languageSubset)`` ----------------------------------------- +--------------------------------------- Highlighting with language detection. Accepts a string with the code to highlight and an optional array of language names and aliases restricting detection to only those languages. The subset can also be set with ``configure``, but the local parameter overrides the option if set. @@ -76,7 +76,7 @@ Configures global options: * ``classPrefix``: a string prefix added before class names in the generated markup, used for backwards compatibility with stylesheets. * ``languages``: an array of language names and aliases restricting auto detection to only these languages. * ``languageDetectRe``: a regex to configure how CSS class names map to language (allows class names like say `color-as-php` vs the default of `language-php`, etc.) -* ``noHighlightRe``: a regex to configure which CSS classes are to be skipped completely +* ``noHighlightRe``: a regex to configure which CSS classes are to be skipped completely. Accepts an object representing options with the values to updated. Other options don't change :: @@ -85,15 +85,14 @@ Accepts an object representing options with the values to updated. Other options tabReplace: ' ', // 4 spaces classPrefix: '' // don't append class prefix // … other options aren't changed - }) + }); hljs.initHighlighting(); ``initHighlighting()`` ---------------------- -Applies highlighting to all ``
..
`` blocks on a page.
-
+Applies highlighting to all ``...
`` blocks on a page.
``initHighlightingOnLoad()``
@@ -113,13 +112,21 @@ Adds new language to the library under the specified name. Used mostly internall
to use common regular expressions defined within it.
+``registerAlias(alias|aliases, {languageName})``
+------------------------------------------------
+
+Adds new language alias or aliases to the library for the specified language name defined under ``languageName`` key.
+
+* ``alias|aliases``: a string or array with the name of alias being registered
+* ``languageName``: the language name as specified by ``registerLanguage``.
+
+
``listLanguages()``
-----------------------------
+-------------------
Returns the languages names list.
-
.. _getLanguage:
@@ -132,7 +139,7 @@ Returns the language object if found, ``undefined`` otherwise.
``requireLanguage(name)``
----------------------
+-------------------------
Looks up a language by name or alias.
@@ -150,5 +157,5 @@ Enables *debug/development* mode. **This mode purposely makes Highlight.js more
For example, if a new version suddenly had a serious bug (or breaking change) that affected only a single language:
-* **In Safe Mode**: All other languages would continue to highlight just fine. The broken language would appear as a code block, but without any highlighting (as if it were plaintext).
+* **In Safe Mode**: All other languages would continue to highlight just fine. The broken language would appear as a code block, but without any highlighting (as if it were plaintext).
* **In Debug Mode**: All highlighting would stop when an error was encountered and a JavaScript error would be thrown.
diff --git a/src/highlight.js b/src/highlight.js
index 38ef8e17f0..c2779be23f 100644
--- a/src/highlight.js
+++ b/src/highlight.js
@@ -685,6 +685,14 @@ const HLJS = function(hljs) {
return languages[name] || languages[aliases[name]];
}
+ function registerAlias(alias, {languageName}) {
+ let list = alias;
+ if (typeof list === 'string') {
+ list = [alias]
+ }
+ list.forEach(alias => aliases[alias] = languageName);
+ }
+
function autoDetection(name) {
var lang = getLanguage(name);
return lang && !lang.disableAutodetect;
@@ -716,6 +724,7 @@ const HLJS = function(hljs) {
registerLanguage,
listLanguages,
getLanguage,
+ registerAlias,
requireLanguage,
autoDetection,
inherit,
diff --git a/test/api/registerAlias.js b/test/api/registerAlias.js
new file mode 100644
index 0000000000..3e03136fe4
--- /dev/null
+++ b/test/api/registerAlias.js
@@ -0,0 +1,24 @@
+'use strict';
+
+const hljs = require('../../build');
+const should = require('should');
+
+describe('.registerAlias()', () => {
+ it('should get an existing language by alias', () => {
+ hljs.registerAlias('jquery', {
+ languageName: 'javascript'
+ });
+ const result = hljs.getLanguage('jquery');
+
+ result.should.be.instanceOf(Object);
+ });
+
+ it('should get an existing language by aliases', () => {
+ hljs.registerAlias(['jquery', 'jqueryui'], {
+ languageName: 'javascript'
+ });
+ const result = hljs.getLanguage('jquery');
+
+ result.should.be.instanceOf(Object);
+ });
+});