From 544817d989bce7ef299aedbbb4ad92641e78691b Mon Sep 17 00:00:00 2001 From: Vivek JM <24496671+vivekjm@users.noreply.github.com> Date: Tue, 28 Jul 2026 12:38:47 +0530 Subject: [PATCH 1/2] Document the option terminator --- .../Articles/DeclaringArguments.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md b/Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md index bae63a2e9..d2806b7bc 100644 --- a/Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md +++ b/Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md @@ -540,13 +540,27 @@ Usage: example [--verbose] [ ...] See 'example --help' for more information. ``` -Any input after the `--` terminator is automatically treated as positional input, so users can provide dash-prefixed values that way even with the default configuration: +##### Separating options from positional arguments + +Use the `--` terminator when a positional value starts with a dash and could +otherwise be interpreted as an option or flag. The parser stops recognizing +options and flags after `--` and treats every remaining input as positional. +The terminator itself isn't included in the parsed values: ``` % example --verbose -- file1.swift file2.swift --other Verbose: true, files: ["file1.swift", "file2.swift", "--other"] ``` +This convention also lets users pass a value that has the same spelling as a +declared option or flag. In the following example, `--verbose` is stored in +`files` instead of setting the `verbose` property: + +``` +% example -- --verbose file1.swift +Verbose: false, files: ["--verbose", "file1.swift"] +``` + The `.unconditionalRemaining` parsing strategy uses whatever input is left after parsing known options and flags, even if that input is dash-prefixed, including the terminator itself. If `files` were defined as `@Argument(parsing: .unconditionalRemaining) var files: [String]`, then the resulting array would also include strings that look like options: ``` From a7f9275eab54353fa4a321705d8c9d1e46bd7b70 Mon Sep 17 00:00:00 2001 From: Vivek JM <24496671+vivekjm@users.noreply.github.com> Date: Sat, 22 Aug 2026 13:14:01 +0530 Subject: [PATCH 2/2] Add guide for using ArgumentParser tools --- .../Documentation.docc/ArgumentParser.md | 1 + .../Articles/DeclaringArguments.md | 16 +--------- .../Articles/UsingArgumentParserTools.md | 30 +++++++++++++++++++ 3 files changed, 32 insertions(+), 15 deletions(-) create mode 100644 Sources/ArgumentParser/Documentation.docc/Articles/UsingArgumentParserTools.md diff --git a/Sources/ArgumentParser/Documentation.docc/ArgumentParser.md b/Sources/ArgumentParser/Documentation.docc/ArgumentParser.md index 291821dd9..605bb297d 100644 --- a/Sources/ArgumentParser/Documentation.docc/ArgumentParser.md +++ b/Sources/ArgumentParser/Documentation.docc/ArgumentParser.md @@ -49,6 +49,7 @@ and then either calls your `run()` method or exits with a useful message. ### Essentials +- - - ``ParsableCommand`` - ``AsyncParsableCommand`` diff --git a/Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md b/Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md index d2806b7bc..bae63a2e9 100644 --- a/Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md +++ b/Sources/ArgumentParser/Documentation.docc/Articles/DeclaringArguments.md @@ -540,27 +540,13 @@ Usage: example [--verbose] [ ...] See 'example --help' for more information. ``` -##### Separating options from positional arguments - -Use the `--` terminator when a positional value starts with a dash and could -otherwise be interpreted as an option or flag. The parser stops recognizing -options and flags after `--` and treats every remaining input as positional. -The terminator itself isn't included in the parsed values: +Any input after the `--` terminator is automatically treated as positional input, so users can provide dash-prefixed values that way even with the default configuration: ``` % example --verbose -- file1.swift file2.swift --other Verbose: true, files: ["file1.swift", "file2.swift", "--other"] ``` -This convention also lets users pass a value that has the same spelling as a -declared option or flag. In the following example, `--verbose` is stored in -`files` instead of setting the `verbose` property: - -``` -% example -- --verbose file1.swift -Verbose: false, files: ["--verbose", "file1.swift"] -``` - The `.unconditionalRemaining` parsing strategy uses whatever input is left after parsing known options and flags, even if that input is dash-prefixed, including the terminator itself. If `files` were defined as `@Argument(parsing: .unconditionalRemaining) var files: [String]`, then the resulting array would also include strings that look like options: ``` diff --git a/Sources/ArgumentParser/Documentation.docc/Articles/UsingArgumentParserTools.md b/Sources/ArgumentParser/Documentation.docc/Articles/UsingArgumentParserTools.md new file mode 100644 index 000000000..191511c5c --- /dev/null +++ b/Sources/ArgumentParser/Documentation.docc/Articles/UsingArgumentParserTools.md @@ -0,0 +1,30 @@ +# Using ArgumentParser Tools + +Learn how to provide input to command-line tools built with `ArgumentParser`. + +## Overview + +Tools built with `ArgumentParser` can accept positional arguments, named +options, and flags. The tool's help screen describes the inputs it supports; +run a tool with the `--help` flag to display it. + +### Separating Options from Positional Arguments + +Use the `--` option terminator when a positional value starts with a dash and +could otherwise be interpreted as an option or flag. A tool stops recognizing +options and flags after `--` and treats every remaining input as positional. +The terminator itself isn't included in the parsed values: + +``` +% example --verbose -- file1.swift file2.swift --other +Verbose: true, files: ["file1.swift", "file2.swift", "--other"] +``` + +This convention also lets you pass a positional value that has the same +spelling as a declared option or flag. In the following example, `--verbose` +is stored in `files` instead of setting the `verbose` flag: + +``` +% example -- --verbose file1.swift +Verbose: false, files: ["--verbose", "file1.swift"] +```