483 lines
12 KiB
JavaScript
483 lines
12 KiB
JavaScript
/**
|
||
* @import {ElementContent, Element, RootData, Root} from 'hast'
|
||
* @import {Emitter, HLJSOptions as HljsOptions, HighlightResult, LanguageFn} from 'highlight.js'
|
||
*/
|
||
|
||
/**
|
||
* @typedef {Object} ExtraOptions
|
||
* Extra fields.
|
||
* @property {ReadonlyArray<string> | null | undefined} [subset]
|
||
* List of allowed languages (default: all registered languages).
|
||
*
|
||
* @typedef Options
|
||
* Configuration for `highlight`.
|
||
* @property {string | null | undefined} [prefix='hljs-']
|
||
* Class prefix (default: `'hljs-'`).
|
||
*
|
||
* @typedef {Options & ExtraOptions} AutoOptions
|
||
* Configuration for `highlightAuto`.
|
||
*/
|
||
|
||
import {ok as assert} from 'devlop'
|
||
import HighlightJs from 'highlight.js/lib/core'
|
||
|
||
/** @type {AutoOptions} */
|
||
const emptyOptions = {}
|
||
|
||
const defaultPrefix = 'hljs-'
|
||
|
||
/**
|
||
* Create a `lowlight` instance.
|
||
*
|
||
* @param {Readonly<Record<string, LanguageFn>> | null | undefined} [grammars]
|
||
* Grammars to add (optional).
|
||
* @returns
|
||
* Lowlight.
|
||
*/
|
||
export function createLowlight(grammars) {
|
||
const high = HighlightJs.newInstance()
|
||
|
||
if (grammars) {
|
||
register(grammars)
|
||
}
|
||
|
||
return {
|
||
highlight,
|
||
highlightAuto,
|
||
listLanguages,
|
||
register,
|
||
registerAlias,
|
||
registered
|
||
}
|
||
|
||
/**
|
||
* Highlight `value` (code) as `language` (name).
|
||
*
|
||
* @example
|
||
* ```js
|
||
* import {common, createLowlight} from 'lowlight'
|
||
*
|
||
* const lowlight = createLowlight(common)
|
||
*
|
||
* console.log(lowlight.highlight('css', 'em { color: red }'))
|
||
* ```
|
||
*
|
||
* Yields:
|
||
*
|
||
* ```js
|
||
* {type: 'root', children: [Array], data: {language: 'css', relevance: 3}}
|
||
* ```
|
||
*
|
||
* @param {string} language
|
||
* Programming language name.
|
||
* @param {string} value
|
||
* Code to highlight.
|
||
* @param {Readonly<Options> | null | undefined} [options={}]
|
||
* Configuration (optional).
|
||
* @returns {Root}
|
||
* Tree; with the following `data` fields: `language` (`string`), detected
|
||
* programming language name; `relevance` (`number`), how sure lowlight is
|
||
* that the given code is in the language.
|
||
*/
|
||
function highlight(language, value, options) {
|
||
assert(typeof language === 'string', 'expected `string` as `name`')
|
||
assert(typeof value === 'string', 'expected `string` as `value`')
|
||
const settings = options || emptyOptions
|
||
const prefix =
|
||
typeof settings.prefix === 'string' ? settings.prefix : defaultPrefix
|
||
|
||
if (!high.getLanguage(language)) {
|
||
throw new Error('Unknown language: `' + language + '` is not registered')
|
||
}
|
||
|
||
// See: <https://github.com/highlightjs/highlight.js/issues/3621#issuecomment-1528841888>
|
||
high.configure({__emitter: HastEmitter, classPrefix: prefix})
|
||
|
||
const result = /** @type {HighlightResult & {_emitter: HastEmitter}} */ (
|
||
high.highlight(value, {ignoreIllegals: true, language})
|
||
)
|
||
|
||
// `highlight.js` seems to use this (currently) for broken grammars, so let’s
|
||
// keep it in there just to be sure.
|
||
/* c8 ignore next 5 */
|
||
if (result.errorRaised) {
|
||
throw new Error('Could not highlight with `Highlight.js`', {
|
||
cause: result.errorRaised
|
||
})
|
||
}
|
||
|
||
const root = result._emitter.root
|
||
|
||
// Cast because it is always defined.
|
||
const data = /** @type {RootData} */ (root.data)
|
||
|
||
data.language = result.language
|
||
data.relevance = result.relevance
|
||
|
||
return root
|
||
}
|
||
|
||
/**
|
||
* Highlight `value` (code) and guess its programming language.
|
||
*
|
||
* @example
|
||
* ```js
|
||
* import {common, createLowlight} from 'lowlight'
|
||
*
|
||
* const lowlight = createLowlight(common)
|
||
*
|
||
* console.log(lowlight.highlightAuto('"hello, " + name + "!"'))
|
||
* ```
|
||
*
|
||
* Yields:
|
||
*
|
||
* ```js
|
||
* {type: 'root', children: [Array], data: {language: 'arduino', relevance: 2}}
|
||
* ```
|
||
*
|
||
* @param {string} value
|
||
* Code to highlight.
|
||
* @param {Readonly<AutoOptions> | null | undefined} [options={}]
|
||
* Configuration (optional).
|
||
* @returns {Root}
|
||
* Tree; with the following `data` fields: `language` (`string`), detected
|
||
* programming language name; `relevance` (`number`), how sure lowlight is
|
||
* that the given code is in the language.
|
||
*/
|
||
function highlightAuto(value, options) {
|
||
assert(typeof value === 'string', 'expected `string` as `value`')
|
||
const settings = options || emptyOptions
|
||
const subset = settings.subset || listLanguages()
|
||
|
||
let index = -1
|
||
let relevance = 0
|
||
/** @type {Root | undefined} */
|
||
let result
|
||
|
||
while (++index < subset.length) {
|
||
const name = subset[index]
|
||
|
||
if (!high.getLanguage(name)) continue
|
||
|
||
const current = highlight(name, value, options)
|
||
|
||
if (
|
||
current.data &&
|
||
current.data.relevance !== undefined &&
|
||
current.data.relevance > relevance
|
||
) {
|
||
relevance = current.data.relevance
|
||
result = current
|
||
}
|
||
}
|
||
|
||
return (
|
||
result || {
|
||
type: 'root',
|
||
children: [],
|
||
data: {language: undefined, relevance}
|
||
}
|
||
)
|
||
}
|
||
|
||
/**
|
||
* List registered languages.
|
||
*
|
||
* @example
|
||
* ```js
|
||
* import {createLowlight} from 'lowlight'
|
||
* import markdown from 'highlight.js/lib/languages/markdown'
|
||
*
|
||
* const lowlight = createLowlight()
|
||
*
|
||
* console.log(lowlight.listLanguages()) // => []
|
||
*
|
||
* lowlight.register({markdown})
|
||
*
|
||
* console.log(lowlight.listLanguages()) // => ['markdown']
|
||
* ```
|
||
*
|
||
* @returns {Array<string>}
|
||
* Names of registered language.
|
||
*/
|
||
function listLanguages() {
|
||
return high.listLanguages()
|
||
}
|
||
|
||
/**
|
||
* Register languages.
|
||
*
|
||
* @example
|
||
* ```js
|
||
* import {createLowlight} from 'lowlight'
|
||
* import xml from 'highlight.js/lib/languages/xml'
|
||
*
|
||
* const lowlight = createLowlight()
|
||
*
|
||
* lowlight.register({xml})
|
||
*
|
||
* // Note: `html` is an alias for `xml`.
|
||
* console.log(lowlight.highlight('html', '<em>Emphasis</em>'))
|
||
* ```
|
||
*
|
||
* Yields:
|
||
*
|
||
* ```js
|
||
* {type: 'root', children: [Array], data: {language: 'html', relevance: 2}}
|
||
* ```
|
||
*
|
||
* @overload
|
||
* @param {Readonly<Record<string, LanguageFn>>} grammars
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {string} name
|
||
* @param {LanguageFn} grammar
|
||
* @returns {undefined}
|
||
*
|
||
* @param {Readonly<Record<string, LanguageFn>> | string} grammarsOrName
|
||
* Grammars or programming language name.
|
||
* @param {LanguageFn | undefined} [grammar]
|
||
* Grammar, if with name.
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*/
|
||
function register(grammarsOrName, grammar) {
|
||
if (typeof grammarsOrName === 'string') {
|
||
assert(grammar !== undefined, 'expected `grammar`')
|
||
high.registerLanguage(grammarsOrName, grammar)
|
||
} else {
|
||
/** @type {string} */
|
||
let name
|
||
|
||
for (name in grammarsOrName) {
|
||
if (Object.hasOwn(grammarsOrName, name)) {
|
||
high.registerLanguage(name, grammarsOrName[name])
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Register aliases.
|
||
*
|
||
* @example
|
||
* ```js
|
||
* import {createLowlight} from 'lowlight'
|
||
* import markdown from 'highlight.js/lib/languages/markdown'
|
||
*
|
||
* const lowlight = createLowlight()
|
||
*
|
||
* lowlight.register({markdown})
|
||
*
|
||
* // lowlight.highlight('mdown', '<em>Emphasis</em>')
|
||
* // ^ would throw: Error: Unknown language: `mdown` is not registered
|
||
*
|
||
* lowlight.registerAlias({markdown: ['mdown', 'mkdn', 'mdwn', 'ron']})
|
||
* lowlight.highlight('mdown', '<em>Emphasis</em>')
|
||
* // ^ Works!
|
||
* ```
|
||
*
|
||
* @overload
|
||
* @param {Readonly<Record<string, ReadonlyArray<string> | string>>} aliases
|
||
* @returns {undefined}
|
||
*
|
||
* @overload
|
||
* @param {string} language
|
||
* @param {ReadonlyArray<string> | string} alias
|
||
* @returns {undefined}
|
||
*
|
||
* @param {Readonly<Record<string, ReadonlyArray<string> | string>> | string} aliasesOrName
|
||
* Map of programming language names to one or more aliases, or programming
|
||
* language name.
|
||
* @param {ReadonlyArray<string> | string | undefined} [alias]
|
||
* One or more aliases for the programming language, if with `name`.
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*/
|
||
function registerAlias(aliasesOrName, alias) {
|
||
if (typeof aliasesOrName === 'string') {
|
||
assert(alias !== undefined)
|
||
high.registerAliases(
|
||
// Note: copy needed because hljs doesn’t accept readonly arrays yet.
|
||
typeof alias === 'string' ? alias : [...alias],
|
||
{languageName: aliasesOrName}
|
||
)
|
||
} else {
|
||
/** @type {string} */
|
||
let key
|
||
|
||
for (key in aliasesOrName) {
|
||
if (Object.hasOwn(aliasesOrName, key)) {
|
||
const aliases = aliasesOrName[key]
|
||
high.registerAliases(
|
||
// Note: copy needed because hljs doesn’t accept readonly arrays yet.
|
||
typeof aliases === 'string' ? aliases : [...aliases],
|
||
{languageName: key}
|
||
)
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Check whether an alias or name is registered.
|
||
*
|
||
* @example
|
||
* ```js
|
||
* import {createLowlight} from 'lowlight'
|
||
* import javascript from 'highlight.js/lib/languages/javascript'
|
||
*
|
||
* const lowlight = createLowlight({javascript})
|
||
*
|
||
* console.log(lowlight.registered('funkyscript')) // => `false`
|
||
*
|
||
* lowlight.registerAlias({javascript: 'funkyscript'})
|
||
* console.log(lowlight.registered('funkyscript')) // => `true`
|
||
* ```
|
||
*
|
||
* @param {string} aliasOrName
|
||
* Name of a language or alias for one.
|
||
* @returns {boolean}
|
||
* Whether `aliasOrName` is registered.
|
||
*/
|
||
function registered(aliasOrName) {
|
||
return Boolean(high.getLanguage(aliasOrName))
|
||
}
|
||
}
|
||
|
||
/** @type {Emitter} */
|
||
class HastEmitter {
|
||
/**
|
||
* @param {Readonly<HljsOptions>} options
|
||
* Configuration.
|
||
* @returns
|
||
* Instance.
|
||
*/
|
||
constructor(options) {
|
||
/** @type {HljsOptions} */
|
||
this.options = options
|
||
/** @type {Root} */
|
||
this.root = {
|
||
type: 'root',
|
||
children: [],
|
||
data: {language: undefined, relevance: 0}
|
||
}
|
||
/** @type {[Root, ...Array<Element>]} */
|
||
this.stack = [this.root]
|
||
}
|
||
|
||
/**
|
||
* @param {string} value
|
||
* Text to add.
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*
|
||
*/
|
||
addText(value) {
|
||
if (value === '') return
|
||
|
||
const current = this.stack[this.stack.length - 1]
|
||
const tail = current.children[current.children.length - 1]
|
||
|
||
if (tail && tail.type === 'text') {
|
||
tail.value += value
|
||
} else {
|
||
current.children.push({type: 'text', value})
|
||
}
|
||
}
|
||
|
||
/**
|
||
*
|
||
* @param {unknown} rawName
|
||
* Name to add.
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*/
|
||
startScope(rawName) {
|
||
this.openNode(String(rawName))
|
||
}
|
||
|
||
/**
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*/
|
||
endScope() {
|
||
this.closeNode()
|
||
}
|
||
|
||
/**
|
||
* @param {HastEmitter} other
|
||
* Other emitter.
|
||
* @param {string} name
|
||
* Name of the sublanguage.
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*/
|
||
__addSublanguage(other, name) {
|
||
const current = this.stack[this.stack.length - 1]
|
||
// Assume only element content.
|
||
const results = /** @type {Array<ElementContent>} */ (other.root.children)
|
||
|
||
if (name) {
|
||
current.children.push({
|
||
type: 'element',
|
||
tagName: 'span',
|
||
properties: {className: [name]},
|
||
children: results
|
||
})
|
||
} else {
|
||
current.children.push(...results)
|
||
}
|
||
}
|
||
|
||
/**
|
||
* @param {string} name
|
||
* Name to add.
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*/
|
||
openNode(name) {
|
||
const self = this
|
||
// First “class” gets the prefix. Rest gets a repeated underscore suffix.
|
||
// See: <https://github.com/highlightjs/highlight.js/commit/51806aa>
|
||
// See: <https://github.com/wooorm/lowlight/issues/43>
|
||
const className = name.split('.').map(function (d, i) {
|
||
return i ? d + '_'.repeat(i) : self.options.classPrefix + d
|
||
})
|
||
const current = this.stack[this.stack.length - 1]
|
||
/** @type {Element} */
|
||
const child = {
|
||
type: 'element',
|
||
tagName: 'span',
|
||
properties: {className},
|
||
children: []
|
||
}
|
||
|
||
current.children.push(child)
|
||
this.stack.push(child)
|
||
}
|
||
|
||
/**
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*/
|
||
closeNode() {
|
||
this.stack.pop()
|
||
}
|
||
|
||
/**
|
||
* @returns {undefined}
|
||
* Nothing.
|
||
*/
|
||
finalize() {}
|
||
|
||
/**
|
||
* @returns {string}
|
||
* Nothing.
|
||
*/
|
||
toHTML() {
|
||
return ''
|
||
}
|
||
}
|