table: README with examples (rather than just pointing to the demo)

jedib0t · May 12, 2018 · 6bc5e8a · 6bc5e8a
1 parent 9f055ab
commit 6bc5e8a
Show file tree

Hide file tree

Showing 2 changed files with 276 additions and 2 deletions.
diff --git a/table/README.md b/table/README.md
@@ -37,9 +37,283 @@ Pretty-print tables into ASCII/Unicode strings.
 +-----+------------+-----------+--------+-----------------------------+
 ```
 
-A demonstration of all the capabilities can be found here: [../cmd/demo-table](../cmd/demo-table)
+A demonstration of all the capabilities can be found here:
+[../cmd/demo-table](../cmd/demo-table)
 
-### TODO
+If you want very specific examples, read ahead.
+
+## Examples
+
+All the examples below are going to start with the following block, although
+nothing except a single Row is mandatory for the `Render()` function to render
+something:
+```go
+package main
+
+import (
+    "os"
+
+    "github.com/jedib0t/go-pretty/table"
+)
+
+func main() {
+    t := table.NewWriter()
+    t.SetOutputMirror(os.Stdout)
+    t.AppendHeader(table.Row{"#", "First Name", "Last Name", "Salary"})
+    t.AppendRows([]table.Row{
+        {1, "Arya", "Stark", 3000},
+        {20, "Jon", "Snow", 2000, "You know nothing, Jon Snow!"},
+    })
+    t.AppendRow([]interface{}{300, "Tyrion", "Lannister", 5000})
+    t.AppendFooter(table.Row{"", "", "Total", 10000})
+    t.Render()
+}
+```
+Running the above will result in:
+```
++-----+------------+-----------+--------+-----------------------------+
+|   # | FIRST NAME | LAST NAME | SALARY |                             |
++-----+------------+-----------+--------+-----------------------------+
+|   1 | Arya       | Stark     |   3000 |                             |
+|  20 | Jon        | Snow      |   2000 | You know nothing, Jon Snow! |
+| 300 | Tyrion     | Lannister |   5000 |                             |
++-----+------------+-----------+--------+-----------------------------+
+|     |            | TOTAL     |  10000 |                             |
++-----+------------+-----------+--------+-----------------------------
+```
+
+### Styles
+
+You can customize almost every single thing about the table above. The previous
+example just defaulted to `StyleDefault` during `Render()`. You can use a
+ready-to-use style (as in [style.go](style.go)) or customize it as you want.
+
+#### Ready-to-use Styles
+
+Table comes with a bunch of ready-to-use Styles that make the table look really
+good. Set or Change the style using:
+```go
+    t.SetStyle(table.StyleLight)
+    t.Render()
+```
+to get:
+```
+┌─────┬────────────┬───────────┬────────┬─────────────────────────────┐
+│   # │ FIRST NAME │ LAST NAME │ SALARY │                             │
+├─────┼────────────┼───────────┼────────┼─────────────────────────────┤
+│   1 │ Arya       │ Stark     │   3000 │                             │
+│  20 │ Jon        │ Snow      │   2000 │ You know nothing, Jon Snow! │
+│ 300 │ Tyrion     │ Lannister │   5000 │                             │
+├─────┼────────────┼───────────┼────────┼─────────────────────────────┤
+│     │            │ TOTAL     │  10000 │                             │
+└─────┴────────────┴───────────┴────────┴─────────────────────────────┘
+```
+
+Or if you want to use a full-color mode, and don't care for boxes, use:
+```go
+    t.SetStyle(table.StyleColoredBright)
+    t.Render()
+```
+to get:
+<img src="images/table-StyleColoredBright.png" width="480px"/>
+
+#### Roll your own Style
+
+You can also roll your own style:
+```go
+    t.SetStyle(table.Style{
+        Name: "myNewStyle",
+        Box: table.BoxStyle{
+            BottomLeft:       "\\",
+            BottomRight:      "/",
+            BottomSeparator:  "v",
+            Left:             "[",
+            LeftSeparator:    "{",
+            MiddleHorizontal: "-",
+            MiddleSeparator:  "+",
+            MiddleVertical:   "|",
+            PaddingLeft:      "<",
+            PaddingRight:     ">",
+            Right:            "]",
+            RightSeparator:   "}",
+            TopLeft:          "(",
+            TopRight:         ")",
+            TopSeparator:     "^",
+            UnfinishedRow:    " ~~~",
+        },
+        Color: table.ColorOptions{
+            AutoIndexColumn: nil,
+            FirstColumn:     nil,
+            Footer:          text.Colors{color.BgCyan, color.FgBlack},
+            Header:          text.Colors{color.BgHiCyan, color.FgBlack},
+            Row:             text.Colors{color.BgHiWhite, color.FgBlack},
+            RowAlternate:    text.Colors{color.BgWhite, color.FgBlack},
+        },
+        Format: table.FormatOptions{
+            Footer: text.FormatUpper,
+            Header: text.FormatUpper,
+            Row:    text.FormatDefault,
+        },
+        Options: table.Options{
+            DrawBorder:      true,
+            SeparateColumns: true,
+            SeparateFooter:  true,
+            SeparateHeader:  true,
+            SeparateRows:    false,
+        },
+    })
+```
+
+Or you can use one of the ready-to-use Styles, and just make a few tweaks:
+```go
+    t.SetStyle(table.StyleLight)
+    t.Style().Color.Header = text.Colors{color.BgHiCyan, color.FgBlack}
+    t.Style().Format.Footer = text.FormatLower
+    t.Style().Options.DrawBorder = false
+```
+
+### Wrapping (or) Row/Column Width restrictions
+
+You can restrict the maximum (text) width for a Row:
+```go
+    t.SetAllowedRowLength(50)
+    t.Render()
+```
+to get:
+```
++-----+------------+-----------+--------+------- ~
+|   # | FIRST NAME | LAST NAME | SALARY |        ~
++-----+------------+-----------+--------+------- ~
+|   1 | Arya       | Stark     |   3000 |        ~
+|  20 | Jon        | Snow      |   2000 | You kn ~
+| 300 | Tyrion     | Lannister |   5000 |        ~
++-----+------------+-----------+--------+------- ~
+|     |            | TOTAL     |  10000 |        ~
++-----+------------+-----------+--------+------- ~
+```
+
+Or restrict the maximum (text) width for a Column:
+```go
+    t.SetAllowedColumnLengths([]int{0, 6, 9, 6, 10})
+    t.SetStyle(table.StyleRounded)
+    t.Render()
+```
+to get:
+```
+╭─────┬────────┬───────────┬────────┬────────────╮
+│   # │ FIRST  │ LAST NAME │ SALARY │            │
+│     │ NAME   │           │        │            │
+├─────┼────────┼───────────┼────────┼────────────┤
+│   1 │ Arya   │ Stark     │   3000 │            │
+│  20 │ Jon    │ Snow      │   2000 │ You know n │
+│     │        │           │        │ othing, Jo │
+│     │        │           │        │ n Snow!    │
+│ 300 │ Tyrion │ Lannister │   5000 │            │
+├─────┼────────┼───────────┼────────┼────────────┤
+│     │        │ TOTAL     │  10000 │            │
+╰─────┴────────┴───────────┴────────┴────────────╯
+```
+
+### Column Control - Alignment & Colors
+
+You can align text in columns horizontally and/or vertically. You can set up
+per-column color styles that will override the directives from the global Style
+set through `SetStyle()`.
+
+```go
+    t.SetAlign([]text.Align{text.AlignDefault, text.AlignRight, text.AlignDefault, text.AlignDefault, text.AlignCenter})
+    t.SetVAlign([]text.VAlign{text.VAlignDefault, text.VAlignMiddle, text.VAlignBottom, text.VAlignMiddle})
+    t.SetColors([]text.Colors{{color.FgWhite, color.BgBlack}, {color.FgWhite, color.BgBlack}})
+    t.SetColorsFooter([]text.Colors{{color.FgRed}, {color.FgGreen}, {color.FgBlue}})
+    t.SetColorsHeader([]text.Colors{{color.FgCyan}, {color.FgMagenta}, {color.FgYellow}, {color.FgBlack, color.BgWhite}})
+```
+
+### Render As ...
+
+Tables can be rendered in other common format:
+
+#### ... CSV
+
+```go
+    t.RenderCSV()
+```
+to get:
+```
+#,First Name,Last Name,Salary,
+1,Arya,Stark,3000,
+20,Jon,Snow,2000,"You know nothing\, Jon Snow!"
+300,Tyrion,Lannister,5000,
+,,Total,10000,
+```
+
+#### ... HTML Table
+
+```go
+    t.RenderHTML()
+```
+to get:
+```html
+<table class="go-pretty-table">
+  <thead>
+  <tr>
+    <th align="right">#</th>
+    <th>First Name</th>
+    <th>Last Name</th>
+    <th align="right">Salary</th>
+    <th>&nbsp;</th>
+  </tr>
+  </thead>
+  <tbody>
+  <tr>
+    <td align="right">1</td>
+    <td>Arya</td>
+    <td>Stark</td>
+    <td align="right">3000</td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td align="right">20</td>
+    <td>Jon</td>
+    <td>Snow</td>
+    <td align="right">2000</td>
+    <td>You know nothing, Jon Snow!</td>
+  </tr>
+  <tr>
+    <td align="right">300</td>
+    <td>Tyrion</td>
+    <td>Lannister</td>
+    <td align="right">5000</td>
+    <td>&nbsp;</td>
+  </tr>
+  </tbody>
+  <tfoot>
+  <tr>
+    <td align="right">&nbsp;</td>
+    <td>&nbsp;</td>
+    <td>Total</td>
+    <td align="right">10000</td>
+    <td>&nbsp;</td>
+  </tr>
+  </tfoot>
+</table>
+```
+
+#### ... Markdown Table
+
+```go
+    t.RenderMarkdown()
+```
+to get:
+```markdown
+| # | First Name | Last Name | Salary |  |
+| ---:| --- | --- | ---:| --- |
+| 1 | Arya | Stark | 3000 |  |
+| 20 | Jon | Snow | 2000 | You know nothing, Jon Snow! |
+| 300 | Tyrion | Lannister | 5000 |  |
+|  |  | Total | 10000 |  |
+```
+
+## TODO
 
   - Generic Cell Content Transformers (with some ready-made ones)
     - Base64 Decoder

diff --git a/table/images/table-StyleColoredBright.png b/table/images/table-StyleColoredBright.png