(chore) Deprecate the requireLanguage API (#2844)

- Entire library now no longer uses any run-time dependencies (no grammar will break because another is missing) - Add docs for fixMarkup deprecation - Add docs for requireLanguage deprecation - Remove `Requires:` meta-data used only for run-time dependencies. - Gzip size is only ~230 bytes larger than before - Fix auto-detect tests now that the equivalency between `cpp` and `arduino` is no longer hidden by the load order. - adds `supersetOf` to resolve conflicts between very similar languages (C++, Arduino). The base language wins in the case of a tie. ie `arduino` is now a `supersetOf` `cpp`. (closes #2275) Note: `Requires: ` still stays overall as it's used to clue the build process about "loose" (non-breaking) sublanguage dependencies between languages. This dependency is purposely loose and therefore still a thing.
highlightjs · Nov 13, 2020 · 9ba5a5d · 9ba5a5d
1 parent e8a8216
commit 9ba5a5d
Show file tree

Hide file tree

Showing 6 changed files with 127 additions and 97 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,5 +1,11 @@
 ## Version 10.4.0 (work in process)
 
+Deprecations:
+
+- (chore) `requireLanguage` is deprecated.
+  - Prefer `getLanguage` (with custom error handling) or built-time dependencies.
+  - See [Library API](https://highlightjs.readthedocs.io/en/latest/api.html#requirelanguage-name) for more information.
+
 Parser:
 
 - fix(vue): Language name now appears in CSS class (#2807) [Michael Rush][]

diff --git a/docs/api.rst b/docs/api.rst
@@ -45,8 +45,10 @@ Returns an object with the following properties:
 * ``second_best``: object with the same structure for second-best heuristically detected language (may be absent)
 
 
-``fixMarkup(value)``
---------------------
+``fixMarkup(value)`` (deprecated as of 10.3)
+--------------------------------------------
+
+**fixMarkup is deprecated and will be removed entirely in v11.**
 
 Post-processing of the highlighted markup. Currently consists of replacing indentation TAB characters and using ``<br>`` tags instead of new-line characters. Options are set globally with ``configure``.
 
@@ -138,8 +140,13 @@ Looks up a language by name or alias.
 Returns the language object if found, ``undefined`` otherwise.
 
 
-``requireLanguage(name)``
--------------------------
+``requireLanguage(name)`` (deprecated as of 10.4)
+-------------------------------------------------
+
+**This has been deprecated and will be removed in a future release.**  If you
+need this type of functionality use ``getLanguage`` with your own error
+handling.  It is highly recommended that all inter-dependencies between grammars
+be handled at built-time, not run-time.  This is what the core library now does.
 
 Looks up a language by name or alias.
 

diff --git a/src/highlight.js b/src/highlight.js
@@ -592,12 +592,23 @@ const HLJS = function(hljs) {
 
     const sorted = results.sort((a, b) => {
       // sort base on relevance
-      return b.relevance - a.relevance;
+      if (a.relevance !== b.relevance) return b.relevance - a.relevance;
+
+      // always award the tie to the base language
+      // ie if C++ and Arduino are tied, it's more likely to be C++
+      if (a.language && b.language) {
+        if (getLanguage(a.language).supersetOf === b.language) {
+          return 1;
+        } else if (getLanguage(b.language).supersetOf === a.language) {
+          return -1;
+        }
+      }
 
       // otherwise say they are equal, which has the effect of sorting on
       // relevance while preserving the original ordering - which is how ties
       // have historically been settled, ie the language that comes first always
       // wins in the case of a tie
+      return 0;
     });
 
     const [best, secondBest] = sorted;
@@ -787,6 +798,9 @@ const HLJS = function(hljs) {
     @returns {Language | never}
   */
   function requireLanguage(name) {
+    console.warn("requireLanguage is deprecated and will be removed entirely in the future.");
+    console.warn("Please see https://github.com/highlightjs/highlight.js/pull/2844");
+
     const lang = getLanguage(name);
     if (lang) { return lang; }
 

diff --git a/src/languages/arduino.js b/src/languages/arduino.js
@@ -2,109 +2,110 @@
 Language: Arduino
 Author: Stefania Mellai <s.mellai@arduino.cc>
 Description: The Arduino® Language is a superset of C++. This rules are designed to highlight the Arduino® source code. For info about language see http://www.arduino.cc.
-Requires: cpp.js
 Website: https://www.arduino.cc
 */
 
+import cPlusPlus from './cpp.js';
+
 /** @type LanguageFn */
 export default function(hljs) {
-
-	var ARDUINO_KW = {
-      keyword:
-        'boolean byte word String',
-      built_in:
-        'setup loop ' +
-        'KeyboardController MouseController SoftwareSerial ' +
-        'EthernetServer EthernetClient LiquidCrystal ' +
-        'RobotControl GSMVoiceCall EthernetUDP EsploraTFT ' +
-        'HttpClient RobotMotor WiFiClient GSMScanner ' +
-        'FileSystem Scheduler GSMServer YunClient YunServer ' +
-        'IPAddress GSMClient GSMModem Keyboard Ethernet ' +
-        'Console GSMBand Esplora Stepper Process ' +
-        'WiFiUDP GSM_SMS Mailbox USBHost Firmata PImage ' +
-        'Client Server GSMPIN FileIO Bridge Serial ' +
-        'EEPROM Stream Mouse Audio Servo File Task ' +
-        'GPRS WiFi Wire TFT GSM SPI SD ' +
-        'runShellCommandAsynchronously analogWriteResolution ' +
-        'retrieveCallingNumber printFirmwareVersion ' +
-        'analogReadResolution sendDigitalPortPair ' +
-        'noListenOnLocalhost readJoystickButton setFirmwareVersion ' +
-        'readJoystickSwitch scrollDisplayRight getVoiceCallStatus ' +
-        'scrollDisplayLeft writeMicroseconds delayMicroseconds ' +
-        'beginTransmission getSignalStrength runAsynchronously ' +
-        'getAsynchronously listenOnLocalhost getCurrentCarrier ' +
-        'readAccelerometer messageAvailable sendDigitalPorts ' +
-        'lineFollowConfig countryNameWrite runShellCommand ' +
-        'readStringUntil rewindDirectory readTemperature ' +
-        'setClockDivider readLightSensor endTransmission ' +
-        'analogReference detachInterrupt countryNameRead ' +
-        'attachInterrupt encryptionType readBytesUntil ' +
-        'robotNameWrite readMicrophone robotNameRead cityNameWrite ' +
-        'userNameWrite readJoystickY readJoystickX mouseReleased ' +
-        'openNextFile scanNetworks noInterrupts digitalWrite ' +
-        'beginSpeaker mousePressed isActionDone mouseDragged ' +
-        'displayLogos noAutoscroll addParameter remoteNumber ' +
-        'getModifiers keyboardRead userNameRead waitContinue ' +
-        'processInput parseCommand printVersion readNetworks ' +
-        'writeMessage blinkVersion cityNameRead readMessage ' +
-        'setDataMode parsePacket isListening setBitOrder ' +
-        'beginPacket isDirectory motorsWrite drawCompass ' +
-        'digitalRead clearScreen serialEvent rightToLeft ' +
-        'setTextSize leftToRight requestFrom keyReleased ' +
-        'compassRead analogWrite interrupts WiFiServer ' +
-        'disconnect playMelody parseFloat autoscroll ' +
-        'getPINUsed setPINUsed setTimeout sendAnalog ' +
-        'readSlider analogRead beginWrite createChar ' +
-        'motorsStop keyPressed tempoWrite readButton ' +
-        'subnetMask debugPrint macAddress writeGreen ' +
-        'randomSeed attachGPRS readString sendString ' +
-        'remotePort releaseAll mouseMoved background ' +
-        'getXChange getYChange answerCall getResult ' +
-        'voiceCall endPacket constrain getSocket writeJSON ' +
-        'getButton available connected findUntil readBytes ' +
-        'exitValue readGreen writeBlue startLoop IPAddress ' +
-        'isPressed sendSysex pauseMode gatewayIP setCursor ' +
-        'getOemKey tuneWrite noDisplay loadImage switchPIN ' +
-        'onRequest onReceive changePIN playFile noBuffer ' +
-        'parseInt overflow checkPIN knobRead beginTFT ' +
-        'bitClear updateIR bitWrite position writeRGB ' +
-        'highByte writeRed setSpeed readBlue noStroke ' +
-        'remoteIP transfer shutdown hangCall beginSMS ' +
-        'endWrite attached maintain noCursor checkReg ' +
-        'checkPUK shiftOut isValid shiftIn pulseIn ' +
-        'connect println localIP pinMode getIMEI ' +
-        'display noBlink process getBand running beginSD ' +
-        'drawBMP lowByte setBand release bitRead prepare ' +
-        'pointTo readRed setMode noFill remove listen ' +
-        'stroke detach attach noTone exists buffer ' +
-        'height bitSet circle config cursor random ' +
-        'IRread setDNS endSMS getKey micros ' +
-        'millis begin print write ready flush width ' +
-        'isPIN blink clear press mkdir rmdir close ' +
-        'point yield image BSSID click delay ' +
-        'read text move peek beep rect line open ' +
-        'seek fill size turn stop home find ' +
-        'step tone sqrt RSSI SSID ' +
-        'end bit tan cos sin pow map abs max ' +
-        'min get run put',
-      literal:
-        'DIGITAL_MESSAGE FIRMATA_STRING ANALOG_MESSAGE ' +
-        'REPORT_DIGITAL REPORT_ANALOG INPUT_PULLUP ' +
-        'SET_PIN_MODE INTERNAL2V56 SYSTEM_RESET LED_BUILTIN ' +
-        'INTERNAL1V1 SYSEX_START INTERNAL EXTERNAL ' +
-        'DEFAULT OUTPUT INPUT HIGH LOW'
+  const ARDUINO_KW = {
+    keyword:
+      'boolean byte word String',
+    built_in:
+      'setup loop ' +
+      'KeyboardController MouseController SoftwareSerial ' +
+      'EthernetServer EthernetClient LiquidCrystal ' +
+      'RobotControl GSMVoiceCall EthernetUDP EsploraTFT ' +
+      'HttpClient RobotMotor WiFiClient GSMScanner ' +
+      'FileSystem Scheduler GSMServer YunClient YunServer ' +
+      'IPAddress GSMClient GSMModem Keyboard Ethernet ' +
+      'Console GSMBand Esplora Stepper Process ' +
+      'WiFiUDP GSM_SMS Mailbox USBHost Firmata PImage ' +
+      'Client Server GSMPIN FileIO Bridge Serial ' +
+      'EEPROM Stream Mouse Audio Servo File Task ' +
+      'GPRS WiFi Wire TFT GSM SPI SD ' +
+      'runShellCommandAsynchronously analogWriteResolution ' +
+      'retrieveCallingNumber printFirmwareVersion ' +
+      'analogReadResolution sendDigitalPortPair ' +
+      'noListenOnLocalhost readJoystickButton setFirmwareVersion ' +
+      'readJoystickSwitch scrollDisplayRight getVoiceCallStatus ' +
+      'scrollDisplayLeft writeMicroseconds delayMicroseconds ' +
+      'beginTransmission getSignalStrength runAsynchronously ' +
+      'getAsynchronously listenOnLocalhost getCurrentCarrier ' +
+      'readAccelerometer messageAvailable sendDigitalPorts ' +
+      'lineFollowConfig countryNameWrite runShellCommand ' +
+      'readStringUntil rewindDirectory readTemperature ' +
+      'setClockDivider readLightSensor endTransmission ' +
+      'analogReference detachInterrupt countryNameRead ' +
+      'attachInterrupt encryptionType readBytesUntil ' +
+      'robotNameWrite readMicrophone robotNameRead cityNameWrite ' +
+      'userNameWrite readJoystickY readJoystickX mouseReleased ' +
+      'openNextFile scanNetworks noInterrupts digitalWrite ' +
+      'beginSpeaker mousePressed isActionDone mouseDragged ' +
+      'displayLogos noAutoscroll addParameter remoteNumber ' +
+      'getModifiers keyboardRead userNameRead waitContinue ' +
+      'processInput parseCommand printVersion readNetworks ' +
+      'writeMessage blinkVersion cityNameRead readMessage ' +
+      'setDataMode parsePacket isListening setBitOrder ' +
+      'beginPacket isDirectory motorsWrite drawCompass ' +
+      'digitalRead clearScreen serialEvent rightToLeft ' +
+      'setTextSize leftToRight requestFrom keyReleased ' +
+      'compassRead analogWrite interrupts WiFiServer ' +
+      'disconnect playMelody parseFloat autoscroll ' +
+      'getPINUsed setPINUsed setTimeout sendAnalog ' +
+      'readSlider analogRead beginWrite createChar ' +
+      'motorsStop keyPressed tempoWrite readButton ' +
+      'subnetMask debugPrint macAddress writeGreen ' +
+      'randomSeed attachGPRS readString sendString ' +
+      'remotePort releaseAll mouseMoved background ' +
+      'getXChange getYChange answerCall getResult ' +
+      'voiceCall endPacket constrain getSocket writeJSON ' +
+      'getButton available connected findUntil readBytes ' +
+      'exitValue readGreen writeBlue startLoop IPAddress ' +
+      'isPressed sendSysex pauseMode gatewayIP setCursor ' +
+      'getOemKey tuneWrite noDisplay loadImage switchPIN ' +
+      'onRequest onReceive changePIN playFile noBuffer ' +
+      'parseInt overflow checkPIN knobRead beginTFT ' +
+      'bitClear updateIR bitWrite position writeRGB ' +
+      'highByte writeRed setSpeed readBlue noStroke ' +
+      'remoteIP transfer shutdown hangCall beginSMS ' +
+      'endWrite attached maintain noCursor checkReg ' +
+      'checkPUK shiftOut isValid shiftIn pulseIn ' +
+      'connect println localIP pinMode getIMEI ' +
+      'display noBlink process getBand running beginSD ' +
+      'drawBMP lowByte setBand release bitRead prepare ' +
+      'pointTo readRed setMode noFill remove listen ' +
+      'stroke detach attach noTone exists buffer ' +
+      'height bitSet circle config cursor random ' +
+      'IRread setDNS endSMS getKey micros ' +
+      'millis begin print write ready flush width ' +
+      'isPIN blink clear press mkdir rmdir close ' +
+      'point yield image BSSID click delay ' +
+      'read text move peek beep rect line open ' +
+      'seek fill size turn stop home find ' +
+      'step tone sqrt RSSI SSID ' +
+      'end bit tan cos sin pow map abs max ' +
+      'min get run put',
+    literal:
+      'DIGITAL_MESSAGE FIRMATA_STRING ANALOG_MESSAGE ' +
+      'REPORT_DIGITAL REPORT_ANALOG INPUT_PULLUP ' +
+      'SET_PIN_MODE INTERNAL2V56 SYSTEM_RESET LED_BUILTIN ' +
+      'INTERNAL1V1 SYSEX_START INTERNAL EXTERNAL ' +
+      'DEFAULT OUTPUT INPUT HIGH LOW'
   };
 
-  var ARDUINO = hljs.requireLanguage('cpp').rawDefinition();
+  const ARDUINO = cPlusPlus(hljs);
 
-  var kws = ARDUINO.keywords;
+  const kws = /** @type {Record<string,any>} */ (ARDUINO.keywords);
 
   kws.keyword += ' ' + ARDUINO_KW.keyword;
   kws.literal += ' ' + ARDUINO_KW.literal;
   kws.built_in += ' ' + ARDUINO_KW.built_in;
 
   ARDUINO.name = 'Arduino';
   ARDUINO.aliases = ['ino'];
+  ARDUINO.supersetOf = "cpp";
 
   return ARDUINO;
 }
diff --git a/src/languages/c.js b/src/languages/c.js
@@ -2,12 +2,13 @@
 Language: C
 Category: common, system
 Website: https://en.wikipedia.org/wiki/C_(programming_language)
-Requires: c-like.js
 */
 
+import cLike from './c-like.js';
+
 /** @type LanguageFn */
 export default function(hljs) {
-  var lang = hljs.requireLanguage('c-like').rawDefinition();
+  const lang = cLike(hljs);
   // Until C is actually different than C++ there is no reason to auto-detect C
   // as it's own language since it would just fail auto-detect testing or
   // simply match with C++.

diff --git a/src/languages/cpp.js b/src/languages/cpp.js
@@ -2,12 +2,13 @@
 Language: C++
 Category: common, system
 Website: https://isocpp.org
-Requires: c-like.js
 */
 
+import cLike from './c-like.js';
+
 /** @type LanguageFn */
 export default function(hljs) {
-  var lang = hljs.requireLanguage('c-like').rawDefinition();
+  const lang = cLike(hljs);
   // return auto-detection back on
   lang.disableAutodetect = false;
   lang.name = 'C++';