Add an EnumerableFlag protocol (#65)

* Add EnumerableFlag protocol

This addresses the need for providing name specifications for enum
flags, since property wrappers can't be used for enum cases.

* Incorporate updated flag-handling logic

* Include test of multiple names for enumerable flags

* Add documentation for EnumerableFlag protocol

* Add `static func help(for:)` to EnumerableFlag

* Update docs to cover `EnumerableFlag`

* Update default value documentation

* Revise the Flag type docs

* Update Documentation/02 Arguments, Options, and Flags.md

Co-authored-by: Kyle Macomber <[email protected]>

Co-authored-by: Kyle Macomber <[email protected]>

Author: natecook1000

Documentation/02 Arguments, Options, and Flags.md

@@ -211,15 +211,15 @@ false false
 Error: Missing one of: '--enable-required-element', '--disable-required-element'
 ```
 
-You can also use flags with types that are `CaseIterable` and `RawRepresentable` with a string raw value. This is useful for providing custom names for a Boolean value, for an exclusive choice between more than two names, or for collecting multiple values from a set of defined choices.
+To create a flag with custom names for a Boolean value, to provide an exclusive choice between more than two names, or for collecting multiple values from a set of defined choices, define an enumeration that conforms to the `EnumerableFlag` protocol.
 
 ```swift
-enum CacheMethod: String, CaseIterable {
+enum CacheMethod: EnumerableFlag {
     case inMemoryCache
     case persistentCache
 }
 
-enum Color: String, CaseIterable {
+enum Color: EnumerableFlag {
     case pink, purple, silver
 }
 
@@ -235,7 +235,7 @@ struct Example: ParsableCommand {
 }
 ``` 
 
-The flag names in this case are drawn from the raw values:
+The flag names in this case are drawn from the raw values — for information about customizing the names and help text, see the  [`EnumerableFlag` documentation](../Sources/ArgumentParser/Parsable%20Types/EnumerableFlag.swift).
 
 ```
 % example --in-memory-cache --pink --silver

Sources/ArgumentParser/Parsable Properties/ArgumentHelp.swift

@@ -19,6 +19,9 @@ public struct ArgumentHelp {
 
   /// An alternative name to use for the argument's value when showing usage
   /// information.
+  ///
+  /// - Note: This property is ignored when generating help for flags, since
+  ///   flags don't include a value.
   public var valueName: String?
 
   /// A Boolean value indicating whether this argument should be shown in

Sources/ArgumentParser/Parsable Properties/Flag.swift

@@ -21,12 +21,12 @@
 /// `verbose` has a default value of `false`, but becomes `true` if `--verbose`
 /// is provided on the command line.
 ///
-/// A flag can have a value that is a `Bool`, an `Int`, or any `CaseIterable`
-/// type. When using a `CaseIterable` type as a flag, the individual cases
+/// A flag can have a value that is a `Bool`, an `Int`, or any `EnumerableFlag`
+/// type. When using an `EnumerableFlag` type as a flag, the individual cases
 /// form the flags that are used on the command line.
 ///
 ///     struct Options {
-///         enum Operation: CaseIterable, ... {
+///         enum Operation: EnumerableFlag {
 ///             case add
 ///             case multiply
 ///         }
@@ -188,7 +188,9 @@ extension Flag where Value == Bool {
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this flag.
-  ///   - initial: The default value for this flag.
+  ///   - initial: A default value to use for this property. If `initial` is
+  ///     `nil`, one of the flags declared by this `@Flag` attribute is required
+  ///     from the user.
   ///   - inversion: The method for converting this flag's name into an on/off
   ///     pair.
   ///   - exclusivity: The behavior to use when an on/off pair of flags is
@@ -226,18 +228,20 @@ extension Flag where Value == Int {
   }
 }
 
-extension Flag where Value: CaseIterable, Value: Equatable, Value: RawRepresentable, Value.RawValue == String {
+// - MARK: EnumerableFlag
+
+extension Flag where Value: EnumerableFlag {
   /// Creates a property that gets its value from the presence of a flag,
-  /// where the allowed flags are defined by a `CaseIterable` type.
+  /// where the allowed flags are defined by an `EnumerableFlag` type.
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this flag.
   ///   - initial: A default value to use for this property. If `initial` is
-  ///     `nil`, this flag is required.
+  ///     `nil`, one of the flags declared by this `@Flag` attribute is required
+  ///     from the user.
   ///   - exclusivity: The behavior to use when multiple flags are specified.
   ///   - help: Information about how to use this flag.
   public init(
-    name: NameSpecification = .long,
     default initial: Value? = nil,
     exclusivity: FlagExclusivity = .exclusive,
     help: ArgumentHelp? = nil
@@ -248,9 +252,14 @@ extension Flag where Value: CaseIterable, Value: Equatable, Value: RawRepresenta
       var hasUpdated = false
       let defaultValue = initial.map(String.init(describing:))
 
-      let args = Value.allCases.map { value -> ArgumentDefinition in
-        let caseKey = InputKey(rawValue: value.rawValue)
-        let help = ArgumentDefinition.Help(options: initial != nil ? .isOptional : [], help: help, defaultValue: defaultValue, key: key)
+      let caseHelps = Value.allCases.map { Value.help(for: $0) }
+      let hasCustomCaseHelp = caseHelps.contains(where: { $0 != nil })
+      
+      let args = Value.allCases.enumerated().map { (i, value) -> ArgumentDefinition in
+        let caseKey = InputKey(rawValue: String(describing: value))
+        let name = Value.name(for: value)
+        let helpForCase = hasCustomCaseHelp ? (caseHelps[i] ?? help) : help
+        let help = ArgumentDefinition.Help(options: initial != nil ? .isOptional : [], help: helpForCase, defaultValue: defaultValue, key: key, isComposite: !hasCustomCaseHelp)
         return ArgumentDefinition.flag(name: name, key: key, caseKey: caseKey, help: help, parsingStrategy: .nextAsValue, initialValue: initial, update: .nullary({ (origin, name, values) in
           hasUpdated = try ArgumentSet.updateFlag(key: key, value: value, origin: origin, values: &values, hasUpdated: hasUpdated, exclusivity: exclusivity)
         }))
@@ -264,15 +273,110 @@ extension Flag where Value: CaseIterable, Value: Equatable, Value: RawRepresenta
 
 extension Flag {
   /// Creates a property that gets its value from the presence of a flag,
-  /// where the allowed flags are defined by a `CaseIterable` type.
+  /// where the allowed flags are defined by an `EnumerableFlag` type.
+  public init<Element>(
+    exclusivity: FlagExclusivity = .exclusive,
+    help: ArgumentHelp? = nil
+  ) where Value == Element?, Element: EnumerableFlag {
+    self.init(_parsedValue: .init { key in
+      // This gets flipped to `true` the first time one of these flags is
+      // encountered.
+      var hasUpdated = false
+      
+      let caseHelps = Element.allCases.map { Element.help(for: $0) }
+      let hasCustomCaseHelp = caseHelps.contains(where: { $0 != nil })
+
+      let args = Element.allCases.enumerated().map { (i, value) -> ArgumentDefinition in
+        let caseKey = InputKey(rawValue: String(describing: value))
+        let name = Element.name(for: value)
+        let helpForCase = hasCustomCaseHelp ? (caseHelps[i] ?? help) : help
+        let help = ArgumentDefinition.Help(options: .isOptional, help: helpForCase, key: key, isComposite: !hasCustomCaseHelp)
+        return ArgumentDefinition.flag(name: name, key: key, caseKey: caseKey, help: help, parsingStrategy: .nextAsValue, initialValue: nil as Element?, update: .nullary({ (origin, name, values) in
+          hasUpdated = try ArgumentSet.updateFlag(key: key, value: value, origin: origin, values: &values, hasUpdated: hasUpdated, exclusivity: exclusivity)
+        }))
+
+      }
+      return exclusivity == .exclusive
+        ? ArgumentSet(exclusive: args)
+        : ArgumentSet(additive: args)
+      })
+  }
+  
+  /// Creates an array property that gets its values from the presence of
+  /// zero or more flags, where the allowed flags are defined by an
+  /// `EnumerableFlag` type.
   ///
-  /// This property has a default value of `nil`; specifying the flag in the
-  /// command-line arguments is not required.
+  /// This property has an empty array as its default value.
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this flag.
+  ///   - help: Information about how to use this flag.
+  public init<Element>(
+    help: ArgumentHelp? = nil
+  ) where Value == Array<Element>, Element: EnumerableFlag {
+    self.init(_parsedValue: .init { key in
+      let caseHelps = Element.allCases.map { Element.help(for: $0) }
+      let hasCustomCaseHelp = caseHelps.contains(where: { $0 != nil })
+
+      let args = Element.allCases.enumerated().map { (i, value) -> ArgumentDefinition in
+        let caseKey = InputKey(rawValue: String(describing: value))
+        let name = Element.name(for: value)
+        let helpForCase = hasCustomCaseHelp ? (caseHelps[i] ?? help) : help
+        let help = ArgumentDefinition.Help(options: .isOptional, help: helpForCase, key: key, isComposite: !hasCustomCaseHelp)
+        return ArgumentDefinition.flag(name: name, key: key, caseKey: caseKey, help: help, parsingStrategy: .nextAsValue, initialValue: [Element](), update: .nullary({ (origin, name, values) in
+          values.update(forKey: key, inputOrigin: origin, initial: [Element](), closure: {
+            $0.append(value)
+          })
+        }))
+      }
+      return ArgumentSet(additive: args)
+    })
+  }
+}
+
+// - MARK: Deprecated CaseIterable/RawValue == String
+
+extension Flag where Value: CaseIterable, Value: RawRepresentable, Value: Equatable, Value.RawValue == String {
+  /// Creates a property that gets its value from the presence of a flag,
+  /// where the allowed flags are defined by a case-iterable type.
+  ///
+  /// - Parameters:
+  ///   - name: A specification for what names are allowed for this flag.
+  ///   - initial: A default value to use for this property. If `initial` is
+  ///     `nil`, this flag is required.
   ///   - exclusivity: The behavior to use when multiple flags are specified.
   ///   - help: Information about how to use this flag.
+  @available(*, deprecated, message: "Add 'EnumerableFlag' conformance to your value type.")
+  public init(
+    name: NameSpecification = .long,
+    default initial: Value? = nil,
+    exclusivity: FlagExclusivity = .exclusive,
+    help: ArgumentHelp? = nil
+  ) {
+    self.init(_parsedValue: .init { key in
+      // This gets flipped to `true` the first time one of these flags is
+      // encountered.
+      var hasUpdated = false
+      let defaultValue = initial.map(String.init(describing:))
+
+      let args = Value.allCases.map { value -> ArgumentDefinition in
+        let caseKey = InputKey(rawValue: value.rawValue)
+        let help = ArgumentDefinition.Help(options: initial != nil ? .isOptional : [], help: help, defaultValue: defaultValue, key: key, isComposite: true)
+        return ArgumentDefinition.flag(name: name, key: key, caseKey: caseKey, help: help, parsingStrategy: .nextAsValue, initialValue: initial, update: .nullary({ (origin, name, values) in
+          hasUpdated = try ArgumentSet.updateFlag(key: key, value: value, origin: origin, values: &values, hasUpdated: hasUpdated, exclusivity: exclusivity)
+        }))
+      }
+      return exclusivity == .exclusive
+        ? ArgumentSet(exclusive: args)
+        : ArgumentSet(additive: args)
+      })
+  }
+}
+
+extension Flag {
+  /// Creates a property that gets its value from the presence of a flag,
+  /// where the allowed flags are defined by a case-iterable type.
+  @available(*, deprecated, message: "Add 'EnumerableFlag' conformance to your value type.")
   public init<Element>(
     name: NameSpecification = .long,
     exclusivity: FlagExclusivity = .exclusive,
@@ -285,15 +389,15 @@ extension Flag {
 
       let args = Element.allCases.map { value -> ArgumentDefinition in
         let caseKey = InputKey(rawValue: value.rawValue)
-        let help = ArgumentDefinition.Help(options: .isOptional, help: help, key: key)
+        let help = ArgumentDefinition.Help(options: .isOptional, help: help, key: key, isComposite: true)
         return ArgumentDefinition.flag(name: name, key: key, caseKey: caseKey, help: help, parsingStrategy: .nextAsValue, initialValue: nil as Element?, update: .nullary({ (origin, name, values) in
           hasUpdated = try ArgumentSet.updateFlag(key: key, value: value, origin: origin, values: &values, hasUpdated: hasUpdated, exclusivity: exclusivity)
         }))
       }
       return exclusivity == .exclusive
         ? ArgumentSet(exclusive: args)
         : ArgumentSet(additive: args)
-      })
+    })
   }
 
   /// Creates an array property that gets its values from the presence of
@@ -305,22 +409,23 @@ extension Flag {
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this flag.
   ///   - help: Information about how to use this flag.
+  @available(*, deprecated, message: "Add 'EnumerableFlag' conformance to your value type.")
   public init<Element>(
     name: NameSpecification = .long,
     help: ArgumentHelp? = nil
   ) where Value == Array<Element>, Element: CaseIterable, Element: RawRepresentable, Element.RawValue == String {
     self.init(_parsedValue: .init { key in
       let args = Element.allCases.map { value -> ArgumentDefinition in
         let caseKey = InputKey(rawValue: value.rawValue)
-        let help = ArgumentDefinition.Help(options: .isOptional, help: help, key: key)
+        let help = ArgumentDefinition.Help(options: .isOptional, help: help, key: key, isComposite: true)
         return ArgumentDefinition.flag(name: name, key: key, caseKey: caseKey, help: help, parsingStrategy: .nextAsValue, initialValue: [Element](), update: .nullary({ (origin, name, values) in
           values.update(forKey: key, inputOrigin: origin, initial: [Element](), closure: {
             $0.append(value)
           })
         }))
       }
       return ArgumentSet(additive: args)
-      })
+    })
   }
 }
 

Sources/ArgumentParser/Parsable Properties/Option.swift

@@ -78,7 +78,8 @@ extension Option where Value: ExpressibleByArgument {
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this flag.
-  ///   - initial: A default value to use for this property.
+  ///   - initial: A default value to use for this property. If `initial` is
+  ///     `nil`, this option and value are required from the user.
   ///   - help: Information about how to use this option.
   public init(
     name: NameSpecification = .long,
@@ -224,7 +225,8 @@ extension Option {
   ///
   /// - Parameters:
   ///   - name: A specification for what names are allowed for this flag.
-  ///   - initial: A default value to use for this property.
+  ///   - initial: A default value to use for this property. If `initial` is
+  ///     `nil`, this option and value are required from the user.
   ///   - help: Information about how to use this option.
   ///   - transform: A closure that converts a string into this property's
   ///     type or throws an error.

Sources/ArgumentParser/Parsable Types/EnumerableFlag.swift

@@ -0,0 +1,79 @@
+//===----------------------------------------------------------*- swift -*-===//
+//
+// This source file is part of the Swift Argument Parser open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+//
+//===----------------------------------------------------------------------===//
+
+/// A type that represents the different possible flags to be used by a
+/// `@Flag` property.
+///
+/// For example, the `Size` enumeration declared here can be used as the type of
+/// a `@Flag` property:
+///
+///     enum Size: String, EnumerableFlag {
+///         case small, medium, large, extraLarge
+///     }
+///
+///     struct Example: ParsableCommand {
+///         @Flag() var sizes: [Size]
+///
+///         func run() {
+///             print(sizes)
+///         }
+///     }
+///
+/// By default, each case name is converted to a flag by using the `.long` name
+/// specification, so a user can call `example` like this:
+///
+///     $ example --small --large
+///     [.small, .large]
+///
+/// Provide alternative or additional name specifications for each case by
+/// implementing the `name(for:)` static method on your `EnumerableFlag` type.
+///
+///     extension Size {
+///         static func name(for value: Self) -> NameSpecification {
+///             switch value {
+///             case .extraLarge:
+///                 return [.customShort("x"), .long]
+///             default:
+///                 return .shortAndLong
+///             }
+///         }
+///     }
+///
+/// With this extension, a user can use short or long versions of the flags:
+///
+///     $ example -s -l -x --medium
+///     [.small, .large, .extraLarge, .medium]
+public protocol EnumerableFlag: CaseIterable, Equatable {
+  /// Returns the name specification to use for the given flag.
+  ///
+  /// The default implementation for this method always returns `.long`.
+  /// Implement this method for your custom `EnumerableFlag` type to provide
+  /// different name specifications for different cases.
+  static func name(for value: Self) -> NameSpecification
+  
+  /// Returns the help information to show for the given flag.
+  ///
+  /// The default implementation for this method always returns `nil`, which
+  /// groups the flags together with the help provided in the `@Flag`
+  /// declaration. Implement this method for your custom type to provide
+  /// different help information for each flag.
+  static func help(for value: Self) -> ArgumentHelp?
+}
+
+extension EnumerableFlag {
+  public static func name(for value: Self) -> NameSpecification {
+    .long
+  }
+  
+  public static func help(for value: Self) -> ArgumentHelp? {
+    nil
+  }
+}

Sources/ArgumentParser/Parsing/ArgumentDefinition.swift

@@ -31,6 +31,7 @@ struct ArgumentDefinition {
     var discussion: String?
     var defaultValue: String?
     var keys: [InputKey]
+    var isComposite: Bool
 
     struct Options: OptionSet {
       var rawValue: UInt
@@ -39,11 +40,12 @@ struct ArgumentDefinition {
       static let isRepeating = Options(rawValue: 1 << 1)
     }
 
-    init(options: Options = [], help: ArgumentHelp? = nil, defaultValue: String? = nil, key: InputKey) {
+    init(options: Options = [], help: ArgumentHelp? = nil, defaultValue: String? = nil, key: InputKey, isComposite: Bool = false) {
       self.options = options
       self.help = help
       self.defaultValue = defaultValue
       self.keys = [key]
+      self.isComposite = isComposite
     }
   }
 

Sources/ArgumentParser/Parsing/ArgumentSet.swift

@@ -130,7 +130,7 @@ extension ArgumentSet {
     // The flag is required if initialValue is `nil`, otherwise it's optional
     let helpOptions: ArgumentDefinition.Help.Options = initialValue != nil ? .isOptional : []
 
-    let help = ArgumentDefinition.Help(options: helpOptions, help: help, defaultValue: initialValue.map(String.init), key: key)
+    let help = ArgumentDefinition.Help(options: helpOptions, help: help, defaultValue: initialValue.map(String.init), key: key, isComposite: true)
     let (enableNames, disableNames) = inversion.enableDisableNamePair(for: key, name: name)
 
     var hasUpdated = false