Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kareman/moderator
A simple, modular command line argument parser in Swift.
https://github.com/kareman/moderator
argument-parser command-line swift swift-library
Last synced: 30 days ago
JSON representation
A simple, modular command line argument parser in Swift.
- Host: GitHub
- URL: https://github.com/kareman/moderator
- Owner: kareman
- License: mit
- Created: 2015-11-05T23:33:29.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2019-03-30T20:02:17.000Z (over 5 years ago)
- Last Synced: 2024-09-15T06:34:24.871Z (about 2 months ago)
- Topics: argument-parser, command-line, swift, swift-library
- Language: Swift
- Size: 15.9 MB
- Stars: 21
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[Run shell commands](https://github.com/kareman/SwiftShell) | Parse command line arguments | [Handle files and directories](https://github.com/kareman/FileSmith)
---
[](https://travis-ci.org/kareman/Moderator)   [](https://github.com/Carthage/Carthage)
# Moderator
Moderator is a simple Swift library for parsing commandline arguments.
## Features
- [x] Modular, easy to extend.
- [x] Supports a [cross platform syntax](https://nottoobadsoftware.com/blog/uncategorized/cross-platform-command-line-arguments-syntax/).
- [x] Generates help text automatically.
- [x] Handles arguments of the type '--option=value'.
- [x] Optional strict parsing, where an error is thrown if there are any unrecognised arguments.
- [x] Any arguments after an "\--" argument are taken literally, they are not parsed as options and any '=' are left untouched.
See also [why Moderator was created](https://nottoobadsoftware.com/blog/swift/moderator-parsing-commandline-arguments-in-swift/).
## Example
from [linuxmain-generator](https://github.com/kareman/linuxmain-generator):
```Swift
import Moderator
import FileSmith
let arguments = Moderator(description: "Automatically add code to Swift Package Manager projects to run unit tests on Linux.")
let overwrite = arguments.add(.option("o","overwrite", description: "Replace /LinuxMain.swift if it already exists."))
let testdirarg = arguments.add(Argument
.optionWithValue("testdir", name: "test directory", description: "The path to the directory with the unit tests.")
.default("Tests"))
_ = arguments.add(Argument
.singleArgument(name: "directory", description: "The project root directory.")
.default("./")
.map { (projectpath: String) in
let projectdir = try Directory(open: projectpath)
try projectdir.verifyContains("Package.swift")
Directory.current = projectdir
})
do {
try arguments.parse()
let testdir = try Directory(open: testdirarg.value)
if !overwrite.value && testdir.contains("LinuxMain.swift") {
throw ArgumentError(errormessage: "\(testdir.path)/LinuxMain.swift already exists. Use -o/--overwrite to replace it.")
}
...
} catch {
WritableFile.stderror.print(error)
exit(Int32(error._code))
}
```
Automatically generated help text:
```text
Automatically add code to Swift Package Manager projects to run unit tests on Linux.
Usage: linuxmain-generator
-o,--overwrite:
Replace /LinuxMain.swift if it already exists.
--testdir :
The path to the directory with the unit tests. Default = 'Tests'.
:
The project root directory. Default = './'.
```
## Introduction
Moderator works by having a single Moderator object which you add individual argument parsers to. When you start parsing it goes through each argument parser _in the order they were added_. Each parser takes the array of string arguments from the command line, finds the arguments it is responsible for, processes them and throws any errors if anything is wrong, _removes the arguments from the array_, returns its output (which for some parsers may be nil if the argument was not found) and passes the modified array to the next parser.
This keeps the code simple and each parser only has to take care of its own arguments. The built-in parsers can easily be customised, and you can create your own parsers from scratch.
## Built-in parsers
### Option
```swift
func option(_ names: String..., description: String? = nil) -> Argument
```
Handles option arguments like `-h` and `--help`. Returns true if the argument is present and false otherwise.
### Option with value
```swift
func optionWithValue(_ names: String..., name valuename: String? = nil, description: String? = nil)
-> Argument
```
Handles option arguments with a following value, like `--help `. It returns the value as a String, or nil if the option is not present.
### Single argument
```swift
func singleArgument(name: String, description: String? = nil) -> Argument
```
Returns the next argument, or nil if there are no more arguments or the next argument is an option. Must be added after any option parsers.
## Customise
### `default`
Can be used on parsers returning optionals, to replace nil with a default value.
### `required`
Can be used on parsers returning optionals, to throw an error on nil.
### `map`
Takes the output of any argument parser and converts it to something else.
### `repeat`
Looks for multiple occurrences of an argument, by repeating an optional parser until it returns nil.
```swift
let m = Moderator()
let options = m.add(Argument.optionWithValue("b").repeat())
let multiple = m.add(Argument.singleArgument(name: "multiple").repeat())
try m.parse(["-b", "b1", "-b", "b2", "-b", "b3", "one", "two", "three"])
```
`options.value` is now `["b1", "b2", "b3"]` and `multiple.value` is `["one", "two", "three"]`.
### `count`
Counts the number of times an option argument occurs.
```swift
let m = Moderator()
let option = m.add(Argument.option("b").count())
try m.parse(["-b", "-b", "some", "other", "-b", "arguments"])
```
`option.value` returns `3`
## Add new parsers
If the built in parsers and customisations are not enough, you can easily create your own parsers. As an example here is the implementation of the singleArgument parser:
```swift
extension Argument {
public static func singleArgument (name: String, description: String? = nil) -> Argument {
return Argument(usage: description.map { ("<"+name+">", $0) }) { args in
let index = args.first == "--" ? args.index(after: args.startIndex) : args.startIndex
guard index != args.endIndex, !isOption(index: index, args: args) else { return (nil, args) }
var args = args
return (args.remove(at: index), args)
}
}
}
```
In the Argument initialiser you return a tuple with the output of the parser and the arguments array without the processed argument(s).
## Installation
### [Swift Package Manager](https://github.com/apple/swift-package-manager)
Add `.Package(url: "https://github.com/kareman/Moderator", "0.5.0")` to your Package.swift:
```swift
import PackageDescription
let package = Package(
name: "somename",
dependencies: [
.Package(url: "https://github.com/kareman/Moderator", "0.5.0")
]
)
```
and run `swift build`.
### [Carthage](https://github.com/Carthage/Carthage)
Add `github "kareman/Moderator"` to your Cartfile, then run `carthage update` and add the resulting framework to the "Embedded Binaries" section of the application. See [Carthage's README][carthage-installation] for further instructions.
[carthage-installation]: https://github.com/Carthage/Carthage/blob/master/README.md#adding-frameworks-to-an-application
### [CocoaPods](https://cocoapods.org/)
Add `Moderator` to your `Podfile`.
```ruby
pod "Moderator", git: "https://github.com/kareman/Moderator.git"
```
Then run `pod install` to install it.
## License
Released under the MIT License (MIT), http://opensource.org/licenses/MIT
Kåre Morstøl, [NotTooBad Software](https://nottoobadsoftware.com)