Skip to content

Instantly share code, notes, and snippets.

@xinpingwang

xinpingwang/ArgumentParser.swift

Created December 2, 2019 03:18
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save xinpingwang/1c9844fcc452bd62676ce86c865eaa09 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save xinpingwang/1c9844fcc452bd62676ce86c865eaa09 to your computer and use it in GitHub Desktop.
Download ZIP
swift argument parser
Raw
ArgumentParser.swift
// from https://github.com/apple/swift-package-manager/blob/cce860c70c3d96d6b21d5f56c06a7edb53996d90/Sources/TSCUtility/ArgumentParser.swift#L1-L1137
/*
This source file is part of the Swift.org open source project
Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception
See http://swift.org/LICENSE.txt for license information
See http://swift.org/CONTRIBUTORS.txt for Swift project authors
*/
import TSCBasic
import Foundation
import func TSCLibc.exit
/// Errors which may be encountered when running argument parser.
public enum ArgumentParserError: Swift.Error {
/// An unknown option is encountered.
case unknownOption(String, suggestion: String?)
/// The value of an argument is invalid.
case invalidValue(argument: String, error: ArgumentConversionError)
/// Expected a value from the option.
case expectedValue(option: String)
/// An unexpected positional argument encountered.
case unexpectedArgument(String)
/// Expected these positional arguments but not found.
case expectedArguments(ArgumentParser, [String])
/// Expected a single argument but got multiple ones.
case duplicateArgument(String)
}
extension ArgumentParserError: LocalizedError {
public var errorDescription: String? {
return description
}
}
extension ArgumentParserError: CustomStringConvertible {
public var description: String {
switch self {
case .unknownOption(let option, let suggestion):
var desc = "unknown option \(option); use --help to list available options"
if let suggestion = suggestion {
desc += "\nDid you mean \(suggestion)?"
}
return desc
case .invalidValue(let argument, let error):
return "\(error) for argument \(argument); use --help to print usage"
case .expectedValue(let option):
return "option \(option) requires a value; provide a value using '\(option) <value>' or '\(option)=<value>'"
case .unexpectedArgument(let argument):
return "unexpected argument \(argument); use --help to list available arguments"
case .expectedArguments(_, let arguments):
return "expected arguments: \(arguments.joined(separator: ", "))"
case .duplicateArgument(let option):
return "expected single value for argument: \(option)"
}
}
}
/// Conversion errors that can be returned from `ArgumentKind`'s failable
/// initializer.
public enum ArgumentConversionError: Swift.Error {
/// The value is unknown.
case unknown(value: String)
/// The value could not be converted to the target type.
case typeMismatch(value: String, expectedType: Any.Type)
/// Custom reason for conversion failure.
case custom(String)
}
extension ArgumentConversionError: LocalizedError {
public var errorDescription: String? {
return description
}
}
extension ArgumentConversionError: CustomStringConvertible {
public var description: String {
switch self {
case .unknown(let value):
return "unknown value '\(value)'"
case .typeMismatch(let value, let expectedType):
return "'\(value)' is not convertible to \(expectedType)"
case .custom(let reason):
return reason
}
}
}
extension ArgumentConversionError: Equatable {
public static func ==(lhs: ArgumentConversionError, rhs: ArgumentConversionError) -> Bool {
switch (lhs, rhs) {
case (.unknown(let lhsValue), .unknown(let rhsValue)):
return lhsValue == rhsValue
case (.unknown, _):
return false
case (.typeMismatch(let lhsValue, let lhsType), .typeMismatch(let rhsValue, let rhsType)):
return lhsValue == rhsValue && lhsType == rhsType
case (.typeMismatch, _):
return false
case (.custom(let lhsReason), .custom(let rhsReason)):
return lhsReason == rhsReason
case (.custom, _):
return false
}
}
}
/// Different shells for which we can generate shell scripts.
public enum Shell: String, StringEnumArgument {
case bash
case zsh
public static var completion: ShellCompletion = .values([
(bash.rawValue, "generate completion script for Bourne-again shell"),
(zsh.rawValue, "generate completion script for Z shell"),
])
}
/// Various shell completions modes supplied by ArgumentKind.
public enum ShellCompletion {
/// Offers no completions at all; e.g. for a string identifier.
case none
/// No specific completions, will offer tool's completions.
case unspecified
/// Offers filename completions.
case filename
/// Custom function for generating completions. Must be provided in the script's scope.
case function(String)
/// Offers completions from predefined list. A description can be provided which is shown in some shells, like zsh.
case values([(value: String, description: String)])
}
/// A protocol representing the possible types of arguments.
///
/// Conforming to this protocol will qualify the type to act as
/// positional and option arguments in the argument parser.
public protocol ArgumentKind {
/// Throwable convertion initializer.
init(argument: String) throws
/// Type of shell completion to provide for this argument.
static var completion: ShellCompletion { get }
}
// MARK: - ArgumentKind conformance for common types
extension String: ArgumentKind {
public init(argument: String) throws {
self = argument
}
public static let completion: ShellCompletion = .none
}
extension Int: ArgumentKind {
public init(argument: String) throws {
guard let int = Int(argument) else {
throw ArgumentConversionError.typeMismatch(value: argument, expectedType: Int.self)
}
self = int
}
public static let completion: ShellCompletion = .none
}
extension Bool: ArgumentKind {
public init(argument: String) throws {
switch argument {
case "true":
self = true
case "false":
self = false
default:
throw ArgumentConversionError.unknown(value: argument)
}
}
public static var completion: ShellCompletion = .unspecified
}
/// A protocol which implements ArgumentKind for string initializable enums.
///
/// Conforming to this protocol will automatically make an enum with is
/// String initializable conform to ArgumentKind.
public protocol StringEnumArgument: ArgumentKind {
init?(rawValue: String)
}
extension StringEnumArgument {
public init(argument: String) throws {
guard let value = Self.init(rawValue: argument) else {
throw ArgumentConversionError.unknown(value: argument)
}
self = value
}
}
/// An argument representing a path (file / directory).
///
/// The path is resolved in the current working directory.
public struct PathArgument: ArgumentKind {
public let path: AbsolutePath
public init(argument: String) throws {
// FIXME: This should check for invalid paths.
if let cwd = localFileSystem.currentWorkingDirectory {
path = AbsolutePath(argument, relativeTo: cwd)
} else {
path = try AbsolutePath(validating: argument)
}
}
public static var completion: ShellCompletion = .filename
}
/// An enum representing the strategy to parse argument values.
public enum ArrayParsingStrategy {
/// Will parse only the next argument and append all values together: `-Xcc -Lfoo -Xcc -Lbar`.
case oneByOne
/// Will parse all values up to the next option argument: `--files file1 file2 --verbosity 1`.
case upToNextOption
/// Will parse all remaining arguments, usually for executable commands: `swift run exe --option 1`.
case remaining
/// Function that parses the current arguments iterator based on the strategy
/// and returns the parsed values.
func parse(_ kind: ArgumentKind.Type, with parser: inout ArgumentParserProtocol) throws -> [ArgumentKind] {
var values: [ArgumentKind] = []
switch self {
case .oneByOne:
guard let nextArgument = parser.next() else {
throw ArgumentParserError.expectedValue(option: parser.currentArgument)
}
try values.append(kind.init(argument: nextArgument))
case .upToNextOption:
/// Iterate over arguments until the end or an optional argument
while let nextArgument = parser.peek(), isPositional(argument: nextArgument) {
/// We need to call next to consume the argument. The peek above did not.
_ = parser.next()
try values.append(kind.init(argument: nextArgument))
}
case .remaining:
while let nextArgument = parser.next() {
try values.append(kind.init(argument: nextArgument))
}
}
return values
}
}
/// A protocol representing positional or options argument.
protocol ArgumentProtocol: Hashable {
// FIXME: This should be constrained to ArgumentKind but Array can't conform
// to it: `extension of type 'Array' with constraints cannot have an
// inheritance clause`.
//
/// The argument kind of this argument for eg String, Bool etc.
associatedtype ArgumentKindTy
/// Name of the argument which will be parsed by the parser.
var name: String { get }
/// Short name of the argument, this is usually used in options arguments
/// for a short names for e.g: `--help` -> `-h`.
var shortName: String? { get }
/// The parsing strategy to adopt when parsing values.
var strategy: ArrayParsingStrategy { get }
/// Defines is the argument is optional
var isOptional: Bool { get }
/// The usage text associated with this argument. Used to generate complete help string.
var usage: String? { get }
/// The shell completions to offer as values for this argument.
var completion: ShellCompletion { get }
// FIXME: Because `ArgumentKindTy`` can't conform to `ArgumentKind`, this
// function has to be provided a kind (which will be different from
// ArgumentKindTy for arrays). Once the generics feature exists we can
// improve this API.
//
/// Parses and returns the argument values from the parser.
func parse(_ kind: ArgumentKind.Type, with parser: inout ArgumentParserProtocol) throws -> [ArgumentKind]
}
extension ArgumentProtocol {
// MARK: - Conformance for Hashable
public func hash(into hasher: inout Hasher) {
return hasher.combine(name)
}
public static func == (_ lhs: Self, _ rhs: Self) -> Bool {
return lhs.name == rhs.name && lhs.usage == rhs.usage
}
}
/// Returns true if the given argument does not starts with '-' i.e. it is
/// a positional argument, otherwise it is an options argument.
fileprivate func isPositional(argument: String) -> Bool {
return !argument.hasPrefix("-")
}
/// A class representing option arguments. These are optional arguments which may
/// or may not be provided in the command line. They are always prefixed by their
/// name. For e.g. --verbosity true.
public final class OptionArgument<Kind>: ArgumentProtocol {
typealias ArgumentKindTy = Kind
let name: String
let shortName: String?
// Option arguments are always optional.
var isOptional: Bool { return true }
let strategy: ArrayParsingStrategy
let usage: String?
let completion: ShellCompletion
init(name: String, shortName: String?, strategy: ArrayParsingStrategy, usage: String?, completion: ShellCompletion) {
precondition(!isPositional(argument: name))
self.name = name
self.shortName = shortName
self.strategy = strategy
self.usage = usage
self.completion = completion
}
func parse(_ kind: ArgumentKind.Type, with parser: inout ArgumentParserProtocol) throws -> [ArgumentKind] {
do {
return try _parse(kind, with: &parser)
} catch let conversionError as ArgumentConversionError {
throw ArgumentParserError.invalidValue(argument: name, error: conversionError)
}
}
func _parse(_ kind: ArgumentKind.Type, with parser: inout ArgumentParserProtocol) throws -> [ArgumentKind] {
// When we have an associated value, we ignore the strategy and only
// parse that value.
if let associatedArgument = parser.associatedArgumentValue {
return try [kind.init(argument: associatedArgument)]
}
// As a special case, Bool options don't consume arguments.
if kind == Bool.self && strategy == .oneByOne {
return [true]
}
let values = try strategy.parse(kind, with: &parser)
guard !values.isEmpty else {
throw ArgumentParserError.expectedValue(option: name)
}
return values
}
}
/// A class representing positional arguments. These arguments must be present
/// and in the same order as they are added in the parser.
public final class PositionalArgument<Kind>: ArgumentProtocol {
typealias ArgumentKindTy = Kind
let name: String
// Postional arguments don't need short names.
var shortName: String? { return nil }
let strategy: ArrayParsingStrategy
let isOptional: Bool
let usage: String?
let completion: ShellCompletion
init(name: String, strategy: ArrayParsingStrategy, optional: Bool, usage: String?, completion: ShellCompletion) {
precondition(isPositional(argument: name))
self.name = name
self.strategy = strategy
self.isOptional = optional
self.usage = usage
self.completion = completion
}
func parse(_ kind: ArgumentKind.Type, with parser: inout ArgumentParserProtocol) throws -> [ArgumentKind] {
do {
return try _parse(kind, with: &parser)
} catch let conversionError as ArgumentConversionError {
throw ArgumentParserError.invalidValue(argument: name, error: conversionError)
}
}
func _parse(_ kind: ArgumentKind.Type, with parser: inout ArgumentParserProtocol) throws -> [ArgumentKind] {
let value = try kind.init(argument: parser.currentArgument)
var values = [value]
switch strategy {
case .oneByOne:
// We shouldn't apply the strategy with `.oneByOne` because we
// already have one, the parsed `parser.currentArgument`.
break
case .upToNextOption, .remaining:
try values.append(contentsOf: strategy.parse(kind, with: &parser))
}
return values
}
}
/// A type-erased argument.
///
/// Note: Only used for argument parsing purpose.
final class AnyArgument: ArgumentProtocol, CustomStringConvertible {
typealias ArgumentKindTy = Any
let name: String
let shortName: String?
let strategy: ArrayParsingStrategy
let isOptional: Bool
let usage: String?
let completion: ShellCompletion
/// The argument kind this holds, used while initializing that argument.
let kind: ArgumentKind.Type
/// True if the argument kind is of array type.
let isArray: Bool
/// A type-erased wrapper around the argument's `parse` function.
private let parseClosure: (ArgumentKind.Type, inout ArgumentParserProtocol) throws -> [ArgumentKind]
init<T: ArgumentProtocol>(_ argument: T) {
self.kind = T.ArgumentKindTy.self as! ArgumentKind.Type
self.name = argument.name
self.shortName = argument.shortName
self.strategy = argument.strategy
self.isOptional = argument.isOptional
self.usage = argument.usage
self.completion = argument.completion
self.parseClosure = argument.parse(_:with:)
isArray = false
}
/// Initializer for array arguments.
init<T: ArgumentProtocol>(_ argument: T) where T.ArgumentKindTy: Sequence {
self.kind = T.ArgumentKindTy.Element.self as! ArgumentKind.Type
self.name = argument.name
self.shortName = argument.shortName
self.strategy = argument.strategy
self.isOptional = argument.isOptional
self.usage = argument.usage
self.completion = argument.completion
self.parseClosure = argument.parse(_:with:)
isArray = true
}
var description: String {
return "Argument(\(name))"
}
func parse(_ kind: ArgumentKind.Type, with parser: inout ArgumentParserProtocol) throws -> [ArgumentKind] {
return try self.parseClosure(kind, &parser)
}
func parse(with parser: inout ArgumentParserProtocol) throws -> [ArgumentKind] {
return try self.parseClosure(self.kind, &parser)
}
}
// FIXME: We probably don't need this protocol anymore and should convert this to a class.
//
/// Argument parser protocol passed in initializers of ArgumentKind to manipulate
/// parser as needed by the argument.
public protocol ArgumentParserProtocol {
/// The current argument being parsed.
var currentArgument: String { get }
/// The associated value in a `--foo=bar` style argument.
var associatedArgumentValue: String? { get }
/// Provides (consumes) and returns the next argument. Returns `nil` if there are not arguments left.
mutating func next() -> String?
/// Peek at the next argument without consuming it.
func peek() -> String?
}
/// Argument parser struct responsible to parse the provided array of arguments
/// and return the parsed result.
public final class ArgumentParser {
/// A class representing result of the parsed arguments.
public class Result: CustomStringConvertible {
/// Internal representation of arguments mapped to their values.
private var results = [String: Any]()
/// Result of the parent parent parser, if any.
private var parentResult: Result?
/// Reference to the parser this result belongs to.
private let parser: ArgumentParser
/// The subparser command chosen.
fileprivate var subparser: String?
/// Create a result with a parser and parent result.
init(parser: ArgumentParser, parent: Result?) {
self.parser = parser
self.parentResult = parent
}
/// Adds a result.
///
/// - Parameters:
/// - values: The associated values of the argument.
/// - argument: The argument for which this result is being added.
/// - Note:
/// While it may seem more fragile to use an array as input in the
/// case of single-value arguments, this design choice allows major
/// simplifications in the parsing code.
fileprivate func add(_ values: [ArgumentKind], for argument: AnyArgument) throws {
if argument.isArray {
var array = results[argument.name] as? [ArgumentKind] ?? []
array.append(contentsOf: values)
results[argument.name] = array
} else {
// We expect only one value for non-array arguments.
guard let value = values.spm_only else {
assertionFailure()
return
}
guard results[argument.name] == nil else {
throw ArgumentParserError.duplicateArgument(argument.name)
}
results[argument.name] = value
}
}
/// Get an option argument's value from the results.
///
/// Since the options are optional, their result may or may not be present.
public func get<T>(_ argument: OptionArgument<T>) -> T? {
return (results[argument.name] as? T) ?? parentResult?.get(argument)
}
/// Array variant for option argument's get(_:).
public func get<T>(_ argument: OptionArgument<[T]>) -> [T]? {
return (results[argument.name] as? [T]) ?? parentResult?.get(argument)
}
/// Get a positional argument's value.
public func get<T>(_ argument: PositionalArgument<T>) -> T? {
return results[argument.name] as? T
}
/// Array variant for positional argument's get(_:).
public func get<T>(_ argument: PositionalArgument<[T]>) -> [T]? {
return results[argument.name] as? [T]
}
/// Get an argument's value using its name.
/// - throws: An ArgumentParserError.invalidValue error if the parsed argument does not match the expected type.
public func get<T>(_ name: String) throws -> T? {
guard let value = results[name] else {
// if we have a parent and this is an option argument, look in the parent result
if let parentResult = parentResult, name.hasPrefix("-") {
return try parentResult.get(name)
} else {
return nil
}
}
guard let typedValue = value as? T else {
throw ArgumentParserError.invalidValue(argument: name, error: .typeMismatch(value: String(describing: value), expectedType: T.self))
}
return typedValue
}
/// Returns true if the given arg is present in the results.
public func exists(arg: String) -> Bool {
return results[arg] != nil
}
/// Get the subparser which was chosen for the given parser.
public func subparser(_ parser: ArgumentParser) -> String? {
if parser === self.parser {
return subparser
}
return parentResult?.subparser(parser)
}
public var description: String {
var description = "ArgParseResult(\(results))"
if let parent = parentResult {
description += " -> " + parent.description
}
return description
}
}
/// The mapping of subparsers to their subcommand.
private(set) var subparsers: [String: ArgumentParser] = [:]
/// List of arguments added to this parser.
private(set) var optionArguments: [AnyArgument] = []
private(set) var positionalArguments: [AnyArgument] = []
// If provided, will be substituted instead of arg0 in usage text.
let commandName: String?
/// Usage string of this parser.
let usage: String
/// Overview text of this parser.
let overview: String
/// See more text of this parser.
let seeAlso: String?
/// If this parser is a subparser.
private let isSubparser: Bool
/// Boolean specifying if the parser can accept further positional
/// arguments (false if it already has a positional argument with
/// `isOptional` set to `true` or strategy set to `.remaining`).
private var canAcceptPositionalArguments: Bool = true
/// Create an argument parser.
///
/// - Parameters:
/// - commandName: If provided, this will be substitued in "usage" line of the generated usage text.
/// Otherwise, first command line argument will be used.
/// - usage: The "usage" line of the generated usage text.
/// - overview: The "overview" line of the generated usage text.
/// - seeAlso: The "see also" line of generated usage text.
public init(commandName: String? = nil, usage: String, overview: String, seeAlso: String? = nil) {
self.isSubparser = false
self.commandName = commandName
self.usage = usage
self.overview = overview
self.seeAlso = seeAlso
}
/// Create a subparser with its help text.
private init(subparser commandName: String, usage: String, overview: String) {
self.isSubparser = true
self.commandName = commandName
self.usage = usage
self.overview = overview
self.seeAlso = nil
}
/// Adds an option to the parser.
public func add<T: ArgumentKind>(
option: String,
shortName: String? = nil,
kind: T.Type = T.self,
usage: String? = nil,
completion: ShellCompletion? = nil
) -> OptionArgument<T> {
assert(!optionArguments.contains(where: { $0.name == option }), "Can not define an option twice")
let argument = OptionArgument<T>(name: option, shortName: shortName, strategy: .oneByOne, usage: usage, completion: completion ?? T.completion)
optionArguments.append(AnyArgument(argument))
return argument
}
/// Adds an array argument type.
public func add<T: ArgumentKind>(
option: String,
shortName: String? = nil,
kind: [T].Type = [T].self,
strategy: ArrayParsingStrategy = .upToNextOption,
usage: String? = nil,
completion: ShellCompletion? = nil
) -> OptionArgument<[T]> {
assert(!optionArguments.contains(where: { $0.name == option }), "Can not define an option twice")
let argument = OptionArgument<[T]>(name: option, shortName: shortName, strategy: strategy, usage: usage, completion: completion ?? T.completion)
optionArguments.append(AnyArgument(argument))
return argument
}
/// Adds an argument to the parser.
///
/// Note: Only one positional argument is allowed if optional setting is enabled.
public func add<T: ArgumentKind>(
positional: String,
kind: T.Type = T.self,
optional: Bool = false,
usage: String? = nil,
completion: ShellCompletion? = nil
) -> PositionalArgument<T> {
precondition(subparsers.isEmpty, "Positional arguments are not supported with subparsers")
precondition(canAcceptPositionalArguments, "Can not accept more positional arguments")
if optional {
canAcceptPositionalArguments = false
}
let argument = PositionalArgument<T>(name: positional, strategy: .oneByOne, optional: optional, usage: usage, completion: completion ?? T.completion)
positionalArguments.append(AnyArgument(argument))
return argument
}
/// Adds an argument to the parser.
///
/// Note: Only one multiple-value positional argument is allowed.
public func add<T: ArgumentKind>(
positional: String,
kind: [T].Type = [T].self,
optional: Bool = false,
strategy: ArrayParsingStrategy = .upToNextOption,
usage: String? = nil,
completion: ShellCompletion? = nil
) -> PositionalArgument<[T]> {
precondition(subparsers.isEmpty, "Positional arguments are not supported with subparsers")
precondition(canAcceptPositionalArguments, "Can not accept more positional arguments")
if optional || strategy == .remaining {
canAcceptPositionalArguments = false
}
let argument = PositionalArgument<[T]>(name: positional, strategy: strategy, optional: optional, usage: usage, completion: completion ?? T.completion)
positionalArguments.append(AnyArgument(argument))
return argument
}
/// Add a parser with a subcommand name and its corresponding overview.
@discardableResult
public func add(subparser command: String, usage: String = "", overview: String) -> ArgumentParser {
precondition(positionalArguments.isEmpty, "Subparsers are not supported with positional arguments")
let parser = ArgumentParser(subparser: command, usage: usage, overview: overview)
subparsers[command] = parser
return parser
}
// MARK: - Parsing
/// A wrapper struct to pass to the ArgumentKind initializers.
struct Parser: ArgumentParserProtocol {
let currentArgument: String
private(set) var associatedArgumentValue: String?
/// The iterator used to iterate arguments.
fileprivate var argumentsIterator: IndexingIterator<[String]>
init(associatedArgumentValue: String?, argumentsIterator: IndexingIterator<[String]>, currentArgument: String) {
self.associatedArgumentValue = associatedArgumentValue
self.argumentsIterator = argumentsIterator
self.currentArgument = currentArgument
}
mutating func next() -> String? {
return argumentsIterator.next()
}
func peek() -> String? {
var iteratorCopy = argumentsIterator
let nextArgument = iteratorCopy.next()
return nextArgument
}
}
/// Parses the provided array and return the result.
public func parse(_ arguments: [String] = []) throws -> Result {
return try parse(arguments, parent: nil)
}
private func parse(_ arguments: [String] = [], parent: Result?) throws -> Result {
let result = Result(parser: self, parent: parent)
// Create options map to quickly look up the arguments.
let optionsTuple = optionArguments.flatMap({ option -> [(String, AnyArgument)] in
var result = [(option.name, option)]
// Add the short names too, if we have them.
if let shortName = option.shortName {
result += [(shortName, option)]
}
return result
})
let optionsMap = Dictionary(uniqueKeysWithValues: optionsTuple)
// Create iterators.
var positionalArgumentIterator = positionalArguments.makeIterator()
var argumentsIterator = arguments.makeIterator()
while let argumentString = argumentsIterator.next() {
let argument: AnyArgument
let parser: Parser
// If argument is help then just print usage and exit.
if argumentString == "-h" || argumentString == "-help" || argumentString == "--help" {
printUsage(on: stdoutStream)
exit(0)
} else if isPositional(argument: argumentString) {
/// If this parser has subparsers, we allow only one positional argument which is the subparser command.
if !subparsers.isEmpty {
// Make sure this argument has a subparser.
guard let subparser = subparsers[argumentString] else {
throw ArgumentParserError.expectedArguments(self, Array(subparsers.keys))
}
// Save which subparser was chosen.
result.subparser = argumentString
// Parse reset of the arguments with the subparser.
return try subparser.parse(Array(argumentsIterator), parent: result)
}
// Get the next positional argument we are expecting.
guard let positionalArgument = positionalArgumentIterator.next() else {
throw ArgumentParserError.unexpectedArgument(argumentString)
}
argument = positionalArgument
parser = Parser(
associatedArgumentValue: nil,
argumentsIterator: argumentsIterator,
currentArgument: argumentString)
} else {
let (argumentString, value) = argumentString.spm_split(around: "=")
// Get the corresponding option for the option argument.
guard let optionArgument = optionsMap[argumentString] else {
let suggestion = bestMatch(for: argumentString, from: Array(optionsMap.keys))
throw ArgumentParserError.unknownOption(argumentString, suggestion: suggestion)
}
argument = optionArgument
parser = Parser(
associatedArgumentValue: value,
argumentsIterator: argumentsIterator,
currentArgument: argumentString)
}
// Update results.
var parserProtocol = parser as ArgumentParserProtocol
let values = try argument.parse(with: &parserProtocol)
try result.add(values, for: argument)
// Restore the argument iterator state.
argumentsIterator = (parserProtocol as! Parser).argumentsIterator
}
// Report if there are any non-optional positional arguments left which were not present in the arguments.
let leftOverArguments = Array(positionalArgumentIterator)
if leftOverArguments.contains(where: { !$0.isOptional }) {
throw ArgumentParserError.expectedArguments(self, leftOverArguments.map({ $0.name }))
}
return result
}
/// Prints usage text for this parser on the provided stream.
public func printUsage(on stream: OutputByteStream) {
/// Space settings.
let maxWidthDefault = 24
let padding = 2
let maxWidth: Int
// Determine the max width based on argument length or choose the
// default width if max width is longer than the default width.
if let maxArgument = (positionalArguments + optionArguments).map({
[$0.name, $0.shortName].compactMap({ $0 }).joined(separator: ", ").count
}).max(), maxArgument < maxWidthDefault {
maxWidth = maxArgument + padding + 1
} else {
maxWidth = maxWidthDefault
}
/// Prints an argument on a stream if it has usage.
func print(formatted argument: String, usage: String, on stream: OutputByteStream) {
// Start with a new line and add some padding.
stream <<< "\n" <<< Format.asRepeating(string: " ", count: padding)
let count = argument.count
// If the argument is longer than the max width, print the usage
// on a new line. Otherwise, print the usage on the same line.
if count >= maxWidth - padding {
stream <<< argument <<< "\n"
// Align full width because usage is to be printed on a new line.
stream <<< Format.asRepeating(string: " ", count: maxWidth + padding)
} else {
stream <<< argument
// Align to the remaining empty space on the line.
stream <<< Format.asRepeating(string: " ", count: maxWidth - count)
}
stream <<< usage
}
stream <<< "OVERVIEW: " <<< overview
if !usage.isEmpty {
stream <<< "\n\n"
// Get the binary name from command line arguments.
let defaultCommandName = CommandLine.arguments[0].components(separatedBy: "/").last!
stream <<< "USAGE: " <<< (commandName ?? defaultCommandName) <<< " " <<< usage
}
if optionArguments.count > 0 {
stream <<< "\n\n"
stream <<< "OPTIONS:"
for argument in optionArguments.lazy.sorted(by: { $0.name < $1.name }) {
guard let usage = argument.usage else { continue }
// Create name with its shortname, if available.
let name = [argument.name, argument.shortName].compactMap({ $0 }).joined(separator: ", ")
print(formatted: name, usage: usage, on: stream)
}
// Print help option, if this is a top level command.
if !isSubparser {
print(formatted: "--help", usage: "Display available options", on: stream)
}
}
if subparsers.keys.count > 0 {
stream <<< "\n\n"
stream <<< "SUBCOMMANDS:"
for (command, parser) in subparsers.sorted(by: { $0.key < $1.key }) {
// Special case for hidden subcommands.
guard !parser.overview.isEmpty else { continue }
print(formatted: command, usage: parser.overview, on: stream)
}
}
if positionalArguments.count > 0 {
stream <<< "\n\n"
stream <<< "POSITIONAL ARGUMENTS:"
for argument in positionalArguments {
guard let usage = argument.usage else { continue }
print(formatted: argument.name, usage: usage, on: stream)
}
}
if let seeAlso = seeAlso {
stream <<< "\n\n"
stream <<< "SEE ALSO: \(seeAlso)"
}
stream <<< "\n"
stream.flush()
}
}
/// A class to bind ArgumentParser's arguments to an option structure.
public final class ArgumentBinder<Options> {
/// The signature of body closure.
private typealias BodyClosure = (inout Options, ArgumentParser.Result) throws -> Void
/// This array holds the closures which should be executed to fill the options structure.
private var bodies = [BodyClosure]()
/// Create a binder.
public init() {
}
/// Bind an option argument.
public func bind<T>(
option: OptionArgument<T>,
to body: @escaping (inout Options, T) throws -> Void
) {
addBody {
guard let result = $1.get(option) else { return }
try body(&$0, result)
}
}
/// Bind an array option argument.
public func bindArray<T>(
option: OptionArgument<[T]>,
to body: @escaping (inout Options, [T]) throws -> Void
) {
addBody {
guard let result = $1.get(option) else { return }
try body(&$0, result)
}
}
/// Bind a positional argument.
public func bind<T>(
positional: PositionalArgument<T>,
to body: @escaping (inout Options, T) throws -> Void
) {
addBody {
// All the positional argument will always be present.
guard let result = $1.get(positional) else { return }
try body(&$0, result)
}
}
/// Bind an array positional argument.
public func bindArray<T>(
positional: PositionalArgument<[T]>,
to body: @escaping (inout Options, [T]) throws -> Void
) {
addBody {
// All the positional argument will always be present.
guard let result = $1.get(positional) else { return }
try body(&$0, result)
}
}
/// Bind two positional arguments.
public func bindPositional<T, U>(
_ first: PositionalArgument<T>,
_ second: PositionalArgument<U>,
to body: @escaping (inout Options, T, U) throws -> Void
) {
addBody {
// All the positional arguments will always be present.
guard let first = $1.get(first) else { return }
guard let second = $1.get(second) else { return }
try body(&$0, first, second)
}
}
/// Bind three positional arguments.
public func bindPositional<T, U, V>(
_ first: PositionalArgument<T>,
_ second: PositionalArgument<U>,
_ third: PositionalArgument<V>,
to body: @escaping (inout Options, T, U, V) throws -> Void
) {
addBody {
// All the positional arguments will always be present.
guard let first = $1.get(first) else { return }
guard let second = $1.get(second) else { return }
guard let third = $1.get(third) else { return }
try body(&$0, first, second, third)
}
}
/// Bind two options.
public func bind<T, U>(
_ first: OptionArgument<T>,
_ second: OptionArgument<U>,
to body: @escaping (inout Options, T?, U?) throws -> Void
) {
addBody {
try body(&$0, $1.get(first), $1.get(second))
}
}
/// Bind three options.
public func bind<T, U, V>(
_ first: OptionArgument<T>,
_ second: OptionArgument<U>,
_ third: OptionArgument<V>,
to body: @escaping (inout Options, T?, U?, V?) throws -> Void
) {
addBody {
try body(&$0, $1.get(first), $1.get(second), $1.get(third))
}
}
/// Bind two array options.
public func bindArray<T, U>(
_ first: OptionArgument<[T]>,
_ second: OptionArgument<[U]>,
to body: @escaping (inout Options, [T], [U]) throws -> Void
) {
addBody {
try body(&$0, $1.get(first) ?? [], $1.get(second) ?? [])
}
}
/// Add three array option and call the final closure with their values.
public func bindArray<T, U, V>(
_ first: OptionArgument<[T]>,
_ second: OptionArgument<[U]>,
_ third: OptionArgument<[V]>,
to body: @escaping (inout Options, [T], [U], [V]) throws -> Void
) {
addBody {
try body(&$0, $1.get(first) ?? [], $1.get(second) ?? [], $1.get(third) ?? [])
}
}
/// Bind a subparser.
public func bind(
parser: ArgumentParser,
to body: @escaping (inout Options, String) throws -> Void
) {
addBody {
guard let result = $1.subparser(parser) else { return }
try body(&$0, result)
}
}
/// Appends a closure to bodies array.
private func addBody(_ body: @escaping BodyClosure) {
bodies.append(body)
}
/// Fill the result into the options structure,
/// throwing if one of the user-provided binder function throws.
public func fill(parseResult result: ArgumentParser.Result, into options: inout Options) throws {
try bodies.forEach { try $0(&options, result) }
}
/// Fill the result into the options structure.
@available(*, deprecated, renamed: "fill(parseResult:into:)")
public func fill(_ result: ArgumentParser.Result, into options: inout Options) {
try! fill(parseResult: result, into: &options)
}
}
Raw
ArgumentParserShellCompletion.swift
// from https://github.com/apple/swift-package-manager/blob/cce860c70c3d96d6b21d5f56c06a7edb53996d90/Sources/TSCUtility/ArgumentParserShellCompletion.swift#L1-L292
/*
This source file is part of the Swift.org open source project
Copyright 2016 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception
See http://swift.org/LICENSE.txt for license information
See http://swift.org/CONTRIBUTORS.txt for Swift project authors
*/
import Foundation
import TSCBasic
fileprivate let removeDefaultRegex = try! NSRegularExpression(pattern: "\\[default: .+?\\]", options: [])
extension ArgumentParser {
/// Generates part of a completion script for the given shell.
///
/// These aren't complete scripts, as some setup code is required. See
/// `Utilities/bash/completions` and `Utilities/zsh/_swift` for example
/// usage.
public func generateCompletionScript(for shell: Shell, on stream: OutputByteStream) {
guard let commandName = commandName else { abort() }
let name = "_\(commandName.replacingOccurrences(of: " ", with: "_"))"
switch shell {
case .bash:
// Information about how to include this function in a completion script.
stream <<< """
# Generates completions for \(commandName)
#
# Parameters
# - the start position of this parser; set to 1 if unknown
"""
generateBashSwiftTool(name: name, on: stream)
case .zsh:
// Information about how to include this function in a completion script.
stream <<< """
# Generates completions for \(commandName)
#
# In the final compdef file, set the following file header:
#
# #compdef \(name)
# local context state state_descr line
# typeset -A opt_args
"""
generateZshSwiftTool(name: name, on: stream)
}
stream.flush()
}
// MARK: - BASH
fileprivate func generateBashSwiftTool(name: String, on stream: OutputByteStream) {
stream <<< """
function \(name)
{
"""
// Suggest positional arguments. Beware that this forces positional arguments
// before options. For example [swift package pin <TAB>] expects a name as the
// first argument. So no options (like --all) will be suggested. However after
// the positional argument; [swift package pin MyPackage <TAB>] will list them
// just fine.
for (index, argument) in positionalArguments.enumerated() {
stream <<< " if [[ $COMP_CWORD == $(($1+\(index))) ]]; then\n"
generateBashCompletion(argument, on: stream)
stream <<< " fi\n"
}
// Suggest subparsers in addition to other arguments.
stream <<< " if [[ $COMP_CWORD == $1 ]]; then\n"
var completions = [String]()
for (subName, _) in subparsers {
completions.append(subName)
}
for option in optionArguments {
completions.append(option.name)
if let shortName = option.shortName {
completions.append(shortName)
}
}
stream <<< """
COMPREPLY=( $(compgen -W "\(completions.joined(separator: " "))" -- $cur) )
return
fi
"""
// Suggest completions based on previous word.
generateBashCasePrev(on: stream)
// Forward completions to subparsers.
stream <<< " case ${COMP_WORDS[$1]} in\n"
for (subName, _) in subparsers {
stream <<< """
(\(subName))
\(name)_\(subName) $(($1+1))
return
;;
"""
}
stream <<< " esac\n"
// In all other cases (no positional / previous / subparser), suggest
// this parsers completions.
stream <<< """
COMPREPLY=( $(compgen -W "\(completions.joined(separator: " "))" -- $cur) )
}
"""
for (subName, subParser) in subparsers {
subParser.generateBashSwiftTool(name: "\(name)_\(subName)", on: stream)
}
}
fileprivate func generateBashCasePrev(on stream: OutputByteStream) {
stream <<< " case $prev in\n"
for argument in optionArguments {
let flags = [argument.name] + (argument.shortName.map({ [$0] }) ?? [])
stream <<< " (\(flags.joined(separator: "|")))\n"
generateBashCompletion(argument, on: stream)
stream <<< " ;;\n"
}
stream <<< " esac\n"
}
fileprivate func generateBashCompletion(_ argument: AnyArgument, on stream: OutputByteStream) {
switch argument.completion {
case .none:
// return; no value to complete
stream <<< " return\n"
case .unspecified:
break
case .values(let values):
let x = values.map({ $0.value }).joined(separator: " ")
stream <<< """
COMPREPLY=( $(compgen -W "\(x)" -- $cur) )
return
"""
case .filename:
stream <<< """
_filedir
return
"""
case .function(let name):
stream <<< """
\(name)
return
"""
}
}
// MARK: - ZSH
private func generateZshSwiftTool(name: String, on stream: OutputByteStream) {
// Completions are provided by zsh's _arguments builtin.
stream <<< """
\(name)() {
arguments=(
"""
for argument in positionalArguments {
stream <<< " \""
generateZshCompletion(argument, on: stream)
stream <<< "\"\n"
}
for argument in optionArguments {
generateZshArgument(argument, on: stream)
}
// Use a simple state-machine when dealing with sub parsers.
if subparsers.count > 0 {
stream <<< """
'(-): :->command'
'(-)*:: :->arg'
"""
}
stream <<< """
)
_arguments $arguments && return
"""
// Handle the state set by the state machine.
if subparsers.count > 0 {
stream <<< """
case $state in
(command)
local modes
modes=(
"""
for (subName, subParser) in subparsers {
stream <<< """
'\(subName):\(subParser.overview)'
"""
}
stream <<< """
)
_describe "mode" modes
;;
(arg)
case ${words[1]} in
"""
for (subName, _) in subparsers {
stream <<< """
(\(subName))
\(name)_\(subName)
;;
"""
}
stream <<< """
esac
;;
esac
"""
}
stream <<< "}\n\n"
for (subName, subParser) in subparsers {
subParser.generateZshSwiftTool(name: "\(name)_\(subName)", on: stream)
}
}
/// Generates an option argument for `_arguments`, complete with description and completion values.
fileprivate func generateZshArgument(_ argument: AnyArgument, on stream: OutputByteStream) {
stream <<< " \""
switch argument.shortName {
case .none: stream <<< "\(argument.name)"
case let shortName?: stream <<< "(\(argument.name) \(shortName))\"{\(argument.name),\(shortName)}\""
}
let description = removeDefaultRegex
.replace(in: argument.usage ?? "", with: "")
.replacingOccurrences(of: "\"", with: "\\\"")
.replacingOccurrences(of: "[", with: "\\[")
.replacingOccurrences(of: "]", with: "\\]")
stream <<< "[\(description)]"
generateZshCompletion(argument, on: stream)
stream <<< "\"\n"
}
/// Generates completion values, as part of an item for `_arguments`.
fileprivate func generateZshCompletion(_ argument: AnyArgument, on stream: OutputByteStream) {
let message = removeDefaultRegex
.replace(in: argument.usage ?? " ", with: "")
.replacingOccurrences(of: "\"", with: "\\\"")
switch argument.completion {
case .none: stream <<< ":\(message): "
case .unspecified: break
case .filename: stream <<< ":\(message):_files"
case let .values(values):
stream <<< ": :{_values ''"
for (value, description) in values {
stream <<< " '\(value)[\(description)]'"
}
stream <<< "}"
case .function(let name): stream <<< ":\(message):\(name)"
}
}
}
fileprivate extension NSRegularExpression {
func replace(`in` original: String, with replacement: String) -> String {
return stringByReplacingMatches(
in: original,
options: [],
range: NSRange(location: 0, length: original.count),
withTemplate: replacement)
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment