columnize

README

Columnize

Easy column-formatted output for golang. Now with color.

Forked from github.com/CiscoCloud/columnize which was forked from github.com/ryanuber/columnize

Columnize is a really small Go package that makes building CLI's a little bit easier. In some CLI designs, you want to output a number similar items in a human-readable way with nicely aligned columns. However, figuring out how wide to make each column is a boring problem to solve and eats your valuable time.

Here is an example:

package main

import (
    "fmt"
    "github.com/StephanieSunshine/columnize"
)

func main() {
    output := []string{
        "Name | Gender | Age",
        "Bob | Male | 38",
        "Sally | Female | 26",
    }
    result := columnize.SimpleFormat(output)
    fmt.Println(result)
}

As you can see, you just pass in a list of strings. And the result:

Name   Gender  Age
Bob    Male    38
Sally  Female  26

Columnize is tolerant of missing or empty fields, or even empty lines, so passing in extra lines for spacing should show up as you would expect.

Configuration

Columnize is configured using a Config, which can be obtained by calling the DefaultConfig() method. You can then tweak the settings in the resulting Config:

config := columnize.DefaultConfig()
config.Delim = "|"
config.Glue = "  "
config.Prefix = ""
config.Empty = ""
config.MaxWidth = []int{10, 0, 0}
config.OutputWidth = 80
config.HeaderColors = nil
config.BodyColors = nil

• Delim is the string by which columns of input are delimited
• Glue is the string by which columns of output are delimited
• Prefix is a string by which each line of output is prefixed
• Empty is a string used to replace blank values found in output
• MaxWidth is an int slice specifying the maximum width of each column.
• OutputWidth is an int specifying the maximum width of an output line.
• HeaderColors is a pointer to a slice of color.In(s any) string {} functions. See github.com/TwiN/go-color for more info.
• BodyColors is a pointer to a slice of color.In(s any) string {} functions. See github.com/TwiN/go-color for more info.

If MaxWidth or OutputWidth is specified and output exceeds the configured width, Columnize breaks a column at a word boundary and continues it on the next line. See below for details.

You can then pass the Config in using the Format method (signature below) to have text formatted to your liking.

Usage

SimpleFormat(intput []string) string

Format(input []string, config *Config) string

Colorizing Fields

Header and body fields can have a specific cell color. See github.com/TwiN/go-color for more info.

config.HeaderColors = &ColorList{color.InRed, color.InGreen}
config.BodyColors = &ColorList{color.InRed, color.InGreen}

Controlling Output Width

Output exceeding the width of the terminal window - particularly columnized output - can be difficult to read. To address this, Columnize provides two configuration parameters for controlling output width.

• MaxWidth is an int slice specifying the maximum width of each column. If the data for a column exceeds its maximum width, Columnize formats the column into two or more lines by breaking its data at a word boundary and continuing it onto the next line. A zero or missing value for a MaxWidth element specifies that the corresponding column is uncontrolled (no maximum width).
• OutputWidth is an int value specifying the maximum width of the entire output line (including prefix and glue). If data width exceeds this value, Columnize sets a MaxWidth for the rightmost uncontrolled column so that the output width satisfies the restriction. You can specify OutputWidth: columnize.AUTO to use the actual width of the terminal window for OutputWidth.

For example:

input := []string{
	"Column a | Column b | Column c",
	"xx | yy | zz",
	"some quite long data | some more data | even longer data for the last column",
	"this one will fit | a break | The quick brown fox jumps over the low lazy dog",
	"qq | rr | ss",
}
config := Config{MaxWidth: []int{10, 0, 15}}
output := Format(input, &config)

results in the output:

Column a    Column b        Column c
xx          yy              zz
some quite  some more data  even longer
long data                   data for the
                            last column
this one    a break         The quick brown
will fit                    fox jumps over
                            the low lazy
                            dog
qq          rr              ss

Specify OutputWidth to restrict the entire output line. For example, the configuration:

config := Config{
   OutputWidth: columnize.AUTO,
}

causes the entire output line to fit in the terminal window. Columnize modifies data lines exceeding the width of the window by setting the appropriate MaxWidth for the last column of data. Columnize adjusts the last uncontrolled column, so if you want it to adjust a column other than the last, specify an explicit MaxWidth for any columns to the right of the one you want Columnize to adjust.

Documentation

Index

• Constants
• func Format(lines []string, config *Config) string
• func GetConsoleWidth() (width int, e error)
• func SimpleFormat(lines []string) string
• type ColorList
• type Config
  • func DefaultConfig() *Config
  • func MergeConfig(a, b *Config) *Config

Constants

const (
	AUTO = -1
)

Functions

func Format

func Format(lines []string, config *Config) string

Format is the public-facing interface that takes either a plain string or a list of strings and returns nicely aligned output.

func GetConsoleWidth

func GetConsoleWidth() (width int, e error)

Get the width of the console

func SimpleFormat

func SimpleFormat(lines []string) string

Convenience function for using Columnize as easy as possible.

Types

type ColorList

type ColorList []func(s any) string

Cellcolor slice

type Config

type Config struct {
	// The string by which the lines of input will be split.
	Delim string

	// The string by which columns of output will be separated.
	Glue string

	// The string by which columns of output will be prefixed.
	Prefix string

	// A replacement string to replace empty fields
	Empty string

	// Maximum width of output; set to AUTO to use actual console width
	OutputWidth int

	// Maximum width of each column
	MaxWidth []int

	// Header colors
	// Function to call that returns colored output
	// Check out github.com/TwiN/go-color color.In[Color]() functions
	// Pointer incase user never sets it
	HeaderColors *ColorList

	// Body colors
	BodyColors *ColorList
}

func DefaultConfig

func DefaultConfig() *Config

Returns a Config with default values.

func MergeConfig

func MergeConfig(a, b *Config) *Config

MergeConfig merges two config objects together and returns the resulting configuration. Values from the right take precedence over the left side.