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
A generated fish script didn't complete an option after an argument.
The cause is the generated fish script doesn't accept an input text which already has arguments.
For example, when the input is `repeat -`, the script can complete `--count`, but when the text is `repeat foo -`, the script cannot complete `repeat foo --count`, because the input text already has the argument "foo".
To fix the issue, `FishCompletionsGenerator` got a capability that can accept a text which has arguments.
- Renames AssertEqualStringsIgnoringTrailingWhitespace to
AssertEqualStrings and updates the implementation to require matching
trailing whitespace.
- Updates AssertEqualStrings to include much easier to read diff output
when CollectionDifference is available. This should add developers
when tests fail by providing more clear errors.
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.
RawRepresentable types that have a non-String raw value are having
values displayed in the help screen by converting the RawRep value
into a string. However, these values are by default parsed by their
raw value, so we should use that for display instead.
This is accomplished by adding a defaultValueDescription
implementation for all ExpressibleByArgument-conforming RawValue
types, and then basing the allValues implementation on that.
This generalizes the existing overloads for String-based RawRep types,
while also allowing users who customize their ExpressibleByArgument
implementation to provide the correct help value for clients.
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.
If a ParsableArguments type doesn't implement init(from:) correctly,
it isn't decodable by the parser. This improves the validation
failure message for such types.
defaultValueDescription is always the enum case name, but that's not a
valid argument when the enum value differs from the case name. Extend
ExpressibleByArgument to use rawValue for defaultValueDescription for
string enums.
- Fixes a bug where built-in flags such as --help and --version were not
properly marked with isOptional which resulted in them appearing in
generated content (such as completion scripts and manuals) as required
arguments.
When an array of argument values fails to parse, no custom error message is
provided, and a list of valid candidate values is available, include the
list as part of the error message.
Addresses #401.
- 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.
- Updates helpMessage(columns:) and helpMessage(for:columns:) with an
includeHidden argument defaulted to false to allow for clients to
programmatically generate hidden help.
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`
When an option value fails to parse, no custom error message is
provided, and a list of valid candidate values is available, include the
list as part of the error message.
Addresses #344.
- Removes `HelpInfo` in favor of a recursively defined `CommandInfo`
which contains more raw metadata about the source command.
Additionally, introduces a top level `ToolInfo` type with a
serialization version to aid future tooling.
- Updates tests to match the new serialized format.
- Renames `DumpHelpInfoGenerator` to `DumpHelpGenerator` to align the
type with the `--dump-help` flag.
- 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.
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.
ArgumentParser is configured not to emit detailed synopsis when it would contain more than a dozen entries. This makes sense; however, eliding all information makes the synopsis rather useless.
While commands may have dozens of options, in most cases, only a few of them are required — so we can keep the synopsis short but still useful by only displaying the required parts.
* Include all positional arguments in shortened synopsis
Nate Cook
Tiago Lopes
matsuji
Rauhul Varma
Rob RussoandRob Russo
David Peterson
Ian
Luciano Almeida
konomae
Kth
Keith Smiley
Adam
Daniel Duan
Aaron Gyes
Craig Siemens
Kotaro Suto
François Lamboley
Miguel A. Perez Ojito
Mike WermuthandMike
Alfredo Delli Bovi
Karoy Lorentey
Kenny
Sergey Petrachkov