Fix type "array" with "duplicate-arguments-array"

[juergba]

Description

closes #162

The array type does not work consistently with option duplicate-arguments-array.
when duplicate-arguments-array === false

• array of type string does reduce duplicate arguments
• array of type number does not reduce duplicate arguments
• array of type boolean only works with arguments provided in pairs, eg --foo true.
  A boolean without value (--foo --no-foo) results in various bugs as empty arrays, lost flags, lost array type and more.

Description of Change

• duplicate-arguments-array has no effect on option type array anymore.
  even when duplicate-arguments-array === false, you are able to specify:
  (output depends on flatten-duplicate-arrays)
  • -x 1 -x 2 -x 3==> [1, 2, 3] or [[1], [2], [3]]
  • -x 1 2 -x 4 5==> [1, 2, 4, 5] or [[1, 2], [4, 5]]
• option type number and string work consistently.
• an array value is always an array, even if just one value is passed.
• maybeCoerceNumber(): fix handling of arrays.
• adapt existing tests, add new tests

Please note: the disabling of creating an array by -x a b c by default will be implemented in another PR.

[bcoe]

@juergba thank you for all the wonderful contributions you've made recently, I will work on getting them merged as soon as possible; I've been buried on other projects and apologize.

[bcoe]

@juergba could I bother you to rebase? I'm getting ready to release a new version of yargs and yargs-parser.

[bcoe]

my thinking is, if you've explicitly set type to array, we should still accept the option being set multiple times -- duplicate-arguments-array applying only to the behavior of keys you haven't explicitly set as an array.

Honestly, I'd kind of like to drop support for -x a b c, and make it so the only way to create an array is -x a -x b -x c; since type array does not mix well with positional arguments.

tldr; I think perhaps we need better documentation around arrays, and to perhaps rethink the behavior of the array option, but I'm so so on this patch.

@coreyfarrell @plroebuck @boneskull have any opinions about array behavior? mainly my idea of deprecating -x 2 3 3 in favor of the more explicit -x 2 -x 3 -x 3.

[juergba]

[...] duplicate-arguments-array applying only to the behavior of keys you haven't explicitly set as an array.

Agree, type array should precede duplicate-arguments-array.
For this PR:

• behavior of number[] is correct
• behavior of string[] has to be fixed, should match number[] pattern
  Note: this will probably "shock" many existing implementations / breaking change

Honestly, I'd kind of like to drop support for -x a b c

What about opts.narg then?

[coreyfarrell]

my thinking is, if you've explicitly set type to array, we should still accept the option being set multiple times -- duplicate-arguments-array applying only to the behavior of keys you haven't explicitly set as an array.

Yes please. In the context of nyc I would like to block use of --temp-dir or --cwd multiple times but not block multiple use of use of --reporter.

Honestly, I'd kind of like to drop support for -x a b c, and make it so the only way to create an array is -x a -x b -x c; since type array does not mix well with positional arguments.

Maybe it would be better to disable -x a b c by default but still have a way to enable it? Worth considering that -x a b c -x d e f can mean x: [['a', 'b', 'c'], ['d', 'e', 'f']]?

[bcoe]

what about opts.narg then?

I think narg would behave differently than array and just take the last set. so, if narg of x was set to 2, and you passed --x a b --x c d, you'd get c, d.

@coreyfarrell

Maybe it would be better to disable -x a b c by default but still have a way to enable it?

I agree with this, maybe a parameter called --positional-arrays, which we start to default to false? Then the array type can be used (by default) simply to imply:

1. this value will always be an array, even if just one value is passed.
2. even if you set duplicate-arguments-array to false, you will still be able to specify -x 1 -x 2 -x 3.

@juergba does this sound reasonable to you for mocha's needs? If so perhaps we could update this patch to reflect this world.

[juergba]

does this sound reasonable to you for mocha's needs?

afaik we don't use -x a b c in Mocha, we only use -x a -x b -x c or -x a,b,c.

If so perhaps we could update this patch to reflect this world.

Ok, I will give it a try. I'm not sure yet about the implications of "disabling -x a b c by default".
I will see ...

[juergba]

@bcoe The behavior of option type boolean[] seems to be completely buggy, even before this PR.

• are option type boolean[] allowed?
• is boolean[]'s expected behavior identical to number[] and string[]?

[bcoe]

@juergba my thinking is we should make this a breaking change, and address some of these long standing issues. If you indicate something is an array, even a boolean, I think you should get an array out the other end, even if it's an empty array (if no argument is set) or an array of one item if only one item is provided.

It might break the internet too much to drop support for -x a b c, but perhaps we could at least add a config setting that allows this to be disabled? Then consider whether we drop the feature eventually, forcing -x a -x b -x c.

[juergba]

I understand your concerns with -x a b c and your plans for an additional config setting. IMO before doing this we should fix some bugs.

The current master shows following results:

var args = parse('--file --file', {
  'array': ['file'],
  'number': ['file'],           // { _: [], file: [ 0, 0, undefined ] }
  // 'string': ['file'],        // { _: [], file: [ [], [], '' ] }
  // 'boolean': ['file'],       // { _: [], file: [ [], [], [] ] }
  configuration: {
    'duplicate-arguments-array': true,
    'flatten-duplicate-arrays': false
  }
})

• two flags => three values parsed
• number and string show default value, boolean is empty
• what about user defaults, they should be used when no values are supplied?
• see Fix: boolean[] - eatArray() with boolean typed arrays and user defaults #185 and Fix: number[] - maybeCoerceNumber(): processing of number typed arrays #187

var args = parse('--file true --file true', {   // same result with '--file --file'
  'boolean': ['file'],    
  configuration: {
    'duplicate-arguments-array': true
  }
})           // { _: [], file: true }

• result should be: [true, true], but is true
• see PR Fix "boolean" flag with "duplicate-arguments-array" #184

We should address those bugs first, before adding new flags. boolean is a special option since the flag itself can carry its value, so --booly === --booly true.

[bcoe]

@juergba I agree, let's start by fixing these bugs.

Do we want to close this issue, in favor of landing fixes like #184? and moving towards a better API for arrays in the long run?

[juergba]

Do we want to close this issue

No, please don't close. This issue covers its own topic, which got lost completely during -x a b c discussion.

[...] moving towards a better API for arrays in the long run?

Yes, landing fixes step by step is a good procedure.

[bcoe]

@juergba any chance we can dust this PR off, I'd like to start working on getting a few more releases of yargs out the door.

[juergba]

Yes, I can make the original issue (type "array" with "duplicate-arguments-array") ready within a few days.

The disabling of creating an array by -x a b c by default is not part of this PR.

[bcoe]

@juergba sounds good to me, I think that's @coreyfarrell's recommendation to make disable -x a b c by default might be smart honestly, but in a future PR ... my concern is this would likely bite quite a few folks, so it's worth opening a discussion.

[juergba]

my thinking is, if you've explicitly set type to array, we should still accept the option being set multiple times -- duplicate-arguments-array applying only to the behavior of keys you haven't explicitly set as an array.

@bcoe please confirm wether you really want above pattern:
(duplicate-arguments-array: false)
[-x 1 2 3 -x 2 3 4] => [[1, 2, 3], [2, 3, 4]]

In #75 the opposite was implemented:
[-x 1 2 3 -x 2 3 4] => [2, 3, 4]

[bcoe]

@juergba if you have duplicate-arguments-array = true, and an option is an array, I feel it should be:

[[1, 2, 3], [2, 3, 4]]

If you have duplicate-arguments-array = false, and an option is an array I feel it should be:

[2, 3, 4].

This agrees with your thinking?

[juergba]

No, this is not what I'm thinking.

Neither after your comment:

my thinking is, if you've explicitly set type to array, we should still accept the option being set multiple times -- duplicate-arguments-array applying only to the behavior of keys you haven't explicitly set as an array.

Nor after @coreyfarrell 's comment:

Yes please. In the context of nyc I would like to block use of --temp-dir or --cwd multiple times but not block multiple use of use of --reporter.

@coreyfarrell can you help, please?

[bcoe]

@juergba duplicate-arguments-array is a specific setting which indicates that the last time a value is set, like -x it should take precedence.

Therefore, in the edge case that you've set a array and duplicate-arguments-array it should have the same behavior:

-x 3 5 5 -x 4 3 2 in which the last -x is preferred, so:

x: [4, 3, 2].

I don't think we should change this behavior ... and it's pretty edge-casey to be honest (not something I've seen many issues about).

What I would be more willing to entertain would be a redefinition of what setting the type array means, i.e., getting rid of support for -x 3 2 4 entirely.

tldr; I'm not super excited about the changes proposed in this PR because it seems like thrash without solving much of a problem I've observed, I'd rather work to make the array setting less surprising (and perhaps retire some of the config settings around arrays in this process).

[bcoe]

getting back to your original PR description:

If duplicate-arguments-array = false

• -x a b c -x d e f and x = string, array = true, should result in [d, e, f]
• -x 1 2 3 -x 4 5 6 and x = number, array = true, should result in [4, 5, 6].
• -x a b c -x d e f and x = string, array = false, should result in d.
• -x 1 2 3 -x 4 5 6 and x = number, array = false, should result in 4.
• -x true true false -x false true true and x = boolean, array = false, should result in false.
• -x true true false -x false true true and x = boolean, array = true, should result in [false, true, true].

If duplicate arguments-array = true

• -x a b c -x d e f and x = string, array = true, should result in [[a, b, c], [d, e, f]]
• -x 1 2 3 -x 4 5 6 and x = number, array = true, should result in [[1, 2, 3], [4, 5, 6]].
• -x a b c -x d e f and x = string, array = false, should result in [a, d].
• -x 1 2 3 -x 4 5 6 and x = number, array = false, should result in [1, 4].
• -x a -x b -x c and x = string, array = false, should result in [a, b, c].
• -x 1 -x 2 -x 3 and x = number, array = false, should result in [1, 2, 3].
• -x true true false -x false true true and x = boolean, array = false, should result in [true, false].
• -x true true false -x false true true and x = boolean, array = true, should result in [[true, true, false], [false, true, true]].

---

☝️ if there are any fixes we can make around these expectations let's make them 👌

And then I'd say, revisit the meaning of array in a separate issue (as I think it's confusing).

[juergba]

Meanwhile a few PR's refering boolean and array have been merged. This PR can be closed.

[bcoe]

@juergba 👍 sorry for this dragging for so long, FYI any chance I could get you to join the slack here:

http://devtoolscommunity.herokuapp.com/

I'd like to roll out a new yargs with a bunch of your fixes, but would first like to make sure that it seems to behave nicely with mocha.