BREAKING: Revamp args parsing

- Remove extra aliases -x, -p, -s, -t, -e, -b, & -c
- Better usage text
- Split opts into groups in the --help message
- Way stricter opts parsing to prevent stupid combinations of options

Fixes #166; Fixes #126

README.md

@@ -22,56 +22,58 @@ npm i -g|-D postcss-cli
 
 <h2 align="center">Usage</h2>
 
-```bash
-postcss [input.css] [OPTIONS] [-o|--output output.css] [-w|--watch]
 ```
+Usage:
+  postcss [input.css] [OPTIONS] [-o|--output output.css] [--watch|-w]
+  postcss <input.css>... [OPTIONS] --dir <output-directory> [--watch|-w]
+  postcss <input.css>... [OPTIONS] --replace
+
+Basic options:
+  -o, --output   Output file                                            [string]
+  -d, --dir      Output directory                                       [string]
+  -r, --replace  Replace (overwrite) the input file                    [boolean]
+  --map, -m      Create an external sourcemap
+  --no-map       Disable the default inline sourcemaps
+  --watch, -w    Watch files for changes and recompile as needed       [boolean]
+  --env          A shortcut for setting NODE_ENV                        [string]
+
+Options for when not using a config file:
+  -u, --use      List of postcss plugins to use                          [array]
+  --parser       Custom postcss parser                                  [string]
+  --stringifier  Custom postcss stringifier                             [string]
+  --syntax       Custom postcss syntax                                  [string]
+
+Advanced options:
+  --ext     Override the output file extension; for use with --dir      [string]
+  --base    Mirror the directory structure relative to this path in the output
+            directory, for use with --dir                               [string]
+  --poll    Use polling for file watching. Can optionally pass polling interval;
+            default 100 ms
+  --config  Set a custom path to look for a config file                 [string]
+
+Options:
+  -v, --version  Show version number                                   [boolean]
+  -h, --help     Show help                                             [boolean]
+
+Examples:
+  postcss input.css -o output.css                       Basic usage
+  cat input.css | postcss -u autoprefixer > output.css  Piping input & output
+
+If no input files are passed, it reads from stdin. If neither -o, --dir, or
+--replace is passed, it writes to stdout.
 
-The input may also be a glob:
-
-```bash
-postcss "src/*.css" [OPTIONS]
+If there are multiple input files, the --dir or --replace option must be passed.
+Input files may contain globs.
 ```
 
-Recursively read a directory:
-
-```bash
-postcss "src/**/*.css" [OPTIONS]
-```
+> ℹ️  More details on custom parsers, stringifiers and syntaxes, can be found [here](https://github.com/postcss/postcss#syntaxes).
 
-> ⚠️  If there are multiple input files, the --dir or --replace option must be passed.
+To recursively read a directory, you'd do:
 
 ```bash
-cat input.css | postcss [OPTIONS] > output.css
+postcss "src/**/*.css" [OPTIONS]
 ```
 
-> ⚠️  If no input files are passed, it reads from stdin. If neither -o, --dir, or
---replace is passed, it writes to stdout.
-
-<h2 align="center">Options</h2>
-
-|Name|Type|Default|Description|
-|:---|:--:|:-----:|:----------|
-|`-d, --dir`|`{String}`|`undefined`|Output Directory|
-|`-b, --base`|`{String}`|`undefined`|Use together with `--dir` for keeping directory structure.|
-|`-x, --ext`|`{String}`|`extname(output)`|Output File Extension|
-|`-o, --output`|`{String}`|`undefined`|Output File|
-|`-r, --replace`|`{String}`|`undefined`|Replace Input <=> Output|
-|`-p, --parser`|`{String}`|`undefined`|Custom PostCSS Parser|
-|`-s, --syntax`|`{String}`|`undefined`|Custom PostCSS Syntax|
-|`-t, --stringifier`|`{String}`|`undefined`|Custom PostCSS Stringifier|
-|`-w, --watch`|`{Boolean}`|`false`|Enable Watch Mode|
-|`--poll`|`{Boolean\|Number}`|`100`|Use polling for file watching. Can optionally pass polling interval; default 100 ms|
-|`-u, --use`|`{Array}`|`[]`|PostCSS Plugins|
-|`-m, --map`|`{Boolean}`|`{ inline: true }`|External Sourcemaps|
-|`--no-map`|`{Boolean}`|`false`|Disable Sourcemaps|
-|`-e, --env`|`{String}`|`process.env.NODE_ENV`|Sets `$NODE_ENV`|
-|`-c, --config`|`{String}`|`dirname(file)`|PostCSS Config Path `postcss.config.js`|
-|`-h, --help`|`{Boolean}`|`false`|CLI Help|
-|`-v, --version`|`{Boolean}`|`false`|CLI Version|
-
-
-> ℹ️  More details on custom parsers, stringifiers and syntaxes, can be found [here](https://github.com/postcss/postcss#syntaxes).
-
 ### [Config](https://github.com/michael-ciniawsky/postcss-load-config)
 
 If you need to pass options to your plugins, or have a long plugin chain, you'll want to use a configuration file.

lib/args.js

@@ -30,81 +30,94 @@ module.exports = require('yargs')
   .usage(
     `${chalk.bold.red(logo)}
 Usage:
-
-  $0 [input.css] [OPTIONS] [--output|-o output.css] [--watch]`
+  $0 [input.css] [OPTIONS] [-o|--output output.css] [--watch|-w]
+  $0 <input.css>... [OPTIONS] --dir <output-directory> [--watch|-w]
+  $0 <input.css>... [OPTIONS] --replace`
   )
+  .group(['o', 'd', 'r', 'map', 'no-map', 'watch', 'env'], 'Basic options:')
   .option('o', {
     alias: 'output',
     desc: 'Output file',
-    type: 'string'
+    type: 'string',
+    conflicts: ['dir', 'replace']
   })
   .option('d', {
     alias: 'dir',
     desc: 'Output directory',
-    type: 'string'
+    type: 'string',
+    conflicts: ['output', 'replace']
   })
   .option('r', {
     alias: 'replace',
     desc: 'Replace (overwrite) the input file',
-    type: 'boolean'
+    type: 'boolean',
+    // HACK: conflicts doesn't work with boolean opts correctly, so we do this
+    // See https://github.com/yargs/yargs/issues/929
+    coerce: v => v || undefined,
+    conflicts: ['output', 'dir']
+  })
+  .alias('map', 'm')
+  .describe('map', 'Create an external sourcemap')
+  .describe('no-map', 'Disable the default inline sourcemaps')
+  .option('watch', {
+    alias: 'w',
+    desc: 'Watch files for changes and recompile as needed',
+    type: 'boolean',
+    // HACK: conflicts doesn't work with boolean opts correctly, so we do this
+    // See https://github.com/yargs/yargs/issues/929
+    coerce: v => v || undefined,
+    conflicts: 'replace'
+  })
+  .option('env', {
+    desc: 'A shortcut for setting NODE_ENV',
+    type: 'string'
   })
+  .group(
+    ['u', 'parser', 'stringifier', 'syntax'],
+    'Options for when not using a config file:'
+  )
   .option('u', {
     alias: 'use',
     desc: 'List of postcss plugins to use',
     type: 'array'
   })
-  .option('p', {
-    alias: 'parser',
+  .option('parser', {
     desc: 'Custom postcss parser',
     type: 'string'
   })
-  .option('t', {
-    alias: 'stringifier',
+  .option('stringifier', {
     desc: 'Custom postcss stringifier',
     type: 'string'
   })
-  .option('s', {
-    alias: 'syntax',
+  .option('syntax', {
     desc: 'Custom postcss syntax',
     type: 'string'
   })
-  .option('w', {
-    alias: 'watch',
-    desc: 'Watch files for changes and recompile as needed',
-    type: 'boolean'
-  })
-  .option('poll', {
-    desc:
-      'Use polling for file watching. Can optionally pass polling interval; default 100 ms'
-  })
-  .option('x', {
-    alias: 'ext',
-    desc: 'Override the output file extension',
+  .group(['ext', 'base', 'poll', 'config'], 'Advanced options:')
+  .option('ext', {
+    desc: 'Override the output file extension; for use with --dir',
     type: 'string',
+    implies: 'dir',
     coerce(ext) {
       if (ext.indexOf('.') !== 0) return `.${ext}`
       return ext
     }
   })
-  .option('e', {
-    alias: 'env',
-    desc: 'A shortcut for setting NODE_ENV',
-    type: 'string'
+  .option('base', {
+    desc:
+      'Mirror the directory structure relative to this path in the output directory, for use with --dir',
+    type: 'string',
+    implies: 'dir'
   })
-  .option('b', {
-    alias: 'base',
+  .option('poll', {
     desc:
-      'Mirror the directory structure relative to this path in the output directory, this only works together with --dir',
-    type: 'string'
+      'Use polling for file watching. Can optionally pass polling interval; default 100 ms',
+    implies: 'watch'
   })
-  .option('c', {
-    alias: 'config',
+  .option('config', {
     desc: 'Set a custom path to look for a config file',
     type: 'string'
   })
-  .alias('m', 'map')
-  .describe('m', 'Create an external sourcemap')
-  .describe('no-map', 'Disable the default inline sourcemaps')
   .version(version)
   .alias('v', 'version')
   .alias('h', 'help')
@@ -116,7 +129,7 @@ Usage:
   .epilog(
     `If no input files are passed, it reads from stdin. If neither -o, --dir, or --replace is passed, it writes to stdout.
 
-If there are multiple input files, the --dir or --replace option must be passed.
+If there are multiple input files, the --dir or --replace option must be passed. Input files may contain globs.
 
 For more details, please see https://github.com/postcss/postcss-cli`
   ).argv

test/error.js

@@ -53,7 +53,7 @@ test('PluginError', t => {
 })
 
 test('CssSyntaxError', t => {
-  return cli(['test/fixtures/a.css', '-p', 'sugarss', '-o', tmp()]).then(
+  return cli(['test/fixtures/a.css', '--parser', 'sugarss', '-o', tmp()]).then(
     ({ err, code }) => {
       t.is(code, 1, 'expected non-zero error code')
       t.regex(err.toString(), /\[1:4] Unnecessary curly bracket/)

test/parser.js

@@ -9,7 +9,7 @@ test('--parser works', async t => {
 
   const { error, stderr } = await cli([
     'test/fixtures/a.sss',
-    '-p',
+    '--parser',
     'sugarss',
     '-o',
     output,

test/stdout.js

@@ -9,7 +9,7 @@ import read from './helpers/read.js'
 test.cb('writes to stdout', t => {
   const cp = execFile(
     path.resolve('bin/postcss'),
-    ['-p', 'sugarss', '-u', 'postcss-import', '--no-map'],
+    ['--parser', 'sugarss', '-u', 'postcss-import', '--no-map'],
     (error, stdout, stderr) => {
       if (error) t.end(error, stderr)
 

test/stringifier.js

@@ -9,7 +9,7 @@ test('--stringifier works', async t => {
 
   const { error, stderr } = await cli([
     'test/fixtures/a.css',
-    '-t',
+    '--stringifier',
     'sugarss',
     '-o',
     output,

test/syntax.js

@@ -9,7 +9,7 @@ test('--syntax works', async t => {
 
   const { error, stderr } = await cli([
     'test/fixtures/a.sss',
-    '-s',
+    '--syntax',
     'sugarss',
     '-o',
     output,