Targone is a command line argument parser for Swift scripts, inspired by Python argparse. It allows script authors to easily define what kind of arguments are expected, whether they are optional, positional or flags, and automatically generate usage description.
See also Morione, A Swift subprocess execution library intended to be used in Swift scripts, inspired by Python
Targone public API is designed keeping in mind ease of use within a script.
To achieve this, most classes have two ways of being initialized, one with explicit argument names and error reporting (Swift
throw), and one simplified version that doesn't require the first label and that does not throw. The second version will instead print an error and aborts execution, following a common pattern in scripts where not all edge cases need to be handled explicitly and abrupt abortion is a valid strategy. See
OptionalArgument for an example.
To extract a parsed value (see
ParsingResult), one could use a function that return
nil if the expected type does not match, or a function that prints an error and aborts execution if the type doesn't match.
Aborting execution does not sound very Swift-like; on the other hand, throwing a Swift-error would make even the most simple script full of
try! and in case of error, print some completely cryptic stack trace that has nothing to do with the error itself. As the goal of Targone is ease of use in a script, we decided not to use
throw. We are aware that this makes it impossible to test some cases in unit tests.
The API is documented in the code and tests.
A simple example Swift script usage can be found in the Example folder.
Prints an error when command line arguments are missing or not matching type
$> Examples/echo.swift usage: echo.swift [-h] [-n NUM<Int>] [--quotes] text echo.swift: error: too few arguments
Automatically generates and prints help
$> Examples/echo.swift --help sage: echo.swift [-h] [--quotes] [-n NUM<Int>] text Echoes some text on stdin positional arguments: text the text to print optional arguments: --help, -h show this help message and exit --num, -n NUM<Int> how many times to print the text --quotes enclose the text within quotes
How to use Targone in your script
import Targone to your script
In order to be able to import it, you need to have the
Targone.framework in the Swift search path. You can achieve this by compiling it yourself or downloading a binary version from a release. You need to invoke Swift with the
-F argument, pointing to the folder where Targone is stored.
Targone can be downloaded locally with Carthage.
Cartfile. After running
you would be able to run any swift file with
swift -F Carthage/Build/Mac
-F flag can also be included in the shebang line of the script, so that you can just invoke the script directly (e.g.
$> do.swift). This is the approach used in the examples included with this project.
You can download the framework binary from the GitHub latest release