enh(parser) new highlight() API (#3053)

Author: joshgoebel

CHANGES.md

@@ -35,6 +35,11 @@ Language grammar improvements:
 
 Deprecations:
 
+- `highlight(languageName, code, ignoreIllegals, continuation)` deprecated as of 10.7
+  - Please use the newer API which takes `code` and then accepts options as an object
+  - IE: `highlight(code, {language, ignoreIllegals})`
+  - `continuation` is for internal use only and no longer supported
+
 - `highlightBlock(el)` deprecated as of 10.7.
   - Please use `highlightElement(el)` instead.
   - Plugin callbacks renamed `before/after:highlightBlock` => `before/after:highlightElement`

README.md

@@ -211,7 +211,7 @@ const hljs = require('highlight.js/lib/core');  // require only the core library
 // separately require languages
 hljs.registerLanguage('xml', require('highlight.js/lib/languages/xml'));
 
-const highlightedCode = hljs.highlight('xml', '<span>Hello World!</span>').value
+const highlightedCode = hljs.highlight('<span>Hello World!</span>', {language: 'xml'}).value
 ```
 
 

docs/api.rst

@@ -4,15 +4,12 @@ Library API
 Highlight.js exports a few functions as methods of the ``hljs`` object.
 
 
-``highlight(languageName, code, ignore_illegals, continuation)``
-----------------------------------------------------------------
+``highlight(languageName, code, ignoreIllegals, continuation)`` (deprecated with 10.7)
+--------------------------------------------------------------------------------------
 
-Core highlighting function.
-Accepts a language name, or an alias, and a string with the code to highlight.
-The ``ignore_illegals`` parameter, when present and evaluates to a true value,
-forces highlighting to finish even in case of detecting illegal syntax for the
-language instead of throwing an exception.
-The ``continuation`` is an optional mode stack representing unfinished parsing.
+**This is the old API, please see the new API immediately below.**
+
+``continuation`` is an optional mode stack representing unfinished parsing.
 When present, the function will restart parsing from this state instead of
 initializing a new one.  This is used internally for `sublanguage` support.
 
@@ -21,6 +18,18 @@ because there is no requirement that a grammar handle linebreaks in any special
 way. It's quite possible for a grammar to have a single mode/regex that matches
 MANY lines at once.  This is not discouraged and entirely up to the grammar.
 
+
+
+``highlight(code, {language, ignoreIllegals})``
+--------------------------------------------------------------------------------------
+
+Core highlighting function.  Accepts the code to highlight (string) and a list of options (object).
+The ``language`` parameter must be present and specify the language name or alias
+of the grammar to be used for highlighting.
+The ``ignoreIllegals`` is an optional parameter than when true forces highlighting
+to finish even in case of detecting illegal syntax for the
+language instead of throwing an exception.
+
 Returns an object with the following properties:
 
 * ``language``: language name, same as the name passed in ``languageName``, returned for consistency with ``highlightAuto``

src/highlight.js

@@ -93,8 +93,14 @@ const HLJS = function(hljs) {
   /**
    * Core highlighting function.
    *
-   * @param {string} languageName - the language to use for highlighting
-   * @param {string} code - the code to highlight
+   * OLD API
+   * highlight(lang, code, ignoreIllegals, continuation)
+   *
+   * NEW API
+   * highlight(code, {lang, ignoreIllegals})
+   *
+   * @param {string} codeOrlanguageName - the language to use for highlighting
+   * @param {string | HighlightOptions} optionsOrCode - the code to highlight
    * @param {boolean} [ignoreIllegals] - whether to ignore illegal matches, default is to bail
    * @param {CompiledMode} [continuation] - current continuation mode, if any
    *
@@ -106,7 +112,24 @@ const HLJS = function(hljs) {
    * @property {CompiledMode} top - top of the current mode stack
    * @property {boolean} illegal - indicates whether any illegal matches were found
   */
-  function highlight(languageName, code, ignoreIllegals, continuation) {
+  function highlight(codeOrlanguageName, optionsOrCode, ignoreIllegals, continuation) {
+    let code = "";
+    let languageName = "";
+    if (typeof optionsOrCode === "object") {
+      code = codeOrlanguageName;
+      ignoreIllegals = optionsOrCode.ignoreIllegals;
+      languageName = optionsOrCode.language;
+      // continuation not supported at all via the new API
+      // eslint-disable-next-line no-undefined
+      continuation = undefined;
+    } else {
+      // old API
+      logger.deprecated("10.7.0", "highlight(lang, code, ...args) has been deprecated.");
+      logger.deprecated("10.7.0", "Please use highlight(code, options) instead.\nhttps://github.com/highlightjs/highlight.js/issues/2277");
+      languageName = codeOrlanguageName;
+      code = optionsOrCode;
+    }
+
     /** @type {BeforeHighlightContext} */
     const context = {
       code,
@@ -133,14 +156,12 @@ const HLJS = function(hljs) {
    * private highlight that's used internally and does not fire callbacks
    *
    * @param {string} languageName - the language to use for highlighting
-   * @param {string} code - the code to highlight
-   * @param {boolean} [ignoreIllegals] - whether to ignore illegal matches, default is to bail
-   * @param {CompiledMode} [continuation] - current continuation mode, if any
+   * @param {string} codeToHighlight - the code to highlight
+   * @param {boolean?} [ignoreIllegals] - whether to ignore illegal matches, default is to bail
+   * @param {CompiledMode?} [continuation] - current continuation mode, if any
    * @returns {HighlightResult} - result of the highlight operation
   */
-  function _highlight(languageName, code, ignoreIllegals, continuation) {
-    const codeToHighlight = code;
-
+  function _highlight(languageName, codeToHighlight, ignoreIllegals, continuation) {
     /**
      * Return keyword data if a match is a keyword
      * @param {CompiledMode} mode - current mode
@@ -708,7 +729,7 @@ const HLJS = function(hljs) {
 
     node = element;
     const text = node.textContent;
-    const result = language ? highlight(language, text, true) : highlightAuto(text);
+    const result = language ? highlight(text, { language, ignoreIllegals: true }) : highlightAuto(text);
 
     // support for v10 API
     fire("after:highlightElement", { el: element, result, text });

test/api/beginKeywords.js

@@ -27,25 +27,25 @@ describe('beginKeywords', () => {
 
   it("should allow subsequence matches to still succeed", () => {
     let content = "A.class = self";
-    let res = hljs.highlight("has-followup", content);
+    let res = hljs.highlight(content, {language: "has-followup"});
     res.value.should.equal('A.<span class="hljs-found">class</span> = self');
   });
 
   it("should ignore a preceeding .", () => {
     let content = "A.class = self";
-    let res = hljs.highlight("test", content);
+    let res = hljs.highlight(content, { language: "test" });
     res.value.should.equal('A.class = self');
   });
 
   it("should ignore a trailing .", () => {
     let content = "class.config = true";
-    let res = hljs.highlight("test", content);
+    let res = hljs.highlight(content, { language: "test" });
     res.value.should.equal('class.config = true');
   });
 
   it('should detect keywords', () => {
     let content = "I have a class yes I do.";
-    let res = hljs.highlight("test", content);
+    let res = hljs.highlight(content, { language: "test" });
     res.value.should.equal('I have a <span class="hljs-keyword">class</span> yes I do.');
   });
 });

test/api/highlight.js

@@ -4,9 +4,47 @@ const hljs   = require('../../build');
 const should = require('should');
 
 describe('.highlight()', () => {
+  it('should support ignoreIllegals (old API)', () => {
+    let code = "float # float";
+    let result = hljs.highlight("java", code, true);
+    result.value.should.equal(`<span class="hljs-keyword">float</span> # <span class="hljs-keyword">float</span>`);
+
+    code = "float # float";
+    result = hljs.highlight("java", code, false);
+    result.value.should.equal("float # float");
+    result.illegal.should.equal(true);
+  });
+  it('should support ignoreIllegals (new API)', () => {
+    let code = "float # float";
+    let result = hljs.highlight(code, { language: "java", ignoreIllegals: true });
+    result.value.should.equal(`<span class="hljs-keyword">float</span> # <span class="hljs-keyword">float</span>`);
+
+    code = "float # float";
+    result = hljs.highlight(code, { language: "java", ignoreIllegals: false });
+    result.value.should.equal("float # float");
+    result.illegal.should.equal(true);
+
+    // defaults to false
+    code = "float # float";
+    result = hljs.highlight(code, { language: "java" });
+    result.value.should.equal("float # float");
+    result.illegal.should.equal(true);
+  });
+  it('should use new API with options', () => {
+    const code = "public void moveTo(int x, int y, int z);";
+    const result = hljs.highlight(code, { language: "java" });
+
+    result.value.should.equal(
+      '<span class="hljs-function"><span class="hljs-keyword">public</span> ' +
+      '<span class="hljs-keyword">void</span> <span class="hljs-title">moveTo</span>' +
+      '<span class="hljs-params">(<span class="hljs-keyword">int</span> x, ' +
+      '<span class="hljs-keyword">int</span> y, ' +
+      '<span class="hljs-keyword">int</span> z)</span></span>;'
+    );
+  });
   it('should works without continuation', () => {
-    const code   = "public void moveTo(int x, int y, int z);";
-    const result = hljs.highlight('java', code, false, false);
+    const code = "public void moveTo(int x, int y, int z);";
+    const result = hljs.highlight(code, { language: 'java' });
 
     result.value.should.equal(
       '<span class="hljs-function"><span class="hljs-keyword">public</span> ' +

test/api/keywords.js

@@ -13,7 +13,7 @@ describe('computing the relevance score of a language', () => {
     }
     const code   = "farmer and of river weeds";
     hljs.registerLanguage("test", grammar)
-    const result = hljs.highlight('test', code, false, false);
+    const result = hljs.highlight(code, { language: 'test' });
 
     result.relevance.should.equal(3)
   });
@@ -27,7 +27,7 @@ describe('computing the relevance score of a language', () => {
     }
     const code   = "farmer and of river weeds";
     hljs.registerLanguage("test", grammar)
-    const result = hljs.highlight('test', code, false, false);
+    const result = hljs.highlight(code, { language: 'test' });
 
     result.relevance.should.equal(13)
   });
@@ -41,7 +41,7 @@ describe('computing the relevance score of a language', () => {
     }
     const code   = "farmer and of river weeds";
     hljs.registerLanguage("test", grammar)
-    const result = hljs.highlight('test', code, false, false);
+    const result = hljs.highlight(code, { language: 'test' });
 
     result.relevance.should.equal(4)
   });

test/browser/plain.js

@@ -16,7 +16,7 @@ describe('plain browser', function() {
 
   it('should return relevance key', async function() {
     await buildFakeDOM.bind(this, defaultCase)();
-    var out = this.hljs.highlight("javascript","");
+    var out = this.hljs.highlight("", { language: "javascript" });
     out.relevance.should.equal(0);
   });
 

test/browser/worker.js

@@ -13,7 +13,7 @@ describe('web worker', function() {
           importScripts(event.data.script);
           postMessage(1);
         } else {
-          var result = hljs.highlight('javascript', event.data);
+          var result = hljs.highlight(event.data, { language: 'javascript' });
           postMessage(result.value);
         }
       };

test/detect/index.js

@@ -56,6 +56,6 @@ describe('hljs.highlightAuto()', () => {
 
   it("compiling the grammars", async function() {
     const languages = hljs.listLanguages();
-    languages.forEach(l => hljs.highlight(l, ""))
+    languages.forEach(lang => hljs.highlight("", { language: lang} ))
   }); // this is also required for the dynamic test generation above to work
 });