goterm

README

Description

This library provides basic building blocks for building advanced console UIs.

Initially created for Gor.

Full API documentation: http://godoc.org/github.com/buger/goterm

Basic usage

Full screen console app, priting current time:

import (
    tm "github.com/buger/goterm"
    "time"
)

func main() {
    tm.Clear() // Clear current screen

    for {
        // By moving cursor to top-left position we ensure that console output
        // will be overwritten each time, instead of adding new.
        tm.MoveCursor(1,1)

        tm.Println("Current Time:", time.Now().Format(time.RFC1123))

        tm.Flush() // Call it every time at the end of rendering

        time.Sleep(time.Second)
    }
}

Print red bold message on white background:

tm.Println(tm.Backgound(tm.Color(tm.Bold("Important header"), tm.RED), tm.WHITE))

Create box and move it to center of the screen:

// Create Box with 30% width of current screen, and height of 20 lines
box := tm.NewBox(30|tm.PCT, 20)

// Add some content to the box
// Note that you can add ANY content, even tables
fmt.Fprint(box, "Some box content")

// Move Box to approx center of the screen
tm.Print(tm.MoveTo(box.String(), 40|tm.PCT, 40|tm.PCT))

Draw table:

// Based on http://golang.org/pkg/text/tabwriter
totals := tm.NewTable(0, 10, 5, ' ', 0)
fmt.Fprintf(totals, "Time\tStarted\tActive\tFinished\n")
fmt.Fprintf(totals, "%s\t%d\t%d\t%d\n", "All", started, started-finished, finished)
tm.Println(totals)

Line charts

Chart example:

    import (
        tm "github.com/buger/goterm"
    )

    chart := tm.NewLineChart(100, 20)
    
    data := new(tm.DataTable)
    data.addColumn("Time")
    data.addColumn("Sin(x)")
	data.addColumn("Cos(x+1)")

    for i := 0.1; i < 10; i += 0.1 {
		data.addRow(i, math.Sin(i), math.Cos(i+1))
	}
    
    tm.Println(chart.Draw(data))

Drawing 2 separate graphs in different scales. Each graph have its own Y axe.

chart.Flags = tm.DRAW_INDEPENDENT

Drawing graph with relative scale (Grapwh draw starting from min value instead of zero)

chart.Flags = tm.DRAW_RELATIVE

Documentation

Overview

Provides basic bulding blocks for advanced console UI

Coordinate system:

1/1---X---->
 |
 Y
 |
 v

Documentation for ANSI codes: http://en.wikipedia.org/wiki/ANSI_escape_code#Colors

Inspired by: http://www.darkcoding.net/software/pretty-command-line-console-output-on-unix-in-python-and-go-lang/

Index

• Constants
• Variables
• func Background(str string, color int) string
• func Bold(str string) string
• func Clear()
• func Color(str string, color int) string
• func CurrentHeight() int
• func Flush()
• func GetXY(x int, y int) (int, int)
• func Height() int
• func MoveCursor(x int, y int)
• func MoveTo(str string, x int, y int) (out string)
• func Print(a ...interface{})
• func Printf(format string, a ...interface{})
• func Println(a ...interface{})
• func Width() int
• type Box
  • func NewBox(width, height int, flags int) *Box
  • func (b *Box) String() (out string)
  • func (b *Box) Write(p []byte) (int, error)
• type Chart
• type DataTable
  • func (d *DataTable) AddColumn(name string)
  • func (d *DataTable) AddRow(elms ...float64)
• type LineChart
  • func NewLineChart(width, height int) *LineChart
  • func (c *LineChart) Draw(data *DataTable) (out string)
  • func (c *LineChart) DrawAxes(maxX, minX, maxY, minY float64, index int)
  • func (c *LineChart) DrawLine(x0, y0, x1, y1 int, symbol string)
• type Table
  • func NewTable(minwidth, tabwidth, padding int, padchar byte, flags uint) *Table
  • func (t *Table) String() string

Constants

const (
	AXIS_LEFT = iota
	AXIS_RIGHT
)

const (
	DRAW_INDEPENDENT = 1 << iota
	DRAW_RELATIVE
)

const (
	BLACK = iota
	RED
	GREEN
	YELLOW
	BLUE
	MAGENTA
	CYAN
	WHITE
)

List of possible colors

const DEFAULT_BORDER = "- │ ┌ ┐ └ ┘"

const PCT = 0x80000000

Set percent flag: num | PCT

Check percent flag: num & PCT

Reset percent flag: num & 0xFF

const RESET = "\033[0m"

Reset all custom styles

const RESET_COLOR = "\033[32m"

Reset to default color

Variables

var Screen *bytes.Buffer = new(bytes.Buffer)

Global screen buffer Its not recommented write to buffer dirrectly, use package Print,Printf,Println fucntions instead.

Functions

func Background

func Background(str string, color int) string

Change background color of string:

tm.Background("string", tm.RED)

func Bold

func Bold(str string) string

Make bold

func Clear

func Clear()

Clear screen

func Color

func Color(str string, color int) string

Apply given color to string:

tm.Color("RED STRING", tm.RED)

func CurrentHeight

func CurrentHeight() int

Get current height. Line count in Screen buffer.

func Flush

func Flush()

Flush buffer and ensure that it will not overflow screen

func GetXY

func GetXY(x int, y int) (int, int)

Get relative or absolute coorditantes To get relative, set PCT flag to number:

// Get 10% of total width to `x` and 20 to y
x, y = tm.GetXY(10|tm.PCT, 20)

func Height

func Height() int

Get console height

func MoveCursor

func MoveCursor(x int, y int)

Move cursor to given position

func MoveTo

func MoveTo(str string, x int, y int) (out string)

Move string to possition

func Print

func Print(a ...interface{})

func Printf

func Printf(format string, a ...interface{})

func Println

func Println(a ...interface{})

func Width

func Width() int

Get console width

Types

type Box

type Box struct {
	Buf *bytes.Buffer

	Width  int
	Height int

	// To get even padding: PaddingX ~= PaddingY*4
	PaddingX int
	PaddingY int

	// Should contain 6 border pieces separated by spaces
	//
	// Example border:
	//   "- │ ┌ ┐ └ ┘"
	Border string

	Flags int // Not used now
}

Box allows you to create independent parts of screen, with its own buffer and borders. Can be used for creating modal windows

Generates boxes likes this: ┌--------┐ │hello │ │world │ │ │ └--------┘

func NewBox

func NewBox(width, height int, flags int) *Box

Create new Box. Width and height can be relative:

// Create box with 50% with of current screen and 10 lines height
box := tm.NewBox(50|tm.PCT, 10, 0)

func (*Box) String

func (b *Box) String() (out string)

Render Box

func (*Box) Write

func (b *Box) Write(p []byte) (int, error)

type Chart

type Chart interface {
	Draw(data DataTable, flags int) string
}

type DataTable

type DataTable struct {
	// contains filtered or unexported fields
}

func (*DataTable) AddColumn

func (d *DataTable) AddColumn(name string)

func (*DataTable) AddRow

func (d *DataTable) AddRow(elms ...float64)

type LineChart

type LineChart struct {
	Buf []string

	Width  int
	Height int

	Flags int
	// contains filtered or unexported fields
}

func NewLineChart

func NewLineChart(width, height int) *LineChart

func (*LineChart) Draw

func (c *LineChart) Draw(data *DataTable) (out string)

func (*LineChart) DrawAxes

func (c *LineChart) DrawAxes(maxX, minX, maxY, minY float64, index int)

func (*LineChart) DrawLine

func (c *LineChart) DrawLine(x0, y0, x1, y1 int, symbol string)

type Table

type Table struct {
	tabwriter.Writer

	Buf *bytes.Buffer
}

Tabwriter with own buffer:

    	totals := tm.NewTable(0, 10, 5, ' ', 0)
		fmt.Fprintf(totals, "Time\tStarted\tActive\tFinished\n")
		fmt.Fprintf(totals, "%s\t%d\t%d\t%d\n", "All", started, started-finished, finished)
		tm.Println(totals)

 Based on http://golang.org/pkg/text/tabwriter

func NewTable

func NewTable(minwidth, tabwidth, padding int, padchar byte, flags uint) *Table

Same as here http://golang.org/pkg/text/tabwriter/#Writer.Init

func (*Table) String

func (t *Table) String() string