The `@_implementationOnly` attribute does not work correctly without
library evolution enabled. The only possible client with this enabled is
Apple, however they have updated to the Swift 6 compiler and can use
`internal import` instead of this attribute. Therefore there is no need
for this package to use the attribute anymore.
Enables and fixes issues with additional platform tests
and the formatter with these additional rules:
- UseLetInEveryBoundCaseVariable
- NeverForceUnwrap
- BeginDocumentationCommentWithOneLineSummary
- ValidateDocumentationComments
- AlwaysUseCamelCase
Adds CI for the following checks:
- YAML lint
- Python lint
- Unacceptable language
- Broken symlinks
- API breakages
In the future the following checks will be added:
- Documentation
- License headers
- Formatting
- Shell check
Moves static read-only vars behind a mutex so they are currency safe.
Users of the api don't need to worry about this because the mutex is
hidden behind an accessor.
The dump help tests previously included the json text in the Swift
source files as multiline strings. This made updating them very tedious
and made diffs hard to follow. This commit moves each of the json dumps
into their own files and adds an easy way of recording new ones as
needed.
Upstreams swiftly's generate-docs-plugin with minimal changes. Adds
tests against argument-parser's built in example tools.
The initial version of this tool is extremely minimal and should be
extended to output much more information contained in tool info, like
generate-manual does.
Cleans up some lingering odds and ends from #647. Specifically switches
CommandInfoV0 to use the old style description and updates
ArgumentInfoV0 to emit value descriptions as a separate dictionary.
Adds a new test target called ArgumentParserToolInfoTests which contains
example json output from dump-help. The test code attempts to parse all
json files in the 'Examples' subdirectory. This will help us catch cases
where ArgumentParser is unable to parse json generated by older versions.
We still need to add a test that asserts old ArgumentParser versions can
parse the output of new versions.
* [cmake] Install libraries in standard directories
Previously, libraries were installed under `lib/swift/${os}/`. They
should be installed in the default library directory for the relevant
target system.
In addition, swiftmodules were installed in the older layout format on
non-Darwin platforms. This changes to use the standard modern layout
format for swiftmodules.
* Use full triple for swiftmodule filenames
* Extract Swift_MODULE_TRIPLE from the function
* Fail early in case the triple cannot be found
* Enable C language before using GNUInstallDirs
* Add C language in project definition
Enabling the C language after Swift was causing issues with using the C
compiler.
Create a `String?` singleton named `CompletionShell.requestingVersion` that
indicates which shell version is requesting completion candidates.
It will be set to the correct value while a Swift custom completion function is
executing to offer completions for a word from a command line (e.g., while
`customCompletion` from `@Option(completion: .custom(customCompletion))`
executes). Otherwise, it will be set to `nil`.
The requesting shell version is communicated to the Swift app via an environment
variable named `SAP_SHELL_VERSION`, which is exported by each of the generated
completion scripts.
Improve some nearby DocC.
Resolve#689
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
A CompletionShell singleton named CompletionShell.requesting has been created
that indicates which shell is requesting completion candidates.
The singleton is populated when a completion script is generated, so functions
used to generate arguments for CompletionKind creation functions can return
completion candidate syntax / shell commands tailored for that shell.
For the custom(:) CompletionKind creation function, the singleton is populated
at runtime (when a completion script requests completions from the Swift app
after a user types tab while composing a command line to call the app).
The requesting shell is communicated to the Swift app via an environment variable
named SAP_SHELL, which is exported by each of the generated completion scripts.
Resolve#672
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
Rewrote Markdown to properly specify Swift 5.7 instead of 5.5,
and to clarify other information related to Swift versions.
Resolve#677
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
Insert missing comma in targets array in Package.swift to fix Swift 5.7 build
break from commit 83c5134a24.
Replace 2 if expressions (which are not supported by Swift 5.7) that were added
to ToolInfo.swift by commit 83c5134a24.
Replace switch expression (which is not supported by Swift 5.7) that was added
to GenerateManual.swift by commit 44dd206a85.
Replace switch expression (which is not supported by Swift 5.7) that was added
to DumpHelpGenerationTests.swift by commit 83c5134a24.
Fixes#675
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
- resolves https://github.com/apple/swift-argument-parser/issues/668
by extending the ToolInfoV0 (help dump) struct to include visibility
information for commands (already exists for arguments).
- updates test output to verify existing examples extend with the
additional key.
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.
- adds check in single and multipage to leverage hidden description in
help dump to determine if the argument should be displayed
- adds check in argument synopsis to only display synopsis if not hidden
- updates existing tests that _had_ hidden output displayed in the
generate-manual output
The documentation as presented doesn't compile. An initializer is
required for a boolean flag.
rdar://132579907
Co-authored-by: Christian Goetze <cgoetze@apple.com>
* Added conversion for InputKey to/from fullPathString.
* Updated custom completions to use the IndexKey.fullPathString.
This resolves an issue where custom completion for arguments in an OptionGroup would fail to match the argument. It was caused by:
- the completion script only using the name of the argument (instead of the full path)
- the CommandParser looking for the matching argument by comparing a name only IndexKey with the “full” IndexKeys
* Updated BashCompletionsGenerator to use customCompletionCall.
The zsh completions already uses this function. The function’s implementation is the same as what the BashCompletionsGenerator is doing. This removes the duplicated logic.
* Updated completion tests to include nested arguments with custom completions.
* Switched to using the split method from the stdlib.
Prevously was using .components(seperatedBy:) from Foundation.
* Updated the fish completions to include arguments
* Introduce subcommand grouping into the command configuration to improve help
Add optional support for grouping subcommands into named groups, to
help bring order to commands with many subcommands without requiring
additional structure. For example, here's the help for a
"subgroupings" command that has an ungrouped subcommand (m), and two
groups of subcommands ("broken" and "complicated").
USAGE: subgroupings <subcommand>
OPTIONS:
-h, --help Show help information.
SUBCOMMANDS:
m
BROKEN SUBCOMMANDS:
foo Perform some foo
bar Perform bar operations
COMPLICATED SUBCOMMANDS:
n
See 'subgroupings help <subcommand>' for detailed help.
To be able freely mix subcommands and subcommand groups, CommandConfiguration
has a new initializer that takes a result builder. The help output
above is created like this:
struct WithSubgroups: ParsableCommand {
static let configuration = CommandConfiguration(
commandName: "subgroupings"
) {
CommandGroup(name: "Broken") {
Foo.self
Bar.self
}
M.self
CommandGroup(name: "Complicated") {
N.self
}
}
}
Each `CommandGroup` names a new group and is given commands (there are
no groups within groups). The other entries are arbitrary
ParsableCommands.
This structure is only cosmetic, and only affects help generation by
providing more structure for the reader. It doesn't impact existing
clients, who can still reason about the flattened list of subcommands
if they prefer.
* Add an optional abstract to command groups
* Expand subcommand group result builders to handle all result-builder syntax
Adds support for if, if-else, if #available, and for..in loops.
* Revert "Add an optional abstract to command groups"
This reverts commit ab563a22c0.
* Eliminate result builders in favor of a second "groupedSubcommands" array
Introduce subcommand groups with a more modest extension to the API that
adds another array of subcommand groups alongside the (ungrouped)
subcommands array. We can consider introducing result builders as a
separate step later, if there's more to be gained from it.
* Drop the (ungrouped) "subcommands" heading when there are none.
When the old (pre-aliases) initializer has all its default parameter
values, it is selected as the overload because it has fewer parameters
overall. Removing the default parameters allows it to still satisfy
(very niche) source compat requirements without actually being
available as an overload.
(Also resolves an extra warning in the tests)
Adds a new API to ParsableArguments and ParsableCommand for getting the
usage string. This allows clients to use argument-parser in a more
piecemeal way to construct their own error screens.
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
Due to the restructuring in #477, there was ambiguity between the
unconstrained `@Option` initializer that uses a transform (but no
initial value) and the one that is constrained to the property being
optional. This marks the unconstrained version as disfavored, which
allows overload resolution to select the optional version when
appropriate.
Also fixes this for `@Argument` and improves documentation
consistency for `@Option`.
Fixes#618.
Nate Cook
Ross Goldberg
Rauhul Varma
Fabrice de Gans
Saleem Abdulrasool
Joseph Heck
Bri Peticca
Christian GoetzeandChristian Goetze
finagolfin
Neil Jones
Craig Siemens
Doug Gregor
Austin
Kotaro Suto
iulianOnofrei (U-lee-aan)
Danny Canter