Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/twof/CLSwift
A framework for writing command line tools in Swift
https://github.com/twof/CLSwift
commandline macos swift
Last synced: 3 months ago
JSON representation
A framework for writing command line tools in Swift
- Host: GitHub
- URL: https://github.com/twof/CLSwift
- Owner: twof
- Created: 2017-09-12T23:57:53.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2018-11-13T19:08:21.000Z (almost 6 years ago)
- Last Synced: 2024-07-17T22:08:10.580Z (4 months ago)
- Topics: commandline, macos, swift
- Language: Swift
- Homepage:
- Size: 1.24 MB
- Stars: 9
- Watchers: 4
- Forks: 2
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-system-swift - CLSwift - line tools** in Swift. Includes type safe argument parsing, input validation, and generated help messages. (The Index / Command Line UI tools)
README
# CLSwift
A Swift framework for writing commandline tools
### Inspiration
There are a large number of really useful commandline tools that work on Linux, but were never ported to macOS. One of those was `xdotool` which is a UI automation tool for things like typing and moving a mouse around. Something similar doesn't exist on macOS so I started porting it over with the intent to make a drop in replacement and called it `osxdotool`. `xdotool` is a large and very mature tool so the complexity got to me early on and I knew I needed a way to orginize everything coherently, but nothing that achieved that well IMO for Swift. `CLSwift` was born.
## Features
* Ingest and parse commandline input into `Command`s, `Option`s, and the parameters associated with each
* Typecast parameters upfront according to expected input
* Validate input by expected number and type of parameters
* Built for modularity. Easily split up argument and flag definitions however you like
* Highly testible. Built to take in example input
* Generated help messages on command misuse
## Examples
### Options
Options are used to alter the functionality of an argument. This is done by getting a dictionary representing state from the argument and changing values within that dictionary. The closure parameter is executed when one of the `triggers` is found in the commandline input and parameters are validated. `Flag` is an `Option` that takes no parameters.
```swift
let flag = Flag(
triggers: ["-f"],
help: "Replaces foo value with baz",
state: ["foo": "bar"]
) { (params, state) -> State in
var newState = state
newState["foo"] = "baz"
return newState
}
let legsOption = Option(
triggers: ["-l"],
help: "Sets leg number of legs",
state: ["legs": 2],
numParams: .number(1)
) { (params, state) -> State in
var newState = state
newState["legs"] = params[0]
return newState
}
```
### Commands
Just like `Option`, the closure parameter is executed when one of the `triggers` is found in the commandline input and parameters are validated. `Option`s are attatched to an argument by passing them in on initialization. This is nice because if you have many arguments that use the same option, you can reuse the exact same `Option` instance.
```swift
let command = Command(
triggers: ["hello"],
help: "Takes foo, hello and legs and does foobar",
numParams: .number(2),
options: [flag, legsOption]
) { (vals, state) in
if state["foo"] as? String == "baz" {
print("-f flag used")
}
if state["legs"] as? Int != 2 {
print("-l flag used")
}
}
```
### Command Center
The following is the typical use case in which `CommandLine.arguments` is used for input, but you can also supply your own input for testing purposes by simply replacing `CommandLine.arguments` with your own array of strings.
The first step is figuring out which of your commands was triggered if any. Then you call `.execute()` on that command which executes the closure supplied on initialization.
`CommandCenter` takes your input and breaks it up into more usable objects which are stored in `commandCenter.input`.
```swift
let commandCenter = CommandCenter(commands: [command], input: CommandLine.arguments)
let triggeredCommand = commandCenter.check()
if let triggeredCommand = triggeredCommand {
triggeredCommand.execute(commandline: commandCenter.input)
}
```
### Help message
The help message for the above looks like this
```bash
Usage: hello [options]
Description:
Takes foo, hello and legs and does foobar
-f Replaces foo value with baz
-l Sets leg number of legs
```
This could be triggered if no parameters were supplied for `-l` for example which would look like this
```bash
$ ./example hello 1 2 -f -l
```