tblfmt

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2021 License: MIT Imports: 18 Imported by: 16

README

About GoDoc Build Status

tblfmt provides a streaming table encoders for result sets (ie, from a database), creating tables like the following:

 author_id | name                  | z
-----------+-----------------------+---
        14 | a	b	c	d  |
        15 | aoeu                 +|
           | test                 +|
           |                       |
        16 | foo\bbar              |
        17 | a	b	\r        +|
           | 	a                  |
        18 | 袈	袈		袈 |
        19 | 袈	袈		袈+| a+
           |                       |
(6 rows)

Installing

Install in the usual Go fashion:

$ go get -u github.com/xo/tblfmt

Using

tblfmt was designed for use by usql and Go's native database/sql types, but will handle any type with the following interface:

// ResultSet is the shared interface for a result set.
type ResultSet interface {
	Next() bool
	Scan(...interface{}) error
	Columns() ([]string, error)
	Close() error
	Err() error
	NextResultSet() bool
}

tblfmt can be used similar to the following:

// _example/main.go
package main

import (
	"log"
	"os"

	_ "github.com/lib/pq"
	"github.com/xo/dburl"
	"github.com/xo/tblfmt"
)

func main() {
	db, err := dburl.Open("postgres://booktest:booktest@localhost")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	result, err := db.Query("select * from authors")
	if err != nil {
		log.Fatal(err)
	}
	defer result.Close()

	enc, err := tblfmt.NewTableEncoder(result,
		// force minimum column widths
		tblfmt.WithWidths([]int{20, 20}),
	)

	if err = enc.EncodeAll(os.Stdout); err != nil {
		log.Fatal(err)
	}
}

Which can produce output like the following:

╔══════════════════════╦═══════════════════════════╦═══╗
║ author_id            ║ name                      ║ z ║
╠══════════════════════╬═══════════════════════════╬═══╣
║                   14 ║ a	b	c	d  ║   ║
║                   15 ║ aoeu                     ↵║   ║
║                      ║ test                     ↵║   ║
║                      ║                           ║   ║
║                    2 ║ 袈	袈		袈 ║   ║
╚══════════════════════╩═══════════════════════════╩═══╝
(3 rows)

Please see the GoDoc listing for the full API.

Testing

Run using standard go test:

$ go test -v

A few environment variables control how testing is done:

  • PSQL_CONN=<connection> - specify local connection string to use with the psql tool for compatibility testing
  • DETERMINISTIC=1 - use a deterministic random seed for the big "random" test

Used like the following:

# retrieve the latest postgres docker image
$ docker pull postgres:latest

# run a postgres database with docker
$ docker run --rm -d -p 127.0.0.1:5432:5432 -e 'POSTGRES_PASSWORD=P4ssw0rd' --name postgres postgres

# do determininstic test and using psql:
$ export DETERMINISTIC=1 PSQL_CONN=postgres://postgres:P4ssw0rd@localhost/?sslmode=disable
$ go test -v

TODO

  1. add center alignment output
  2. allow user to override alignment
  3. finish template implementations for HTML, LaTeX, etc.
  4. add title for tables
  5. finish compatibility with PostgreSQL (psql) output

Documentation

Overview

Package tblfmt provides streaming table encoders for result sets (ie, from a database).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultTableSummary 

func DefaultTableSummary() map[int]func(io.Writer, int) (int, error)

DefaultTableSummary is the default table summary.

func Encode 

func Encode(w io.Writer, resultSet ResultSet, options map[string]string) error

Encode encodes the result set to the writer using the supplied map options.

func EncodeAll 

func EncodeAll(w io.Writer, resultSet ResultSet, options map[string]string) error

EncodeAll encodes all result sets to the writer using the supplied map options.

func EncodeCSV 

func EncodeCSV(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeCSV encodes the result set to the writer as CSV using the supplied encoding options.

func EncodeCSVAll 

func EncodeCSVAll(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeCSVAll encodes all result sets to the writer as CSV using the supplied encoding options.

func EncodeExpanded 

func EncodeExpanded(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeExpanded encodes result set to the writer as a table using the supplied encoding options.

func EncodeExpandedAll 

func EncodeExpandedAll(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeExpandedAll encodes all result sets to the writer as a table using the supplied encoding options.

func EncodeJSON 

func EncodeJSON(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeJSON encodes the result set to the writer as JSON using the supplied encoding options.

func EncodeJSONAll 

func EncodeJSONAll(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeJSONAll encodes all result sets to the writer as JSON using the supplied encoding options.

func EncodeTable 

func EncodeTable(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeTable encodes result set to the writer as a table using the supplied encoding options.

func EncodeTableAll 

func EncodeTableAll(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeTableAll encodes all result sets to the writer as a table using the supplied encoding options.

func EncodeTemplate 

func EncodeTemplate(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeTemplate encodes the result set to the writer using a template from the supplied encoding options.

func EncodeTemplateAll 

func EncodeTemplateAll(w io.Writer, resultSet ResultSet, opts ...Option) error

EncodeTemplateAll encodes all result sets to the writer using a template from the supplied encoding options.

func FromMap 

func FromMap(opts map[string]string) (Builder, []Option)

FromMap creates an encoder for the provided result set, applying the named options.

Types

type Align 

type Align int

Align indicates an alignment direction for a value. 

const (
	AlignLeft Align = iota
	AlignRight
	AlignCenter
)

Align values.

func (Align) String 

func (a Align) String() string

String satisfies the fmt.Stringer interface.

type Builder 

type Builder func(ResultSet, ...Option) (Encoder, error)

Builder is the shared builder interface.

type CSVEncoder 

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

CSVEncoder is an unbuffered CSV encoder for result sets.

func (*CSVEncoder) Encode 

func (enc *CSVEncoder) Encode(w io.Writer) error

Encode encodes a single result set to the writer using the formatting options specified in the encoder.

func (*CSVEncoder) EncodeAll 

func (enc *CSVEncoder) EncodeAll(w io.Writer) error

EncodeAll encodes all result sets to the writer using the encoder settings.

type Encoder 

type Encoder interface {
	Encode(io.Writer) error
	EncodeAll(io.Writer) error
}

Encoder is the shared interface for encoders.

func NewCSVEncoder 

func NewCSVEncoder(resultSet ResultSet, opts ...Option) (Encoder, error)

NewCSVEncoder creates a new CSV encoder using the provided options.

func NewExpandedEncoder 

func NewExpandedEncoder(resultSet ResultSet, opts ...Option) (Encoder, error)

NewExpandedEncoder creates a new table encoder using the provided options.

func NewJSONEncoder 

func NewJSONEncoder(resultSet ResultSet, opts ...Option) (Encoder, error)

NewJSONEncoder creates a new JSON encoder using the provided options.

func NewTableEncoder 

func NewTableEncoder(resultSet ResultSet, opts ...Option) (Encoder, error)

NewTableEncoder creates a new table encoder using the provided options.

func NewTemplateEncoder 

func NewTemplateEncoder(resultSet ResultSet, opts ...Option) (Encoder, error)

NewTemplateEncoder creates a new template encoder using the provided options.

type Error 

type Error string

Error is an error. 

const (
	// ErrResultSetIsNil is the result set is nil error.
	ErrResultSetIsNil Error = "result set is nil"

	// ErrResultSetHasNoColumns is the result set has no columns error.
	ErrResultSetHasNoColumns Error = "result set has no columns"

	// ErrInvalidFormat is the invalid format error.
	ErrInvalidFormat Error = "invalid format"

	// ErrInvalidLineStyle is the invalid line style error.
	ErrInvalidLineStyle Error = "invalid line style"

	// ErrUnknownTemplate is the unknown template error.
	ErrUnknownTemplate Error = "unknown template"
)

Error values.

func (Error) Error 

func (err Error) Error() string

Error satisfies the error interface.

type EscapeFormatter 

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

EscapeFormatter is an escaping formatter, that handles formatting the standard Go types.

If Marshaler is not nil, then it will be passed any map[string]interface{} and []interface{} values encountered. If nil, then the standard encoding/json.Encoder will be used instead.

func NewEscapeFormatter 

func NewEscapeFormatter(opts ...EscapeFormatterOption) *EscapeFormatter

NewEscapeFormatter creates a escape formatter to handle basic Go values, such as []byte, string, time.Time. Formatting for map[string]interface{} and []interface{} will be passed to a marshaler provided by WithMarshaler, otherwise the standard encoding/json.Encoder will be used to marshal those values.

func (*EscapeFormatter) Format 

func (f *EscapeFormatter) Format(vals []interface{}) ([]*Value, error)

Format satisfies the Formatter interface.

func (*EscapeFormatter) Header 

func (f *EscapeFormatter) Header(headers []string) ([]*Value, error)

Header satisfies the Formatter interface.

type EscapeFormatterOption 

type EscapeFormatterOption func(*EscapeFormatter)

EscapeFormatterOption is an escape formatter option.

func WithEscapeJSON 

func WithEscapeJSON(escapeJSON bool) EscapeFormatterOption

WithEscapeJSON is an escape formatter option to escape special JSON characters in non-complex values.

func WithHeaderAlign added in v0.2.0 

func WithHeaderAlign(a Align) EscapeFormatterOption

WithHeaderAlign sets the alignment of header values.

func WithInvalid 

func WithInvalid(invalid string) EscapeFormatterOption

WithInvalid is an escape formatter option to set the invalid value used when an invalid rune is encountered during escaping.

func WithJSONConfig 

func WithJSONConfig(prefix, indent string, escapeHTML bool) EscapeFormatterOption

WithJSONConfig is an escape formatter option to set the JSON encoding prefix, indent value, and whether or not to escape HTML. Passed to the standard encoding/json.Encoder when a marshaler has not been set on the escape formatter.

func WithMarshaler 

func WithMarshaler(marshaler func(interface{}) ([]byte, error)) EscapeFormatterOption

WithMarshaler is an escape formatter option to set a standard Go encoder to use for encoding the value.

func WithMask 

func WithMask(mask string) EscapeFormatterOption

WithMask is an escape formatter option to set the mask used for empty headers.

func WithTimeFormat 

func WithTimeFormat(timeFormat string) EscapeFormatterOption

WithTimeFormat is an escape formatter option to set the time format used for time values.

type Executor added in v0.2.0 

type Executor interface {
	Execute(io.Writer, interface{}) error
}

type ExpandedEncoder 

type ExpandedEncoder struct {
	TableEncoder
}

ExpandedEncoder is a buffered, lookahead expanded table encoder for result sets.

func (*ExpandedEncoder) Encode 

func (enc *ExpandedEncoder) Encode(w io.Writer) error

Encode encodes a single result set to the writer using the formatting options specified in the encoder.

func (*ExpandedEncoder) EncodeAll 

func (enc *ExpandedEncoder) EncodeAll(w io.Writer) error

EncodeAll encodes all result sets to the writer using the encoder settings.

type Formatter 

type Formatter interface {
	// Header returns a slice of formatted values for the provided headers.
	Header([]string) ([]*Value, error)

	// Format returns a slice of formatted value the provided row values.
	Format([]interface{}) ([]*Value, error)
}

Formatter is the common interface for formatting values.

type JSONEncoder 

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

JSONEncoder is an unbuffered JSON encoder for result sets.

func (*JSONEncoder) Encode 

func (enc *JSONEncoder) Encode(w io.Writer) error

Encode encodes a single result set to the writer using the formatting options specified in the encoder.

func (*JSONEncoder) EncodeAll 

func (enc *JSONEncoder) EncodeAll(w io.Writer) error

EncodeAll encodes all result sets to the writer using the encoder settings.

type LineStyle 

type LineStyle struct {
	Top  [4]rune
	Mid  [4]rune
	Row  [4]rune
	Wrap [4]rune
	End  [4]rune
}

LineStyle is a table line style.

See the ASCII, OldASCII, and Unicode styles below for predefined table styles.

Tables generally look like the following: 

+-----------+---------------------------+---+
| author_id |           name            | z |
+-----------+---------------------------+---+
|        14 | a       b       c       d |   |
|        15 | aoeu                     +|   |
|           | test                     +|   |
|           |                           |   |
+-----------+---------------------------+---+

When border is 0, then no surrounding borders will be shown: 

author_id           name            z
--------- ------------------------- -
       14 a       b       c       d
       15 aoeu                     +
          test                     +

When border is 1, then a border between columns will be shown: 

 author_id |           name            | z
-----------+---------------------------+---
        14 | a       b       c       d |
        15 | aoeu                     +|
           | test                     +|
           |                           |

func ASCIILineStyle 

func ASCIILineStyle() LineStyle

ASCIILineStyle is the ASCII line style for tables.

Tables using this style will look like the following: 

+-----------+---------------------------+---+
| author_id |           name            | z |
+-----------+---------------------------+---+
|        14 | a       b       c       d |   |
|        15 | aoeu                     +|   |
|           | test                     +|   |
|           |                           |   |
+-----------+---------------------------+---+

func OldASCIILineStyle 

func OldASCIILineStyle() LineStyle

OldASCIILineStyle is the old ASCII line style for tables.

Tables using this style will look like the following: 

+-----------+---------------------------+---+
| author_id |           name            | z |
+-----------+---------------------------+---+
|        14 | a       b       c       d |   |
|        15 | aoeu                      |   |
|           : test                          |
|           :                               |
+-----------+---------------------------+---+

func UnicodeDoubleLineStyle 

func UnicodeDoubleLineStyle() LineStyle

UnicodeDoubleLineStyle is the Unicode double line style for tables.

Tables using this style will look like the following: 

╔═══════════╦═══════════════════════════╦═══╗
║ author_id ║           name            ║ z ║
╠═══════════╬═══════════════════════════╬═══╣
║        14 ║ a       b       c       d ║   ║
║        15 ║ aoeu                     ↵║   ║
║           ║ test                     ↵║   ║
║           ║                           ║   ║
╚═══════════╩═══════════════════════════╩═══╝

func UnicodeLineStyle 

func UnicodeLineStyle() LineStyle

UnicodeLineStyle is the Unicode line style for tables.

Tables using this style will look like the following: 

┌───────────┬───────────────────────────┬───┐
│ author_id │           name            │ z │
├───────────┼───────────────────────────┼───┤
│        14 │ a       b       c       d │   │
│        15 │ aoeu                     ↵│   │
│           │ test                     ↵│   │
│           │                           │   │
└───────────┴───────────────────────────┴───┘

type Option 

type Option func(interface{}) error

Option is a Encoder option.

func WithBorder 

func WithBorder(border int) Option

WithBorder is a encoder option to set the border size.

func WithCount 

func WithCount(count int) Option

WithCount is a encoder option to set the buffered line count.

func WithEmpty 

func WithEmpty(empty string) Option

WithEmpty is a encoder option to set the value used in empty (nil) cells.

func WithFieldSeparator 

func WithFieldSeparator(fieldsep rune) Option

WithFieldSeparator is a encoder option to set the field separator.

func WithFormatter 

func WithFormatter(formatter Formatter) Option

WithFormatter is a encoder option to set a formatter for formatting values.

func WithHtmlTemplate added in v0.2.0 

func WithHtmlTemplate(t string) Option

WithHtmlTemplate is a encoder option to set the raw html template used.

func WithInline 

func WithInline(inline bool) Option

WithInline is a encoder option to set the column headers as inline to the top line.

func WithLineStyle 

func WithLineStyle(lineStyle LineStyle) Option

WithLineStyle is a encoder option to set the table line style.

func WithMinExpandWidth added in v0.3.0 

func WithMinExpandWidth(w int) Option

WithMinExpandWidth is a encoder option to set maximum width before switching to expanded format.

func WithMinPagerHeight added in v0.3.0 

func WithMinPagerHeight(h int) Option

WithMinPagerHeight is a encoder option to set maximum height before redirecting output to pager.

func WithMinPagerWidth added in v0.3.0 

func WithMinPagerWidth(w int) Option

WithMinPagerWidth is a encoder option to set maximum width before redirecting output to pager.

func WithNamedTemplate 

func WithNamedTemplate(name string) Option

WithNamedTemplate is a encoder option to set the template used.

func WithNewline 

func WithNewline(newline string) Option

WithNewline is a encoder option to set the newline.

func WithPager added in v0.3.0 

func WithPager(p string) Option

WithPager is a encoder option to set the pager command.

func WithSummary 

func WithSummary(summary map[int]func(io.Writer, int) (int, error)) Option

WithSummary is a encoder option to set a summary callback map.

func WithTableAttributes added in v0.2.0 

func WithTableAttributes(a string) Option

WithTableAttributes is a encoder option to set the table attributes.

func WithTextTemplate added in v0.2.0 

func WithTextTemplate(t string) Option

WithTextTemplate is a encoder option to set the raw text template used.

func WithTitle 

func WithTitle(title string) Option

WithTitle is a encoder option to set the title value used.

func WithWidths 

func WithWidths(widths []int) Option

WithWidths is a encoder option to set (minimum) widths for a column.

type ResultSet 

type ResultSet interface {
	Next() bool
	Scan(...interface{}) error
	Columns() ([]string, error)
	Close() error
	Err() error
	NextResultSet() bool
}

ResultSet is the shared interface for a result set.

type TableEncoder 

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

TableEncoder is a buffered, lookahead table encoder for result sets.

func (*TableEncoder) Encode 

func (enc *TableEncoder) Encode(w io.Writer) error

Encode encodes a single result set to the writer using the formatting options specified in the encoder.

func (*TableEncoder) EncodeAll 

func (enc *TableEncoder) EncodeAll(w io.Writer) error

EncodeAll encodes all result sets to the writer using the encoder settings.

type TemplateEncoder 

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

TemplateEncoder is an unbuffered template encoder for result sets.

func (*TemplateEncoder) Encode 

func (enc *TemplateEncoder) Encode(w io.Writer) error

Encode encodes a single result set to the writer using the formatting options specified in the encoder.

func (*TemplateEncoder) EncodeAll 

func (enc *TemplateEncoder) EncodeAll(w io.Writer) error

EncodeAll encodes all result sets to the writer using the encoder settings.

type Value 

type Value struct {
	// Buf is the formatted value.
	Buf []byte

	// Newlines are the positions of newline characters in Buf.
	Newlines [][2]int

	// Tabs are the positions of tab characters in Buf, split per line.
	Tabs [][][2]int

	// Width is the remaining width.
	Width int

	// Align indicates value alignment.
	Align Align

	// Raw tracks whether or not the message should be encoded or not.
	Raw bool
}

Value contains information pertaining to a formatted value.

func FormatBytes 

func FormatBytes(src []byte, invalid []byte, invalidWidth int, esc bool) *Value

FormatBytes parses src, saving escaped (encoded) and unescaped runes to a Value, along with tab and newline positions in the generated buf.

func (*Value) LineWidth 

func (v *Value) LineWidth(l, offset, tab int) int

LineWidth returns the line width (in runes) of line l.

func (*Value) MaxWidth 

func (v *Value) MaxWidth(offset, tab int) int

MaxWidth calculates the maximum width (in runes) of the longest line contained in Buf, relative to starting offset and the tab width.

func (Value) String added in v0.2.0 

func (v Value) String() string

Source Files

View all Source files

Directories

Path Synopsis
_example/main.go
 _example/main.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.