Swiftpack.co - Package - scottrhoyt/SwiftyTextTable

SwiftyTextTable

A lightweight Swift library for generating text tables.

Build Status codecov.io Carthage compatible Swift Package Manager compatible CocoaPods Platform OS X + Linux Language Swift 4.0

Example

Swift Language Support

SwiftyTextTable is now Swift 4.0 compatible! The last release to support Swift 3.1 was 0.7.1. The last release to support Swift 2.3 was 0.3.1.

Installation

Carthage (OS X)

You can use Carthage to install SwiftyTextTable by adding it to your Cartfile:

github "scottrhoyt/SwiftyTextTable"

Swift Package Manager (OS X + Linux)

You can use The Swift Package Manager to install SwiftyTextTable by adding the proper description to your Package.swift file:

import PackageDescription

let package = Package(
    name: "<YOUR_PROJECT_NAME>",
    dependencies: [
        .package(url: "https://github.com/scottrhoyt/SwiftyTextTable.git", from: "0.5.0")
    ]
)

CocoaPods (OS X)

You can use CocoaPods to install SwiftyTextTable by adding it to your Podfile:

pod 'SwiftyTextTable'

Manual

Simply copy the *.swift files from the Source/SwiftyTextTable directory into your project.

Usage

import SwiftyTextTable

// First create some columns
let foo = TextTableColumn(header: "foo")
let bar = TextTableColumn(header: "bar")
let baz = TextTableColumn(header: "baz")

// Then create a table with the columns
var table = TextTable(columns: [foo, bar, baz])

// Then add some rows
table.addRow([1, 2, 3])
table.addRow([11, 22, 33])

// Then render the table and use
let tableString = table.render()
print(tableString)

/*
+-----+-----+-----+
| foo | bar | baz |
+-----+-----+-----+
| 1   | 2   | 3   |
| 11  | 22  | 33  |
+-----+-----+-----+
*/

// Put a header on the table if you'd like
table.header = "my foo table"
print(table.render())

/*
+-----------------+
| my foo table    |
+-----------------+
| foo | bar | baz |
+-----+-----+-----+
| 1   | 2   | 3   |
| 11  | 22  | 33  |
+-----+-----+-----+
*/

Any CustomStringConvertible can be used for row values.

Creating Tables from Arrays of Objects with TextTableRepresentable

Let's say you have an array of objects that looks this:

enum AnimalType: String, CustomStringConvertible {
    case dog = "Dog"
    case cat = "Cat"
    case gorilla = "Gorilla"

    var description: String {
        return self.rawValue
    }
}

struct Pet {
    let type: AnimalType
    let name: String
    let canHazPizza: Bool
}

let furball = Pet(type: .cat, name: "Furball", canHazPizza: false)
let bestFriend = Pet(type: .dog, name: "Best Friend", canHazPizza: true)
let scary = Pet(type: .gorilla, name: "Scary", canHazPizza: true)
let pets = [furball, bestFriend, scary]

Now you want to print a table containing your pets. You can accomplish this by having Pet conform to TextTableRepresentable:

extension Pet: TextTableRepresentable {
    static var columnHeaders: [String] {
        return ["Name", "Animal", "Can Haz Pizza?"]
    }

    var tableValues: [CustomStringConvertible] {
        return [name, type, canHazPizza ? "yes" : "no"]
    }

    // Optional
    static var tableHeader: String? {
      return "My Pets"
    }
}

You can now print a table of your pets simply:

print(pets.renderTextTable())

/*
+----------------------------------------+
| My Pets                                |
+----------------------------------------+
| Name        | Animal  | Can Haz Pizza? |
+-------------+---------+----------------+
| Furball     | Cat     | no             |
| Best Friend | Dog     | yes            |
| Scary       | Gorilla | yes            |
+-------------+---------+----------------+
*/

Fence Custimization

You can also customize the output of TextTable.render() by using different values for columnFence, rowFence, and cornerFence.

table.columnFence = ":"
table.rowFence = "."
table.cornerFence = "."

print(table.render())

/*
...................
: foo : bar : baz :
...................
: 1   : 2   :     :
: 11  : 22  : 33  :
...................
*/

Row Padding/Truncation

When adding rows, TextTable will automatically pad the rows with empty strings when there are fewer values than columns. TextTable will also disregard all values over the column count.

let foo = TextTableColumn(header: "foo")
let bar = TextTableColumn(header: "bar")
let baz = TextTableColumn(header: "baz")

var table = TextTable(columns: [foo, bar, baz])

table.addRow([1, 2])
table.addRow([11, 22, 33])
table.addRow([111, 222, 333, 444])

let tableString = table.render()
print(tableString)

/*
+-----+-----+-----+
| foo | bar | baz |
+-----+-----+-----+
| 1   | 2   |     |
| 11  | 22  | 33  |
| 111 | 222 | 333 |
+-----+-----+-----+
*/

Console Formatting Support

SwiftyTextTable will recognize many console escape sequences used to format output (e.g. Rainbow) and account for them in constructing the table.

API Reference

Check out the full API reference here.

License

SwiftyTextTable is released under the MIT License.

Github

link
Stars: 238

Dependencies

Used By

Total: 1

Releases

0.9.0 -

0.9.0

Breaking
  • None
Enhancements
  • Pre-compute column width to increase rendering performance.
Bug Fixes
  • Fix column width when using terminal escape sequences such as coloring.

0.8.2 -

Fix Swift Package Manager manifest to include SwiftyTextTable library product.

0.8.1 -

Update SwiftPM package manifest to v4 format.

-

Breaking
  • Update to Swift 4.
Enhancements
  • None
Bug Fixes
  • None

-

Breaking
  • None
Enhancements
  • None
Bug Fixes
  • Fix Swift 4.0.2 deprecation of String.characters

-

Breaking
  • None
Enhancements
  • CI tests for Xcode 9 and Swift 4 on Linux support.
Bug Fixes
  • Fixes for Xcode 9 beta 3

Table Service -

Breaking
  • TextTableColumn.width was refactored to TextTableColumn.width() to better reflect the O(n) complexity of calculating this value.
  • TextTableObject was renamed to TextTableRepresentable.
Enhancements
  • Added Documentation.
  • Re-enabled console formatting support for Linux.
  • Improved compilation time.
  • Added convenience method for rendering tables from an array of TextTableRepresentables (renderTextTable).
  • Now available via CocoaPods.
Bug Fixes
  • None

0.5.0: Heading In The Right Direction -

0.5.0: Heading In The Right Direction

Breaking
  • TableObject.tableHeaders was rename TableObject.columnHeaders for clarity.
Enhancements
  • TextTables can now optionally have table headers.
  • TableObjects can now optionally supply a table header
Bug Fixes
  • None

0.4.0: Swift 3.0 Support -

0.4.0: Swift 3.0 Support

Breaking
  • SwiftyTextTable adopts the new Swift 3.0 convention of explicit first parameter labels for functions.
  • Linux support for dealing with console formatting escape sequences has been removed for the time being due to regular expression portability problems.
Enhancements
  • Swift 3.0 support!
Bug Fixes
  • None

0.3.1: Swift 2.3 update -

This is an updated release for compatibility with Swift 2.3 and Xcode 8.

0.3.0: Table Objects Oh My! -

Breaking
  • TextTable.addRow now takes an array instead of an argument list. This was to support TextTableObject.
Enhancements
  • TextTableObject allows for easy table creation from an array of objects.
  • Better SPM testing support.
Bug Fixes
  • None

0.2.2: No Escape -

This release adds console escape sequence stripping in column width calculation so that you can safely add formatting to table headers/values (e.g. Rainbow).

0.2.1: Fence Fix -

Fix SPM test failure.

0.2.0: Picket Fence -

Added ability to customize values for row, column, and corner fences.

-

-

-

-

-

0.1.0: Initial Release -