(parser) Add hljs.registerAlias() public API (#2540)

* Add hljs.registerAlias(alias, languageName) public API
* Add .registerAlias() test

Author: taufik-nurrohman

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][]

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 ``<pre><code>..</code></pre>`` blocks on a page.
-
+Applies highlighting to all ``<pre><code>...</code></pre>`` 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.

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,

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);
+  });
+});