textcolumns

Documentation

Overview

Package textcolumns helps to output structs (and events of structs) using metadata from a `Columns` instance in a tabular way suitable for consoles or other frontends using fixed-width characters / fonts.

It can automatically size the output tables according to either screen size or content and provides some helpful tools to get a consistent output.

Initializing

You can create a new formatter by calling

tc := textcolumns.NewFormatter(columnMap)

You can specify options by adding one or more of the WithX() functions to the initializer. The columns.ColumnMap can be obtained by calling columns.GetColumpMap on your `Column` instance.

Output

After you have initialized the formatter, you can use

tc.FormatHeader()

to obtain the header line as string, which will look something like this:

NODE                PID COMM             NAME                                 TIME

You can also pass a filled struct to

tc.FormatEntry(&event)

to get a string like this:

Node1                 2 AAA                                                   12ns

Even simpler, use

tc.WriteTable(os.Stdout, entries)

to directly print the whole table:

NODE                PID COMM             NAME                                 TIME
----------------------------------------------------------------------------------
Node1                 2 AAA                                                   12ns
Node1                 1 AAA              Yay                           14.677772ms
Node1                 2 AnotherComm                                    24.645772ms
Node2                 4 BBB                                           3.462217772s
Node2                 3 BBB                                                  333ns

Custom Columns

By default, Columns will show all fields that have a column tag without the `hide` attribute. Using

tc.SetShowColumns("node,time")

you can adjust the output to contain exactly the specified columns.

Index

• Constants
• func GetTerminalWidth() int
• type Column
• type HeaderStyle
• type Option
  • func WithAutoScale(autosScale bool) Option
  • func WithColumnDivider(divider string) Option
  • func WithDefaultColumns(columns []string) Option
  • func WithHeaderStyle(headerStyle HeaderStyle) Option
  • func WithRowDivider(divider string) Option
  • func WithShouldTruncate(ellipsis bool) Option
• type Options
  • func DefaultOptions() *Options
• type TextColumnsFormatter
  • func NewFormatter[T any](columns columns.ColumnMap[T], options ...Option) *TextColumnsFormatter[T]
  • func (tf *TextColumnsFormatter[T]) AdjustWidthsToContent(entries []*T, considerHeaders bool, maxWidth int, force bool)
  • func (tf *TextColumnsFormatter[T]) AdjustWidthsToScreen()
  • func (tf *TextColumnsFormatter[T]) FormatEntry(entry *T) string
  • func (tf *TextColumnsFormatter[T]) FormatHeader() string
  • func (tf *TextColumnsFormatter[T]) FormatRowDivider() string
  • func (tf *TextColumnsFormatter[T]) FormatTable(entries []*T) string
  • func (tf *TextColumnsFormatter[T]) RecalculateWidths(maxWidth int, force bool)
  • func (tf *TextColumnsFormatter[T]) SetAutoScale(enableAutoScale bool)
  • func (tf *TextColumnsFormatter[T]) SetShowColumns(columns []string) error
  • func (tf *TextColumnsFormatter[T]) SetShowDefaultColumns()
  • func (tf *TextColumnsFormatter[T]) WriteTable(writer io.Writer, entries []*T) error

Constants

const (
	DividerSpace = " "
	DividerTab   = "\t"
	DividerDash  = "—"
	DividerNone  = ""
)

Functions

func GetTerminalWidth

func GetTerminalWidth() int

GetTerminalWidth returns the width of the terminal (if one is in use) or 0 otherwise

Types

type Column

type Column[T any] struct {
	// contains filtered or unexported fields
}

type HeaderStyle

type HeaderStyle int

const (
	HeaderStyleNormal HeaderStyle = iota
	HeaderStyleUppercase
	HeaderStyleLowercase
)

type Option

type Option func(*Options)

func WithAutoScale

func WithAutoScale(autosScale bool) Option

WithAutoScale sets whether auto-scaling to screen width should be enabled

func WithColumnDivider

func WithColumnDivider(divider string) Option

WithColumnDivider sets the string that should be used as divider between columns

func WithDefaultColumns

func WithDefaultColumns(columns []string) Option

WithDefaultColumns sets the columns that should be displayed by default

func WithHeaderStyle

func WithHeaderStyle(headerStyle HeaderStyle) Option

WithHeaderStyle sets the style to be used for the table header

func WithRowDivider

func WithRowDivider(divider string) Option

WithRowDivider sets the string that should be used (repeatedly) to build the divider between header and content

func WithShouldTruncate

func WithShouldTruncate(ellipsis bool) Option

WithShouldTruncate sets whether strings should be truncated.

type Options

type Options struct {
	AutoScale      bool        // if enabled, the screen size will be used to scale the widths
	ColumnDivider  string      // defines the string that should be used as spacer in between columns (default " ")
	DefaultColumns []string    // defines which columns to show by default; will be set to all visible columns if nil
	HeaderStyle    HeaderStyle // defines how column headers are decorated (e.g. uppercase/lowercase)
	RowDivider     string      // defines the (to be repeated) string that should be used below the header
	ShouldTruncate bool        // defines whether to truncate strings or not
}

func DefaultOptions

func DefaultOptions() *Options

type TextColumnsFormatter

type TextColumnsFormatter[T any] struct {
	// contains filtered or unexported fields
}

func NewFormatter

func NewFormatter[T any](columns columns.ColumnMap[T], options ...Option) *TextColumnsFormatter[T]

NewFormatter returns a TextColumnsFormatter that will turn entries of type T into tables that can be shown on terminals or other frontends using fixed-width characters

func (*TextColumnsFormatter[T]) AdjustWidthsToContent

func (tf *TextColumnsFormatter[T]) AdjustWidthsToContent(entries []*T, considerHeaders bool, maxWidth int, force bool)

AdjustWidthsToContent will calculate widths of columns by getting the maximum length found for each column in the input array. If considerHeaders is true, header lengths will also be considered when calculating. If maxWidth > 0, space will be reduced to accordingly to match the given width. If force is true, fixed widths will be ignored and scaled as well in the case that maxWidths is exceeded.

func (*TextColumnsFormatter[T]) AdjustWidthsToScreen

func (tf *TextColumnsFormatter[T]) AdjustWidthsToScreen()

AdjustWidthsToScreen will try to get the width of the screen buffer and, if successful, call RecalculateWidths with that value

func (*TextColumnsFormatter[T]) FormatEntry

func (tf *TextColumnsFormatter[T]) FormatEntry(entry *T) string

FormatEntry returns an entry as a formatted string, respecting the given formatting settings

func (*TextColumnsFormatter[T]) FormatHeader

func (tf *TextColumnsFormatter[T]) FormatHeader() string

FormatHeader returns the formatted header line with all visible column names, separated by ColumnDivider

func (*TextColumnsFormatter[T]) FormatRowDivider

func (tf *TextColumnsFormatter[T]) FormatRowDivider() string

FormatRowDivider returns a string that repeats the defined RowDivider until the total length of a row is reached

func (*TextColumnsFormatter[T]) FormatTable

func (tf *TextColumnsFormatter[T]) FormatTable(entries []*T) string

FormatTable returns header, divider and the formatted entries with the current settings as a string

func (*TextColumnsFormatter[T]) RecalculateWidths

func (tf *TextColumnsFormatter[T]) RecalculateWidths(maxWidth int, force bool)

RecalculateWidths sets the screen width and automatically scales columns to fit (if enabled in options) If force is true, fixed widths will also be adjusted.

func (*TextColumnsFormatter[T]) SetAutoScale

func (tf *TextColumnsFormatter[T]) SetAutoScale(enableAutoScale bool)

SetAutoScale enables or disables the AutoScale option for the formatter. This will recalculate the widths.

func (*TextColumnsFormatter[T]) SetShowColumns

func (tf *TextColumnsFormatter[T]) SetShowColumns(columns []string) error

SetShowColumns takes a list of column names that will be displayed when using the output methods Returns an error if any of the columns is not available.

func (*TextColumnsFormatter[T]) SetShowDefaultColumns

func (tf *TextColumnsFormatter[T]) SetShowDefaultColumns()

SetShowDefaultColumns resets the shown columns to those defined by default

func (*TextColumnsFormatter[T]) WriteTable

func (tf *TextColumnsFormatter[T]) WriteTable(writer io.Writer, entries []*T) error

WriteTable writes header, divider and the formatted entries with the current settings to writer