This is a library supporting the development of command-line tools in the programming language Swift on macOS. It also compiles under Linux. The library provides the following functionality:
- Management of command-line arguments,
- Usage of escape sequences on terminals, and
- Reading strings on terminals using a lineread-inspired implementation based on the library Linenoise-Swift, but supporting unicode input, multiple lines, and styled text.
CommandLineKit handles command-line arguments with the following protocol:
- A new Flags object gets created either for the system-provided command-line arguments or for a custom sequence of arguments.
- For every flag, a Flag
object is being created and registered in the
Flagsobject. - Once all flag objects are declared and registered, the command-line gets parsed. After parsing is complete, the flag objects can be used to access the extracted options and arguments.
CommandLineKit defines different types of Flag subclasses for handling options (i.e. flags without parameters) and arguments (i.e. flags with parameters). Arguments are either singleton arguments (i.e. they have exactly one value) or they are repeated arguments (i.e. they have many values). Arguments are parameterized with a type which defines how to parse values. The framework natively supports int, double, string, and enum types, which means that in practice, just using the built-in flag classes are almost always sufficient. Nevertheless, the framework is extensible and supports arbitrary argument types.
A flag is identified by a short name character and a long name string. At least one of the two needs to be
defined. For instance, the "help" option could be defined by the short name "h" and the long name "help".
On the command-line, a user could either use -h or --help to refer to this option; i.e. short names are
prefixed with a single dash, long names are prefixed with a double dash.
An argument is a parameterized flag. The parameters follow directly the flag identifier (typically separated by
a space). For instance, an integer argument with long name "size" could be defined as: --size 64. If the
argument is repeated, then multiple parameters may follow the flag identifier, as in this
example: --size 2 4 8 16. The sequence is terminated by either the end of the command-line arguments,
another flag, or the terminator "---". All command-line arguments following the terminator are not being parsed
and are returned in the parameters field of the Flags object.
Here is an example
from the LispKit project. It uses factory methods (like flags.string,
flags.int, flags.option, flags.strings, etc.) provided by the
Flags
class to create and register individual flags.
// Create a new flags object for the system-provided command-line arguments
var flags = Flags()
// Define the various flags
let filePaths = flags.strings("f", "filepath",
description: "Adds file path in which programs are searched for.")
let libPaths = flags.strings("l", "libpath",
description: "Adds file path in which libraries are searched for.")
let heapSize = flags.int("x", "heapsize",
description: "Initial capacity of the heap", value: 1000)
let importLibs = flags.strings("i", "import",
description: "Imports library automatically after startup.")
let prelude = flags.string("p", "prelude",
description: "Path to prelude file which gets executed after " +
"loading all provided libraries.")
let prompt = flags.string("r", "prompt",
description: "String used as prompt in REPL.", value: "> ")
let quiet = flags.option("q", "quiet",
description: "In quiet mode, optional messages are not printed.")
let help = flags.option("h", "help",
description: "Show description of usage and options of this tools.")
// Parse the command-line arguments and return error message if parsing fails
if let failure = flags.parsingFailure() {
print(failure)
exit(1)
}The framework supports printing the supported options via the Flags.usageDescription function. For the
command-line flags as defined above, this function returns the following usage description:
usage: LispKitRepl [<option> ...] [---] [<program> <arg> ...]
options:
-f, --filepath <value> ...
Adds file path in which programs are searched for.
-l, --libpath <value> ...
Adds file path in which libraries are searched for.
-h, --heapsize <value>
Initial capacity of the heap
-i, --import <value> ...
Imports library automatically after startup.
-p, --prelude <value>
Path to prelude file which gets executed after loading all provided libraries.
-r, --prompt <value>
String used as prompt in REPL.
-q, --quiet
In quiet mode, optional messages are not printed.
-h, --help
Show description of usage and options of this tools.
Command-line tools can inspect whether a flag was set via the Flag.wasSet field. For flags with
parameters, the parameters are stored in the Flag.value field. The type of this field is dependent on the
flag type. For repeated flags, an array is used.
Here is an example how the flags defined by the code snippet above could be used:
// If help flag was provided, print usage description and exit tool
if help.wasSet {
print(flags.usageDescription(usageName: TextStyle.bold.properties.apply(to: "usage:"),
synopsis: "[<option> ...] [---] [<program> <arg> ...]",
usageStyle: TextProperties.none,
optionsName: TextStyle.bold.properties.apply(to: "options:"),
flagStyle: TextStyle.italic.properties),
terminator: "")
exit(0)
}
...
// Define how optional messages and errors are printed
func printOpt(_ message: String) {
if !quiet.wasSet {
print(message)
}
}
...
// Set heap size (assuming 1234 is the default if the flag is not set)
virtualMachine.setHeapSize(heapSize.value ?? 1234)
...
// Register all file paths
for path in filePaths.value {
virtualMachine.fileHandler.register(path)
}
...
// Load prelude file if it was provided via flag `prelude`
if let file = prelude.value {
virtualMachine.load(file)
}The code below illustrates how to combine the Command protocol with property wrappers
declaring the various command-line flags. The whole lifecycle of a command-line tool that
is declared like this will be managed automatically. After flags are being parsed, either
methods run() or fail(with:) are being called (depending on whether flag parsing
succeeds or fails).
@main struct LispKitRepl: Command {
@CommandArguments(short: "f", description: "Adds file path in which programs are searched for.")
var filePath: [String]
@CommandArguments(short: "l", description: "Adds file path in which libraries are searched for.")
var libPaths: [String]
@CommandArgument(short: "x", description: "Initial capacity of the heap")
var heapSize: Int = 1234
...
@CommandOption(short: "h", description: "Show description of usage and options of this tools.")
var help: Bool
@CommandParameters // Inject the unparsed parameters
var params: [String]
@CommandFlags // Inject the flags object
var flags: Flags
mutating func fail(with reason: String) throws {
print(reason)
exit(1)
}
mutating func run() throws {
// If help flag was provided, print usage description and exit tool
if help {
print(flags.usageDescription(usageName: TextStyle.bold.properties.apply(to: "usage:"),
synopsis: "[<option> ...] [---] [<program> <arg> ...]",
usageStyle: TextProperties.none,
optionsName: TextStyle.bold.properties.apply(to: "options:"),
flagStyle: TextStyle.italic.properties),
terminator: "")
exit(0)
}
...
// Define how optional messages and errors are printed
func printOpt(_ message: String) {
if !quiet {
print(message)
}
}
...
// Set heap size
virtualMachine.setHeapSize(heapSize)
...
// Register all file paths
for path in filePaths {
virtualMachine.fileHandler.register(path)
}
...
// Load prelude file if it was provided via flag `prelude`
if let file = prelude {
virtualMachine.load(file)
}
}
}CommandLineKit provides a
TextProperties
structure for bundling a text color, a background color, and a text style in a single object. Text properties can be
merged with the with(:) functions and applied to a string with the apply(to:) function.
Individual enumerations for TextColor, BackgroundColor, and TextStyle define the individual properties.
CommandLineKit includes a significantly improved version of the "readline" API originally defined by the library Linenoise-Swift. It supports unicode text, multi-line text entry, and styled text. It supports all the existing features such as advanced keyboard support, history, text completion, and hints.
The following code illustrates the usage of the LineReader API:
if let ln = LineReader() {
ln.setCompletionCallback { currentBuffer in
let completions = [
"Hello!",
"Hello Google",
"Scheme is awesome!"
]
return completions.filter { $0.hasPrefix(currentBuffer) }
}
ln.setHintsCallback { currentBuffer in
let hints = [
"Foo",
"Lorem Ipsum",
"Scheme is awesome!"
]
let filtered = hints.filter { $0.hasPrefix(currentBuffer) }
if let hint = filtered.first {
let hintText = String(hint.dropFirst(currentBuffer.count))
return (hintText, TextColor.grey.properties)
} else {
return nil
}
}
print("Type 'exit' to quit")
var done = false
while !done {
do {
let output = try ln.readLine(prompt: "> ",
maxCount: 200,
strippingNewline: true,
promptProperties: TextProperties(.green, nil, .bold),
readProperties: TextProperties(.blue, nil),
parenProperties: TextProperties(.red, nil, .bold))
print("Entered: \(output)")
ln.addHistory(output)
if output == "exit" {
break
}
} catch LineReaderError.CTRLC {
print("\nCaptured CTRL+C. Quitting.")
done = true
} catch {
print(error)
}
}
}Author: Matthias Zenger (matthias@objecthub.com)
Copyright © 2018-2023 Google LLC.
Please note: This is not an official Google product.