Github
/
prism
mirror of
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
prism/docs/Prism.html

1460 lines
25 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Prism - 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">Prism</h1>
<section>
<header>
<h2>
Prism
</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#line19">line 19</a>
</li></ul></dd>
<dt class="tag-author">Author:</dt>
<dd class="tag-author">
<ul>
<li>Lea Verou &lt;https://lea.verou.me></li>
</ul>
</dd>
<dt class="tag-license">License:</dt>
<dd class="tag-license"><ul class="dummy"><li>MIT <https://opensource.org/licenses/MIT></li></ul></dd>
</dl>
<div class="description usertext"><p>Prism: Lightweight, robust, elegant syntax highlighting</p></div>
</div>
<h3 class="subsection-title">Namespaces</h3>
<dl>
<dt><a href="Prism.hooks.html">hooks</a></dt>
<dd></dd>
<dt><a href="Prism.languages.html">languages</a></dt>
<dd></dd>
</dl>
<h3 class="subsection-title">Members</h3>
<h4 class="name" id=".disableWorkerMessageHandler"><span class="type-signature">(static) </span>disableWorkerMessageHandler<span class="type-signature"> :boolean</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#line73">line 73</a>
</li></ul></dd>
<dt class="tag-default">Default Value:</dt>
<dd class="tag-default"><ul class="dummy">
<li>false</li>
</ul></dd>
</dl>
<div class="description usertext">
<p>By default, if Prism is in a web worker, it assumes that it is in a worker it created itself, so it uses
<code>addEventListener</code> to communicate with its parent instance. However, if you're using Prism manually in your
own worker, you don't want it to do this.</p>
<p>By setting this value to <code>true</code>, Prism will not add its own listeners to the worker.</p>
<p>You obviously have to change this value before Prism executes. To do this, you can add an
empty Prism object into the global scope before loading the Prism script like this:</p>
<pre class="prettyprint source lang-js"><code>window.Prism = window.Prism || {};
Prism.disableWorkerMessageHandler = true;
// Load Prism's script
</code></pre>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">boolean</span>
</li>
</ul>
<h4 class="name" id=".manual"><span class="type-signature">(static) </span>manual<span class="type-signature"> :boolean</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#line51">line 51</a>
</li></ul></dd>
<dt class="tag-default">Default Value:</dt>
<dd class="tag-default"><ul class="dummy">
<li>false</li>
</ul></dd>
</dl>
<div class="description usertext">
<p>By default, Prism will attempt to highlight all code elements (by calling <a href="Prism.html#.highlightAll"><code>Prism.highlightAll</code></a>) on the
current page after the page finished loading. This might be a problem if e.g. you wanted to asynchronously load
additional languages or plugins yourself.</p>
<p>By setting this value to <code>true</code>, Prism will not automatically highlight all code elements on the page.</p>
<p>You obviously have to change this value before the automatic highlighting started. To do this, you can add an
empty Prism object into the global scope before loading the Prism script like this:</p>
<pre class="prettyprint source lang-js"><code>window.Prism = window.Prism || {};
Prism.manual = true;
// add a new &lt;script> to load Prism's script
</code></pre>
</div>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">boolean</span>
</li>
</ul>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id=".highlight"><span class="type-signature">(static) </span>highlight<span class="signature">(text, grammar, language)</span><span class="type-signature"> &rarr; {string}</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#line655">line 655</a>
</li></ul></dd>
</dl>
<div class="description usertext">
<p>Low-level function, only use if you know what you’re doing. It accepts a string of text as input
and the language definitions to use, and returns a string with the HTML produced.</p>
<p>The following hooks will be run:</p>
<ol>
<li><code>before-tokenize</code></li>
<li><code>after-tokenize</code></li>
<li><code>wrap</code>: On each <a href="Token.html"><code>Token</code></a>.</li>
</ol>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>Prism.highlight('var foo = true;', Prism.languages.javascript, 'javascript');</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>text</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>A string with the code to be highlighted.</p></td>
</tr>
<tr>
<td class="name"><code>grammar</code></td>
<td class="type">
<span class="param-type"><a href="global.html#Grammar">Grammar</a></span>
</td>
<td class="description last"><p>An object containing the tokens to use.</p>
<p>Usually a language definition like <code>Prism.languages.markup</code>.</p></td>
</tr>
<tr>
<td class="name"><code>language</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The name of the language definition passed to <code>grammar</code>.</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>The highlighted HTML.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type">string</span>
</dd>
</dl>
<h4 class="name" id=".highlightAll"><span class="type-signature">(static) </span>highlightAll<span class="signature">(async<span class="signature-attributes">opt</span>, callback<span class="signature-attributes">opt</span>)</span><span class="type-signature"></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#line497">line 497</a>
</li></ul></dd>
</dl>
<div class="description usertext">
<p>This is the most high-level function in Prism’s API.
It fetches all the elements that have a <code>.language-xxxx</code> class and then calls <a href="Prism.html#.highlightElement"><code>Prism.highlightElement</code></a> on
each one of them.</p>
<p>This is equivalent to <code>Prism.highlightAllUnder(document, async, callback)</code>.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>async</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><p>Same as in <a href="Prism.html#.highlightAllUnder"><code>Prism.highlightAllUnder</code></a>.</p></td>
</tr>
<tr>
<td class="name"><code>callback</code></td>
<td class="type">
<span class="param-type"><a href="global.html#HighlightCallback">HighlightCallback</a></span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
</td>
<td class="description last"><p>Same as in <a href="Prism.html#.highlightAllUnder"><code>Prism.highlightAllUnder</code></a>.</p></td>
</tr>
</tbody>
</table>
<h4 class="name" id=".highlightAllUnder"><span class="type-signature">(static) </span>highlightAllUnder<span class="signature">(container, async<span class="signature-attributes">opt</span>, callback<span class="signature-attributes">opt</span>)</span><span class="type-signature"></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#line516">line 516</a>
</li></ul></dd>
</dl>
<div class="description usertext">
<p>Fetches all the descendants of <code>container</code> that have a <code>.language-xxxx</code> class and then calls
<a href="Prism.html#.highlightElement"><code>Prism.highlightElement</code></a> on each one of them.</p>
<p>The following hooks will be run:</p>
<ol>
<li><code>before-highlightall</code></li>
<li><code>before-all-elements-highlight</code></li>
<li>All hooks of <a href="Prism.html#.highlightElement"><code>Prism.highlightElement</code></a> for each element.</li>
</ol>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>container</code></td>
<td class="type">
<span class="param-type">ParentNode</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last"><p>The root element, whose descendants that have a <code>.language-xxxx</code> class will be highlighted.</p></td>
</tr>
<tr>
<td class="name"><code>async</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><p>Whether each element is to be highlighted asynchronously using Web Workers.</p></td>
</tr>
<tr>
<td class="name"><code>callback</code></td>
<td class="type">
<span class="param-type"><a href="global.html#HighlightCallback">HighlightCallback</a></span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
</td>
<td class="description last"><p>An optional callback to be invoked on each element after its highlighting is done.</p></td>
</tr>
</tbody>
</table>
<h4 class="name" id=".highlightElement"><span class="type-signature">(static) </span>highlightElement<span class="signature">(element, async<span class="signature-attributes">opt</span>, callback<span class="signature-attributes">opt</span>)</span><span class="type-signature"></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#line562">line 562</a>
</li></ul></dd>
</dl>
<div class="description usertext">
<p>Highlights the code inside a single element.</p>
<p>The following hooks will be run:</p>
<ol>
<li><code>before-sanity-check</code></li>
<li><code>before-highlight</code></li>
<li>All hooks of <a href="Prism.html#.highlight"><code>Prism.highlight</code></a>. These hooks will be run by an asynchronous worker if <code>async</code> is <code>true</code>.</li>
<li><code>before-insert</code></li>
<li><code>after-highlight</code></li>
<li><code>complete</code></li>
</ol>
<p>Some the above hooks will be skipped if the element doesn't contain any text or there is no grammar loaded for
the element's language.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th>Default</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>element</code></td>
<td class="type">
<span class="param-type">Element</span>
</td>
<td class="attributes">
</td>
<td class="default">
</td>
<td class="description last"><p>The element containing the code.
It must have a class of <code>language-xxxx</code> to be processed, where <code>xxxx</code> is a valid language identifier.</p></td>
</tr>
<tr>
<td class="name"><code>async</code></td>
<td class="type">
<span class="param-type">boolean</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
<code>false</code>
</td>
<td class="description last"><p>Whether the element is to be highlighted asynchronously using Web Workers
to improve performance and avoid blocking the UI when highlighting very large chunks of code. This option is
<a href="https://prismjs.com/faq.html#why-is-asynchronous-highlighting-disabled-by-default">disabled by default</a>.</p>
<p>Note: All language definitions required to highlight the code must be included in the main <code>prism.js</code> file for
asynchronous highlighting to work. You can build your own bundle on the
<a href="https://prismjs.com/download.html">Download page</a>.</p></td>
</tr>
<tr>
<td class="name"><code>callback</code></td>
<td class="type">
<span class="param-type"><a href="global.html#HighlightCallback">HighlightCallback</a></span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="default">
</td>
<td class="description last"><p>An optional callback to be invoked after the highlighting is done.
Mostly useful when <code>async</code> is <code>true</code>, since in that case, the highlighting is done asynchronously.</p></td>
</tr>
</tbody>
</table>
<h4 class="name" id=".tokenize"><span class="type-signature">(static) </span>tokenize<span class="signature">(text, grammar)</span><span class="type-signature"> &rarr; {<a href="global.html#TokenStream">TokenStream</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#line694">line 694</a>
</li></ul></dd>
</dl>
<div class="description usertext">
<p>This is the heart of Prism, and the most low-level function you can use. It accepts a string of text as input
and the language definitions to use, and returns an array with the tokenized code.</p>
<p>When the language definition includes nested tokens, the function is called recursively on each of these tokens.</p>
<p>This method could be useful in other contexts as well, as a very crude parser.</p>
</div>
<h5>Example</h5>
<pre class="prettyprint"><code>let code = `var foo = 0;`;
let tokens = Prism.tokenize(code, Prism.languages.javascript);
tokens.forEach(token => {
if (token instanceof Prism.Token &amp;&amp; token.type === 'number') {
console.log(`Found numeric literal: ${token.content}`);
}
});</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>text</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>A string with the code to be highlighted.</p></td>
</tr>
<tr>
<td class="name"><code>grammar</code></td>
<td class="type">
<span class="param-type"><a href="global.html#Grammar">Grammar</a></span>
</td>
<td class="description last"><p>An object containing the tokens to use.</p>
<p>Usually a language definition like <code>Prism.languages.markup</code>.</p></td>
</tr>
</tbody>
</table>
<h5>Returns:</h5>
<div class="param-desc">
<p>An array of strings and tokens, a token stream.</p>
</div>
<dl class="param-type">
<dt>
Type
</dt>
<dd>
<span class="param-type"><a href="global.html#TokenStream">TokenStream</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>
Reference in New Issue View Git Blame Copy Permalink