postcss.language.txt

                                  ┏━━━━━━━━━━━━━┓
                                  ┃   POSTCSS   ┃
                                  ┗━━━━━━━━━━━━━┛

ALTERNATIVES ==>                  #Parser:
                                  #  - postCSS: more audience and better fit for processing plugins.
                                  #  - gonzales-pe
                                  #  - reworkcss/css
                                  #  - parser-lib
                                  #Postprocessor:
                                  #  - Sass: more power than Less (see Less doc for Sass/Less comparisons)
                                  #  - Less: more user-friendly than Sass (see Less doc for Sass/Less comparisons)
                                  #  - Stylus: more features than Sass/Less
                                  #  - PostCSS (prefer):
                                  #     - more modular and powerful.
                                  #     - handles better new CSS features (nesting, etc.) that will make preprocessors
                                  #       less relevant as a whole.

VERSION ==>                       #5.0.19
                                  #CSS parser/stringifier, with good plugins support, allowing easy CSS processing.

SUMMARY ==>                       #  - parsing/stringifier of CSS
                                  #  - use plugins middleware
                                  #  - can customize parsing/stringifier to support new syntax (Sass/Less/Stylus/CSS-in-JS)
                                  #  - can be used as a Sass/Less/Stylus-like processor, with almost same features, with
                                  #    extra support for JavaScript functions/mixins
                                  #  - reporting is done separately
                                  #  - others:
                                  #     - url() processing


CONFIG ==>                        #Can be:
                                  #  - postcss --config CONF_FILE
CONF_FILE                         #JSON or Node module exporting CONF_OBJ
CONF_OBJ.OPT                      #Like postcss --OPT


postcss [FILE|DIR...]             #Def: stdin
                                  #Version 2.5.1
--output FILE                     #Def: stdout
--dir DIR                         #
--replace                         #Replace input file

--watch                           #

--[no-]map [FILE]                 #Sourcemaps (def: inline)
--[no-]map.inline                 #Inline sourcemaps (def: true)
--[no-]map.annotation 'FILE'      #Sourcemap output
--[no-]map.prev 'FILE'            #Sourcemaps from a previous compilation step, e.g. Sess/Less
                                  #Def: automatically detects it
--[no-]map.sourcesContent         #Sets sourcemap origin (def: true)

                                  ┏━━━━━━━━━━━━━┓
                                  ┃   PLUGINS   ┃
                                  ┗━━━━━━━━━━━━━┛

                                  ┌─────────────┐
                                  │   PLUGINS   │
                                  └─────────────┘

CONF_OBJ.plugin
postcss --PLUGIN.option           #PLUGIN_OPTS

postcss
--use PLUGIN ...                  #
--local-plugins                   #Require PLUGIN from $PWD, as opposed to DIR where PostCSS is installed

POSTCSS.plugin                    #PLUGIN() is middleware called during PROCESSOR.process():
('PLUGIN', PLUGINFUNC(PLUGIN_OPTS)#  - ROOT can be modified. It can also be replaced by assigning RESULT.root
->PLUGIN(ROOT,RESULT))->PLUGINFUNC#  - RESULT can get extra messages.
                                  #  - PLUGIN() must return PROMISE if async
PLUGINFUNC(PLUGIN_OPTS)->PLUGIN   #
PLUGINFUNC.postcss                #PLUGIN (from PLUGINFUNC()) created right away

POSTCSS([VAL_ARR])->PROCESSOR
PROCESSOR.use(VAL)->PROCESSOR     #VAL can be:
                                  #  - any FUNC(ROOT, RESULT), including PLUGIN
                                  #  - { postcss(ROOT, RESULT) ... }: use OBJ.postcss
                                  #  - PLUGINFUNC: use PLUGINFUNC.postcss
                                  #  - PROCESSOR2: use PROCESSOR2.plugins
@use PLUGIN([PLUGN_OPT: VAL,...])##Loads Plugin from CSS, for a given files
@use PLUGIN PLUGIN_OPTS          ##Use POSTCSS-USE PLUGIN (2.0.2) with PLUGIN_OPTS:
                                 ##  - modules VAL[_ARR]: plugins to whitelist (mandatory)
                                 ##    Can be '*'

PROCESSOR.plugins                 #PLUGIN_ARR
PLUGIN.postcssPlugin              #'PLUGIN'
PLUGIN.postcssVersion             #PostCSS version

                                  ┌────────────┐
                                  │   CUSTOM   │
                                  └────────────┘

PREPROCESSING VS POSTPROCESSING   #Concepts:
 ==>                              #  - processing: Sass/Less/Stylus or using Sass/Less/Stylus-like PostCSS plugins
                                  #  - preprocessing: PostCSS plugins used before processing:
                                  #     - need SYNTAX so that processor-specific syntax:
                                  #        - does not crash crashing
                                  #        - semantics is present in parsed nodes
                                  #     - advantages:
                                  #        - closer to the source, e.g. want to lint source not output CSS
                                  #        - useful if no processing involved, e.g. Sass library
                                  #     - but might make plugins (which only take standard CSS into account) misbehave
                                  #  - postprocessing: PostCSS plugins used after processing


postcss --parser MODULE           #Resolving to PARSER
CONF_OBJ.parser                   #PARSER
PARSER                            #Is FUNC or {parser: FUNC}
PARSER('CSS', CONF_OBJ)->ROOT     #PARSER does the 'CSS'->ROOT conversion, which helps using PostCSS with something different
                                  #than standard CSS (e.g. Sass/Less)

postcss --stringifier MODULE      #Resolving to STRINGIFIER
CONF_OBJ.stringifier              #STRINGIFIER
NODE.toString(STRINGIFIER)        #
STRINGIFIER                       #Is FUNC or {stringifier: FUNC}
STRINGIFIER                       #STRINGIFIER does the ROOT->final output conversion (formatter)
(ROOT,FUNC(STR,NOD[,'start|end']))#Must call each successive NODE with FUNC, and provide corresponding output STR.

postcss --syntax MODULE           #Resolving to SYNTAX
CONF_OBJ.syntax                   #SYNTAX
SYNTAX                            #Is { parser: PARSER, stringifier: STRINGIFIER }

                                  ┌──────────────┐
                                  │   SYNTAXES   │
                                  └──────────────┘

POSTCSS-SCSS                      #SYNTAX to support Sass syntax (0.1.7)
                                  #Supported without SYNTAX:
                                  #  - selector nesting
                                  #Somewhat supported without SYNTAX:
                                  #  - %CLASS: TAG SELECTOR
                                  #  - @extend|mixin|etc.: ATRULE with PARAMS and children {...}
                                  #  - !default|optional, $VAR: part of surrounding value, as a WORD
                                  #  - PROP[: VAL] { PROP2: VAL }: TAG SELECTOR. PROP: VAL fails with POSTCSS-SELECTOR-PARSER
                                  #  - $VAR: VAL: DECLARATION
                                  #  - #{...}: part of surrounding value, as a WORD, but does not work when used e.g. as SELECTOR
                                  #Supported only with SYNTAX:
                                  #  - // COMMENT: COMMENT with: raws.inline true
                                  #  - can use #{...} anywhere. In SELECTOR will be ID|TAG depending on # place

POSTCSS-LESS                      #SYNTAX to support Less syntax (4.1.8)
                                  #Supported without SYNTAX:
                                  #  - selector nesting
                                  #Somewhat supported without SYNTAX:
                                  #  - :extend(SELECTOR): PSEUDO selector
                                  #  - @VAR: part of surrounding value, as WORD
                                  #  - EXPR: part of surrounding value, as WORD|SPACE|DIV|STRING|FUNCTION...
                                  #  - PROP+: VAL: use 'PROP+' as PROP
                                  #  - @VAR: VAL: ATRULE
                                  #  - MIXIN(...): MIXIN(...) is TAG SELECTOR. Only work with {...}
                                  #Supported only with SYNTAX:
                                  #  - // COMMENT: COMMENT with COMMENT.raws.inline true
                                  #  - @VAR: VAL: DECLARATION
                                  #  - MIXIN(...) [{...}]:
                                  #     - RULE with:
                                  #        - selector 'MIXIN(...)'
                                  #        - params, raws.params.value|raw '(...)'
                                  #        - {...}: children
                                  #     - must be .MIXIN or #MIXIN

SUGARSS                           #SYNTAX to support indentation-based syntax, like Stylus (0.1.2)
                                  #Syntax:
                                  #  - tabs instead of {}
                                  #     - multiline:
                                  #        - the continuation line must have bigger indent (but anything bigger, so can vertically align)
                                  #        - if ambiguous, use trailing \
                                  #  - // COMMENT
                                  #  - must use spaces around tokens, e.g. PROP: VAL
                                  #  - extension .sss, MIME type 'text/s-sugarss'

POSTCSS-JS                        #SYNTAX to support CSS in JS (0.1.2)
                                  #Can also be used for 'CSS' <-> CSS_OBJ conversion
                                  #SYNTAX API differences:
                                  #  - OBJ.parse(CSS_OBJ)->ROOT instead of OBJ.parse('CSS')->ROOT
                                  #  - OBJ.objectify(ROOT)->CSS_OBJ instead of OBJ.stringify(ROOT)
                                  #  - OBJ.[a]sync([VAL_ARR])->FUNC(CSS_OBJ)->CSS_OBJ:
                                  #    shortcut to POSTCSS([VAL_ARR]).process(CSS_OBJ)->CSS_OBJ (using OBJ.parse|objectify)
                                  #Takes in JavaScript CSS_OBJ

                                  ┏━━━━━━━━━━━━━━━━┓
                                  ┃   PROCESSING   ┃
                                  ┗━━━━━━━━━━━━━━━━┛

                                  ┌────────────────┐
                                  │   PROCESSING   │
                                  └────────────────┘

POSTCSS.parse('CSS', OBJ)->ROOT   #OBJ:
                                  #  - from 'FILE'
                                  #  - map: inline BOOL, annotation 'FILE'|BOOL, prev 'FILE'|BOOL, sourcesContent BOOL

PROCESSOR.process                 #CONF_OBJ also has:
('CSS'|ROOT|RESULT, CONF_OBJ)     #  - from|to 'FILE'
->PROMISE(RESULT)                 #  - map: same as POSTCSS.parse()
                                  #When using synchronous plugins, can use PROMISE.result RESULT instead
                                  #Note: processing is only fired when PROMISE.then|catch() or RESULT.FUNC() is called
PLUGINFUNC.process(VAL, CONF_OBJ) #Same as POSTCSS([PLUGINFUNC(CONF_OBJ)]).process(VAL, CONF_OBJ)

RESULT.root                       #ROOT
RESULT.toString()
RESULT.css|content                #Same as RESULT.root.toString()

RESULT.warn('REASON', OBJ)        #Same as OBJ.node.warn('REASON', OBJ), but node is optional.
RESULT.warnings()->WARNING_ARR    #
RESULT.messages                   #CSSSYNTAXERR|WARNING_ARR

RESULT.map                        #Similar to INPUT.map
RESULT.processor                  #PROCESSOR
RESULT.opts                       #OBJ passed to PROCESSOR.process() or to ROOT.toResult()

                                  ┌──────────┐
                                  │   NODE   │
                                  └──────────┘

NODE                              #
NODE_PROPS                        #Plain OBJ with attributes specific to a NODE|CONTAINER subtype, e.g. name|params for ATRULE
NODE.type                         #'root|atrule|rule|decl|comment'

NODE.toString()->'CSS'            #
NODE.raws                         #OBJ:
                                  #  (RULE|DECLARATION|ATRULE|COMMENT)
                                  #  - before STR: whitespaces and browser hacks before NODE, before/* for a COMMENT
                                  #  (ROOT|RULE|COMMENT)
                                  #  - after STR: whitespaces and browser hacks after NODE, after */ for a COMMENT
                                  #  (ROOT|RULE)
                                  #  - semicolon BOOL: true if last child has it
                                  #  (RULE|DECLARATION)
                                  #  - between STR: anything in-between
                                  #  (ATRULE)
                                  #  - afterName STR: whitespaces between @RULE and VAL
                                  #  (DECLARATION)
                                  #  - important STR
NODE.raw('VAR')                   #Similar to NODE.raws.VAR, except fill in default
NODE.source                       #Location from input file (for sourcemaps) as OBJ:
                                  #  - input INPUT
                                  #  - start|end: line|column NUM
                                  #Will be null when creating new NODE from scratch. Should then take a NODE with source and
                                  #either copy its NODE.source or clone it.

NODE.root()->ROOT                 #
NODE.parent                       #NODE|undefined
NODE.prev|next()->NODE|undefined  #Siblings
                                  #Fires exception for ROOT

NODE.moveTo(CONTAINER)            #
NODE.moveBefore|After(NODE2)      #
NODE.remove()                     #
NODE.replaceWith(NODE2...)        #
NODE.clone([OBJ])->NODE2          #OBJ is assigned to NODE2
NODE.cloneBefore|After([OBJ])     #Clone then inserts before|after

NODE.error('REASON'[, OBJ])       #OBJ:
->CSSSYNTAXERR                    #  - plugin 'PLUGIN' (def: set automatically)
                                  #  - word STR: highlight this word
                                  #  - index NUM: highlight this character
NODE.warn(RESULT, 'REASON'[, OBJ])#Same OBJ as NODE.error()
                                  #Adds a WARNING to RESULT.messages

                                  ┌───────────────┐
                                  │   CONTAINER   │
                                  └───────────────┘

CONTAINER                         #NODE that contain other NODE
CONTAINER.nodes                   #NODE_ARR
CONTAINER.first|last              #NODE
CONTAINER.index(NODE)->NUM|-1     #

CONTAINER.every|some(FUNC)        #Same as CONTAINER.nodes.every|some(FUNC)
CONTAINER.each(FUNC)              #Same as CONTAINER.nodes.each(FUNC) except:
                                  #  - can return false to stop iteration
                                  #  - safe if mutation children during iteration
CONTAINER.walk(FUNC(NODE, NUM))   #Like CONTAINER.each() but iterates over descendants
CONTAINER.walkDecls|              #Like CONTAINER.walk() but:
AtRules|Rules|Comments            #  - filters only DECLARATION|ATRULE|RULE|COMMENT
([STR|REGEXP, ]FUNC(NODE, NUM))   #  - filters according to STR|REGEXP:
                                  #     - used to match DECLARATION.prop, ATRULE.name or RULE selector
                                  #     - not used for COMMENT
CONTAINER.replaceValues           #Replace children DECLARATION values.
(STR|REGEXP[, OBJ], STR2[(...)])  #STR2(...) gets same arguments as STR.replace(...)
                                  #OBJ:
                                  #  - props 'PROP'_ARR: only for those properties
                                  #  - fast 'STR': does indexOf(STR) before performing REGEXP.test(), just can be performance
                                  #    boost

CONTAINER.prepend|append          #NODE_VAL can be:
(NODE_VAL[_ARR]...)               #  - NODE
                                  #  - NODE_PROPS
                                  #  - 'CSS' (slower)
CONTAINER.insertBefore|After
(NODE|NUM, NODE_VAL)              #
CONTAINER.removeChild(NODE|NUM)   #
CONTAINER.removeAll()             #

                                  ┌───────────┐
                                  │   NODES   │
                                  └───────────┘

POSTCSS.root|atRule|rule|decl|
comment([NODE_PROPS])->ROOT|
ATRULE|RULE|DECLARATION|COMMENT   #Creates new NODE of that type

ROOT                              #CSS file, as CONTAINER
ROOT.toResult(OBJ)->RESULT        #OBJ: same as POSTCSS.parse()

ATRULE                            #'@RULE VAL... [{ ... }]', as CONTAINER
                                  #{ ... } are children
                                  #With Sass, this can be @at-root|extend|import|debug|warn|error|if|else|
                                  #for|each|while|mixin|include|content|function
ATRULE.name                       #'RULE'
ATRULE.params                     #'VAL...'

RULE                              #'SELECTORS { ... }', as CONTAINER
                                  #{ ... } are children
                                  #Support nesting, i.e. a RULE can be parent of another RULE
                                  #Can be 'MIXIN(...) [{...}]' (with Less), with RULE.selector|params (see above)
RULE.selector                     #'SELECTORS'. See POSTCSS-SELECTOR-PARSER to parse this.
                                  #Can include PROP[: VAL], #{...} (with Sass), MIXIN(...), :extend(...) (with Less)
RULE.selectors                    #'SELECTOR'_ARR

DECLARATION                       #'PROP: VAL', as NODE
                                  #Can be '$VAR|@VAR: VAL' (with Sass/Less)
DECLARATION.prop                  #'PROP'
                                  #Can be 'PROP+[_]' (with Less)
DECLARATION.value                 #'VAL'
                                  #Can include '!default|optional', $VAR, #{EXPR} (with Sass), EXPR, @VAR (with Less)
DECLARATION.important             #BOOL

COMMENT                           #'/* COMMENT */', as NODE
COMMENT.text                      #'COMMENT'

                                  ┌───────────────┐
                                  │   SELECTORS   │
                                  └───────────────┘

POSTCSS-SELECTOR-PARSER
(FUNC(S_ROOT))->S_PROCESSOR        ##Does selector parsing (1.3.3)
S_PROCESSOR.process('CSS')
->S_PROCESSOR                      ##
S_PROCESSOR.result                 ##'CSS'

                                  ┌───────────────────┐
                                  │   SELECTOR NODE   │
                                  └───────────────────┘

S_NODE                           ##Like NODE but for selectors

S_NODE.type                      ##'attribute|class|combinator|comment|id|nesting|pseudo|root|selector|string|tag|universal'
S_NODE.parent|toString|next|prev|
replaceWith|remove|clone(...)    ##Like NODE
S_NODE.spaces.before|after       ##Like NODE.raws.before|after

S_NODE.source                    ##Like NODE, but without OBJ.input, and not on S_ROOT|SELECTOR
S_NODE.sourceIndex               ##Place NUM inside CSS file. Not on S_ROOT|SELECTOR


                                  ┌────────────────────────┐
                                  │   SELECTOR CONTAINER   │
                                  └────────────────────────┘

S_CONTAINER                      ##Like CONTAINER but for selectors, i.e. contains S_NODE

S_CONTAINR.nodes|first|last|index##Like CONTAINER
S_CONTAINER.every|some|each|walk|
prepend|append|insertBefore|After|
removeChild|removeAll(...)       ##Like CONTAINER, except arguments can only be S_NODE
S_CONTAINER.map|reduce|filter|sort
(...)                            ##Like CONTAINER.nodes.map|reduce|filter|sort(...)

S_CONTAINER.walkAttributes|
Classes|Combinators|Comments|
Ids|Nesting|Pseudos|Tags|
Universals(...)                  ##Like CONTAINER.walk*(...)

S_CONTAINR.split(FUNC(NOD)->BOOL)##Returns S_CONTAINER.nodes as S_NODE_ARR_ARR: the subgroups are decided by returning true
                                 ##(this terminates current subgroup and start new one)

                                  ┌────────────────────┐
                                  │   SELECTOR NODES   │
                                  └────────────────────┘

POSTCSS-SELECTOR-PARSER.
attribute|className|combinator|
comment|id|nesting|pseudo|root|
selector|string|tag|universal
([S_NODE_PROPS])->S_NODE         ##Creates new S_NODE of that type

S_ROOT                           ##S_CONTAINER representing SELECTORS. Parent of SELECTOR

S_SELECTOR                       ##S_CONTAINER representing SELECTOR.
                                 ##Parent of S_CLASS|ID|TAG|UNIVERSAL|ATTR|COMBINATOR|COMMENT|PSEUDO

S_COMBINATOR                     ##S_NODE representing space > + ~
S_COMBINATOR.value               ##' |>|+|~'

S_PSEUDO                         ##S_CONTAINER representing :[:]PSEUDO[(...)]
                                 ##Parent of ...
                                 ##Can be :extend(...) (with Less)
S_PSEUDO.value                   ##':[:]PSEUDO'

S_CLASS|ID|TAG|UNIVERSAL|NESTING ##S_NODE representing .CLASS #ID TAG * &
                                 ##TAG can also be: %PLACEHOLDER, PROP (with Sass), MIXIN(...) (with Less)
                                 ##TAG|ID can be #{...} (with Sass)
S_CLASS|ID|TAG|UNIVERSAL|NESTING
.value                           ##'CLASS|ID|TAG|*|&'

S_ATTR                           ##S_NODE representing [ATTR] or [ATTRopVAL]
S_ATTR.attribute                 ##'ATTR'
S_ATTR.operator                  ##'op' or undefined
S_ATTR.value                     ##'VAL' or undefined

S_COMMENT                        ##S_NODE representing /* COMMENT */
S_COMMENT.value                  ##'/* COMMENT */'

S_STRING                         ##S_NODE representing any STR
S_NODE.value                     ##STR

                                  ┌────────────┐
                                  │   VALUES   │
                                  └────────────┘

POSTCSS-VALUE-PARSER('CSS')      ##Parser for PROP values and media features (3.3.0)
->V_RESULT                       ##Less EXPR is parsed as many WORD|SPACE|DIV|STRING|FUNCTION
POSTCSS-VALUE-PARSER(V_NODE_ARR, ##Recurse over V_NODE_ARR
FUNC(V_NODE, NUM, V_NODE_ARR)    ##If FUNC() returns false, does not recurse over that node children (only works if BOOL false)
[, BOOL])                        ##If BOOL true (def: false), recurse from inwards to outermost
V_RESULT.walk(...)               ##Same as POSTCSS-VALUE-PARSER(V_RESULT.nodes, ...)

POSTCSS-VALUE-PARSER.stringify
(V_NODE_ARR[,FUNC(V_NOD)->'CSS'])
->'CSS'                          ##
V_RESULT.toString()->'CSS'       ##

V_RESULT.nodes                   ##V_NODE_ARR

V_NODE.type                      ##'word|string|div|space|comment|function'
V_NODE.sourceIndex               ##Place NUM in the source 'CSS'

V_DIV                            ##V_NODE representing tokens separators, i.e. , / or :
V_DIV.value                      ##',', '/' or ':'
V_DIV.before|after               ##Whitespace STR

V_WORD                           ##V_NODE representing any VAL single token, except "STR", 'STR' or FUNC
                                 ##Can include !default|optional, $VAR, #{EXPR} (with Sass), @VAR (with Less)
V_WORD.value                     ##'VAL'

V_STRING                         ##V_NODE representing "STR" or 'STR'
V_STRING.value                   ##'STR'
V_STRING.quote                   ##' or "
V_STRING.unclosed                ##BOOL: true if not closed properly

V_FUNCTION                       ##V_NODE representing FUNC(...) or media feature (VAR: VAL)
V_FUNCTION.value                 ##'FUNC' ('' for media feature)
V_FUNCTION.before|after          ##Whitespaces STR around parenthesis
V_FUNCTION.unclosed              ##BOOL: true if not closed properly
V_FUNCTION.nodes                 ##Arguments as V_NODE_ARR

V_COMMENT                        ##V_NODE representing /* COMMENT */
V_COMMENT.value                  ##'COMMENT'
V_COMMENT.unclosed               ##BOOL: true if not closed properly

V_SPACE                          ##V_NODE representing whitespace
V_SPACE.value                    ##STR

POSTCSS-VALUE-PARSER.unit('LENP')##Returns OBJ: number 'NUM', unit 'UNIT'
                                 ##If error, returns false

                                  ┌───────────────┐
                                  │   UTILITIES   │
                                  └───────────────┘

PROCESSOR.version                 #STR

POSTCSS.vendor                    #VENDOR
VENDOR.prefix('PROP')             #Returns prefix, e.g. '-moz-'
VENDOR.unprefixed('PROP')         #Returns without prefix

POSTCSS.list                      #LIST, which [de]compose space|comma-separated PROP VAL
LIST.space('VAL  ...')->VAL_ARR   #
LIST.comma('VAL, ...')->VAL_ARR   #

                                  ┏━━━━━━━━━━━━━━━┓
                                  ┃   REPORTING   ┃
                                  ┗━━━━━━━━━━━━━━━┛

                                  ┌───────────┐
                                  │   INPUT   │
                                  └───────────┘

INPUT                             #CSS input source
INPUT.file                        #'FILE'. Requires OBJ.from to be defined
INPUT.id                          #Automatic 'ID'
INPUT.from                        #INPUT.file or, if unset, INPUT.id
INPUT.origin(LINE, COL)           #Returns position in original input source as OBJ: file STR, line|column NUM
INPUT.map                         #Sourcemap (using mozilla source-map module)

                                  ┌─────────────────────┐
                                  │   WARNINGS/ERRORS   │
                                  └─────────────────────┘


CSSSYNTAXERR                      #Error message. Child of ERROR
CSSSYNTAXERR.message              #'[PLUGIN:]FILE:LINE:COL: REASON'
CSSSYNTAXERR.plugin               #'PLUGIN'
CSSSYNTAXERR.file                 #'FILE'. Requires OBJ.from to be defined
CSSSYNTAXERR.line|column          #NUM
                                  #Can use previous sourcemap (see --map.prev)
CSSSYNTAXERR.reason               #'REASON'
CSSSYNTAXERR.input                #INPUT
CSSSYNTAXERR.source               #'CSS' of the source
CSSYNTAXERR.showSourceCode([BOOL])#Returns STR showing source code that failed
                                  #BOOL is color output (def: process.stdout.isTTY and process.env.NODE_DISABLE_COLORS)
                                  #Empty if map.inline true and map.sourceContent false

WARNING                           #Warning message
WARNING.toString()->STR           #Like CSSSYNTAXERR.message
WARNING.plugin|file|line|column   #Like CSSSYNTAXERR
WARNING.text                      #Like CSSSYNTAXERR.reason
WARNING.node                      #NODE
WARNING.type                      #'warning'

                                  ┌───────────────┐
                                  │   REPORTING   │
                                  └───────────────┘

POSTCSS-REPORTER(PLUGIN_OPTS)    ##PLUGIN (1.3.3) that prints RESULT.messages using console.log()
                                 ##Must be last PLUGIN
                                 ##PLUGIN_OPTS:
                                 ##  - formatter({ messages OBJ_ARR, source 'CSS' })->STR: custom formatter
                                 ##  - sortByPosition BOOL (def: true): sort messages by lines/columns
                                 ##  - positionless 'first' (def), 'last' or 'any': where to sort message without lines/columns
                                 ##  - noIcon BOOL (def: false): does not show icon in logs
                                 ##  - noPlugin BOOL (def: false): does not show 'PLUGIN' in logs
                                 ##  - plugins 'PLUGIN'_ARR: filter by plugin
                                 ##  - throwError BOOL (def: false): throws error if warning found
                                 ##  - clearMessages BOOL (def: false): initialize RESULT.messages afterwards
                                 ##Can also use PLUGIN({ messages OBJ_ARR, source 'CSS' })->STR

                                  ┏━━━━━━━━━━━━━━━┓
                                  ┃   PROCESSOR   ┃
                                  ┗━━━━━━━━━━━━━━━┛

COMPARISON WITH SASS/LESS/STYLUS ##Has the core features, except few features:
  ==>                            ##  (Sass, easily emulated)
                                 ##    @debug|warn|error
                                 ##  (Sass)
                                 ##    PROP: VAL {PROP2: VAL}
                                 ##    @at-root
                                 ##    $VAR !default
                                 ##    $VAR types
                                 ##  (Sass/Less)
                                 ##    EXPR
                                 ##Allow custom JavaScript in functions/mixins

                                  ┌───────────────┐
                                  │   SASS-LIKE   │
                                  └───────────────┘

POSTCSS-INLINE-COMMENT()         ##PLUGIN (2.0.0) removing // COMMENT

POSTCSS-NESTED(OBJ)              ##PLUGIN (1.0.0) resolving in SELECTOR:
                                 ##  - &
                                 ##  - nested @media|supports|document
                                 ##    Can add other @ATRULE with OBJ.bubble 'ATRULE'_ARR
                                 ##Must be set after some PLUGIN using @ATRULE, e.g. POSTCSS-FOR, POSTCSS-MIXINS

POSTCSS-SIMPLE-VARS(OBJ)         ##PLUGIN (1.2.0) processing $VAR: VAL, $VAL and $(VAL)
                                 ##OBJ:
                                 ##  - variables OBJ2[()]: add $VAR: VAL declarations
                                 ##  - only OBJ2: only process for $VAR
                                 ##  - onVariables(OBJ2): callback with all $VAR declarations
                                 ##  - unknown(NODE, 'VAR', RESULT): callback on unknown $VAL
                                 ##  - silent BOOL: if false (def), throws error on unknown $VAL
                                 ##Must be set after some PLUGIN using $VAR syntax, e.g. POSTCSS-FOR, POSTCSS-MIXINS

POSTCSS-IMPORT(OBJ)              ##PLUGIN (8.0.2) processing @import "MODULE|URL" [MEDIAQUERYLIST];
                                 ##Path resolution:
                                 ##  - module:
                                 ##     - looked into node_modules/, web_modules/ or $PWD
                                 ##     - uses OBJ.root (def: CONF_OBJ.from, or $PWD)
                                 ##  - relative URL: uses OBJ.path 'DIR'[_ARR], CONF_OBJ.from, $PWD
                                 ##OBJ:
                                 ##  - skipDuplicates BOOL: if true (def), only import once same file
                                 ##  - transform('CSS')->[PROMISE of]'CSS': transform file content when importing
                                 ##  - plugins PLUGIN_ARR: same with plugins
                                 ##  - onImport('FILE'_ARR): callback when all @import done
                                 ##  - addDependencyTo OBJ: same as onImport(FILE_ARR) { FILE_ARR.forEach(OBJ.addDependency) }
                                 ##    Used for Webpack hot reloading
                                 ##  - resolve(...): custom path resolution function
                                 ##  - load(...): custom file loading function
                                 ##Must be set before any other [post-]processing PLUGIN

POSTCSS-EXTEND()                 ##PLUGIN (1.0.1) processing @extend SELECTORS (except !optional) and %CLASS

POSTCSS-CONDITIONALS()           ##PLUGIN (2.0.2) processing @if BOOL and @else

POSTCSS-FOR()                    ##PLUGIN (2.0.1) processing @for $VAR from NUM to NUM2 [by NUM3]

POSTCSS-EACH(OBJ)                ##PLUGIN (0.9.1) processing:
                                 ##  - @each $VAR[, $INDEX] in STR,... {...}
                                 ##  - @each $VAR,... in (STR,...),... {...}
                                 ##Must use as $(VAL)
                                 ##OBJ.plugins.beforeEach|afterEach 'PLUGIN'_ARR: called before|after each iteration

                                  ┌─────────────────┐
                                  │   STYLUS-LIKE   │
                                  └─────────────────┘

POSTCSS-PROPERTY-LOOKUP(OBJ)     ##PLUGIN (1.2.1) allowing @PROP and @(PROP) in values, which resolves to current RULE's PROP value
                                 ##OBJ:
                                 ##  - logLevel 'warn' (def) or 'error': if PROP cannot be found

                                  ┌────────────┐
                                  │   CUSTOM   │
                                  └────────────┘

POSTCSS-FUNCTIONS(OBJ)           ##PLUGIN (2.1.0) allowing FUNC(...), defined in JavaScript
                                 ##OBJ:
                                 ##  - functions.FUNC(STR,...)->STR2
                                 ##  - glob 'GLOB': load modules exporting OBJ.functions

POSTCSS-MIXINS(OBJ)              ##PLUGIN (4.0.1) processing @mixin:
                                 ##  - simple declaration:
                                 ##     - @define-mixin MIXIN [$VAR[: VAL],...] {...}
                                 ##        - block can use $VAL, $(VAL) and @mixin-content
                                 ##  - complex declaration:
                                 ##     - OBJ.mixins.MIXIN CSS_OBJ[(NODE, STR...)]
                                 ##     - can also autoload from modules using OBJ.mixinsFiles|Dir 'FILE|DIR'[_ARR]
                                 ##  - use:
                                 ##     - @mixin MIXIN [VAL,...] [{...}]
                                 ##OBJ:
                                 ##  - silent BOOL: if false (def), throws error on unknown MIXIN

POSTCSS-URL(OBJ)                 ##PLUGIN (5.1.1) processing url('URL')
                                 ##Main action depends on OBJ.url:
                                 ##  - 'rebase' (def): rebase relative URLs to CONF_OBJ.to|from or $PWD
                                 ##  - 'copy':
                                 ##     - rebase relative URLs to CONF_OBJ.to|from or OBJ.assetsPath 'DIR', then copy files
                                 ##     - if OBJ.useHash true, rename filename by checksum
                                 ##  - 'inline':
                                 ##     - base64 inlining
                                 ##     - use OBJ.basePath 'DIR' or $PWD for relative URLs
                                 ##     - Can filter according to OBJ:
                                 ##        - maxSize NUM (in KB, def: 14)
                                 ##        - filter('URL')->BOOL or REGEXP|'GLOB'
                                 ##     - if filtered, will OBJ.fallback FUNC instead (same format as FUNC below)
                                 ##  - FUNC('URL', DECLARATION, CONF_OBJ.from, 'CSS_DIR', CONF_OBJ.to, PLUGIN_OPTS, RESULT)->'URL'

POSTCSS-FONT-MAGICIAN(OBJ)       ##PLUGIN (1.4.0) creating @font-face rules based on existing font-family rules
                                 ##Using font-family 'FONT' will create @font-face { ... } with:
                                 ##  - font-family 'FONT'
                                 ##  - font-style|weight: depends on FONT
                                 ##  - src: local|url(...) ...
                                 ##PLUGIN_OPTS:
                                 ##  - format 'FORMAT ...': which local|url() are generated, among:
                                 ##     - local: local('FONT[-VARIANT]')
                                 ##     - 'woff|woff2|ttf|eot|svg|otf' (def: 'local woff2 woff eot'): url(URL)
                                 ##  - foundries 'VAL ...': font, including variant, local fonts and URLs, where VAL can be:
                                 ##     - hosted: DIR/FONT.EXT using PLUGIN_OPTS.hosted 'DIR'
                                 ##     - google: Google Fonts URLs
                                 ##     - bootstrap: 'FONT' is 'monospace|serif|sans-serif':
                                 ##        - which translates to local URLs to fonts used by Bootstrap for those font families
                                 ##        - including variants
                                 ##     - custom: using PLUGIN_OPTS.custom.FONT.variants.VARIANT.WEIGHT_NUM OBJ:
                                 ##        - local "'FONT'"_ARR
                                 ##        - url.FORMAT URL
                                 ##  - aliases.FONT 'FONT2'
                                 ##  - async 'FILE.js':
                                 ##     - instead of transforming CSS, creating FILE
                                 ##     - loading FILE will inject @font-face in a <style>

POSTCSS-AUTORESET(OBJ)           ##PLUGIN (1.1.5) creating a CSS reset for each component, by prepending a rule to each file.
                                 ##OBJ:
                                 ##  - reset CSS_OBJ|STR:
                                 ##     - declarations of the rule
                                 ##     - STR are shortcut:
                                 ##        - 'initial' (def): { all: initial } (must use POSTCSS-INITIAL, part of CSSNEXT)
                                 ##        - 'sizes': { margin|padding|border: 0; font-size: 100%; font: inherit; vertical-align: baseline }
                                 ##  - rulesMatcher:
                                 ##     - SELECTOR of the rule
                                 ##     - can be:
                                 ##        - FUNC(RULE)->BOOL
                                 ##        - 'bem' (def): anything that does not include --MODIFIER, :PSEUDO
                                 ##        - 'suit': anything that does not include --MODIFIER, :PSEUDO or is-STATE