683 lines
14 KiB
HTML
683 lines
14 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
|
|
<meta charset="utf-8">
|
|
<title>languages - Documentation</title>
|
|
|
|
|
|
<meta property="og:title" content="Prism generated API documentation"/>
|
|
<meta property="og:type" content="website"/>
|
|
<meta property="og:image" content="/logo.svg"/>
|
|
<meta property="og:site_name" content="Prism"/>
|
|
<meta property="og:url" content="https://prismjs.com"/>
|
|
|
|
<script src="scripts/prettify/prettify.js"></script>
|
|
<script src="scripts/prettify/lang-css.js"></script>
|
|
<!--[if lt IE 9]>
|
|
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
|
|
<![endif]-->
|
|
<link type="text/css" rel="stylesheet" href="styles/prettify.css">
|
|
<link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
|
|
<script src="scripts/nav.js" defer></script>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<link rel="icon" type="image/png" href="/favicon.png"/>
|
|
</head>
|
|
<body>
|
|
|
|
<input type="checkbox" id="nav-trigger" class="nav-trigger" />
|
|
<label for="nav-trigger" class="navicon-button x">
|
|
<div class="navicon"></div>
|
|
</label>
|
|
|
|
<label for="nav-trigger" class="overlay"></label>
|
|
|
|
<nav >
|
|
|
|
<input type="text" id="nav-search" placeholder="Search" />
|
|
|
|
<h2><a href="index.html">Home</a></h2><h2><a href="https://prismjs.com" class="menu-item" id="website_link" >PrismJS</a></h2><h2><a href="https://github.com/PrismJS/prism" target="_blank" class="menu-item" id="github_link" >GitHub</a></h2><h3>Classes</h3><ul><li><a href="Token.html">Token</a></li></ul><h3>Namespaces</h3><ul><li><a href="Prism.html">Prism</a><ul class='members'><li data-type='member'><a href="Prism.html#.manual">manual</a></li></ul><ul class='methods'><li data-type='method'><a href="Prism.html#.highlight">highlight</a></li><li data-type='method'><a href="Prism.html#.highlightAll">highlightAll</a></li><li data-type='method'><a href="Prism.html#.highlightAllUnder">highlightAllUnder</a></li><li data-type='method'><a href="Prism.html#.highlightElement">highlightElement</a></li><li data-type='method'><a href="Prism.html#.tokenize">tokenize</a></li></ul></li><li><a href="Prism.hooks.html">hooks</a><ul class='methods'><li data-type='method'><a href="Prism.hooks.html#.add">add</a></li><li data-type='method'><a href="Prism.hooks.html#.run">run</a></li></ul></li><li><a href="Prism.languages.html">languages</a><ul class='methods'><li data-type='method'><a href="Prism.languages.html#.extend">extend</a></li><li data-type='method'><a href="Prism.languages.html#.insertBefore">insertBefore</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#Grammar">Grammar</a></li><li><a href="global.html#GrammarToken">GrammarToken</a></li><li><a href="global.html#HighlightCallback">HighlightCallback</a></li><li><a href="global.html#HookCallback">HookCallback</a></li><li><a href="global.html#TokenStream">TokenStream</a></li></ul>
|
|
</nav>
|
|
|
|
<div id="main">
|
|
|
|
<h1 class="page-title">languages</h1>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<section>
|
|
|
|
<header>
|
|
|
|
<h2>
|
|
<span class="ancestors"><a href="Prism.html">Prism</a>.</span>
|
|
|
|
languages
|
|
</h2>
|
|
|
|
|
|
</header>
|
|
|
|
<article>
|
|
|
|
<div class="container-overview">
|
|
|
|
|
|
|
|
<dl class="details">
|
|
|
|
|
|
<dt class="tag-source">Source:</dt>
|
|
<dd class="tag-source"><ul class="dummy"><li>
|
|
<a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line257">line 257</a>
|
|
</li></ul></dd>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="description usertext"><p>This namespace contains all currently loaded languages and the some helper functions to create and modify languages.</p></div>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h3 class="subsection-title">Methods</h3>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h4 class="name" id=".extend"><span class="type-signature">(static) </span>extend<span class="signature">(id, redef)</span><span class="type-signature"> → {<a href="global.html#Grammar">Grammar</a>}</span></h4>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<dl class="details">
|
|
|
|
|
|
<dt class="tag-source">Source:</dt>
|
|
<dd class="tag-source"><ul class="dummy"><li>
|
|
<a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line286">line 286</a>
|
|
</li></ul></dd>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="description usertext">
|
|
<p>Creates a deep copy of the language with the given id and appends the given tokens.</p>
|
|
<p>If a token in <code>redef</code> also appears in the copied language, then the existing token in the copied language
|
|
will be overwritten at its original position.</p>
|
|
<h2>Best practices</h2>
|
|
<p>Since the position of overwriting tokens (token in <code>redef</code> that overwrite tokens in the copied language)
|
|
doesn't matter, they can technically be in any order. However, this can be confusing to others that trying to
|
|
understand the language definition because, normally, the order of tokens matters in Prism grammars.</p>
|
|
<p>Therefore, it is encouraged to order overwriting tokens according to the positions of the overwritten tokens.
|
|
Furthermore, all non-overwriting tokens should be placed after the overwriting ones.</p>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h5>Example</h5>
|
|
|
|
<pre class="prettyprint"><code>Prism.languages['css-with-colors'] = Prism.languages.extend('css', {
|
|
// Prism.languages.css already has a 'comment' token, so this token will overwrite CSS' 'comment' token
|
|
// at its original position
|
|
'comment': { ... },
|
|
// CSS doesn't have a 'color' token, so this token will be appended
|
|
'color': /\b(?:red|green|blue)\b/
|
|
});</code></pre>
|
|
|
|
|
|
|
|
|
|
<h5>Parameters:</h5>
|
|
|
|
|
|
<table class="params">
|
|
<thead>
|
|
<tr>
|
|
|
|
<th>Name</th>
|
|
|
|
|
|
<th>Type</th>
|
|
|
|
|
|
|
|
|
|
|
|
<th class="last">Description</th>
|
|
</tr>
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
|
|
<tr>
|
|
|
|
<td class="name"><code>id</code></td>
|
|
|
|
|
|
<td class="type">
|
|
|
|
|
|
<span class="param-type">string</span>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
|
|
|
|
|
|
<td class="description last"><p>The id of the language to extend. This has to be a key in <code>Prism.languages</code>.</p></td>
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td class="name"><code>redef</code></td>
|
|
|
|
|
|
<td class="type">
|
|
|
|
|
|
<span class="param-type"><a href="global.html#Grammar">Grammar</a></span>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
|
|
|
|
|
|
<td class="description last"><p>The new tokens to append.</p></td>
|
|
</tr>
|
|
|
|
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h5>Returns:</h5>
|
|
|
|
|
|
<div class="param-desc">
|
|
<p>The new language created.</p>
|
|
</div>
|
|
|
|
|
|
|
|
<dl class="param-type">
|
|
<dt>
|
|
Type
|
|
</dt>
|
|
<dd>
|
|
|
|
<span class="param-type"><a href="global.html#Grammar">Grammar</a></span>
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h4 class="name" id=".insertBefore"><span class="type-signature">(static) </span>insertBefore<span class="signature">(inside, before, insert, root<span class="signature-attributes">opt</span>)</span><span class="type-signature"> → {<a href="global.html#Grammar">Grammar</a>}</span></h4>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<dl class="details">
|
|
|
|
|
|
<dt class="tag-source">Source:</dt>
|
|
<dd class="tag-source"><ul class="dummy"><li>
|
|
<a href="prism-core.js.html">prism-core.js</a>, <a href="prism-core.js.html#line371">line 371</a>
|
|
</li></ul></dd>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="description usertext">
|
|
<p>Inserts tokens <em>before</em> another token in a language definition or any other grammar.</p>
|
|
<h2>Usage</h2>
|
|
<p>This helper method makes it easy to modify existing languages. For example, the CSS language definition
|
|
not only defines CSS highlighting for CSS documents, but also needs to define highlighting for CSS embedded
|
|
in HTML through <code><style></code> elements. To do this, it needs to modify <code>Prism.languages.markup</code> and add the
|
|
appropriate tokens. However, <code>Prism.languages.markup</code> is a regular JavaScript object literal, so if you do
|
|
this:</p>
|
|
<pre class="prettyprint source lang-js"><code>Prism.languages.markup.style = {
|
|
// token
|
|
};
|
|
</code></pre>
|
|
<p>then the <code>style</code> token will be added (and processed) at the end. <code>insertBefore</code> allows you to insert tokens
|
|
before existing tokens. For the CSS example above, you would use it like this:</p>
|
|
<pre class="prettyprint source lang-js"><code>Prism.languages.insertBefore('markup', 'cdata', {
|
|
'style': {
|
|
// token
|
|
}
|
|
});
|
|
</code></pre>
|
|
<h2>Special cases</h2>
|
|
<p>If the grammars of <code>inside</code> and <code>insert</code> have tokens with the same name, the tokens in <code>inside</code>'s grammar
|
|
will be ignored.</p>
|
|
<p>This behavior can be used to insert tokens after <code>before</code>:</p>
|
|
<pre class="prettyprint source lang-js"><code>Prism.languages.insertBefore('markup', 'comment', {
|
|
'comment': Prism.languages.markup.comment,
|
|
// tokens after 'comment'
|
|
});
|
|
</code></pre>
|
|
<h2>Limitations</h2>
|
|
<p>The main problem <code>insertBefore</code> has to solve is iteration order. Since ES2015, the iteration order for object
|
|
properties is guaranteed to be the insertion order (except for integer keys) but some browsers behave
|
|
differently when keys are deleted and re-inserted. So <code>insertBefore</code> can't be implemented by temporarily
|
|
deleting properties which is necessary to insert at arbitrary positions.</p>
|
|
<p>To solve this problem, <code>insertBefore</code> doesn't actually insert the given tokens into the target object.
|
|
Instead, it will create a new object and replace all references to the target object with the new one. This
|
|
can be done without temporarily deleting properties, so the iteration order is well-defined.</p>
|
|
<p>However, only references that can be reached from <code>Prism.languages</code> or <code>insert</code> will be replaced. I.e. if
|
|
you hold the target object in a variable, then the value of the variable will not change.</p>
|
|
<pre class="prettyprint source lang-js"><code>var oldMarkup = Prism.languages.markup;
|
|
var newMarkup = Prism.languages.insertBefore('markup', 'comment', { ... });
|
|
|
|
assert(oldMarkup !== Prism.languages.markup);
|
|
assert(newMarkup === Prism.languages.markup);
|
|
</code></pre>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h5>Parameters:</h5>
|
|
|
|
|
|
<table class="params">
|
|
<thead>
|
|
<tr>
|
|
|
|
<th>Name</th>
|
|
|
|
|
|
<th>Type</th>
|
|
|
|
|
|
<th>Attributes</th>
|
|
|
|
|
|
|
|
|
|
<th class="last">Description</th>
|
|
</tr>
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
|
|
<tr>
|
|
|
|
<td class="name"><code>inside</code></td>
|
|
|
|
|
|
<td class="type">
|
|
|
|
|
|
<span class="param-type">string</span>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
<td class="attributes">
|
|
|
|
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
|
|
|
|
<td class="description last"><p>The property of <code>root</code> (e.g. a language id in <code>Prism.languages</code>) that contains the
|
|
object to be modified.</p></td>
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td class="name"><code>before</code></td>
|
|
|
|
|
|
<td class="type">
|
|
|
|
|
|
<span class="param-type">string</span>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
<td class="attributes">
|
|
|
|
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
|
|
|
|
<td class="description last"><p>The key to insert before.</p></td>
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td class="name"><code>insert</code></td>
|
|
|
|
|
|
<td class="type">
|
|
|
|
|
|
<span class="param-type"><a href="global.html#Grammar">Grammar</a></span>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
<td class="attributes">
|
|
|
|
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
|
|
|
|
<td class="description last"><p>An object containing the key-value pairs to be inserted.</p></td>
|
|
</tr>
|
|
|
|
|
|
|
|
<tr>
|
|
|
|
<td class="name"><code>root</code></td>
|
|
|
|
|
|
<td class="type">
|
|
|
|
|
|
<span class="param-type">Object.<string, any></span>
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
<td class="attributes">
|
|
|
|
<optional><br>
|
|
|
|
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
|
|
|
|
|
<td class="description last"><p>The object containing <code>inside</code>, i.e. the object that contains the
|
|
object to be modified.</p>
|
|
<p>Defaults to <code>Prism.languages</code>.</p></td>
|
|
</tr>
|
|
|
|
|
|
</tbody>
|
|
</table>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h5>Returns:</h5>
|
|
|
|
|
|
<div class="param-desc">
|
|
<p>The new grammar object.</p>
|
|
</div>
|
|
|
|
|
|
|
|
<dl class="param-type">
|
|
<dt>
|
|
Type
|
|
</dt>
|
|
<dd>
|
|
|
|
<span class="param-type"><a href="global.html#Grammar">Grammar</a></span>
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</article>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
<br class="clear">
|
|
|
|
<footer>
|
|
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.4</a> using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
|
|
</footer>
|
|
|
|
<script>prettyPrint();</script>
|
|
<script src="scripts/polyfill.js"></script>
|
|
<script src="scripts/linenumber.js"></script>
|
|
|
|
<script src="scripts/search.js" defer></script>
|
|
|
|
|
|
|
|
<link type="text/css" rel="stylesheet" href="styles/overwrites.css">
|
|
|
|
</body>
|
|
</html> |