Addressing PR comments

Author: bkhouri

Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md

@@ -333,32 +333,26 @@ The `defaultAsFlag` parameter allows you to create options that can work both as
 
 ```swift
 struct Example: ParsableCommand {
-    @Option(defaultAsFlag: "default", help: "Set output format.")
-    var format: String?
-
-    @Option(defaultAsFlag: 8080, help: "Server port.")
-    var port: Int?
+    @Option(defaultAsFlag: "json", help: "Set the export format.")
+    var export: String?
 
     func run() {
-        print("Format: \(format ?? "none")")
-        print("Port: \(port ?? 3000)")
+        print("Export: \(format ?? "<don't export>")")
     }
 }
 ```
 
 **Command-line behavior:**
 ```
-% example                    # format = nil, port = nil
-% example --format           # format = "default", port = nil
-% example --format json      # format = "json", port = nil
-% example --port             # format = nil, port = 8080
-% example --port 9000        # format = nil, port = 9000
+% example                    # export = nil
+% example --export           # export = "json"
+% example --format yaml      # format = "yaml"
 ```
 
 The `defaultAsFlag` parameter creates a hybrid that supports both patterns:
-- **Flag behavior**: `--format` (sets format to "default")
-- **Option behavior**: `--format json` (sets format to "json")
-- **No usage**: format remains `nil`
+- **Flag behavior**: `--export` (sets format to "json")
+- **Option behavior**: `--export yaml` (sets format to "yaml")
+- **No usage**: `export` remains `nil`
 
 #### Type requirements
 
@@ -405,7 +399,7 @@ The parser determines whether a value follows the option:
 2. **No value available**: Use the `defaultAsFlag` value
 3. **Explicit value provided**: Parse and use that value
 
-This works with all parsing strategies (`.next`, `.scanningForValue`, `.unconditional`), though `.unconditional` defeats the purpose by always requiring a value.
+This works with parsing strategies `.next` and `.scanningForValue`.  The `.unconditional` parsing strategy defeats the purpose by always requiring a value.
 
 For complete examples and API reference, see the [`default-as-flag`](https://github.com/apple/swift-argument-parser/tree/main/Examples/default-as-flag) example.
 

Sources/ArgumentParser/Parsable Properties/Option.swift

@@ -161,7 +161,46 @@ public struct SingleValueParsingStrategy: Hashable {
   }
 }
 
+/// The strategy to use when parsing a single value from `@Option` arguments with `defaultAsFlag`.
+///
+/// This is a subset of `SingleValueParsingStrategy` that excludes strategies incompatible
+/// with default-as-flag behavior.
+public struct DefaultAsFlagParsingStrategy: Hashable {
+  internal var base: ArgumentDefinition.ParsingStrategy
+
+  /// Parse the input after the option and expect it to be a value.
+  ///
+  /// For inputs such as `--foo foo`, this would parse `foo` as the
+  /// value. However, the input `--foo --bar foo bar` would
+  /// result in an error. Even though two values are provided, they don't
+  /// succeed each option. Parsing would result in an error such as the following:
+  ///
+  ///     Error: Missing value for '--foo <foo>'
+  ///     Usage: command [--foo <foo>]
+  ///
+  /// When used with `defaultAsFlag`, if no value is found, the default flag value is used.
+  public static var next: DefaultAsFlagParsingStrategy {
+    self.init(base: .default)
+  }
+
+  /// Parse the next input, as long as that input can't be interpreted as
+  /// an option or flag.
+  ///
+  /// - Note: This will skip other options and _read ahead_ in the input
+  /// to find the next available value. This may be *unexpected* for users.
+  /// Use with caution.
+  ///
+  /// For example, if `--foo` takes a value, then the input `--foo --bar bar`
+  /// would be parsed such that the value `bar` is used for `--foo`.
+  ///
+  /// This is the **default behavior** for `defaultAsFlag` options.
+  public static var scanningForValue: DefaultAsFlagParsingStrategy {
+    self.init(base: .scanningForValue)
+  }
+}
+
 extension SingleValueParsingStrategy: Sendable {}
+extension DefaultAsFlagParsingStrategy: Sendable {}
 
 /// The strategy to use when parsing multiple values from `@Option` arguments into an
 /// array.
@@ -504,7 +543,7 @@ extension Option {
   }
 
   /// Creates an optional property that reads its value from a labeled option,
-  /// with a default value when the flag is provided without an argument.
+  /// with a default value when the flag is provided without a value.
   ///
   /// This initializer allows providing a `defaultAsFlag` value that is used
   /// when the flag is present but no value follows it:
@@ -518,15 +557,15 @@ extension Option {
   ///   - wrappedValue: A default value to use for this property, provided
   ///     implicitly by the compiler during property wrapper initialization.
   ///   - name: A specification for what names are allowed for this option.
-  ///   - defaultAsFlag: The value to use when the flag is provided without an argument.
+  ///   - defaultAsFlag: The value to use when the flag is provided without a value.
   ///   - parsingStrategy: The behavior to use when looking for this option's value.
   ///   - help: Information about how to use this option.
   ///   - completion: The type of command-line completion provided for this option.
   public init<T>(
     wrappedValue: _OptionalNilComparisonType,
     name: NameSpecification = .long,
     defaultAsFlag: T,
-    parsing parsingStrategy: SingleValueParsingStrategy = .scanningForValue,
+    parsing parsingStrategy: DefaultAsFlagParsingStrategy = .scanningForValue,
     help: ArgumentHelp? = nil,
     completion: CompletionKind? = nil
   ) where T: ExpressibleByArgument, Value == T? {
@@ -646,7 +685,7 @@ extension Option {
   }
 
   /// Creates an optional property that reads its value from a labeled option,
-  /// with a default value when the flag is provided without an argument.
+  /// with a default value when the flag is provided without a value.
   ///
   /// This initializer allows providing a `defaultAsFlag` value that is used
   /// when the flag is present but no value follows it:
@@ -658,14 +697,14 @@ extension Option {
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this option.
-  ///   - defaultAsFlag: The value to use when the flag is provided without an argument.
+  ///   - defaultAsFlag: The value to use when the flag is provided without a value.
   ///   - parsingStrategy: The behavior to use when looking for this option's value.
   ///   - help: Information about how to use this option.
   ///   - completion: The type of command-line completion provided for this option.
   public init<T>(
     name: NameSpecification = .long,
     defaultAsFlag: T,
-    parsing parsingStrategy: SingleValueParsingStrategy = .scanningForValue,
+    parsing parsingStrategy: DefaultAsFlagParsingStrategy = .scanningForValue,
     help: ArgumentHelp? = nil,
     completion: CompletionKind? = nil
   ) where T: ExpressibleByArgument, Value == T? {
@@ -759,7 +798,7 @@ extension Option {
 
   /// Creates an optional property that reads its value from a labeled option,
   /// parsing with the given closure, with a default value when the flag is
-  /// provided without an argument.
+  /// provided without a value.
   ///
   /// This initializer allows providing a `defaultAsFlag` value that is used
   /// when the flag is present but no value follows it:
@@ -773,7 +812,7 @@ extension Option {
   ///   - wrappedValue: A default value to use for this property, provided
   ///     implicitly by the compiler during property wrapper initialization.
   ///   - name: A specification for what names are allowed for this option.
-  ///   - defaultAsFlag: The value to use when the flag is provided without an argument.
+  ///   - defaultAsFlag: The value to use when the flag is provided without a value.
   ///   - parsingStrategy: The behavior to use when looking for this option's value.
   ///   - help: Information about how to use this option.
   ///   - completion: The type of command-line completion provided for this option.
@@ -784,7 +823,7 @@ extension Option {
     wrappedValue: _OptionalNilComparisonType,
     name: NameSpecification = .long,
     defaultAsFlag: T,
-    parsing parsingStrategy: SingleValueParsingStrategy = .scanningForValue,
+    parsing parsingStrategy: DefaultAsFlagParsingStrategy = .scanningForValue,
     help: ArgumentHelp? = nil,
     completion: CompletionKind? = nil,
     transform: @Sendable @escaping (String) throws -> T
@@ -907,7 +946,7 @@ extension Option {
 
   /// Creates an optional property that reads its value from a labeled option,
   /// parsing with the given closure, with a default value when the flag is
-  /// provided without an argument.
+  /// provided without a value.
   ///
   /// This initializer allows providing a `defaultAsFlag` value that is used
   /// when the flag is present but no value follows it:
@@ -919,7 +958,7 @@ extension Option {
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this option.
-  ///   - defaultAsFlag: The value to use when the flag is provided without an argument.
+  ///   - defaultAsFlag: The value to use when the flag is provided without a value.
   ///   - parsingStrategy: The behavior to use when looking for this option's value.
   ///   - help: Information about how to use this option.
   ///   - completion: The type of command-line completion provided for this option.
@@ -929,7 +968,7 @@ extension Option {
   public init<T>(
     name: NameSpecification = .long,
     defaultAsFlag: T,
-    parsing parsingStrategy: SingleValueParsingStrategy = .scanningForValue,
+    parsing parsingStrategy: DefaultAsFlagParsingStrategy = .scanningForValue,
     help: ArgumentHelp? = nil,
     completion: CompletionKind? = nil,
     transform: @Sendable @escaping (String) throws -> T