Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/SDGGiesbrecht/SDGCommandLine
Tools for Implementing a Command Line Interface
https://github.com/SDGGiesbrecht/SDGCommandLine
Last synced: 2 months ago
JSON representation
Tools for Implementing a Command Line Interface
- Host: GitHub
- URL: https://github.com/SDGGiesbrecht/SDGCommandLine
- Owner: SDGGiesbrecht
- License: other
- Created: 2017-08-02T20:59:19.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-09-08T19:15:53.000Z (5 months ago)
- Last Synced: 2024-11-12T21:17:38.230Z (2 months ago)
- Language: Swift
- Homepage: https://sdggiesbrecht.github.io/SDGCommandLine/
- Size: 1.35 MB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-system-swift - SDGCommandLine
README
macOS • Windows • Web • Ubuntu • tvOS • iOS • Android • Amazon Linux • watchOS
[Documentation](https://sdggiesbrecht.github.io/SDGCommandLine/%F0%9F%87%A8%F0%9F%87%A6EN)
# SDGCommandLine
SDGCommandLine provides tools for implementing a command line interface.
> [יְהַלְלוּ אֶת־שֵׁם יהוה כִּי הוּא צִוָּה וְנִבְרָאוּ׃](https://www.biblegateway.com/passage/?search=Psalm+148&version=WLC;NIV)
>
> [May they praise the name of the Lord, for He commanded and they came into being!](https://www.biblegateway.com/passage/?search=Psalm+148&version=WLC;NIV)
>
> ―a psalmist
### Features
- Automatic parsing of options and subcommands
- Automatic `help` subcommand
- Testable output
- Colour formatting tools
- Automatic `•no‐colour` option
- Interface localization
- Automatic `set‐language` subcommand to set language preferences.
- Automatic `•language` option to run in a specific language only once.
- Versioning tools
- Automatic `version` subcommand
- Automatic `•use‐version` option to attempt to download and temporarily use a specific version instead of the one which is installed (only for public Swift packages).
### Example Usage
This example creates a tool with the following interface:
```shell
$ parrot speak
Squawk!
$ parrot speak •phrase "Hello, world!"
Hello, world!
```
`main.swift` must consist of the following:
```swift
Parrot.main()
```
The rest can be anywhere in the project (but putting it in a separate, testable library module is recommended):
```swift
import SDGCommandLine
struct Parrot: Tool {
static let applicationIdentifier: StrictString = "tld.Developper.Parrot"
static let version: Version? = Version(1, 0, 0)
static let packageURL: URL? = URL(string: "https://website.tld/Parrot")
static let rootCommand: Command = parrot
}
let parrot = Command(
name: UserFacing({ _ in "parrot" }),
description: UserFacing({ _ in "behaves like a parrot." }),
subcommands: [speak]
)
let speak = Command(
name: UserFacing({ _ in "speak" }),
description: UserFacing({ _ in "speaks." }),
directArguments: [],
options: [phrase],
execution: { (_, options: Options, output: Command.Output) throws -> Void in
if let specific = options.value(for: phrase) {
output.print(specific)
} else {
output.print("Squawk!")
}
}
)
let phrase = Option(
name: UserFacing({ _ in "phrase" }),
description: UserFacing({ _ in "A custom phrase to speak." }),
type: ArgumentType.string
)
enum MyLocalizations: String, InputLocalization {
case english = "en"
static let cases: [MyLocalizations] = [.english]
static let fallbackLocalization: MyLocalizations = .english
}
```
Tests are easy to set up:
```swift
func testParrot() {
switch parrot.execute(with: ["speak", "•phrase", "Hello, world!"]) {
case .success(let output):
XCTAssertEqual(output, "Hello, world!")
case .failure:
XCTFail("The parrot is not co‐operating.")
}
}
```
Some platforms lack certain features. The compilation conditions which appear throughout the documentation are defined as follows:
```swift
.define("PLATFORM_LACKS_FOUNDATION_PROCESS", .when(platforms: [.wasi, .tvOS, .iOS, .watchOS])),
.define("PLATFORM_LACKS_FOUNDATION_PROCESS_INFO", .when(platforms: [.wasi])),
```
## Importing
SDGCommandLine provides libraries for use with the Swift Package Manager.
Simply add SDGCommandLine as a dependency in `Package.swift` and specify which of the libraries to use:
```swift
let package = Package(
name: "MyPackage",
dependencies: [
.package(
url: "https://github.com/SDGGiesbrecht/SDGCommandLine",
from: Version(3, 0, 6)
),
],
targets: [
.target(
name: "MyTarget",
dependencies: [
.product(name: "SDGCommandLine", package: "SDGCommandLine"),
.product(name: "SDGCommandLineTestUtilities", package: "SDGCommandLine"),
.product(name: "SDGExportedCommandLineInterface", package: "SDGCommandLine"),
]
)
]
)
```
The modules can then be imported in source files:
```swift
import SDGCommandLine
import SDGCommandLineTestUtilities
import SDGExportedCommandLineInterface
```
## About
The SDGCommandLine project is maintained by Jeremy David Giesbrecht.
If SDGCommandLine saves you money, consider giving some of it as a [donation](https://paypal.me/JeremyGiesbrecht).
If SDGCommandLine saves you time, consider devoting some of it to [contributing](https://github.com/SDGGiesbrecht/SDGCommandLine) back to the project.
> [Ἄξιος γὰρ ὁ ἐργάτης τοῦ μισθοῦ αὐτοῦ ἐστι.](https://www.biblegateway.com/passage/?search=Luke+10&version=SBLGNT;NIV)
>
> [For the worker is worthy of his wages.](https://www.biblegateway.com/passage/?search=Luke+10&version=SBLGNT;NIV)
>
> ―ישוע/Yeshuʼa