Ordered Multi-Option Collection Support

[manav-Mnv]

This feature enables the Swift Argument Parser to collect multiple different option names into a single ordered array while preserving the relative global ordering of those flags as they appear on the command line. This is achieved by introducing a new @Option initializer that passes both the used flag name and its value to a transform closure, allowing for precise mapping of interleaved options to a single property.

1. ArgumentDefinition.swift

I added a new initializer that changes the internal parsing block to pass the Name (as a String) to the transformation logic:

// New ArgumentDefinition init
transform: @escaping (_ name: String, _ valueString: String) throws -> Container.Contained

2. Option.swift

I added overloads to the @Option initializers that make this name available to the user-provided transform closure:

// New @Option initializer for arrays
public init<T>(
  name: NameSpecification = .long,
  ...,
  transform: @escaping (String, String) throws -> T // name is now available here!
) where Value == [T]

Existing Code: You had to create separate properties for different options (e.g., @Option var resize: [Int] and @Option var blur: [Int]). While each array was ordered, there was no way to know if the user typed --resize 10 --blur 5 or --blur 5 --resize 10.

New Code: You can now define a single property that accepts multiple different flag names. Because the transform closure receives the name of the flag being parsed, you can collect different operations into one array while perfectly preserving the interleaved order of the command-line input.

---

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]

Hi @manav-Mnv! This looks like an implementation of #862 – could you take a look at the discussion there and address the comments in any implementation?