|
| 1 | +--- |
| 2 | +layout: blog |
| 3 | +title: yargs 10 Released |
| 4 | +excerpt: yargs 10 released |
| 5 | +--- |
| 6 | + |
| 7 | +{::options parse_block_html="true" /} |
| 8 | +<div class="page-content align-items"> |
| 9 | +<div class="page-box-full left"> |
| 10 | +# yargs 10 Released |
| 11 | + |
| 12 | +_wow, I just noticed it's been over a year since I wrote about a release of |
| 13 | +yargs. I'm excited about `yargs@10` and I hope you'll find it's been worth |
| 14 | +the wait._ |
| 15 | + |
| 16 | +Commands are my favorite feature in yargs, they let |
| 17 | +you quickly hammer-out a CLI-application addressing both the |
| 18 | +problem of flow-control and human-readable help output: |
| 19 | + |
| 20 | +<pre> |
| 21 | + <code class="hljs language-javascript">require('yargs') |
| 22 | + .command('append <w1> <w2>', 'append two strings', (yargs) => {}, (argv) => { |
| 23 | + console.log(argv.w1 + argv.w2) |
| 24 | + }) |
| 25 | + .command('add <n1> <n2>', 'add two numbers', (yargs) => {}, (argv) => { |
| 26 | + console.log(argv.n1 + argv.n2) |
| 27 | + }) |
| 28 | + .argv</code></pre> |
| 29 | + |
| 30 | +Even though I love the feature, I had a couple major beefs with the API: |
| 31 | + |
| 32 | +* I like the [positional argument DSL](https://github.com/yargs/yargs/blob/master/docs/advanced.md#positional-arguments) (`<foo>`, `[bar]`, etc.), but positional |
| 33 | + arguments were missing many of the features available to flag arguments: |
| 34 | + you couldn't set their type, configure a coerce method, etc. |
| 35 | +* there was a major disconnect between how you described the root-level |
| 36 | + entry-point to your application and the subcommands that your application |
| 37 | + accepts. `.usage()` hadn't ever been updated to reflect a world in-which |
| 38 | + commands exist. |
| 39 | + |
| 40 | +The goal of `yargs@10` was to address the above issues. |
| 41 | + |
| 42 | +## .positional(<name>, <options>) |
| 43 | + |
| 44 | +The new [`.positional()`](https://github.com/yargs/yargs/blob/master/docs/api.md#positionalkey-opt) method allows you to provide the same parsing hints |
| 45 | +for positional arguments that you could already provide for flag arguments. |
| 46 | +Let's look at an updated version of our example application: |
| 47 | + |
| 48 | +<pre> |
| 49 | + <code class="hljs language-javascript">require('yargs') |
| 50 | + .command('append <w1> <w2>', 'append two strings', (yargs) => { |
| 51 | + yargs.positional('w1', { |
| 52 | + describe: 'the left-hand word', |
| 53 | + type: 'string' |
| 54 | + }).positional('w2', { |
| 55 | + describe: 'the right-hand word', |
| 56 | + type: 'string' |
| 57 | + }) |
| 58 | + }, (argv) => { |
| 59 | + console.log(argv.w1 + argv.w2) |
| 60 | + }) |
| 61 | + .command('add <n1> <n2>', 'add two numbers', (yargs) => { |
| 62 | + yargs.positional('n1', { |
| 63 | + describe: 'the left-hand number', |
| 64 | + type: 'number' |
| 65 | + }).positional('n2', { |
| 66 | + describe: 'the right-hand number', |
| 67 | + type: 'number' |
| 68 | + }) |
| 69 | + }, (argv) => { |
| 70 | + console.log(argv.n1 + argv.n2) |
| 71 | + }) |
| 72 | + .argv</code></pre> |
| 73 | + |
| 74 | +To provide parsing hints for positional arguments, simply use the method |
| 75 | +`.positional()` in your command's [builder function](https://github.com/yargs/yargs/blob/master/docs/api.md#commandmodule). Positional arguments |
| 76 | +now go through the same parser that parses flag arguments and behavior |
| 77 | +will be identical. |
| 78 | + |
| 79 | +## .usage(<cmd>, [description], [builder], [handler]) |
| 80 | + |
| 81 | +If you provide more than one argument to the [`.usage()`](https://github.com/yargs/yargs/blob/master/docs/api.md#usagemessagecommand-desc-builder-handler) method, `.usage()` |
| 82 | +now acts as an alias for a [default command](https://github.com/yargs/yargs/blob/master/docs/advanced.md#default-commands). This allows you to configure a command |
| 83 | +that runs as the main entry-point to your application. |
| 84 | + |
| 85 | +Let's look at an example: |
| 86 | + |
| 87 | +<pre> |
| 88 | + <code class="hljs language-javascript">require('yargs') |
| 89 | + .usage('$0 <name>', 'say hello', (yargs) => { |
| 90 | + yargs.positional('name', { |
| 91 | + describe: 'the person to say hello to', |
| 92 | + type: 'string' |
| 93 | + }) |
| 94 | + }, (argv) => { |
| 95 | + console.info(`hello ${argv.name}`) |
| 96 | + }) |
| 97 | + .argv</code></pre> |
| 98 | + |
| 99 | +You can now use the same powerful command DSL for |
| 100 | +describing the root-entry point to your application as you use for subcommands! |
| 101 | + |
| 102 | +## Upgrading |
| 103 | + |
| 104 | +There have been a couple breaking changes in this release: |
| 105 | + |
| 106 | +* `.usage()` previously accepted an object as a second argument, treating this |
| 107 | + as an alias for `.option([obj])`. |
| 108 | +* the API for defining hidden options has been made more explicit; rather than |
| 109 | + a falsy description representing a hidden option, the configuration value |
| 110 | + `hidden: true` should be set. |
| 111 | +* help is now only shown if `help` is the last positional argument. |
| 112 | + |
| 113 | +For a complete list of changes, see our [CHANGELOG.md](https://github.com/yargs/yargs/blob/master/CHANGELOG.md) |
| 114 | + |
| 115 | +I hope you like what `yargs@10` has to offer, |
| 116 | + |
| 117 | +-- [Ben](https://github.com/bcoe). |
| 118 | + |
| 119 | +</div> |
| 120 | + |
| 121 | +{::options parse_block_html="true" /} |
| 122 | +<div class="page-box right"> |
| 123 | +## Support Yargs Development |
| 124 | + |
| 125 | +<br /> |
| 126 | + |
| 127 | +Yargs is developed on evenings and weekends by |
| 128 | +volunteers. Why not grab them dinner or a drink? |
| 129 | + |
| 130 | +<br /> |
| 131 | + |
| 132 | +[](https://gratipay.com/yargs/) |
| 133 | + |
| 134 | +</div> |
| 135 | +</div> |
0 commit comments