Swiftline is a set of tools to help you create command line applications. Swiftline is inspired by highline
Swiftline contains the following:
- Colorize: Helps adding colors to strings written to the terminal
- Ask , Choose and agree: Easily create prompt for asking the user more info
- Run: A quick way to run an external command and read its standard output and standard error.
- Env: Read and write environment variables ruby-flavored
- Args: Parses command line arguments and return a hash of the passed flags
Contents
Usage Installation Examples Docs Tests
Usage
Colorize
🎨
Colorize helps styling the strings before printing them to the terminal. You can change the text color, the text background and the text style. Colorize works by extending String struct to add styling to it.
To change the text color, use either string.f or string.foreground:
print("Red String".f.Red)
print("Blue String".foreground.Blue)
To change the text background color, use either string.b or string.background:
print("I have a white background".b.White)
print("My background color is green".background.Green)
To change the text background style, use either string.s or string.style:
print("I am a bold string".s.Bold)
print("I have an underline".style.Underline)
You can compose foreground, background, and style:
print("I am an underlined red on white string".s.Underline.f.Red.b.White)
Ask, Choose, Agree
❓
Ask, Choose and Agree are used to prompt the user for more information.
Ask
Ask presents the user with a prompt and waits for the user input.
let userName = ask("Enter user name?")
userName will contain the name entered by the user
Ask can be used to ask for value of Int, Double or Float types, to ask for an integer for example:
let age = ask("How old are you?", type: Int.self)
If the user prints something thats not convertible to integer, a new prompt is displayed to him, this prompt will keep displaying until the user enters an Int:
How old are you?
None
You must enter a valid Integer.
? Error
You must enter a valid Integer.
? 5
5
Validations are added by calling addInvalidCase on AskSettings.
let name = ask("Who are you?") { settings in
settings.addInvalidCase("Snuffles is not allowed") { value in
value.containsString("Snuffles")
}
}
If the user entered Snuffles ask will keep displaying the invalid message passed to addInvalidCase
Who are you?
Snuffles
Snuffles is not allowed
? Snuffles
Snuffles is not allowed
? Snowball
Your name is Snowball
AskSettings.confirm will ask the user to confirm his choice after entering it
let name = ask("Who are you?") { settings in
settings.confirm = true
}
The above will output:
Who are you?
Snuffles
Are you sure? YES
Your name is Snuffles
Choose
Choose is used to prompt the user to select an item between several possible items.
To display a choice of programming lanaugage for example:
let choice = choose("Whats your favorite programming language? ",
choices: "Swift", "Objective C", "Ruby", "Python", "Java :S")
This will print:
1. Swift
2. Objective C
3. Ruby
4. Python
5. Java :S
Whats your favorite programming language?
The user can either choose the numbers (1..5) or the item itself. If the user enters a wrong input. A prompt will keep showing until the user makes a correct choice
Whats your favorite programming language? JavaScript
You must choose one of [1, 2, 3, 4, 5, Swift, Objective C, Ruby, Python, Java :S].
? BBB
You must choose one of [1, 2, 3, 4, 5, Swift, Objective C, Ruby, Python, Java :S].
? Swift
You selected Swift, good choice!
You can customize the return value for each choice element. For example if you want to get an Int from the choice, you would do this
let choice = choose("Whats your favorite programming language? ", type: Int.self) { settings in
settings.addChoice("Swift") { 42 }
settings.addChoice("Objective C") { 20 }
}
The number on the left can be changed to letters, here is how you could do that:
let choice = choose("Whats your favorite programming language? ", type: String.self) { settings in
//choice value will be set to GOOD
settings.addChoice("Swift") { "GOOD" }
//choice value will be set to BAD
settings.addChoice("Java") { "BAD" }
settings.index = .Letters
settings.indexSuffix = " ----> "
}
That will print:
a ----> Swift
b ----> Java
Whats your favorite programming language?
Agree
Agree is used to ask a user for a Yes/No question. It returns a boolean representing the user input.
let choice = agree("Are you sure you want to `rm -rf /` ?")
If the user enters any invalid input, agree will keep prompting him for a Yes/No question
Are you sure you want to `rm -rf /` ? What!
Please enter "yes" or "no".
Are you sure you want to `rm -rf /` ? Wait
Please enter "yes" or "no".
Are you sure you want to `rm -rf /` ? No
You entered false
Run
🏃
Run provides a quick, concise way to run an external command and read its standard output and standard error.
To execute a simple command you would do:
let result = run("ls -all")
print(result.stdout)
result type is RunResults, it contains:
exitStatus: The command exit statusstdout: The standard output for the command executedstderr: The standard error for the command executed
While run("command") can split the arguments by spaces. Some times argument splitting is not trivial. If you have multiple argument to pass to the command to execute, you should use run(command: String, args: String...). The above translates to:
let result = run("ls", args: "-all")
To customize the run function, you can pass in a customization block:
let result = run("ls -all") { settings in
settings.dryRun = true
settings.echo = [.Stdout, .Stderr, .Command]
settings.interactive = false
}
settings is an instance of RunSettings, which contains the following variables:
settings.dryRun: defaults to false. If false, the command is actually run. If true, the command is logged to the stdout paramter of resultsettings.echo: Customize the message printed to stdout,echocan contain any of the following:EchoSettings.Stdout: The stdout returned from running the command will be printed to the terminalEchoSettings.Stderr: The stderr returned from running the command will be printed to the terminalEchoSettings.Command: The command executed will be printed to the terminal
settings.interactive: defaults to false. If set to true the command will be executed usingsystemkernel function and only the exit status will be captured. If set to false, the command will be executed usingNSTaskand both stdout and stderr will be captured. Setinteractiveto true if you expect the launched command to ask input from the user through the stdin.
runWithoutCapture("command") is a quick way to run a command in interactive mode. The return value is the exit code of that command.
Env
Env is used to read and write the environment variables passed to the script
// Set enviroment variable
Env.set("key1", "value1")
// Get environment variable
Env.get("SomeKey")
// Clear all variables
Env.clear()
// Get all keys and values
Env.keys()
Env.values()
Args
Returns the arguments passed to the script. For example when calling script -f1 val1 -f2 val2 -- val3 val4
Args.all returns an array of all the raw arguments, in this example it will be ["-f1", "val1", "-f2", "val2", "--", "val3", "val4"
Args.parsed returns a structure that contains a parsed map of arguments and an array of arguments, for this example:
Args.parsed.parameters returns ["val3", "val4"]
Args.parsed.flags returns a dictinary of flags ["f1": "val1", "f2", "val2"]
Args.parsed.command returns the name of the executable itself "script"
Installation
You can install Swiftline using CocoaPods, carthage and Swift package manager
CocoaPods
use_frameworks!
pod 'Swiftline'
Carthage
github 'swiftline/swiftline'
Swift Package Manager
Add swiftline as dependency in your Package.swift
import PackageDescription
let package = Package(name: "YourPackage",
dependencies: [
.Package(url: "https://github.com/Swiftline/Swiftline.git", majorVersion: 0, minor: 3),
]
)
CocoaPods + Rome plugin
If you want to use swiftline in a script you can use Rome CocoaPods plugin. This plugin builds the framework from the pod file and place them in a Rome directory.
platform :osx, '10.10'
plugin 'cocoapods-rome'
pod 'Swiftline'
Manual
To install Swiftline manually, add Pod/Swiftline directory to your project.
Examples
A list of examples can be found here
Tests
Tests can be found here. They can be normally run from the Xcode .
Documentation
Documentation can be found here
Future Improvement
- Add gather (from highline) to ask function
- Figure out a way to eliminate the need of
interactive - Add Glob handling
- Better documentation
Credits
Daniel Beere for creating the logo @DanielBeere check out danielbeere on dribble Omar Abdelhafith current project maintainer @ifnottrue
1 Dec 25, 2021
4 Sep 29, 2022
18 Aug 19, 2022
3k Dec 30, 2022
1.5k Dec 29, 2022
1.1k Dec 1, 2022
86 Dec 15, 2022
21 Sep 13, 2022
32 Nov 17, 2022
15 Nov 24, 2022
2.3k Jan 9, 2023
36 Dec 23, 2022
52 Nov 9, 2022
36 Nov 25, 2022
523 Dec 29, 2022
3 Sep 28, 2022
131 Nov 14, 2022
0 Nov 5, 2021