gridt

README

Gridt

Display contents as a grid in the terminal!

Format unidimensional lists (slices) as grids, with well-defined columns, suitable for fixed-width fonts, for the sake of readability.

It's both a CLI and a Go library.

Inspired by ogham/rust-term-grid and by the fact that I needed it for paemuri/ipe.

Example

What we do not want:

What we want:

Install

Brew

brew tap paemuri/packages
brew install gridt

Go

go install github.com/paemuri/gridt/cmd/gridt

Run

Default

gridt

Runs the program with default configuration. It gets the values from stdin lines.

Flags

-h or --help

Shows the CLI help message.

-v or --version

Shows the CLI version.

-f <file> or --file <file>

Instead of getting the lines from stdin, gets it from a specific file.

-s <sep> or --separator <sep>

Defines what separates every value column. Defaults to " ".

-d <direction> or --direction <direction>

Defines writing direction. It can be top-to-bottom or left-to-right. Defaults to top-to-bottom.

Library usage

// Just create an empty grid...
grid := gridt.New(gridt.TopToBottom, "  ")

// Verify if it fits in a determined width...
dim, ok := grid.FitIntoWidth(100)

// And get its string!
if ok {
  fmt.Print(dim.String())
}

// But also, you can do a lot more!

// Create a grid with pre-defined cells...
grid := gridt.New(gridt.LeftToRight, "  ", "cell1", "cell2", "cell3")

// Manipulate the cells...
grid.Add("cell4", "cell5", "cell6")
grid.Insert(2, "cell2.1", "cell2.3")
grid.Delete(0)

// Base the size of the grid on the number of columns,
// instead of the number of caracters...
dim, ok := grid.FitIntoColumns(3)

License

This project code is in the public domain. See the LICENSE file.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be in the public domain, without any additional terms or conditions.

Documentation

Index

• type Dimensions
  • func (d Dimensions) Bytes() []byte
  • func (d Dimensions) Columns() int
  • func (d Dimensions) Lines() int
  • func (d Dimensions) String() string
  • func (d Dimensions) Widths() []int
• type Direction
• type Grid
  • func New(d Direction, sep string, s ...string) *Grid
  • func (g *Grid) Add(s ...string) *Grid
  • func (g Grid) Cells() []string
  • func (g *Grid) Delete(i ...int) *Grid
  • func (g Grid) Direction() Direction
  • func (g Grid) FitIntoColumns(max int) (dim Dimensions, ok bool)
  • func (g Grid) FitIntoWidth(max int) (dim Dimensions, ok bool)
  • func (g *Grid) Insert(i int, s ...string) *Grid
  • func (g Grid) Separator() string

Types

type Dimensions

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

Dimensions contains the dimensions of the grid and the possibility to format it.

func (Dimensions) Bytes

func (d Dimensions) Bytes() []byte

Bytes formats the grid into a byte slice.

func (Dimensions) Columns

func (d Dimensions) Columns() int

Columns represents the quantity of columns the grid has.

func (Dimensions) Lines

func (d Dimensions) Lines() int

Lines represents the quantity of lines the grid has.

func (Dimensions) String

func (d Dimensions) String() string

String formats the grid into a string.

func (Dimensions) Widths

func (d Dimensions) Widths() []int

Widths represents the widths of each column in the grid.

type Direction

type Direction int8

Direction represents the direction in which the values will be written.

const (
	// LeftToRight is a direction in which the values will be written.
	// It goes from the first cell (0,0) to the end of the line, returning to the beginning of the second line.
	// Exactly the same as a typewritter.
	LeftToRight Direction = iota
	// TopToBottom is a direction in which the values will be written.
	// It goes from the first cell (0,0) to the bottom of the column, returning to the top of the second column.
	// Exactly the same as how `ls` command works by default.
	TopToBottom
)

type Grid

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

Grid represents the values' grid, that will be exported as a pretty formatted string.

func New

func New(d Direction, sep string, s ...string) *Grid

New returns a new Grid. `d` represents the direction in which the values will be written. `sep` represents the separator; a string that will be between each column. `s` is the cells that will be added right after initialization.

func (*Grid) Add

func (g *Grid) Add(s ...string) *Grid

Add adds a cell to the grid. `s` is the values that will be added.

func (Grid) Cells

func (g Grid) Cells() []string

Cells returns all cells of the grid.

func (*Grid) Delete

func (g *Grid) Delete(i ...int) *Grid

Delete deletes a value in a specified position in the grid. `i` the position of the value.

func (Grid) Direction

func (g Grid) Direction() Direction

Direction returns the direction in which the grid will be written.

func (Grid) FitIntoColumns

func (g Grid) FitIntoColumns(max int) (dim Dimensions, ok bool)

FitIntoColumns formats the grid, based on a maximum quantity of columns. `max` represents the maximum quantity of columns of the grid. `dim` represents the dimensions of the grid, used for formatting. See `Dimensions`. `ok` says whether the the grid fits in the maximum width informed. If false, discard `dim`.

func (Grid) FitIntoWidth

func (g Grid) FitIntoWidth(max int) (dim Dimensions, ok bool)

FitIntoWidth formats the grid, based on a maximum width. `max` represents the maximum width of the grid, based on characters. `dim` represents the dimensions of the grid, used for formatting. See `Dimensions`. `ok` says whether the the grid fits in the maximum width informed. If false, discard `dim`.

func (*Grid) Insert

func (g *Grid) Insert(i int, s ...string) *Grid

Insert inserts a value in a specified position in the grid. `i` the position of the value. `s` is the value that will be added.

func (Grid) Separator

func (g Grid) Separator() string

Separator returns the separator; the string that will be between each column.