* Do not indent zsh cases.
Simplify zsh indent generation.
* Do not prefix zsh cases with an open parenthesis.
* Prevent zsh parameter word splitting.
Brace & quote parameter uses.
Use [@] for quoted array output.
* Improve comment in ZshCompletionsGenerator.swift.
* Fix incorrect zsh shellCommand single quotes:
4 consecutive single quotes were obviously intended to be 2 escaped single quotes,
but that isn't zsh syntax.
Use 2 double quotes instead.
* Remove extraneous zsh newline.
* Improve zsh variable declarations: scoping, typing & readonly.
Remove trailing spaces from InstallingCompletionScripts.md.
* Include zsh words before current subcommand in custom completion arg.
* Make subcommandHandler in ZshCompletionsGenerator.swift immutable.
* Escape zsh single quotes via '\'' instead of via '"'"'.
* Escape single quotes in zsh shellCommand String.
If someone already escapes single quotes from the String, this will cause an issue,
but no one should be required to go to the trouble to manually escape single quotes
in their script, especially since the requirement isn't documented or normal.
* Fix zsh custom completions for empty [String] & String elements.
If a Swift custom completion function returns an empty [String], if the user tries to
complete it, refuse to complete instead of inserting a blank space into the command line.
If a Swift custom completion function returns a [String] including a Swift empty String
or including a String with a description but with a blank completion
(e.g., ":description"), if that completion is selected, complete to a zsh empty string
'' instead of inserting a blank space into the command line.
Disambiguating between an empty [String] & a [String] with one empty String element
requires that an extra value be appended to the output of the Swift custom function,
which is then removed by the completion script.
* Simplify zsh subcommand completion function dispatch.
* Restrict access to symbols in ZshCompletionsGenerator.swift.
* Add default help to zsh completions iff no existing help subcommand.
* Use interpolated Strings in ZshCompletionsGenerator.swift.
* Create & use zsh __completion function.
* Improve zsh escaping.
* Set zsh settings to a known state.
Disable history ! in zsh completion scripts.
* Inline single-use functions & variables in ZshCompletionsGenerator.swift.
* Overhaul ZshCompletionsGenerator.swift as [ParsableCommand.Type] extension.
* Move functions in ZshCompletionsGenerator.swift.
Move from ArgumentDefinition extension to [ParsableCommand.Type] extension.
* Move zsh helper functions before command functions to mirror other shells.
* Prefix zsh helper functions with command name to prevent naming clashes.
Function names are globally scoped.
Without namespacing, if 2 programs use different versions of Swift Argument Parser,
one could overwrite the other's different version of the same helper function.
Renamed functions from *_completion to *_complete, as they complete, not return a
completion.
* Separate zsh _arguments flags from specs using :.
* Rename zsh args variable as arg_specs.
* Simplify zshCompletionString(…).
* Allow generating zsh setup scripts for arguments.
* Use zsh array for list completions instead of nested strings.
Allows list completions to contain spaces.
Resolve#726
* Make CompletionShell.format(…) internal instead of public.
* Reword uses of "iff" in completions code.
Redid a comment as a DocC.
* Replace zsh END_MARKER pseudo-completion with a space to ease migration.
Document why & how this pseudo-completion is used.
Do not trim whitespace in testing, as that breaks with the space pseudo-completion.
Testing should be as exact as possible; trimming whitespace makes it less exact.
* Throw error if attempting to generate a zsh completion script for no commands.
Force unwrap first in ZshCompletionsGenerator.swift.
---------
Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com>
Enables and fixes issues with additional platform tests
and the formatter with these additional rules:
- UseLetInEveryBoundCaseVariable
- NeverForceUnwrap
- BeginDocumentationCommentWithOneLineSummary
- ValidateDocumentationComments
- AlwaysUseCamelCase
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.
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)
* Respect the `COLUMNS` and `LINES` environment variables, if set, when determining screen size.
* Add test for COLUMNS environment override
* Make columns test idempotent against there being a COLUMNS value already set in the environment
* Make help tests be more explicit about screen widths.
The `ArgumentParserTestHelpers` module depends on
`ArgumentParserToolInfo` but fails to indicate that dependency. This
was exposed whilst improving static linking for Windows.
- 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.
- 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.
In addition to being useful, this allows us to drop the `@testable`
annotation for the ArgumentParser import in ArgumentParserTestHelpers,
which resolves#463.
- Changes the generate-manual --single-page argument to --multi-page, so
generate-manual with create a single manual page with all subcommand
information by default instead of many distinct files.
- Adds a swift package manager command plugin called
GenerateManualPlugin. The plugin can be invoked from the command line
using `swift package experimental-generate-manual`. The plugin is
prefixed for now with "experimental-" to indicate it is not mature and
may see breaking changes to its CLI and output in the future. The
plugin can be can be used to generate a manual in MDoc syntax for any
swift-argument-parser tool that can be executed via
`tool --experimental-dump-info`.
- The plugin works by converting the `ToolInfoV0` structure from the
`ArgumentParserToolInfo` library into MDoc AST nodes using a custom
(SwiftUI-esk) result builder DSL. The MDoc AST is then lowered to a
string and written to disk.
- The MDoc AST included is not general purpose and doesn't represent the
true language exactly, so it is private to the underlying
`generate-manual` tool. In the future it would be interesting to
finish fleshing out this MDoc library and spin it out, however this is
not a priority.
- Next steps include:
- Improving the command line interface for the plugin.
- Adding support for "extended discussions" to Commands and exposing
this information in manuals.
- Further improve the escaping logic to properly escape MDoc macros
that might happen to appear in user's help strings.
- Ingesting external content a-la swift-docc so the entire tool
documentation does not need to be included in the binary itself.
- Bug fixes and addressing developer/user feedback.
Built with love,
@rauhul
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#>
}
```
- Changes ArgumentVisibility from an enum to a struct. This will allow
ArgumentParser to add cases in the future without breaking clients
that could have been exhaustively switching across all cases. It also
allows us to implement protocol conformances on the internal type and
avoid exposing them on the public type.
- 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`
- 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.
- TestHelpers has a implicit dependency on Foundation through
ArgumentParser, so it needs to link against Foundation
- The find package calls should be REQUIRED and CONFIG so they can take
advantage of CMake configs
* Eliminate #file warnings
* Test source compatibility for property wrappers
This adds compilation tests for all the property wrappers, including
all the various permutations of their default parameter values.
* Add an API for converting an error to an exit code
* Make ExitCode more useful as a value type
* Update tests to use ExitCode values
* Typo fix
* Add a test for ExitCode.isSuccess
* Switch to just using ExitCode for tests
Nate Cook
Ross Goldberg
Rauhul Varma
Gwynne Raskind
Rauhul Varma
Saleem Abdulrasool
Keith Smiley
Jake Petroules
Kotaro Suto
Gwen Mittertreiner
Elliott Williams