In some use cases, there is a need to have an option argument behave
like a flag.
This change introduced 4 new intialiazers to `Option` that accept a
`defaultAsFlag` value.
With the following usage:
```swift
struct Example: ParsableCommand {
@Option(defaultAsFlag: "default", help: "Set output format.")
var format: String?
func run() {
print("Format: \(format ?? "none")")
}
}
```
The `defaultAsFlag` parameter creates a hybrid that supports both patterns:
- **Flag behavior**: `--format` (sets format to "default")
- **Option behavior**: `--format json` (sets format to "json")
- **No usage**: format remains `nil`
As a user of the command line tool, the `--help` output clearly distinguishes
between the the hybrid and regular usages.
```
OPTIONS:
--format [<format>] Set output format. (default as flag: default)
````
Note the `(default as flag: ...)` text instead of regular `(default: ...)`,
and the optional value syntax `[<value>]` instead of required `<value>`.
Fixes: #829
* Replace the cursor index within the completing word parameter of custom-completion closures with a `String` `completionPrefix` parameter.
* Simplify String.prefix(…) call in CommandParser.swift.
They indicate to the Swift custom completion function:
1. the word for which completions are being requested.
2. the location of the cursor within that word.
Since `ExpressibleByArgument` already maintains a list of
enumerable values for an argument, we can extend this to serve
as an ordered list for a new dictionary property that maps the
value name to its description, if applicable. The new property
is a static variable on `ExpressibleByArgument` labelled
`allValueDescriptions`.
If the description string for a value is the same as the value
string, it's assumed that the description is not implemented.
The new value strings are used in the help screen, in the
dump-help JSON output, and in the generated manual.
This adds support for aliases for subcommands via a new parameter to
CommandConfigurations constructors. The aliases are passed as an array
of strings, where the default is just an empty array that signifies there
are no aliases. The aliases are supported regardless of if a different
commandName is chosen or not. This also updates how subcommands show up
in the help text. Any aliases are now displayed to the right of the original
command.
In addition to the functionality itself, this change:
1. Updates some of the EndToEnd parsing tests to make sure they function
while using aliases.
2. Sprinkles mentions where I saw fit in the documentation.
3. Updates the Math example to have aliases for `math stats average`
(`math stats avg`), and `math multiply` (`math mul`).
`math`'s help text now looks like the below:
```
~ math --help
OVERVIEW: A utility for performing maths.
USAGE: math <subcommand>
OPTIONS:
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
add (default) Print the sum of the values.
multiply, mul Print the product of the values.
stats Calculate descriptive statistics.
See 'math help <subcommand>' for detailed help.
~ math stats --help
OVERVIEW: Calculate descriptive statistics.
USAGE: math stats <subcommand>
OPTIONS:
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
average, avg Print the average of the values.
stdev Print the standard deviation of the values.
quantiles Print the quantiles of the values (TBD).
See 'math help stats <subcommand>' for detailed help.
```
and use of the aliases:
```
~ math mul 10 10
100
~ math stats avg 10 20
15.0
```
This change does NOT add any updates to the shell completion logic for
this feature.
Fixes#248
CI is allowing a `guard #available(macOS 12)` in the tests to pass,
but then reporting macOS version 10.16 both in ProcessInfo and in
the guard in the actual `CountLines.run()` method, which results
in an inconsistency. Switching the minimum platform for
`count-lines` until we can sort out the configuration issue.
This adds underscored initializers that let library users add `= nil` to
declarations of optional `@Option` and `@Argument` properties. Previously,
default values have been available for properties of non-optional types
only.
These new initializers use `_OptionalNilComparisonType` as the wrapped
value parameter, so only a `nil` literal is acceptable in the default
value position. This avoids the problem of declaring an optional property
with a non-`nil` default, which ends up negating the purpose of an optional.
This adds `-parse-as-library` to the example targets which use `@main`
resulting in a compile failure as `@main` is not processed unless the
target is marked as library.
Authored-by: Saleem Abdulrasool <compnerd@compnerd.org>
Adds a new `AsyncParsableCommand` protocol, which provides a
`static func main() async` entry point and can call through to the root
command's or a subcommand's asynchronous `run()` method. For this
asynchronous execution, the root command must conform to `AsyncParsableCommand`,
but its subcommands can be a mix of asynchronous and synchronous commands.
Due to an issue in Swift 5.5, you can only use `@main` on an
`AsyncParsableCommand` root command starting in Swift 5.6.
This change also includes a workaround for clients that are using Swift 5.5.
Declare a separate type that conforms to `AsyncMainProtocol` and add the `@main`
attribute to that type.
```
@main enum Main: AsyncMain {
typealias Command = <#command#>
}
```
Support for generating shell completion scripts for `ParsableCommand`
types, with customization points for `ExpressibleByArgument` types and
individual arguments and options. Zsh and Bash are supported in this
initial release.
* Use type inference for flags / options
* Use default value syntax for arg/option arrays
* Allow a default for flag arrays
* Fix some whitespace
* Allow arguments validations to warn instead of fail
* Move nonsense flag warning to argument validation
* Update guides/readme with default literal syntax
* Allow normal Swift default property initialization syntax
This change allows the normal `var foo = "blah"` default initialization
syntax for `Option`s, as a parallel initialization method as using the
`default` parameter.
* Add simple tests for default property initialization
* Centralize some constructor logic into a private `init`
Preparing for another no-initial value `init` to be added and the existing one with a `default` parameter to be deprecated
* Deprecate previous `Option.init` with `default` parameter
It's replaced with an `init` containing no default value parameter, which will be used when the user does not provide any value.
Also add a (most likely unnecessary) sanity test to make sure initializations without a default value still work.
Also copy out documentation to allow clean removal of the older `init` when the time comes.
* Document added test cases
* Correct punctuation
* Extend standard default initialization syntax to `Option`s with `transform` parameters
* Actually replace previous `init` with private version
This mirrors the non-transform variants, and should have been included in the previous commits
* Clean up usage of default parameter values
Private `init` doesn't need defaults, and the deprecated public ones shouldn't have it to avoid confusion with the new methods
* Clean up documentation
Treat new initializers as the originally intended way to allow for clean removal of the deprecated methods
Also add some additional documentation to the deprecated methods to help point users in the right direction
* Extend standard default initialization to `Argument`s
* Extend standard default initialization to `Flag`s
* Default flags with inversions to nil/required
* Extend standard default initialization to no-inversion boolean `Flags`
Prints a warning when that default value is `true` instead of `false`, as the flag value will be pinned regardless of user input
* Eliminate deprecation spam from default value initialization
All examples and unit tests have been transitioned to the new syntax, with the exception of `SourceCompatEndToEndTests`, which should not have the old style removed until it is no longer valid source.
* Add source compatibility tests for new default syntax and associated changes
* Update top-level documentation
* Add built-in support for --version flag
* Test that command-defined --version overrides the built-in.
* Document the `version:` parameter in CommandConfiguration
* Include --version in the generated help.
* build: update cmake for TestHelpers rename
* build: make CMake build on macOS work
Unfortunately, XCTest importing is not working for some reason
currently. However, this allows you to build on Darwin as follows:
```
cmake -G Ninja -D CMAKE_BUILD_TYPE=Release -D BUILD_TESTING=NO -S . -B out
ninja -C out
```
Windows and Linux builds remain functional.
* build: refactor Examples build with CMake
Although this goes contrary to best practices for CMake, this helps keep
the source tree a bit leaner for the Examples.
This adds an `ExitCode` error type that stores an exit code,
and updates the exit machinery to (1) use `ExitCode` as the source
for exit codes, and (2) silently exit when the provided error
is an `ExitCode` instance.
When a validation error is thrown from a subcommand, we aren't correctly
including the command stack, so only the root command's usage is shown.
This bundles the validation error together with the command stack so the
error message has all the context it needs.
Bassam (Sam) Khouri
Nate Cook
Ross Goldberg
Konstantin Krokhin
Rauhul Varma
Bri Peticca
Kotaro Suto
Danny Canter
Cœur
Kth
Saleem Abdulrasool
Adam Sharp
Mike Lewis
Brad Larson