Skip to content
This repository has been archived by the owner on Sep 26, 2024. It is now read-only.
/ Prism Public archive

Colored text for Swift command line tools.

License

Notifications You must be signed in to change notification settings

jordanbaird/Prism

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation




Continuous Integration Code Coverage Swift Versions Supported Platforms Latest Release License

Styles

About

Prism is a DSL that uses declarative syntax to create beautiful formatted text for Swift command line tools. It's powerful, easy to use, and supports both macOS and Linux.

Install

Add the following dependency to your Package.swift file:

.package(url: "https://github.com/jordanbaird/Prism", from: "0.1.2")

Usage

Read the full documentation here

Start by creating an instance of the Prism type. Its initializer accepts a closure, which you populate with various attributes.

let formatted = Prism(spacing: .spaces) {
    ForegroundColor(.green, "This text's color is green.")
    Bold("This text is bold.")
    Italic("This text is italic.")
    Underline("This text is underlined.")
    Strikethrough("This text has a strikethrough.")
}

Attributes behave similarly to Prism itself, giving you the ability to nest other elements inside them.

let formatted = Prism(spacing: .newlines) {
    Bold {
        "This text is bold."
        Italic("This text is bold and italic.")
        Underline("This text is bold and underlined.")
        BackgroundColor(.cyan) {
            Underline {
                "This text is bold, underlined, and has a cyan background."
                IgnoreFormatting("This text has no formatting.")
                "Back to bold and underlined, with a cyan background."
            }
        }
    }
}

The DSL's ElementBuilder implicitly wraps strings inside a special, non-modifying Standard attribute, allowing instances of the String type — including string literals — to be used inline with other elements and attributes. In the following example, the two Prism blocks are semantically identical:

let formatted1 = Prism {
    Bold("Some bold text.")
    Standard("Just regular old text.")
    Italic("Some italic text.")
}

let formatted2 = Prism {
    Bold("Some bold text.")
    "Just regular old text."
    Italic("Some italic text.")
}

print(formatted1 == formatted2)
// Prints: "true"

The Prism type conforms to the CustomStringConvertible protocol, allowing its formatted contents to be printed directly to stdout.

let wonderfulWorld = Prism {
    "I see"
    ForegroundColor(.blue) {
        "skies that are blue."
    }
    ForegroundColor(.red) {
        "Red roses, too."
    }
}

print(wonderfulWorld)

If the output destination (i.e. terminal or console) does not support formatted text, the unformatted version of the text will be automatically printed instead. For example, here's what the above code prints in Xcode's console:



Note that some terminal clients may display certain elements differently than others. Prism simply provides the terminal with a set of control codes for each attribute. It is up to the terminal to determine how it will display the control codes that Prism provides it.

License

Prism is available under the MIT license.