ArgumentParserKit
Type-safe and easy way for parsing command line arguments in your macOS command line tools
I think the ArgumentParser Apple hides inside their Swift Package Manager deserves more. That's why I extracted the relevant source code into a Pod to make it available to a larger audience. The ArgumentParser offers a type-safe and easy way to parse arguments given via the command line to your program. Keep in mind that Apple itself makes clear that you use this private and maybe unstable API at your own risk.
The ArgumentParser
has out of the box support for the --help
or -h
argument. He prints out a beautiful overview of your command line tool usage.
๐ป Welcome to this awesome Command Line Tool ๐
OVERVIEW: Does amazing things for you
USAGE: CommandLineTool <options>
OPTIONS:
--name, -n A name
--help, -h Display available options
Example
do {
// The first argument is always the executable, drop it
let arguments = Array(CommandLine.arguments.dropFirst())
let parser = ArgumentParser(usage: "<options>", overview: "A description")
let nameOption = parser.add(option: "--name", shortName: "-n", kind: String.self, usage: "A name")
let parsedArguments = try parser.parse(arguments)
let name = parsedArguments.get(nameOption)
print(name)
} catch {
// handle parsing error
}
How to use
The parsed argument values are only four steps away from you if you use the ArgumentParser
.
1. Create a parser
Use the initializer of the ArgumentParser
class.
/// 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.
///
init(commandName: String? = nil, usage: String, overview: String, seeAlso: String? = nil)
2. Tell the parser about the arguments to parse
Tell the parser which arguments (for the ArgumentParser
an argument is an instance of OptionArgument
) your command line tool offers via the add
-method.
/// Add an argument to a parser.
///
/// - Parameters:
/// - option: The name of the argument, for example "--name".
/// - shortName: The shortened name of the argument, e.g. "-n".
/// - kind: The concrete type of the argument.
/// - usage: The description of the argument.
///
func add<T: ArgumentKind>(option: String, shortName: String? = nil, kind: T.Type, usage: String? = nil)
3. Parse arguments passed to your command line tool
Pass your arguments array to the parse
-method of your parser instance.
/// Parses the provided array and returns the result.
///
func parse(_ arguments: [String] = []) throws -> Result
4. Get the values of the passed arguments
After parsing you can access the argument values calling the get
-method on the Result
type returned by the parse
-method of the ArgumentParser
. Simply pass in the OptionArgument
returned by the add
-method of the ArgumentParser
.
/// Get an option argument's value from the results.
///
/// Since the options are optional, their result may or may not be present.
///
func get<T>(_ argument: OptionArgument<T>) -> T?
Requirements
Deployment target has to be greater than or equal to macOS 10.10.
Installation
Cocoapods
ArgumentParserKit is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod 'ArgumentParserKit'
Swift package manager
Add this Swift package as a dependency to your Package.swift
.package(url: "https://github.com/crelies/ArgumentParserKit.git", from: "1.0.0")
Further resources
Take a look at Parsing Command Line Arguments using the internal ArgumentParser
inside of the Swift Package Manager
Author
Apple Inc. and the Swift project authors
License
ArgumentParserKit is available under the Apache License v2.0 with Runtime Library Exception. See the LICENSE file for more info.