format

type CSVFormatter ¶

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

CSVFormatter provides shared CSV formatting logic for both buffered and streaming modes.

func NewCSVFormatter(out io.Writer, skipHeaders bool) *CSVFormatter

func (f *CSVFormatter) FinishFormat() error

func (f *CSVFormatter) InitFormat(columnNames []string, config FormatConfig, previewRows []Row) error

func (f *CSVFormatter) WriteRow(row Row) error

type Cell ¶ added in v0.28.0

type Cell interface {
	// Format returns styled text for display (may include ANSI codes).
	// Called by tablewriter via tw.Formatter interface when FormatConfig.Styled is true.
	// When Styled is false, callers should use RawText() instead.
	Format() string

	// RawText returns plain text without styling.
	// Used by non-table formatters (CSV, XML, etc.) that must not contain ANSI codes.
	RawText() string

	// WithText creates a new Cell with replaced text but preserved styling behavior.
	// Used by table formatters after width-wrapping to carry styling through.
	WithText(text string) Cell
}

Cell is the interface for a single formatted cell. The format package is agnostic to the concrete type — it only calls these methods. Concrete adapters (PlainCell, StyledCell) implement styling logic.

Cell also satisfies tw.Formatter (via Format()), enabling per-cell styling when passed to tablewriter.

type ColumnHint ¶ added in v0.29.0

type ColumnHint struct {
	// PreferredMinWidth is the width needed to avoid wrapping all NoWrap cells
	// in this column. Strategies should try to satisfy this but may go below
	// if space is tight.
	PreferredMinWidth int
}

ColumnHint carries per-column metadata that strategies can use for allocation.

type FormatConfig ¶

type FormatConfig struct {
	TabWidth        int
	Verbose         bool
	SkipColumnNames bool
	SQLTableName    string
	SQLBatchSize    int64
	PreviewRows     int64
	Styled          bool                // When true, table output uses Cell.Format() (may include ANSI codes). When false, uses RawText().
	WidthStrategy   enums.WidthStrategy // Column width allocation algorithm. Zero value = GreedyFrequency (default).
	TabVisualize    bool                // When true, visualize tab characters with → symbol in table output.
}

FormatConfig holds configuration values needed by formatters. This replaces the dependency on *systemVariables, exposing only the fields that formatters actually use.

type FormatFunc ¶

type FormatFunc func(out io.Writer, rows []Row, columnNames []string, config FormatConfig, screenWidth int) error

FormatFunc is a function type that formats and writes result data. It takes an output writer, rows, column names, config, and screen width.

func NewFormatter(mode Mode) (FormatFunc, error)

type FormatFuncFactory ¶ added in v0.28.0

type FormatFuncFactory func(mode Mode) (FormatFunc, error)

FormatFuncFactory creates a buffered FormatFunc for the given mode. The mode parameter allows a single factory to handle multiple related modes.

type GreedyFrequencyStrategy ¶ added in v0.29.0

type GreedyFrequencyStrategy struct{}

GreedyFrequencyStrategy implements the original frequency-based greedy expansion algorithm. It starts with header-proportional widths, then greedily expands columns that would benefit the most cells (highest frequency count).

func (GreedyFrequencyStrategy) CalculateWidths(wc *widthCalculator, availableWidth int,
	headers []string, rows []Row, hints []ColumnHint,
) []int

type HTMLFormatter ¶

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

HTMLFormatter provides streaming HTML table output.

func NewHTMLFormatter(out io.Writer, skipHeaders bool) *HTMLFormatter

func (f *HTMLFormatter) FinishFormat() error

func (f *HTMLFormatter) InitFormat(columnNames []string, config FormatConfig, previewRows []Row) error

func (f *HTMLFormatter) WriteRow(row Row) error

type MarginalCostStrategy ¶ added in v0.29.0

type MarginalCostStrategy struct{}

MarginalCostStrategy minimizes total wrap-lines across all cells using a greedy max-heap approach. At each step, it allocates one extra character to the column that yields the largest reduction in total wrap-lines.

Complexity: O(availableWidth * log(numCols)).

func (MarginalCostStrategy) CalculateWidths(wc *widthCalculator, availableWidth int,
	headers []string, rows []Row, hints []ColumnHint,
) []int

type Mode ¶ added in v0.28.0

type Mode string

Mode represents the output format mode as a string. Built-in modes are defined as constants below. Custom modes can be registered via RegisterFormatFunc and RegisterStreamingFormatter.

Mode values use UPPER_SNAKE_CASE to match the enumer-generated strings of enums.DisplayMode, enabling conversion via format.Mode(dm.String()).

const (
	ModeUnspecified        Mode = "UNSPECIFIED"
	ModeTable              Mode = "TABLE"
	ModeTableComment       Mode = "TABLE_COMMENT"
	ModeTableDetailComment Mode = "TABLE_DETAIL_COMMENT"
	ModeVertical           Mode = "VERTICAL"
	ModeTab                Mode = "TAB"
	ModeHTML               Mode = "HTML"
	ModeXML                Mode = "XML"
	ModeCSV                Mode = "CSV"
)

func (m Mode) IsTableMode() bool

type NoWrapCell ¶ added in v0.29.0

type NoWrapCell struct {
	Cell
}

NoWrapCell wraps any Cell to indicate its content should preferably not be wrapped. Strategies use this to compute PreferredMinWidth per column so that short values like NULL, true, false are kept intact when space allows.

func (c NoWrapCell) WithText(s string) Cell

type PlainCell ¶ added in v0.28.0

type PlainCell struct {
	Text string
}

PlainCell is the simplest Cell implementation — no styling. Used by client-side statements (SHOW, DESCRIBE, DUMP) and tests.

func (c PlainCell) Format() string

func (c PlainCell) RawText() string

func (c PlainCell) WithText(s string) Cell

type ProportionalStrategy ¶ added in v0.29.0

type ProportionalStrategy struct{}

ProportionalStrategy allocates column widths proportionally to each column's natural width (the maximum width across header and all rows). It starts with header-proportional + minColumnWidth floor, then distributes remaining space proportionally to each column's deficit.

func (ProportionalStrategy) CalculateWidths(wc *widthCalculator, availableWidth int,
	headers []string, rows []Row, hints []ColumnHint,
) []int

type Row ¶

type Row = []Cell

Row is a slice of Cell representing one row of formatted data.

func StringsToRow(ss ...string) Row

type StreamingFormatter ¶

type StreamingFormatter interface {
	// InitFormat is called once with column names and configuration.
	// For table formats, previewRows contains the first N rows for width calculation.
	// For other formats, previewRows may be empty as they don't need preview.
	InitFormat(columnNames []string, config FormatConfig, previewRows []Row) error

	// WriteRow outputs a single row.
	WriteRow(row Row) error

	// FinishFormat completes the output (e.g., closing tags, final flush).
	FinishFormat() error
}

StreamingFormatter defines the interface for format-specific streaming output. Each format (CSV, TAB, etc.) implements this interface to handle streaming output.

func NewStreamingFormatter(mode Mode, out io.Writer, config FormatConfig) (StreamingFormatter, error)

type StreamingFormatterFactory ¶ added in v0.28.0

type StreamingFormatterFactory func(mode Mode, out io.Writer, config FormatConfig) (StreamingFormatter, error)

StreamingFormatterFactory creates a StreamingFormatter for the given mode. The mode parameter allows a single factory to handle multiple related modes.

type StyledCell ¶ added in v0.28.0

type StyledCell struct {
	Text  string
	Style string // ANSI SGR sequence, e.g. "\033[32m" for green, "\033[1m" for bold
}

StyledCell renders values with a configurable ANSI SGR sequence. Used for type-based styling (e.g., STRING → green, INT64 → bold, NULL → dim). The Style field holds an ANSI SGR sequence (e.g., "\033[32m" for green). In the styled path, wrapRowStyled handles SGR carry-over across line breaks, so Format() only needs to wrap the entire text — no per-line logic needed.

func (c StyledCell) Format() string

func (c StyledCell) RawText() string

func (c StyledCell) WithText(s string) Cell

type TabFormatter ¶

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

TabFormatter provides shared tab-separated formatting logic.

func NewTabFormatter(out io.Writer, skipHeaders bool) *TabFormatter

func (f *TabFormatter) FinishFormat() error

func (f *TabFormatter) InitFormat(columnNames []string, config FormatConfig, previewRows []Row) error

func (f *TabFormatter) WriteRow(row Row) error

type TableParams ¶

type TableParams struct {
	// VerboseHeaders contains header strings rendered with type information.
	// These may include newlines (e.g., "Name\nSTRING") and are used for display
	// when Verbose mode is enabled.
	VerboseHeaders []string
	ColumnAlign    []tw.Align
}

TableParams holds additional parameters for table formatting that are not part of the standard FormatConfig (used only by table format).

type TableStreamingFormatter ¶

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

TableStreamingFormatter provides table output using tablewriter. It supports both streaming mode (output as rows arrive) and buffered mode (collect all rows, then render). This is the single table rendering engine used by both the streaming and buffered code paths.

func NewTableFormatterForBuffered(out io.Writer, config FormatConfig, screenWidth int, mode Mode, params TableParams) *TableStreamingFormatter

func NewTableStreamingFormatter(out io.Writer, config FormatConfig, screenWidth int, previewSize int, mode Mode) *TableStreamingFormatter

func (f *TableStreamingFormatter) FinishFormat() error

func (f *TableStreamingFormatter) InitFormat(columnNames []string, config FormatConfig, previewRows []Row) error

func (f *TableStreamingFormatter) WriteRow(row Row) error

type ValueFormatMode ¶ added in v0.28.0

type ValueFormatMode int

ValueFormatMode specifies how row values should be formatted before being passed to a formatter. This allows formatters to declare their value formatting requirements, decoupling the value formatting decision from mode-name checks in execute_sql.go.

const (
	// DisplayValues formats values for human display (e.g., NULL as "NULL" text,
	// timestamps in readable format). This is the default for built-in modes.
	DisplayValues ValueFormatMode = iota

	// SQLLiteralValues formats values as valid SQL literals (e.g., NULL keyword,
	// strings quoted, bytes as hex). Used by SQL export modes.
	SQLLiteralValues
)

func ValueFormatModeFor(mode Mode) ValueFormatMode

type VerticalFormatter ¶

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

VerticalFormatter provides shared vertical formatting logic.

func NewVerticalFormatter(out io.Writer) *VerticalFormatter

func (f *VerticalFormatter) FinishFormat() error

func (f *VerticalFormatter) InitFormat(columnNames []string, config FormatConfig, previewRows []Row) error

func (f *VerticalFormatter) WriteRow(row Row) error

type WidthCount ¶

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

WidthCount tracks the width and frequency of column values.

func (wc WidthCount) Count() int

func (wc WidthCount) Length() int

type WidthStrategy ¶ added in v0.29.0

type WidthStrategy interface {
	CalculateWidths(wc *widthCalculator, availableWidth int,
		headers []string, rows []Row, hints []ColumnHint) []int
}

WidthStrategy defines the interface for pluggable column width algorithms. Strategies receive availableWidth already overhead-subtracted (caller handles table border overhead). The returned slice must have len(headers) elements, each >= minColumnWidth.

func NewWidthStrategy(ws enums.WidthStrategy) WidthStrategy

type XMLFormatter ¶

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

XMLFormatter provides streaming XML output.

func NewXMLFormatter(out io.Writer, skipHeaders bool) *XMLFormatter

func (f *XMLFormatter) FinishFormat() error

func (f *XMLFormatter) InitFormat(columnNames []string, config FormatConfig, previewRows []Row) error

func (f *XMLFormatter) WriteRow(row Row) error