.config/coc/extensions/node_modules/coc-prettier/node_modules/postcss-reporter/README.md

   1 # postcss-reporter
   2 [![Build Status](https://travis-ci.org/postcss/postcss-reporter.svg?branch=master)](https://travis-ci.org/postcss/postcss-reporter)
   3 [![AppVeyor Build Status](https://img.shields.io/appveyor/ci/davidtheclark/postcss-reporter/master.svg?label=windows%20build)](https://ci.appveyor.com/project/davidtheclark/postcss-reporter)
   4
   5 A PostCSS plugin to `console.log()` the messages (warnings, etc.) registered by other PostCSS plugins.
   6
   7 ## Purpose
   8
   9 As of PostCSS 4.1, a single PostCSS process can accumulate messages from all of the plugins it uses.
  10 Most of these messages are [warnings](https://github.com/postcss/postcss/blob/master/docs/guidelines/plugin.md#32-use-resultwarn-for-warnings).
  11 Presumably, plugin authors want you to see those messages.
  12 So this plugin exists to read the accumulated messages (or messages from only the plugins you've specified), format them, and print them to the console.
  13
  14 By default, the messages are formatted for human legibility and sorted according to the line/column positions attached to the messages. But another formatting function can be passed in with an option, and sorting can be turned of with an option.
  15
  16 *By default, only warnings are logged*. If you would like to see more messages, you can change the `filter` function.
  17
  18 ## Example Output
  19
  20 ![Example](example.png?raw=true)
  21
  22 ## Installation
  23
  24 ```
  25 npm install postcss-reporter
  26 ```
  27
  28 Version 1.0.0+ is compatible with PostCSS 5+. (Earlier versions are compatible with PostCSS 4.)
  29
  30 ## Usage
  31
  32 Add it to your plugin list *after any plugins whose messages you want to log*, and optionally pass it an object of options.
  33
  34 For example, using [gulp-postcss](https://github.com/postcss/gulp-postcss):
  35
  36 ```js
  37 gulp.task('css', function() {
  38   return gulp.src('./src/*.css')
  39     .pipe(postcss([
  40       bemLinter(),
  41       customProperties(),
  42       calc(),
  43       rejectAllColors(),
  44       reporter(myOptions) // <------ ding
  45     ]))
  46     .pipe(gulp.dest('./dist'));
  47 });
  48 ```
  49
  50 ## Options
  51
  52 **clearReportedMessages** (boolean, default = `false`)
  53
  54 If true, the plugin will clear the result's messages after it logs them. This prevents other plugins, or the whatever runner you use, from logging the same information again and causing confusion.
  55
  56 **formatter** (function, default = the default formatter)
  57
  58 By default, this reporter will format the messages for human legibility in the console.
  59 To use another formatter, pass a function that
  60
  61   - accepts an object containing a `messages` array and a `source` string
  62   - returns the string to report
  63
  64 For example, you could write a formatter like this:
  65
  66 ```js
  67 reporter({
  68   formatter: function(input) {
  69     return input.source + ' produced ' + input.messages.length + ' messages';
  70   }
  71 })
  72 ```
  73
  74 **plugins** (array of strings, default = `[]`)
  75
  76 If `plugins` is empty (as it is by default), the reporter will log messages from every PostCSS plugin.
  77
  78 There are 2 ways to limit output:
  79
  80 - **Whitelist:** Provide an array of the plugins whose messages you would like to show.
  81   For example, `{ plugins: ['postcss-bem-linter'] }` will only log messages from the `postcss-bem-linter` plugin.
  82 - **Blacklist:** Prefix all plugins in the array with `!` to specify only those plugins whose messages you would like to hide.
  83   (All other plugins will be shown.)
  84   For example, `{ plugins: ['!postcss-bem-linter'] }` will never log messages from the `postcss-bem-linter` plugin; but will log messages from every other plugin.
  85
  86 **filter** (function)
  87
  88 Provide a filter function. It receives the message object and returns a truthy or falsy value, indicating whether that particular message should be reported or not.
  89
  90 By default, only messages with `type: "warning"` warnings are logged. (These are the messages produced when the plugin author uses PostCSS's `warn()` function.)
  91
  92 For example, `function(message) { return true }` will only every message, regardless of the plugin or whether it's a warning or not.
  93
  94 **clearAllMessages** (boolean, default = `false`)
  95
  96 If `true`, not pass any messages into other plugins, or the whatever runner you use, for logging.
  97
  98 **throwError** (boolean, default = `false`)
  99
 100 If `true`, after the plugin logs your messages it will throw an error if it found any warnings.
 101
 102 **sortByPosition** (boolean, default = `true`)
 103
 104 If `false`, messages will not be sorted by line/column position.
 105
 106 **positionless** (`"first"|"last"|"any"`, default = `"first"`)
 107
 108 By default, messages without line/column positions will be grouped at the beginning of the output.
 109 To put them at the end, instead, use `"last"`.
 110 To not bother sorting these, use `"any"`.
 111
 112 **noIcon** (boolean, default = `false`)
 113
 114 If `true`, no exclamatory triangle icons will be printed next to warnings.
 115
 116 **noPlugin** (boolean, default = `false`)
 117
 118 If `true`, plugin names will not be printed in brackets after messages.
 119
 120 ## How to get output without colors
 121
 122 If you would like no colors in the console output, simply pass `--no-colors` when you invoke whatever command runs this plugin. (This works because of [chalk](https://github.com/sindresorhus/chalk).)
 123
 124 ## Standalone formatter
 125
 126 You can also use this module's formatter as a library, with following API:
 127
 128 ```js
 129 var formatter = require('postcss-reporter/lib/formatter');
 130 var myFormatter = formatter(myOptions);
 131 // to use defaults, just pass no options: `formatter()`
 132 var warningLog = myFormatter({
 133   messages: someMessages,
 134   source: someSource
 135 });
 136 console.log(warningLog);
 137 ```
 138
 139 These are the formatter's options:
 140
 141 - sortByPosition (boolean, default = `true`)
 142 - noIcon (boolean, default = `false`) - Do not print any warning exclamatory triangle icons
 143 - noPlugin (boolean, default = `false`) - Do not print plugin names