@@ -104,51 +104,189 @@ public struct ArgumentArrayParsingStrategy: Hashable {
104104 /// Parse only unprefixed values from the command-line input, ignoring
105105 /// any inputs that have a dash prefix. This is the default strategy.
106106 ///
107- /// For example, for a parsable type defined as following:
107+ /// `remaining` is the default parsing strategy for argument arrays.
108108 ///
109- /// struct Options: ParsableArguments {
110- /// @Flag var verbose: Bool
111- /// @Argument(parsing: .remaining) var words: [String]
109+ /// For example, the `Example` command defined below has a `words` array that
110+ /// uses the `remaining` parsing strategy:
111+ ///
112+ /// @main
113+ /// struct Example: ParsableCommand {
114+ /// @Flag var verbose = false
115+ ///
116+ /// @Argument(parsing: .remaining)
117+ /// var words: [String]
118+ ///
119+ /// func run() {
120+ /// print(words.joined(separator: "\n"))
121+ /// }
112122 /// }
113123 ///
114- /// Parsing the input `--verbose one two` or `one two --verbose` would result
115- /// in `Options(verbose: true, words: ["one", "two"])`. Parsing the input
116- /// `one two --other` would result in an unknown option error for `--other`.
124+ /// Any non-dash-prefixed inputs will be captured in the `words` array.
125+ ///
126+ /// ```
127+ /// $ example --verbose one two
128+ /// one
129+ /// two
130+ /// $ example one two --verbose
131+ /// one
132+ /// two
133+ /// $ example one two --other
134+ /// Error: Unknown option '--other'
135+ /// ```
136+ ///
137+ /// If a user uses the `--` terminator in their input, all following inputs
138+ /// will be captured in `words`.
117139 ///
118- /// This is the default strategy for parsing argument arrays.
140+ /// ```
141+ /// $ example one two -- --verbose --other
142+ /// one
143+ /// two
144+ /// --verbose
145+ /// --other
146+ /// ```
119147 public static var remaining : ArgumentArrayParsingStrategy {
120148 self . init ( base: . default)
121149 }
122150
151+ /// After parsing, capture all unrecognized inputs in this argument array.
152+ ///
153+ /// You can use the `allUnrecognized` parsing strategy to suppress
154+ /// "unexpected argument" errors or to capture unrecognized inputs for further
155+ /// processing.
156+ ///
157+ /// For example, the `Example` command defined below has an `other` array that
158+ /// uses the `allUnrecognized` parsing strategy:
159+ ///
160+ /// @main
161+ /// struct Example: ParsableCommand {
162+ /// @Flag var verbose = false
163+ /// @Argument var name: String
164+ ///
165+ /// @Argument(parsing: .allUnrecognized)
166+ /// var other: [String]
167+ ///
168+ /// func run() {
169+ /// print(other.joined(separator: "\n"))
170+ /// }
171+ /// }
172+ ///
173+ /// After parsing the `--verbose` flag and `<name>` argument, any remaining
174+ /// input is captured in the `other` array.
175+ ///
176+ /// ```
177+ /// $ example --verbose Negin one two
178+ /// one
179+ /// two
180+ /// $ example Asa --verbose --other -zzz
181+ /// --other
182+ /// -zzz
183+ /// ```
184+ public static var allUnrecognized : ArgumentArrayParsingStrategy {
185+ self . init ( base: . allUnrecognized)
186+ }
187+
188+ /// Before parsing, capture all inputs that follow the `--` terminator in this
189+ /// argument array.
190+ ///
191+ /// For example, the `Example` command defined below has a `words` array that
192+ /// uses the `postTerminator` parsing strategy:
193+ ///
194+ /// @main
195+ /// struct Example: ParsableCommand {
196+ /// @Flag var verbose = false
197+ /// @Argument var name = ""
198+ ///
199+ /// @Argument(parsing: .postTerminator)
200+ /// var words: [String]
201+ ///
202+ /// func run() {
203+ /// print(words.joined(separator: "\n"))
204+ /// }
205+ /// }
206+ ///
207+ /// Before looking for the `--verbose` flag and `<name>` argument, any inputs
208+ /// after the `--` terminator are captured into the `words` array.
209+ ///
210+ /// ```
211+ /// $ example --verbose Asa -- one two --other
212+ /// one
213+ /// two
214+ /// --other
215+ /// $ example Asa Extra -- one two --other
216+ /// Error: Unexpected argument 'Extra'
217+ /// ```
218+ ///
219+ /// - Note: This parsing strategy can be surprising for users, since it
220+ /// changes the behavior of the `--` terminator. Prefer ``remaining``
221+ /// whenever possible.
222+ public static var postTerminator : ArgumentArrayParsingStrategy {
223+ self . init ( base: . postTerminator)
224+ }
225+
123226 /// Parse all remaining inputs after parsing any known options or flags,
124227 /// including dash-prefixed inputs and the `--` terminator.
125228 ///
126- /// When you use the `unconditionalRemaining` parsing strategy, the parser
127- /// stops parsing flags and options as soon as it encounters a positional
128- /// argument or an unrecognized flag. For example, for a parsable type
129- /// defined as following:
229+ /// You can use the `captureForPassthrough` parsing strategy if you need to
230+ /// capture a user's input to manually pass it unchanged to another command.
130231 ///
131- /// struct Options: ParsableArguments {
132- /// @Flag
133- /// var verbose: Bool = false
232+ /// When you use this parsing strategy, the parser stops parsing flags and
233+ /// options as soon as it encounters a positional argument or an unrecognized
234+ /// flag, and captures all remaining inputs in the array argument.
134235 ///
135- /// @Argument(parsing: .unconditionalRemaining)
236+ /// For example, the `Example` command defined below has an `words` array that
237+ /// uses the `captureForPassthrough` parsing strategy:
238+ ///
239+ /// @main
240+ /// struct Example: ParsableCommand {
241+ /// @Flag var verbose = false
242+ ///
243+ /// @Argument(parsing: .captureForPassthrough)
136244 /// var words: [String] = []
245+ ///
246+ /// func run() {
247+ /// print(words.joined(separator: "\n"))
248+ /// }
137249 /// }
138250 ///
139- /// Parsing the input `--verbose one two --verbose` includes the second
140- /// `--verbose` flag in `words`, resulting in
141- /// `Options(verbose: true, words: ["one", "two", "--verbose"])`.
251+ /// Any values after the first unrecognized input are captured in the `words`
252+ /// array.
253+ ///
254+ /// ```
255+ /// $ example --verbose one two --other
256+ /// one
257+ /// two
258+ /// --other
259+ /// $ example one two --verbose
260+ /// one
261+ /// two
262+ /// --verbose
263+ /// ```
264+ ///
265+ /// With the `captureForPassthrough` parsing strategy, the `--` terminator
266+ /// is included in the captured values.
267+ ///
268+ /// ```
269+ /// $ example --verbose one two -- --other
270+ /// one
271+ /// two
272+ /// --
273+ /// --other
274+ /// ```
142275 ///
143276 /// - Note: This parsing strategy can be surprising for users, particularly
144- /// when combined with options and flags. Prefer `remaining` whenever
145- /// possible, since users can always terminate options and flags with
146- /// the `--` terminator. With the `remaining` parsing strategy, the input
147- /// `--verbose -- one two --verbose ` would have the same result as the above
148- /// example: `Options(verbose: true, words: ["one", "two", "--verbose"])` .
149- public static var unconditionalRemaining : ArgumentArrayParsingStrategy {
277+ /// when combined with options and flags. Prefer `` remaining`` or
278+ /// ``allUnrecognized`` whenever possible, since users can always terminate
279+ /// options and flags with the `--` terminator. With the `remaining`
280+ /// parsing strategy, the input `--verbose -- one two --other ` would have
281+ /// the same result as the first example above .
282+ public static var captureForPassthrough : ArgumentArrayParsingStrategy {
150283 self . init ( base: . allRemainingInput)
151284 }
285+
286+ @available ( * , deprecated, renamed: " captureForPassthrough " )
287+ public static var unconditionalRemaining : ArgumentArrayParsingStrategy {
288+ . captureForPassthrough
289+ }
152290}
153291
154292// MARK: - @Argument T: ExpressibleByArgument Initializers
0 commit comments