doc: "if and only if" should be "if" in util.parseArgs default value

[Slayer95]

The default value is legal by means other than defaulting.

[himself65]

upstream comment:

#54431 (comment)

[Slayer95]

Re: #54431, the critical part is "the option does not appear in the arguments to be parsed".

However, the way it's currently worded "if and only if", it literally means that the value passed as default behaves as a sentinel value: when it matches, the option was missing; otherwise, the option was in the arguments provided.

But that's not how it works. It's a one-side implication.

[aduh95]

Well it says "to be used", so I don't think it says the value could not be the default value if the option appears in the arguments.
Maybe we can try to rephrase it further to remove the ambiguity:

    * `default` {string | boolean | string\[] | boolean\[]} It must be of the
      same type as the `type` property. When `multiple` is `true`, it must be an
      array. It is ignored when when the option appears in the arguments to be
      parsed.

[shadowspawn]

@aduh95 That leaves out what default is actually used for. Adding your suggestion to the previous text:

`default` {string | boolean | string\[] | boolean\[]} The default value to
      be used if the option does not appear in the arguments to be parsed,
      and ignored if the option does appear. It must be of the same type as the
     `type` property. When `multiple` is `true`, it must be an array. 

[Slayer95]

`default` {string | boolean | string\[] | boolean\[]} The default value to
      be used if the option does not appear in the arguments to be parsed,
      and ignored if the option does appear. It must be of the same type as the
     `type` property. When `multiple` is `true`, it must be an array. 

This wording is also an "if and only if", just more verbose. This wording implies that if string option --foo has a default value of "bar", then --foo=bar is ignored.

I'd go with this:

* `default` {string | boolean | string\[] | boolean\[]} The value to be used if the
      option does not appear in the arguments to be parsed. It must be of the
      same type as the `type` property. When `multiple` is `true`, it must be an
      array. It is ignored when the option appears in the arguments to be
      parsed.

[Slayer95]

I added a new commit, with an expanded text that is hopefully clearer in the context of #54396 and #54431. Does this work for you, @shadowspawn ?

[shadowspawn]

What is this new text about: even if the provided value is falsy? I don't understand why this has been added.

Otherwise, I agree hopefully clearer, spelling out the (if and only if). :-)

[Slayer95]

What is this new text about: even if the provided value is falsy? I don't understand why this has been added.

This is my takeaway from #54396. "falsy" meaning x == false, but actually left open to interpretation, so that whatever false/empty/zero/value someone may think will lead to the parser entering defaulting mechanics, it will not be taken.

Otherwise, I agree hopefully clearer, spelling out the (if and only if). :-)

Well, this was an if (and only if) -note the distinct position of the parens. Whenever such half-parenthesized construct is used, it means that if some convenient assumptions are made, a backwards implication holds, but there are readings where the implication is only forwards. i.e. Considering those additional assumptions, the text turns out to mean not p <=> q, but p => q ∧ r <= s, where either p is equivalent to r, or q is equivalent to s.

Sorry for beating the dead horse, but I think I didn't manage to properly justify how the previous text was problematic, and I just took the chance.

[shadowspawn]

This is my takeaway from #54396. "falsy" meaning x == false, but actually left open to interpretation, so that whatever false/empty/zero/value someone may think will lead to the parser entering defaulting mechanics, it will not be taken.

That wasn't the issue, and thanks for asking me to take a look. The previous wording change was a bit difficult (like this one!) and clearly hasn't worked for everyone.

The original cause for a wording change was that someone came in hoping to allow:

util
util --foo
util --foo FOO

The previous wording did not make it clear enough to them that they couldn't use a default value to cover that middle case.

[Slayer95]

I wanted to liberally fit util --foo in the "foo is falsey" when parsed as a string; but I forgot it would actually be true if parsed as a boolean. I also wanted to make the "it is ignored..." sentence explicitly non-normative. But there's no such concept in Node.js docs. Documentation is hard. 😄

[aduh95]

Landed in ce4a16f