* 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.
- 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#>
}
```
- 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.
Before version 5.2, target names need to be unique in the package
dependency graph. TestHelpers causes a conflict with SE0270_RangeSet,
and possibly others, so renaming. Fixes#18.
Nate Cook
Rauhul Varma
Elliott Williams