diff --git a/CHANGES.md b/CHANGES.md index 564d2874c8..a10d111c42 100644 --- 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 index 73fb131c65..877f2c0bda 100644 --- 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 ``
`` 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 index f4bc9e1e74..c4e2f6ddb5 100644 --- 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 index ce105003c7..a706ad6ff5 100644 --- a/src/languages/arduino.js +++ b/src/languages/arduino.js @@ -2,102 +2,102 @@ Language: Arduino Author: Stefania Mellai 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} */ (ARDUINO.keywords); kws.keyword += ' ' + ARDUINO_KW.keyword; kws.literal += ' ' + ARDUINO_KW.literal; @@ -105,6 +105,7 @@ export default function(hljs) { ARDUINO.name = 'Arduino'; ARDUINO.aliases = ['ino']; + ARDUINO.supersetOf = "cpp"; return ARDUINO; } diff --git a/src/languages/c.js b/src/languages/c.js index d2eb8223f2..1ace9d497d 100644 --- 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 index 7c9f940031..7aab27f772 100644 --- 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++';