reflectable

Documentation

Overview

Package reflectable implements facilities for formatting arbitrary Go values into human-readable tables, using reflection.

Package reflectable provides facilities for formatting arbitrary Go values into human-readable tables using reflection. It supports multiple output formats and can handle complex Go data structures including structs, slices, maps, and primitive types.

Responsibilities

This package is responsible for:

• Using Go reflection to introspect arbitrary values and their types.
• Converting Go values into tabular representations with configurable formatting options.
• Supporting multiple output formats including human-readable tables, Markdown tables, and CSV.
• Providing struct field customization through tags for display names, alignment, sorting, and visibility.
• Handling complex data structures like nested structs, slices of structs, and maps.

Usage Context

This package is used by command implementations that need to display structured data to users in a consistent, readable format. It enables commands to output query results, configuration data, and other structured information in tables that can be easily consumed by both humans and tools.

The main entry point is FormatValue, which takes formatting options and an arbitrary Go value and returns a formatted string representation.

Example Usage

// Basic usage
options := reflectable.NewOptions()
result, err := reflectable.FormatValue(options, someStruct)

// Struct field customization via tags
type MyStruct struct {
	LongerFieldName string `table:"name,omitempty"`
}

Index

• func FormatValue(options *Options, value interface{}) (result string, err error)
• func FormatValueUsingWriter(writer TableWriter, value interface{})
• type Format
• type Options
  • func NewOptions() *Options
  • func (o *Options) WithColor(enabled bool) *Options
  • func (o *Options) WithFormat(format Format) *Options
  • func (o *Options) WithMaxTableWidth(maxTableWidth int) *Options
• type TableProperties
• type TableWriter

Functions

func FormatValue

func FormatValue(options *Options, value interface{}) (result string, err error)

FormatValue formats the given value as a table, using the go-pretty pretty table package.

func FormatValueUsingWriter

func FormatValueUsingWriter(writer TableWriter, value interface{})

FormatValueUsingWriter formats and writes a value as a table using the provided tableWriter.

Types

type Format

type Format int

Format for table output.

const (
	// FormatTable emits the table in human-readable format (not machine-readable).
	FormatTable Format = iota
	// FormatMarkdown emits the table in Markdown format.
	FormatMarkdown
	// FormatCSV emits the table in CSV format.
	FormatCSV
)

type Options

type Options struct {
	// Format for table output.
	Format Format
	// Maximum width for tables.
	MaxTableWidth int
	// Enable colorized output?
	ColorEnabled bool
}

Options encapsulates options for formatting and displaying tables.

func NewOptions

func NewOptions() *Options

NewOptions constructs new Options with default values.

func (*Options) WithColor

func (o *Options) WithColor(enabled bool) *Options

WithColor enables or disables colorized output.

func (*Options) WithFormat

func (o *Options) WithFormat(format Format) *Options

WithFormat sets the format for table output.

func (*Options) WithMaxTableWidth

func (o *Options) WithMaxTableWidth(maxTableWidth int) *Options

WithMaxTableWidth sets the maximum width for tables.

type TableProperties

type TableProperties struct {
	// Whether the first column is a header
	HeaderColumn bool
}

type TableWriter

type TableWriter interface {
	// Starts a new table.
	StartTable(properties TableProperties)
	// Ends the current open table.
	EndTable()

	// Starts a new header row.
	StartHeaderRow()
	// Ends the current open header row.
	EndHeaderRow()
	// Starts a new (non-header) row.
	StartRow()
	// Ends the current (non-header) row.
	EndRow()

	// Starts a new column in the current open row.
	StartColumn()
	// Ends the current open column; does not close the open row.
	EndColumn()

	// Right-aligns the column at the given index.
	RightAlignColumn(index int)
	// Requests sorting by the values in the column at the given index.
	SortByColumn(index int)

	// Writes a value to the current open column.
	WriteValue(value interface{})

	// Checks if we're currently in a table.
	InTable() bool
}

TableWriter is an interface for writing tabular data. It provides methods to manage tables, rows, columns, and their properties.