Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/scottrhoyt/SwiftyTextTable

A lightweight library for generating text tables.
https://github.com/scottrhoyt/SwiftyTextTable

carthage cocoapods command-line linux macos swift swift-package-manager tabular-data

Last synced: about 1 month ago
JSON representation

A lightweight library for generating text tables.

Lists

README 

        
# SwiftyTextTable



A lightweight Swift library for generating text tables.



[![Build Status](https://travis-ci.org/scottrhoyt/SwiftyTextTable.svg?branch=master)](https://travis-ci.org/scottrhoyt/SwiftyTextTable)

[![codecov.io](https://codecov.io/github/scottrhoyt/SwiftyTextTable/coverage.svg?branch=master)](https://codecov.io/github/scottrhoyt/SwiftyTextTable?branch=master)

[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)

[![Swift Package Manager compatible](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg)](https://github.com/apple/swift-package-manager)

[![CocoaPods](https://img.shields.io/cocoapods/v/SwiftyTextTable.svg)]()

![Platform OS X + Linux](https://img.shields.io/badge/Platform-OS%20X%20%2B%20Linux-blue.svg)

[![Language Swift 4.0](https://img.shields.io/badge/Language-Swift%204.0-orange.svg)](https://swift.org)



![Example](http://i.imgur.com/utoa6TK.png)



## Swift Language Support



SwiftyTextTable is now Swift 4.0 compatible! The last release to support Swift

3.1 was [0.7.1](https://github.com/scottrhoyt/SwiftyTextTable/releases/tag/0.7.1).

The last release to support Swift 2.3 was [0.3.1](https://github.com/scottrhoyt/SwiftyTextTable/releases/tag/0.3.1).



## Installation



### Carthage (OS X)

You can use [Carthage](https://github.com/Carthage/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](https://swift.org/package-manager) to

install SwiftyTextTable by adding the proper description to your

`Package.swift` file:



```swift

import PackageDescription



let package = Package(

    name: "",

    dependencies: [

        .package(url: "https://github.com/scottrhoyt/SwiftyTextTable.git", from: "0.5.0")

    ]

)

```



### CocoaPods (OS X)



You can use [CocoaPods](https://cocoapods.org) to install SwiftyTextTable by

adding it to your `Podfile`:



```ruby

pod 'SwiftyTextTable'

```



### Manual



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

your project.



## Usage



```swift

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:



```swift

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`:



```swift

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:



```swift

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`.



```swift

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.



```swift

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](https://github.com/onevcat/Rainbow)) and account for them

in constructing the table.



### API Reference



Check out the full API reference [here](http://scottrhoyt.github.io/SwiftyTextTable/).



## License



SwiftyTextTable is released under the [MIT License](https://github.com/scottrhoyt/SwiftyTextTable/blob/master/LICENSE).