Add new FlagOption type

[bkhouri]

There is a need to have an argument act as a flag or as an option. Introduce a new FlagOption type that support this.

Fixes: #829

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[rauhul]

• xctest instead of swift-testing to support swift 5.7
• synopsis: [--log-level [log-level]] or [--log-level [<log-level>]]
• dump-help snapshot tests
• completion snapshot tests
• manpage support
• manpage snapshot tests
• documentation

[rgoldberg]

Would it make more sense instead to provide this functionality via Option? Like:

@Option(parsing: .scanningForValue(default: "text"))
var showBinPath: String?

You'd add/modify the following (I haven't checked the code for proper generics/types/compilation/keywords/etc.; it's just pseudo-code to illustrate the concept. I also haven't checked to see what problems adding the new SingleValueParsingStrategy to Option might cause):

public struct SingleValueParsingStrategy: Hashable {
  …
  // This is an addition
  public static func scanningForValue<Value>(default: Value) -> SingleValueParsingStrategy {
    self.init(base: .scanningForValue(default: default))
  }
  …
}

struct ArgumentDefinition {
  …
  enum ParsingStrategy {
    …
    // This is a modification
    case scanningForValue(default: Any? = nil)
    …
  }
  …
}

One possible issue: must ensure that the option terminator -- ensures that json in the following command line is interpreted as positional argument 1, not as a value for --show-bin-path, but that problem might exist for this any FlagOption solution, too:

cmd --show-bin-path -- json

[bkhouri]

Thanks for the feedback @rgoldberg . What you proposed makes more sense than what I implemented.