render

package
v0.4.17 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AlignField 

func AlignField(f field.Field, col column.Info, layout layout.Layout) string

func MinWidth 

func MinWidth(rlr ruler.Ruler, col column.Info, layout layout.Layout) (chars int, hasHorizontal bool)

MinWidth returns the minimum width of a ruler's field when rendered for a set of column flags and a given layout.

The width 0 will be returned if the column's width is 0 and the layout's CollapseEmpty field is true.

The hasHorizontal flag will be true if at least one horizontal character is included in the minimal ruler. If none of a ruler's fields includes a horizontal character and none of the columns are wider than the minimal ruler, then at least one column should be widened to ensure that the ruler can be parsed properly.

func PaddingWidth 

func PaddingWidth(f field.Field, col column.Info, layout layout.Layout) (left, right int)

PaddingWidth calculates the number of spaces to add to the left and/or right of a field's encoded string in order to make the field align with the rest of its column.

Scenarios: 

Assumptions:
	- padding = column.Chars - field.Chars

| column  |  field  ||           left           |           right            | description |
| ------- | ------- || ------------------------ | -------------------------- | ----------- |
| number  | number  || padding - right          | column.right - field.right | expected    |
|         | version || padding - right          | column.right - field.right |             |
|         | text    || padding                  | 0                          |             |
| ------- | ------- || ------------------------ | -------------------------- | ----------- |
| version | version || column.left - field.left | padding - left             | expected    |
|         | number  || column.left - field.left | padding - left             |             |
|         | text    || 0                        | padding                    |             |
| ------- | ------- || ------------------------ | -------------------------- | ----------- |
| center  | any     || padding / 2              | padding - left             |             |
| right   | any     || padding                  | 0                          |             |
| left    | any     || 0                        | padding                    |             |

func RenderRulerField 

func RenderRulerField(rlr ruler.Ruler, col column.Info, layout layout.Layout) string

RenderRulerField returns a single field of a ruler.

  • the field MUST be column.Width.Chars + 2 characters wide, i.e. data + padding
  • exception: layout.CollapseEmpty may reduce the field to "" if the column's width is 0
  • if the ruler's padding character is whitespace, the padding character must be the first and last character of the field
  • if the ruler's padding character is not a whitespace, then the ruler must be fill the whole field
  • alignment and sorting hints must be added if allowed by the layout

Ruler construction:

  • c = column info
  • m = align marker
  • s = sort marker
  • p = padding, if ruler is padded

Layout: 

absolute column width |<------------------------- c.Chars ------------------------->|
numeric alignment                        |<----- c.Left ----->|<----- c.Right ----->|
version alignment     |<----- c.Left ----->|<----- c.Right ----->|
column hints          |p m.left ------------- m.middle ----------------- m.right s p|

Invariants / Assumptions:

  • column.Width.Chars must be >= minimum width for ruler
  • either column.Width.Left + column.Width.Right == column.Width.Chars or column.Width.Left + column.Width.Right == 0
  • bit patterns define where markers should be placed, i.e. left|middle|right
  • middle != center: center
  • at least one ruler field MUST contain at least one horizontal character otherwise, the ruler will not be accepted by the ruler parser

func Row 

func Row(row row.Row[field.Field], cols []column.Info, layout layout.Layout) string

RenderRow returns a row of table data, aligned to the table's column widths

- the number of fields and columns must be identical

func RowCmpFunc 

func RowCmpFunc(cols column.Index) func(a, b row.Row[field.Field]) int

func Ruler 

func Ruler(rlr ruler.Ruler, cols []column.Info, layout layout.Layout) string

func SortIndex 

func SortIndex(tableIndex column.Index) column.Index

SortIndex returns a column index of the columns to be used for sorting, in prioritised order.

Goals:

  • do not sort tables which do not have sorting enabled on any of their columns
  • otherwise, sort tables by comparing their data in the order specified by their column's sorting configuration
  • finally, use any trailing columns as a "tie breaker" if necessary
  • sort direction has no effect

Behaviour:

If no columns have sorting enabled then an empty index is returned.

In all other cases:

  • an index is returned with the same number of columns as the provided index
  • the "sorting enabled" columns appear first, in increasing priority order (1, 2, ... 7)
  • followed by the "sorting enabled" columns with priority 0
  • followed by any remaining columns (even if sorting is not enabled)

Types

type CmpFunc 

type CmpFunc func(a, b field.Field) int

type CommandAPI added in v0.4.17 

type CommandAPI struct {
	*Table
}

CommandAPI provides a simplified API for user command interactions with a Table

See [command.ConfigAPI]

func (*CommandAPI) FillColumns added in v0.4.17 

func (cfg *CommandAPI) FillColumns(cols []column.Locator, value string)

func (*CommandAPI) Index added in v0.4.17 

func (cfg *CommandAPI) Index() column.Index

func (*CommandAPI) SetIndex added in v0.4.17 

func (cfg *CommandAPI) SetIndex(newIndex column.Index)

func (*CommandAPI) SetPrefix added in v0.4.17 

func (cfg *CommandAPI) SetPrefix(symbols ...string)

TODO: 2026-02-23 broken: prefix needs to be applied BEFORE parsing currently, commands are only applied during the render step

type Option 

type Option func(*Table)

func WithColumns 

func WithColumns(cols column.Index) Option

func WithLayout 

func WithLayout(layout layout.Layout) Option

func WithPrefix 

func WithPrefix(prefix string) Option

func WithRows 

func WithRows(rows [][]string) Option

TODO: 2026-02-22 see ImportRows dependency

func WithRulers 

func WithRulers(rulers overlay.Overlay[ruler.Ruler]) Option

func WithTextLines 

func WithTextLines(textLines overlay.Overlay[string]) Option

type OverlayItem 

type OverlayItem interface {
	Line() int // the overlay's position in the overall document (0-based)
	Row() int  // the number of the next table row to appear after this overlay item
}

type RowGroup 

type RowGroup struct {
	Start int
	End   int
}

RowGroup contains the start and end indexes for a sub-slice of table rows between two overlay lines. e.g.: rowsInGroup = table.Rows[group.Start:group.End]

func RowGroups 

func RowGroups(overlayItems []OverlayItem, rowCount int) []RowGroup

RowGroups collates the ranges of contiguous table rows between overlay lines

Given the document: (with line and row numbers) 

// Table of Meteor Showers:                     // text  {line:  0, row: 0}
//                                              // text  {line:  1, row: 0}
// +------------+----------+--------------+     // ruler {line:  2, row: 0}
// | Hemisphere |  Dates   |     Name     |     // row 0
// | ========== | ======== | ============ |     // ruler {line:  4, row: 0}
// | both       | 04-23/24 | Lyrids       |     // row 1
// |            | 05-05/06 | Eta Aquarids |     // row 2
// |            | 10-21/22 | Orionids     |     // row 3
// |            | 11-17/18 | Leonids      |     // row 4
// |            | 12-14/15 | Geminids     |     // row 5
// |            | 12-22/23 | Ursids       |     // row 6
// | ---------- | -------- | ------------ |     // ruler {line: 11, row: 7}
// | northern   | 08-12/13 | Perseids     |     // row 7
// |            | 10-08/09 | Draconids    |     // row 8
// +------------+----------+--------------+     // ruler {line: 14, row: 9}
//                                              // text  {line: 15, row: 9}
// Source: the internet                         // text  {line: 16, row: 9}

Here we can see how the overlaid items are interwoven between the table rows.

With the above example we would expect the 3 groups of rows: (written in go's slice format) 

rows[0:1]   column header
rows[1:7]   both hemispheres
rows[7:9]   northern hemisphere

type RulerField 

type RulerField struct {
	Padding string //   // ---+-------------+
	//                  //    v             v
	//                  //    _?----?----???_
	//                  //     ^ ^  ^  ^ ^^^
	LeftMark     string // ----+ |  |  | |||
	LeftFill     int    // ------+  |  | |||
	LineMark     string // ------+  |  | |||
	MiddleMark   string // ---------+  | |||
	RightFill    int    // ------------+ |||
	RightMark    string // --------------+||
	OrderMark    string // ---------------+|
	PriorityMark string // ----------------+
}

func (*RulerField) HasHorizontal 

func (f *RulerField) HasHorizontal() bool

func (*RulerField) MinLeft 

func (f *RulerField) MinLeft() int

func (*RulerField) MinRight 

func (f *RulerField) MinRight() int

func (*RulerField) MinWidth 

func (f *RulerField) MinWidth() int

func (*RulerField) String 

func (f *RulerField) String() string

type Table 

type Table struct {
	Prefix    string
	Layout    layout.Layout
	Index     column.Index
	Rows      []row.Row[field.Field]
	Rulers    overlay.Overlay[ruler.Ruler]
	TextLines overlay.Overlay[string]
	// contains filtered or unexported fields
}

render.Table is a derived structure used for rendering psv.Table's

Differences to internal.Table:

  • data is stored as a grid of field.Field structs

Note:

  • go does not allow cyclic module references
  • => cannot reference internal.Table from this package

func New 

func New(opts ...Option) *Table

func (*Table) ApplyCommands 

func (t *Table) ApplyCommands() error

ApplyCommands applies all of the commands provided via the table's Layout

Any errors encountered while parsing the commands are returned as WARNINGS i.e.

  • unparsable commands are ignored / not applied
  • the error(s) should be shown to the user (e.g. via STDERR)

func (*Table) ImportRows 

func (t *Table) ImportRows()

ImportRows imports ONLY the fields required AFTER commands have been run on the render.Table

func (*Table) LineCount 

func (t *Table) LineCount() int

func (*Table) OverlayItems 

func (t *Table) OverlayItems() []OverlayItem

func (*Table) Render 

func (t *Table) Render() ([]byte, error)

Errors should NEVER prevent the table from being rendered. - as of 2026-02-20 the only errors possible are "command parsing" errors

func (*Table) RenderTable 

func (t *Table) RenderTable() []byte

func (*Table) RowCount 

func (t *Table) RowCount() int

func (*Table) RulerCount 

func (t *Table) RulerCount() int

func (*Table) SetPrefixSymbols 

func (t *Table) SetPrefixSymbols(symbols ...string)

func (*Table) SortRows 

func (t *Table) SortRows()

SortRows uses the sorting flags in this table's index to determine how the table's rows should be sorted. Assumptions:

  • the number of rows to be sorted is the same as the number of rows in the table
  • i.e. table.RowGroups() compares the table's overlay positions with the rows in the table

func (*Table) TextlineCount 

func (t *Table) TextlineCount() int

Source Files

View all Source files

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.