<!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#.disableWorkerMessageHandler">disableWorkerMessageHandler</a></li><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#line299">line 299</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#line336">line 336</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#line421">line 421</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.10</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>
