Add an EnumerableFlag protocol

[natecook1000]

Description

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

Detailed Design

This includes a new EnumerableFlag protocol:

/// A type that represents the different possible flags to be used by a
/// `@Flag` property.
public protocol EnumerableFlag: CaseIterable {
  /// Returns the name specification to use for the given flag.
  static func name(for value: Self) -> NameSpecification

  /// Returns the help information to show for the given flag.
  static func help(for value: Self) -> ArgumentHelp?
}

As well as new EnumerableFlag-constrained @Flag initializers that replace the current ones that are constrained to String/CaseIterable.

Documentation Plan

Wrote type- and symbol-level documentation for EnumerableFlag, revised docs for the new initializers, and updated the "Argument, Options, and Flags" guide.

Test Plan

Modified unit tests to use the new protocol and added tests that use the original, deprecated versions.

Source Impact

This deprecates the @Flag initializers that are constrained to CaseIterable/RawRepresentable and RawValue == String. These initializers will continue to work, and can be removed in a future version.

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

[natecook1000]

@swift-ci Please test

[kylemacomber]

At first I thought the Array case was counter intuitive:

enum Color: EnumerableFlag {
    case pink, purple, silver
}

struct Example: ParsableCommand {
   @Flag() var colors: [Color]
   
   func run() throws {
       print(colors)
   }
}

% example --pink --silver
[.pink, .silver]

... and was going to suggest it be broken out into a separate property wrapper, but I see the synergy with the Int use case.

[kylemacomber]

Seems like we could accept any RangeReplaceableCollection. And also maybe SetAlgebra? It's a little weird to conform an OptionSet to CaseIterable, but that's a more efficient storage representation for your Color example.

[natecook1000]

Seems like we could accept any RangeReplaceableCollection. And also maybe SetAlgebra? It's a little weird to conform an OptionSet to CaseIterable, but that's a more efficient storage representation for your Color example.

We could definitely make these generic over RangeReplaceableCollection, though we'd want to do that across the board (i.e. for @Option and @Argument types, too). SetAlgebra would require another set of overloads, since we don't have an abstraction that ties the two "create an empty one and then add things to it" protocols.

[natecook1000]

@swift-ci Please test

[kylemacomber]

LGTM!