1 # node-dashdash changelog
9 - [issue #30] Change the output used by dashdash's Bash completion support to
10 indicate "there are no completions for this argument" to cope with different
11 sorting rules on different Bash/platforms. For example:
13 $ triton -v -p test2 package get <TAB> # before
14 ##-no -tritonpackage- completions-##
16 $ triton -v -p test2 package get <TAB> # after
17 ##-no-completion- -results-##
21 - New `synopsisFromOpt(<option spec>)` function. This will be used by
22 [node-cmdln](https://github.com/trentm/node-cmdln) to put together a synopsis
23 of options for a command. Some examples:
25 > synopsisFromOpt({names: ['help', 'h'], type: 'bool'});
27 > synopsisFromOpt({name: 'file', type: 'string', helpArg: 'FILE'});
33 - [issue #20] `bashCompletionSpecFromOptions` breaks on an options array with
34 an empty-string group.
39 - Update assert-plus dep to 1.x to get recent fixes (particularly for
42 - Drop testing (and official support in packages.json#engines) for node 0.8.x.
43 Add testing against node 5.x and 4.x with `make testall`.
45 - [pull #16] Change the `positiveInteger` type to NOT accept zero (0).
46 For those who might need the old behaviour, see
47 "examples/custom-option-intGteZero.js". (By Dave Pacheco.)
52 - Bash completion: Add `argtypes` to specify the types of positional args.
53 E.g. this would allow you to have an `ssh` command with `argtypes = ['host',
54 'cmd']` for bash completion. You then have to provide Bash functions to
55 handle completing those types via the `specExtra` arg. See
56 "[examples/ddcompletion.js](examples/ddcompletion.js)" for an example.
58 - Bash completion: Tweak so that options or only offered as completions when
59 there is a leading '-'. E.g. `mytool <TAB>` does NOT offer options, `mytool
60 -<TAB>` *does*. Without this, a tool with options would never be able to
61 fallback to Bash's "default" completion. For example `ls <TAB>` wouldn't
62 result in filename completion. Now it will.
64 - Bash completion: A workaround for not being able to explicitly have *no*
65 completion results. Because dashdash's completion uses `complete -o default`,
66 we fallback to Bash's "default" completion (typically for filename
67 completion). Before this change, an attempt to explicitly say "there are
68 no completions that match" would unintentionally trigger filename completion.
69 Instead as a workaround we return:
71 $ ddcompletion --none <TAB> # the 'none' argtype
74 $ ddcompletion # a custom 'fruit' argtype
77 ##-no -fruit- completions-##
79 This is a bit of a hack, but IMO a better experience than the surprise
80 of matching a local filename beginning with 'z', which isn't, in this
85 - Bash completion: Document `<option spec>.completionType`. Add `includeHidden`
86 option to `bashCompletionSpecFromOptions()`. Add support for dealing with
92 - Support for generating Bash completion files. See the "Bash completion"
93 section of the README.md and "examples/ddcompletion.js" for an example.
98 - Add the `arrayFlatten` boolean option to `dashdash.addOptionType` used for
99 custom option types. This allows one to create an `arrayOf...` option type
100 where each usage of the option can return multiple results. For example:
102 node mytool.js --foo a,b --foo c
104 We could define an option type for `--foo` such that
105 `opts.foo = ['a', 'b', 'c']`. See
106 "[examples/custom-option-arrayOfCommaSepString.js](examples/custom-option-arrayOfCommaSepString.js)"
112 - Trim the published package to the minimal bits. Before: 24K tarball, 144K unpacked.
113 After: 12K tarball, 48K unpacked. `npm` won't let me drop the README.md. :)
118 - [issue #9] Support `includeDefault` in help config (similar to `includeEnv`) to have a
119 note of an option's default value, if any, in help output.
120 - [issue #11] Fix option group breakage introduced in v1.9.0.
125 - [issue #10] Custom option types added with `addOptionType` can specify a
126 "default" value. See "examples/custom-option-fruit.js".
131 - Support `hidden: true` in an option spec to have help output exclude this
137 - [issue #8] Fix parsing of a short option group when one of the
138 option takes an argument. For example, consider `tail` with
139 a `-f` boolean option and a `-n` option that takes a number
140 argument. This should parse:
144 Before this change, that would not parse correctly.
145 It is suspected that this was introduced in version 1.4.0
146 (with commit 656fa8bc71c372ebddad0a7026bd71611e2ec99a).
153 - Exclude 'tools/' dir in packages published to npm.
160 - Support an option group *empty string* value:
166 to render as a blank line in option help. This can help separate loosely
167 related sets of options without resorting to a title for option groups.
174 - [pull #7] Support for `<parser>.help({helpWrap: false, ...})` option to be able
175 to fully control the formatting for option help (by Patrick Mooney) `helpWrap:
176 false` can also be set on individual options in the option objects, e.g.:
183 help: 'long help with\n newlines' +
184 '\n spaces\n and such\nwill render correctly'
194 - [pull #6] Support headings between groups of options (by Joshua M. Clulow)
198 { group: 'Armament Options' },
199 { names: [ 'weapon', 'w' ], type: 'string' },
200 { group: 'General Options' },
201 { names: [ 'help', 'h' ], type: 'bool' }
205 will give you this help output:
220 - Add support for adding custom option types. "examples/custom-option-duration.js"
221 shows an example adding a "duration" option type.
223 $ node custom-option-duration.js -t 1h
225 $ node custom-option-duration.js -t 1s
227 $ node custom-option-duration.js -t 5d
228 duration: 432000000 ms
229 $ node custom-option-duration.js -t bogus
230 custom-option-duration.js: error: arg for "-t" is not a valid duration: "bogus"
232 A custom option type is added via:
234 var dashdash = require('dashdash');
235 dashdash.addOptionType({
239 parseArg: function (option, optstr, arg) {
244 - [issue #4] Add `date` and `arrayOfDate` option types. They accept these date
245 formats: epoch second times (e.g. 1396031701) and ISO 8601 format:
246 `YYYY-MM-DD[THH:MM:SS[.sss][Z]]` (e.g. "2014-03-28",
247 "2014-03-28T18:35:01.489Z"). See "examples/date.js" for an example usage.
249 $ node examples/date.js -s 2014-01-01 -e $(date +%s)
250 start at 2014-01-01T00:00:00.000Z
251 end at 2014-03-29T04:26:18.000Z
258 - [pull #2, pull #3] Add a `allowUnknown: true` option on `createParser` to
259 allow unknown options to be passed through as `opts._args` instead of parsing
260 throwing an exception (by https://github.com/isaacs).
262 See 'allowUnknown' in the README for a subtle caveat.
267 - Fix a subtlety where a *bool* option using both `env` and `default` didn't
268 work exactly correctly. If `default: false` then all was fine (by luck).
269 However, if you had an option like this:
272 names: ['verbose', 'v'],
274 'default': true, // <--- this
278 wanted `FOO_VERBOSE=0` to make the option false, then you need the fix
279 in this version of dashdash.
284 - [issue #1] Fix an envvar not winning over an option 'default'. Previously
285 an option with both `default` and `env` would never take a value from the
286 environment variable. E.g. `FOO_FILE` would never work here:
289 names: ['file', 'f'],
291 'default': 'default.file',
298 - [Backward incompatible change for boolean envvars] Change the
299 interpretation of environment variables for boolean options to consider '0'
300 to be false. Previous to this *any* value to the envvar was considered
301 true -- which was quite misleading. Example:
303 $ FOO_VERBOSE=0 node examples/foo.js
304 # opts: { verbose: [ false ],
305 _order: [ { key: 'verbose', value: false, from: 'env' } ],
312 - Fix for `parse.help({includeEnv: true, ...})` handling to ensure that an
313 option with an `env` **but no `help`** still has the "Environment: ..."
316 { names: ['foo'], type: 'string', env: 'FOO' }
320 --foo=ARG Environment: FOO=ARG
325 - Transform the option key on the `opts` object returned from
326 `<parser>.parse()` for convenience. Currently this is just
327 `s/-/_/g`, e.g. '--dry-run' -> `opts.dry_run`. This allow one to use hyphen
328 in option names (common) but not have to do silly things like
329 `opt["dry-run"]` to access the parsed results.
334 - Environment variable integration. Envvars can be associated with an option,
335 then option processing will fallback to using that envvar if defined and
336 if the option isn't specified in argv. See the "Environment variable
337 integration" section in the README.
339 - Change the `<parser>.parse()` signature to take a single object with keys
340 for arguments. The old signature is still supported.
342 - `dashdash.createParser(CONFIG)` alternative to `new dashdash.Parser(CONFIG)`
343 a la many node-land APIs.
348 - Add "positiveInteger" and "arrayOfPositiveInteger" option types that only
349 accept positive integers.
351 - Add "integer" and "arrayOfInteger" option types that accepts only integers.
352 Note that, for better or worse, these do NOT accept: "0x42" (hex), "1e2"
353 (with exponent) or "1.", "3.0" (floats).
358 - Fix not modifying the given option spec objects (which breaks creating
359 a Parser with them more than once).