mirror of
https://github.com/hanzoai/postcss.git
synced 2026-09-24 17:01:56 +00:00
278 lines
23 KiB
HTML
278 lines
23 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<title>processor.es6 - Documentation</title>
|
||
|
||
<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">
|
||
</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>
|
||
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="AtRule.html">AtRule</a><ul class='methods'><li data-type='method'><a href="AtRule.html#append">append</a></li><li data-type='method'><a href="AtRule.html#each">each</a></li><li data-type='method'><a href="AtRule.html#every">every</a></li><li data-type='method'><a href="AtRule.html#index">index</a></li><li data-type='method'><a href="AtRule.html#insertAfter">insertAfter</a></li><li data-type='method'><a href="AtRule.html#insertBefore">insertBefore</a></li><li data-type='method'><a href="AtRule.html#prepend">prepend</a></li><li data-type='method'><a href="AtRule.html#removeAll">removeAll</a></li><li data-type='method'><a href="AtRule.html#removeChild">removeChild</a></li><li data-type='method'><a href="AtRule.html#replaceValues">replaceValues</a></li><li data-type='method'><a href="AtRule.html#some">some</a></li><li data-type='method'><a href="AtRule.html#walk">walk</a></li><li data-type='method'><a href="AtRule.html#walkAtRules">walkAtRules</a></li><li data-type='method'><a href="AtRule.html#walkComments">walkComments</a></li><li data-type='method'><a href="AtRule.html#walkDecls">walkDecls</a></li><li data-type='method'><a href="AtRule.html#walkRules">walkRules</a></li></ul></li><li><a href="Comment.html">Comment</a><ul class='methods'><li data-type='method'><a href="Comment.html#after">after</a></li><li data-type='method'><a href="Comment.html#before">before</a></li><li data-type='method'><a href="Comment.html#cleanRaws">cleanRaws</a></li><li data-type='method'><a href="Comment.html#clone">clone</a></li><li data-type='method'><a href="Comment.html#cloneAfter">cloneAfter</a></li><li data-type='method'><a href="Comment.html#cloneBefore">cloneBefore</a></li><li data-type='method'><a href="Comment.html#error">error</a></li><li data-type='method'><a href="Comment.html#next">next</a></li><li data-type='method'><a href="Comment.html#prev">prev</a></li><li data-type='method'><a href="Comment.html#raw">raw</a></li><li data-type='method'><a href="Comment.html#remove">remove</a></li><li data-type='method'><a href="Comment.html#replaceWith">replaceWith</a></li><li data-type='method'><a href="Comment.html#root">root</a></li><li data-type='method'><a href="Comment.html#toString">toString</a></li><li data-type='method'><a href="Comment.html#warn">warn</a></li></ul></li><li><a href="Container.html">Container</a><ul class='methods'><li data-type='method'><a href="Container.html#after">after</a></li><li data-type='method'><a href="Container.html#append">append</a></li><li data-type='method'><a href="Container.html#before">before</a></li><li data-type='method'><a href="Container.html#cleanRaws">cleanRaws</a></li><li data-type='method'><a href="Container.html#clone">clone</a></li><li data-type='method'><a href="Container.html#cloneAfter">cloneAfter</a></li><li data-type='method'><a href="Container.html#cloneBefore">cloneBefore</a></li><li data-type='method'><a href="Container.html#each">each</a></li><li data-type='method'><a href="Container.html#error">error</a></li><li data-type='method'><a href="Container.html#every">every</a></li><li data-type='method'><a href="Container.html#index">index</a></li><li data-type='method'><a href="Container.html#insertAfter">insertAfter</a></li><li data-type='method'><a href="Container.html#insertBefore">insertBefore</a></li><li data-type='method'><a href="Container.html#next">next</a></li><li data-type='method'><a href="Container.html#prepend">prepend</a></li><li data-type='method'><a href="Container.html#prev">prev</a></li><li data-type='method'><a href="Container.html#raw">raw</a></li><li data-type='method'><a href="Container.html#remove">remove</a></li><li data-type='method'><a href="Container.html#removeAll">removeAll</a></li><li data-type='method'><a href="Container.html#removeChild">removeChild</a></li><li data-type='method'><a href="Container.html#replaceValues">replaceValues</a></li><li data-type='method'><a href="Container.html#replaceWith">replaceWith</a></li><li data-type='method'><a href="Container.html#root">root</a></li><li data-type='method'><a href="Container.html#some">some</a></li><li data-type='method'><a href="Container.html#toString">toString</a></li><li data-type='method'><a href="Container.html#walk">walk</a></li><li data-type='method'><a href="Container.html#walkAtRules">walkAtRules</a></li><li data-type='method'><a href="Container.html#walkComments">walkComments</a></li><li data-type='method'><a href="Container.html#walkDecls">walkDecls</a></li><li data-type='method'><a href="Container.html#walkRules">walkRules</a></li><li data-type='method'><a href="Container.html#warn">warn</a></li></ul></li><li><a href="CssSyntaxError.html">CssSyntaxError</a><ul class='methods'><li data-type='method'><a href="CssSyntaxError.html#showSourceCode">showSourceCode</a></li><li data-type='method'><a href="CssSyntaxError.html#toString">toString</a></li></ul></li><li><a href="Declaration.html">Declaration</a><ul class='methods'><li data-type='method'><a href="Declaration.html#after">after</a></li><li data-type='method'><a href="Declaration.html#before">before</a></li><li data-type='method'><a href="Declaration.html#cleanRaws">cleanRaws</a></li><li data-type='method'><a href="Declaration.html#clone">clone</a></li><li data-type='method'><a href="Declaration.html#cloneAfter">cloneAfter</a></li><li data-type='method'><a href="Declaration.html#cloneBefore">cloneBefore</a></li><li data-type='method'><a href="Declaration.html#error">error</a></li><li data-type='method'><a href="Declaration.html#next">next</a></li><li data-type='method'><a href="Declaration.html#prev">prev</a></li><li data-type='method'><a href="Declaration.html#raw">raw</a></li><li data-type='method'><a href="Declaration.html#remove">remove</a></li><li data-type='method'><a href="Declaration.html#replaceWith">replaceWith</a></li><li data-type='method'><a href="Declaration.html#root">root</a></li><li data-type='method'><a href="Declaration.html#toString">toString</a></li><li data-type='method'><a href="Declaration.html#warn">warn</a></li></ul></li><li><a href="Input.html">Input</a><ul class='methods'><li data-type='method'><a href="Input.html#origin">origin</a></li></ul></li><li><a href="LazyResult.html">LazyResult</a><ul class='methods'><li data-type='method'><a href="LazyResult.html#catch">catch</a></li><li data-type='method'><a href="LazyResult.html#finally">finally</a></li><li data-type='method'><a href="LazyResult.html#then">then</a></li><li data-type='method'><a href="LazyResult.html#toString">toString</a></li><li data-type='method'><a href="LazyResult.html#warnings">warnings</a></li></ul></li><li><a href="Node.html">Node</a><ul class='methods'><li data-type='method'><a href="Node.html#after">after</a></li><li data-type='method'><a href="Node.html#before">before</a></li><li data-type='method'><a href="Node.html#cleanRaws">cleanRaws</a></li><li data-type='method'><a href="Node.html#clone">clone</a></li><li data-type='method'><a href="Node.html#cloneAfter">cloneAfter</a></li><li data-type='method'><a href="Node.html#cloneBefore">cloneBefore</a></li><li data-type='method'><a href="Node.html#error">error</a></li><li data-type='method'><a href="Node.html#next">next</a></li><li data-type='method'><a href="Node.html#prev">prev</a></li><li data-type='method'><a href="Node.html#raw">raw</a></li><li data-type='method'><a href="Node.html#remove">remove</a></li><li data-type='method'><a href="Node.html#replaceWith">replaceWith</a></li><li data-type='method'><a href="Node.html#root">root</a></li><li data-type='method'><a href="Node.html#toString">toString</a></li><li data-type='method'><a href="Node.html#warn">warn</a></li></ul></li><li><a href="PreviousMap.html">PreviousMap</a><ul class='methods'><li data-type='method'><a href="PreviousMap.html#consumer">consumer</a></li><li data-type='method'><a href="PreviousMap.html#withContent">withContent</a></li></ul></li><li><a href="Processor.html">Processor</a><ul class='methods'><li data-type='method'><a href="Processor.html#process">process</a></li><li data-type='method'><a href="Processor.html#use">use</a></li></ul></li><li><a href="Result.html">Result</a><ul class='methods'><li data-type='method'><a href="Result.html#toString">toString</a></li><li data-type='method'><a href="Result.html#warn">warn</a></li><li data-type='method'><a href="Result.html#warnings">warnings</a></li></ul></li><li><a href="Root.html">Root</a><ul class='methods'><li data-type='method'><a href="Root.html#after">after</a></li><li data-type='method'><a href="Root.html#append">append</a></li><li data-type='method'><a href="Root.html#before">before</a></li><li data-type='method'><a href="Root.html#cleanRaws">cleanRaws</a></li><li data-type='method'><a href="Root.html#clone">clone</a></li><li data-type='method'><a href="Root.html#cloneAfter">cloneAfter</a></li><li data-type='method'><a href="Root.html#cloneBefore">cloneBefore</a></li><li data-type='method'><a href="Root.html#each">each</a></li><li data-type='method'><a href="Root.html#error">error</a></li><li data-type='method'><a href="Root.html#every">every</a></li><li data-type='method'><a href="Root.html#index">index</a></li><li data-type='method'><a href="Root.html#insertAfter">insertAfter</a></li><li data-type='method'><a href="Root.html#insertBefore">insertBefore</a></li><li data-type='method'><a href="Root.html#next">next</a></li><li data-type='method'><a href="Root.html#prepend">prepend</a></li><li data-type='method'><a href="Root.html#prev">prev</a></li><li data-type='method'><a href="Root.html#raw">raw</a></li><li data-type='method'><a href="Root.html#remove">remove</a></li><li data-type='method'><a href="Root.html#removeAll">removeAll</a></li><li data-type='method'><a href="Root.html#removeChild">removeChild</a></li><li data-type='method'><a href="Root.html#replaceValues">replaceValues</a></li><li data-type='method'><a href="Root.html#replaceWith">replaceWith</a></li><li data-type='method'><a href="Root.html#root">root</a></li><li data-type='method'><a href="Root.html#some">some</a></li><li data-type='method'><a href="Root.html#toResult">toResult</a></li><li data-type='method'><a href="Root.html#toString">toString</a></li><li data-type='method'><a href="Root.html#walk">walk</a></li><li data-type='method'><a href="Root.html#walkAtRules">walkAtRules</a></li><li data-type='method'><a href="Root.html#walkComments">walkComments</a></li><li data-type='method'><a href="Root.html#walkDecls">walkDecls</a></li><li data-type='method'><a href="Root.html#walkRules">walkRules</a></li><li data-type='method'><a href="Root.html#warn">warn</a></li></ul></li><li><a href="Rule.html">Rule</a><ul class='methods'><li data-type='method'><a href="Rule.html#after">after</a></li><li data-type='method'><a href="Rule.html#append">append</a></li><li data-type='method'><a href="Rule.html#before">before</a></li><li data-type='method'><a href="Rule.html#cleanRaws">cleanRaws</a></li><li data-type='method'><a href="Rule.html#clone">clone</a></li><li data-type='method'><a href="Rule.html#cloneAfter">cloneAfter</a></li><li data-type='method'><a href="Rule.html#cloneBefore">cloneBefore</a></li><li data-type='method'><a href="Rule.html#each">each</a></li><li data-type='method'><a href="Rule.html#error">error</a></li><li data-type='method'><a href="Rule.html#every">every</a></li><li data-type='method'><a href="Rule.html#index">index</a></li><li data-type='method'><a href="Rule.html#insertAfter">insertAfter</a></li><li data-type='method'><a href="Rule.html#insertBefore">insertBefore</a></li><li data-type='method'><a href="Rule.html#next">next</a></li><li data-type='method'><a href="Rule.html#prepend">prepend</a></li><li data-type='method'><a href="Rule.html#prev">prev</a></li><li data-type='method'><a href="Rule.html#raw">raw</a></li><li data-type='method'><a href="Rule.html#remove">remove</a></li><li data-type='method'><a href="Rule.html#removeAll">removeAll</a></li><li data-type='method'><a href="Rule.html#removeChild">removeChild</a></li><li data-type='method'><a href="Rule.html#replaceValues">replaceValues</a></li><li data-type='method'><a href="Rule.html#replaceWith">replaceWith</a></li><li data-type='method'><a href="Rule.html#root">root</a></li><li data-type='method'><a href="Rule.html#some">some</a></li><li data-type='method'><a href="Rule.html#toString">toString</a></li><li data-type='method'><a href="Rule.html#walk">walk</a></li><li data-type='method'><a href="Rule.html#walkAtRules">walkAtRules</a></li><li data-type='method'><a href="Rule.html#walkComments">walkComments</a></li><li data-type='method'><a href="Rule.html#walkDecls">walkDecls</a></li><li data-type='method'><a href="Rule.html#walkRules">walkRules</a></li><li data-type='method'><a href="Rule.html#warn">warn</a></li></ul></li><li><a href="Warning.html">Warning</a><ul class='methods'><li data-type='method'><a href="Warning.html#toString">toString</a></li></ul></li></ul><h3>Namespaces</h3><ul><li><a href="list.html">list</a><ul class='methods'><li data-type='method'><a href="list.html#.comma">comma</a></li><li data-type='method'><a href="list.html#.space">space</a></li></ul></li><li><a href="postcss.html">postcss</a><ul class='methods'><li data-type='method'><a href="postcss.html#.atRule">atRule</a></li><li data-type='method'><a href="postcss.html#.comment">comment</a></li><li data-type='method'><a href="postcss.html#.decl">decl</a></li><li data-type='method'><a href="postcss.html#.parse">parse</a></li><li data-type='method'><a href="postcss.html#.plugin">plugin</a></li><li data-type='method'><a href="postcss.html#.root">root</a></li><li data-type='method'><a href="postcss.html#.rule">rule</a></li><li data-type='method'><a href="postcss.html#.stringify">stringify</a></li></ul></li><li><a href="vendor.html">vendor</a><ul class='methods'><li data-type='method'><a href="vendor.html#.prefix">prefix</a></li><li data-type='method'><a href="vendor.html#.unprefixed">unprefixed</a></li></ul></li></ul><h3><a href="global.html">Global</a></h3>
|
||
</nav>
|
||
|
||
<div id="main">
|
||
|
||
<h1 class="page-title">processor.es6</h1>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<section>
|
||
<article>
|
||
<pre class="prettyprint source linenums"><code>import LazyResult from './lazy-result'
|
||
|
||
/**
|
||
* Contains plugins to process CSS. Create one `Processor` instance,
|
||
* initialize its plugins, and then use that instance on numerous CSS files.
|
||
*
|
||
* @example
|
||
* const processor = postcss([autoprefixer, precss])
|
||
* processor.process(css1).then(result => console.log(result.css))
|
||
* processor.process(css2).then(result => console.log(result.css))
|
||
*/
|
||
class Processor {
|
||
/**
|
||
* @param {Array.<Plugin|pluginFunction>|Processor} plugins PostCSS plugins.
|
||
* See {@link Processor#use} for plugin format.
|
||
*/
|
||
constructor (plugins = []) {
|
||
/**
|
||
* Current PostCSS version.
|
||
*
|
||
* @type {string}
|
||
*
|
||
* @example
|
||
* if (result.processor.version.split('.')[0] !== '6') {
|
||
* throw new Error('This plugin works only with PostCSS 6')
|
||
* }
|
||
*/
|
||
this.version = '7.0.1'
|
||
/**
|
||
* Plugins added to this processor.
|
||
*
|
||
* @type {pluginFunction[]}
|
||
*
|
||
* @example
|
||
* const processor = postcss([autoprefixer, precss])
|
||
* processor.plugins.length //=> 2
|
||
*/
|
||
this.plugins = this.normalize(plugins)
|
||
}
|
||
|
||
/**
|
||
* Adds a plugin to be used as a CSS processor.
|
||
*
|
||
* PostCSS plugin can be in 4 formats:
|
||
* * A plugin created by {@link postcss.plugin} method.
|
||
* * A function. PostCSS will pass the function a @{link Root}
|
||
* as the first argument and current {@link Result} instance
|
||
* as the second.
|
||
* * An object with a `postcss` method. PostCSS will use that method
|
||
* as described in #2.
|
||
* * Another {@link Processor} instance. PostCSS will copy plugins
|
||
* from that instance into this one.
|
||
*
|
||
* Plugins can also be added by passing them as arguments when creating
|
||
* a `postcss` instance (see [`postcss(plugins)`]).
|
||
*
|
||
* Asynchronous plugins should return a `Promise` instance.
|
||
*
|
||
* @param {Plugin|pluginFunction|Processor} plugin PostCSS plugin
|
||
* or {@link Processor}
|
||
* with plugins.
|
||
*
|
||
* @example
|
||
* const processor = postcss()
|
||
* .use(autoprefixer)
|
||
* .use(precss)
|
||
*
|
||
* @return {Processes} Current processor to make methods chain.
|
||
*/
|
||
use (plugin) {
|
||
this.plugins = this.plugins.concat(this.normalize([plugin]))
|
||
return this
|
||
}
|
||
|
||
/**
|
||
* Parses source CSS and returns a {@link LazyResult} Promise proxy.
|
||
* Because some plugins can be asynchronous it doesn’t make
|
||
* any transformations. Transformations will be applied
|
||
* in the {@link LazyResult} methods.
|
||
*
|
||
* @param {string|toString|Result} css String with input CSS or any object
|
||
* with a `toString()` method,
|
||
* like a Buffer. Optionally, send
|
||
* a {@link Result} instance
|
||
* and the processor will take
|
||
* the {@link Root} from it.
|
||
* @param {processOptions} [opts] Options.
|
||
*
|
||
* @return {LazyResult} Promise proxy.
|
||
*
|
||
* @example
|
||
* processor.process(css, { from: 'a.css', to: 'a.out.css' })
|
||
* .then(result => {
|
||
* console.log(result.css)
|
||
* })
|
||
*/
|
||
process (css, opts = { }) {
|
||
if (this.plugins.length === 0 && opts.parser === opts.stringifier) {
|
||
if (process.env.NODE_ENV !== 'production') {
|
||
if (typeof console !== 'undefined' && console.warn) {
|
||
console.warn(
|
||
'You did not set any plugins, parser, or stringifier. ' +
|
||
'Right now PostCSS do nothing. Pick plugins for your case ' +
|
||
'on https://www.postcss.parts/ and usem them in postcss.config.js.'
|
||
)
|
||
}
|
||
}
|
||
}
|
||
return new LazyResult(this, css, opts)
|
||
}
|
||
|
||
normalize (plugins) {
|
||
let normalized = []
|
||
for (let i of plugins) {
|
||
if (i.postcss) i = i.postcss
|
||
|
||
if (typeof i === 'object' && Array.isArray(i.plugins)) {
|
||
normalized = normalized.concat(i.plugins)
|
||
} else if (typeof i === 'function') {
|
||
normalized.push(i)
|
||
} else if (typeof i === 'object' && (i.parse || i.stringify)) {
|
||
if (process.env.NODE_ENV !== 'production') {
|
||
throw new Error(
|
||
'PostCSS syntaxes cannot be used as plugins. Instead, please use ' +
|
||
'one of the syntax/parser/stringifier options as outlined ' +
|
||
'in your PostCSS runner documentation.'
|
||
)
|
||
}
|
||
} else {
|
||
throw new Error(i + ' is not a PostCSS plugin')
|
||
}
|
||
}
|
||
return normalized
|
||
}
|
||
}
|
||
|
||
export default Processor
|
||
|
||
/**
|
||
* @callback builder
|
||
* @param {string} part Part of generated CSS connected to this node.
|
||
* @param {Node} node AST node.
|
||
* @param {"start"|"end"} [type] Node’s part type.
|
||
*/
|
||
|
||
/**
|
||
* @callback parser
|
||
*
|
||
* @param {string|toString} css String with input CSS or any object
|
||
* with toString() method, like a Buffer.
|
||
* @param {processOptions} [opts] Options with only `from` and `map` keys.
|
||
*
|
||
* @return {Root} PostCSS AST
|
||
*/
|
||
|
||
/**
|
||
* @callback stringifier
|
||
*
|
||
* @param {Node} node Start node for stringifing. Usually {@link Root}.
|
||
* @param {builder} builder Function to concatenate CSS from node’s parts
|
||
* or generate string and source map.
|
||
*
|
||
* @return {void}
|
||
*/
|
||
|
||
/**
|
||
* @typedef {object} syntax
|
||
* @property {parser} parse Function to generate AST by string.
|
||
* @property {stringifier} stringify Function to generate string by AST.
|
||
*/
|
||
|
||
/**
|
||
* @typedef {object} toString
|
||
* @property {function} toString
|
||
*/
|
||
|
||
/**
|
||
* @callback pluginFunction
|
||
* @param {Root} root Parsed input CSS.
|
||
* @param {Result} result Result to set warnings or check other plugins.
|
||
*/
|
||
|
||
/**
|
||
* @typedef {object} Plugin
|
||
* @property {function} postcss PostCSS plugin function.
|
||
*/
|
||
|
||
/**
|
||
* @typedef {object} processOptions
|
||
* @property {string} from The path of the CSS source file.
|
||
* You should always set `from`,
|
||
* because it is used in source map
|
||
* generation and syntax error messages.
|
||
* @property {string} to The path where you’ll put the output
|
||
* CSS file. You should always set `to`
|
||
* to generate correct source maps.
|
||
* @property {parser} parser Function to generate AST by string.
|
||
* @property {stringifier} stringifier Class to generate string by AST.
|
||
* @property {syntax} syntax Object with `parse` and `stringify`.
|
||
* @property {object} map Source map options.
|
||
* @property {boolean} map.inline Does source map should
|
||
* be embedded in the output
|
||
* CSS as a base64-encoded
|
||
* comment.
|
||
* @property {string|object|false|function} map.prev Source map content
|
||
* from a previous
|
||
* processing step
|
||
* (for example, Sass).
|
||
* PostCSS will try to find
|
||
* previous map automatically,
|
||
* so you could disable it by
|
||
* `false` value.
|
||
* @property {boolean} map.sourcesContent Does PostCSS should set
|
||
* the origin content to map.
|
||
* @property {string|false} map.annotation Does PostCSS should set
|
||
* annotation comment to map.
|
||
* @property {string} map.from Override `from` in map’s
|
||
* sources`.
|
||
*/
|
||
</code></pre>
|
||
</article>
|
||
</section>
|
||
|
||
|
||
|
||
|
||
</div>
|
||
|
||
<br class="clear">
|
||
|
||
<footer>
|
||
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
|
||
</footer>
|
||
|
||
<script>prettyPrint();</script>
|
||
<script src="scripts/linenumber.js"></script>
|
||
</body>
|
||
</html>
|