Arguments declared with the `.allUnrecognized` parsing strategy
currently capture built-in flags, which isn't intended. This
fixes that issue by looking for built-in flags in the captured
portion of the input before decoding.
Fixes rdar://104990388
When a property wrapper is applied to a property, the property's
storage is given a name with a prefixed underscore. That is,
for a property named `x`, the actual storage is named `_x`.
That prefixed storage is what is visible through reflection, so
when building an ArgumentSet from a command type's Mirror, we
need to remove the leading underscore. This is done when creating
an InputKey for each property.
However, InputKeys are also created from CodingKeys during
decoding of a ParsableCommand. These CodingKeys _do not_ have
the leading underscore that is visible, so any underscores
that appear are actually from the declaration of the property
with an underscored name. Removing leading underscores from
CodingKey names results in a mismatch when trying to find
the decoded value.
This change simplifies the InputKey type to use an array
path instead of an indirect enum and removes the leading
underscore dropping when creating an InputKey from a CodingKey.
rdar://104928743
* Use existential CodingKey parameters consistently
Swift 5.7 supports implicit opening for existentials, so these
conversions from `CodingKey` parameters to pass to methods that
are generic over `CodingKey` work fine. Prior to Swift 5.7, however,
these don't compile, with the message that `CodingKey` doesn't conform
to itself.
* Bump the required Swift version for the count-lines test
The overload resolution for the `static func main()` in an `@main`
type still had issues in Swift 5.6, such that a package with a min.
platform below that which works for concurrency backdeployment doesn't
properly resolve the AsyncParsableCommand `main()` function. In
Swift 5.7, this is properly resolved, so just the availability on
the main type is sufficient.
This change just skips the test of `count-lines` prior to Swift 5.7,
so that we can maintain the open platform minimum for the package
as a whole.
This adds two new parsing options for argument arrays, and renames
`.unconditionalRemaining` to `.captureForPassthrough`.
- `.allUnrecognized` collects all the inputs that weren't used during
parsing. This essentially suppresses all "unrecognized flag/option"
and "unexpected argument" errors, and makes those extra inputs
available to the client.
- `.postTerminator` collects all inputs that follow the `--`
terminator, before trying to parse any other positional arguments.
This is a non-standard, but sometimes useful parsing strategy.
This change lets you provide a title for option groups, which is used
when generating the help screen. Titled option groups, when they exist,
are placed between the ARGUMENTS and OPTIONS section of the help.
Multiple option groups with the same title are coalesced into a single
group.
For example, this command declaration:
struct Extras: ParsableArguments {
@Flag(help: "Print extra output while processing.")
var verbose: Bool = false
@Flag(help: "Include details no one asked for.")
var oversharing: Bool = false
}
@main
struct Example: ParsableCommand {
@OptionGroup(title: "Extras")
var extras: Extras
@Argument var name: String?
@Option var title: String?
}
yields this help screen:
USAGE: example [--verbose] [--oversharing] [<name>] [--title <title>]
ARGUMENTS:
<name>
EXTRAS:
--verbose Print extra output while processing.
--oversharing Include details no one asked for.
OPTIONS:
--title <title>
-h, --help Show help information.
In the help for flags like --prefix/--no-prefix, use the name of the
default flag instead of true/false. When EnumerableFlag types
have separate help strings, show the correct default flag name
on the default flag in the help.
- Fixes#466.
- Adds initializers to ArgumentDefinition generic over a Container type.
The Container type must conform to a new internal protocol
ArgumentDefinitionContainer which describes functionality like default
set of help options for the argument defined by the property wrapper,
etc.
- Adds overloads for Optional @Arguments and @Options with default
values which emit deprecation warning to guide users towards using the
non-Optional versions.
- Make ArgumentSet(_:visibility:) filter correctly
The ArgumentSet initializer was previously only filtering out option
groups with visibility lower than requested. With this change, the
resulting ArgumentSet only includes values that are valid for display.
In addition, this moves the visibility parameter out of
UsageGenerator.synopsis(); that type needs to have the correct
visibility level at initialization.
- Mark non-parsed properties as private
This applies to properties that are defined without a property
wrapper. This kind of property should never be included in the help,
since they aren't included in the command-line tool's UI.
- Replaces `ArgumentSet.init(_:creatingHelp:includeHidden:)` with
`ArgumentSet.init(_:visibility:)`. `visibility` intentionally does not
have a default value to ensure that callers only have the correct
arguments. As part of this change `includeHidden` has been replaced
throughout the codebase with `visibility`. This change also fixes a
bug where arguments with hidden `visibility` were being displayed in the
generated command usage string.
- Renames ArgumentHelp.Visibility to ArgumentVisibility.
- Replaces ArgumentDefinition.shouldDisplay with a visibility property
whose value is derived from ArgumentHelp.visibility.
Swift Package Manager adopted _hiddenFromHelp, the resulting help is
much more approachable for basic usage, but leaves no way to view
all the advanced options it accepts. This takes from swiftc's + clang's
playbook and adds a hidden `--help-hidden` flag that prints all help,
including those using `_hiddenFromHelp`
* Propagate unconditional remaining arguments to higher commands
This changes the behavior of parsing when a subcommand includes an
argument array with an unconditionalRemaining parsing strategy, such
that parsing options stops when the subcommand is encountered, so
that the subcommand can pick up those additional options.
* Correctly track used input origins for single-dash options
When capturing the values for an option with a single-dash with the .upToNextOption
parsing strategy, the parser was stopping its search for values when it encountered
the "unpacked" short option candidates. This change removes the single-dash option
before looking for values, which strips those short options (e.g. -h) from
consideration. Fixes#327.
- Adds an overload of ArgumentDefinition.init with a generic constraint
on ExpressibleByArgument that propogates the conformance to the
construction of ArgumentDefinition.Help. This allows the
allValueStrings of the type conforming to ExpressibleByArgument to
become the allValues property of the help object.
If a command defines an @Argument property with the .unconditionalRemaining
parsing strategy, we need to stop parsing input when we encounter either a
positional argument or an unrecognized option/flag label. Note that this is
a change in behavior, as seen in the modified test.
- Removes unused codepaths.
- Simplifies synopsis string codepaths by removing optionality. This
complexity is moved to the caller who is now responsible for filtering
out hidden arguments and options. This change is desirable as it
allows the caller to determine if the argument should be hidden. For
example, while it makes sense to hide arguments in help text, it may
not make sense to hide them when dumping the arguments for another
tool to consume.
- Removes one layer of help properties by directly including the members
of ArgumentHelp in ArgumentDefinition.Help. This also results in the
discussion field which previously existed in both structures, now
having a single source of truth. Adds helper method for setting each
of these members using an instance of ArgumentHelp. Makes previously
optional Strings into plain Strings and updates points of use to check
for the empty string case.
This fixes a bug where an @Option array defined with the .upToNextOption
parsing strategy would only capture the last "group" of elements. e.g. in:
example --test one two --test three four
the `--test` property would only have the value `["three", "four"]`.
Fixes rdar://73908471
Fixes “Internal error. Invalid state while parsing command-line arguments.” that is encountered when an unparsed value is optional.
Root causes:
- `ParsedArgumentsContainer.decodeNil` returns false for optional values because it only does a `!contains(key)` check. This should instead return nil if the value of the element is nil.
- The decoder did not know about unparsed input origins that and would result in unexpected behavior when decoding nil default values.
- The `value` of `Mirror.Child` is defined as `Any` but this is confusing because the value could be `Optional<Any>` which is not equal to `nil` even when the `Optional` case is `.none`.
Co-authored-by: Mike <mike.wermuth@icloud.com>
Fixes an issue where the inversion of a flag would not be hidden whe the ArgumentHelp shouldDisplay value is false.
Added a unit test to check for this behavior.
We're newly able to decode actual optional types due to allowing
unparsed variable properties. "Normal" optional values are still
wrapped in non-optional property wrappers, so ArgumentDecoder didn't
need to handle optional values until now. Fixes#285
* Allow variable properties in parsable types
This captures the default value for non-parsable properties
when building the ArgumentSet, which in turn get set as initial
values before decoding.
If helpNames is not modified, Subcommand will inherit helpNames from its immediate parent.
The helpNames is generated from `commandStack: [ParsableCommand.Type]`.
`getHelpNames()` extension method of `Array` is order sensitive and assumes that the element of `commandStack` at indexed `i` is the parent of the element at indexed `i+1`
This removes the nesting inside the ArgumentSet data structure, which
had semantic meaning in an earlier version. This flattening, plus a
switch to using dictionary lookup instead of linear scanning, provides
another performance boost.
* Convert some linear operations to constant time
* Temporary test command for performance testing
* Improve SplitArguments docs
* Re-enable split arguments unit test
* Restore repeat example
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.
* Add a precondition to prevent the parsing of a command that has itself as its subcommand.
This avoids the infinite recursion that causes a crash and shows the user a meaningful error message.
Fixes: https://github.com/apple/swift-argument-parser/issues/192
* Fix the detection of a command that has itself as its subcommand
- The recursion detection now works for both the root command and its subcommands
- Add a test to shows that the fix works
* Fix typo in TreeTests
* 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
This pushes any errors indicated by unexpected arguments after parsing
out to the same late position. We were previously stopping immediately
when the command is a leaf node; that isn't necessary and created an
awkward second error path.
* Use the first long name in usage (#167)
Sorting names for option has been changed.
* Usage will choose the first long name, if available, or otherwise the first short name
* Help screen will show short names, then long names, in the order of their declaration.
Solves (#167)
* Fix adding same name more than once.
Checkin long names in sort caused single dash long names to be treated as a short name.
Fixed sort to check “short” instead of “long”
Update current test to cover more cases.
* Add isShort control to Name
*Replace sortedNames with partitionedNames
*Extract uniquifying logic into SequenceExtensions.swift
* Refactor short test with computed property
* Use pattern-matching instead of equality comparison
* Remove ExpressibleByArgument conformance for Optional
It turns out that the conditional conformance for Optional was a bad idea, and
it should be handled more like Array, with specific initializers for the Optional
case. Primarily, this is because providing a default value for an optional property
doesn't make sense -- the default is already nil, and a non-nil default means that
the property will never be nil and therefore shouldn't be optional.
* Drop duplicated argument definitions
d1 and d6 are duplicates of c2 and c, respectively.
* Correctly mark optional args/options as optional
* Correct documentation for Option/Argument
* Use the correct parameter name in the documentation
Gwynne Raskind
Nate Cook
David Peterson
Rauhul Varma
Kth
Keith Smiley
Adam
Matt Zanchelli
Kotaro Suto
Mike WermuthandMike
Md Abir Hasan Zoha
Elliott Williams
Niccolò Fontana
Mike Lewis
John Mueller
ibrahim oktay