Help us shape the future of Go! Take the 2026 Go Developer Survey

render

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package render turns a (masked) product result into the text an agent sees, within the caps of a profile: a table (TSV or JSON) or any typed JSON value. Control and bidirectional characters are escaped, invalid UTF-8 is replaced, NULL is "NULL" (null in JSON), binary values are "<bytes:N>" and times ISO 8601.

Cells are cut while they are converted, so a huge value never costs more than its cap in output.

Index

Constants

View Source
const (
	FormatTSV  = "tsv"
	FormatJSON = "json"
)

Formats.

View Source
const TouchedColumn = "personal_column"

TouchedColumn is the kind of personal data reported for a value masked because its column looks personal.

Variables

View Source
var DefaultCaps = Caps{MaxRows: 200, MaxCellChars: 200, MaxOutputBytes: 65_536}

DefaultCaps are the caps of an unset field.

View Source
var ErrOutputCap = errors.New("render: the result is over the output cap")

ErrOutputCap means a value encodes to more than Caps.MaxOutputBytes: nothing is written. The product pages or narrows its result.

View Source
var ErrUnmasked = errors.New("render: screen not built by MaskScreen")

ErrUnmasked is the error of a MaskedScreen that MaskScreen did not build.

Functions

func CapText

func CapText(s string, maxChars int, jsonMode bool) (string, bool)

CapText is capText in JSON mode (true) or TSV mode, and whether it cut s.

func Render

func Render(w io.Writer, t Table, l Caps, format string) error

Render writes t to w in format "tsv" (the default when empty) or "json". Rows beyond MaxRows are dropped and reported as truncated; rows that would push the output past MaxOutputBytes are dropped with a marker.

func Text

func Text(v any) string

Text is the display form of a non-nil value: bytes as <bytes:N>, times in RFC 3339, floats with NaN and ±Infinity spelled out.

func Value

func Value(w io.Writer, v any, l Caps) error

Value writes v as one line of JSON: every string, object keys included, escaped and cut at Caps.MaxCellChars characters (as a table cell in JSON mode); numbers, booleans and nulls keep their JSON type. The output is at most Caps.MaxOutputBytes, or ErrOutputCap and nothing written. MaxRows does not apply: a product bounds its own lists.

Types

type Caps

type Caps struct {
	MaxRows        int
	MaxCellChars   int
	MaxOutputBytes int
	// CutNote is the footer line that tells how many cells were cut; nil
	// gives the default wording.
	CutNote func(cells, maxChars int) string
}

Caps bound an output. Zero or negative fields take the defaults (DefaultCaps).

type Cells

type Cells struct {
	Header []string
	Rows   [][]string
	Footer []string
}

Cells is the TSV rendering of a table split into cells, with the same caps as Render: the header labels, the rows shown and the lines after them (cut marker, row count).

func TSVCells

func TSVCells(t Table, l Caps) Cells

TSVCells is what Render writes in format tsv for a table with columns, before the cells are joined.

type Line added in v0.3.0

type Line []Part

Line is one line of an approval screen, in parts.

func Structure added in v0.3.0

func Structure(text string) Line

Structure is a line with no value in it.

type MaskedScreen added in v0.3.0

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

MaskedScreen is an approval screen that went through MaskScreen: the only form in which a screen may leave the lock (to the hub, in a ticket). It has no exported field and no other constructor; its zero value is not a screen (Valid is false and it does not encode).

func MaskScreen added in v0.3.0

func MaskScreen(src ScreenSource, m Masking) MaskedScreen

MaskScreen masks src: every value whose column looks personal is masked whole, and the detectors mask what they find in values, structure, header, note and warnings alike. The structure of the request stays visible.

func (MaskedScreen) MarshalJSON added in v0.3.0

func (m MaskedScreen) MarshalJSON() ([]byte, error)

MarshalJSON encodes the masked screen as a ticket.Screen; a screen MaskScreen did not build does not encode.

func (MaskedScreen) Screen added in v0.3.0

func (m MaskedScreen) Screen() ticket.Screen

Screen is the masked screen, for a ticket (a copy).

func (MaskedScreen) Touched added in v0.3.0

func (m MaskedScreen) Touched() []string

Touched names the kinds of personal data masked (ticket.PII.Touched): detector names and TouchedColumn, sorted.

func (MaskedScreen) Valid added in v0.3.0

func (m MaskedScreen) Valid() bool

Valid reports whether MaskScreen built m.

type Masking added in v0.3.0

type Masking struct {
	// Detectors find personal values in any text (pii.Detectors); none
	// is every detector (pii.AllDetectors), never no detection.
	Detectors []pii.Detector
	// Personal reports a personal column; nil is pii.LooksPersonalColumn.
	Personal func(column, typ string) bool
}

Masking says what is personal on a screen.

type Part added in v0.3.0

type Part struct {
	Text string
	// Value marks a value; structure is masked only where a detector finds
	// personal data in it.
	Value bool
	// Column and ColumnType name where the value goes or comes from ("email",
	// "varchar"); "" when unknown.
	Column, ColumnType string
}

A Part is one piece of a line of an approval screen: structure (keywords, identifiers, operators, which stay visible) or a value (a literal, a parameter, a field of a message), with the column or field it belongs to when the product knows it.

type ScreenSource added in v0.3.0

type ScreenSource struct {
	// Header names the request ("db / shop · tier read").
	Header string
	// Note is the agent's one-line reason (untrusted).
	Note string
	// Body are the lines of the request; Warnings are shown in red.
	Body     []Line
	Warnings []string
	// Red frames the screen in red outside production too.
	Red bool
}

ScreenSource is an approval screen as a product draws it, before masking.

type Table

type Table struct {
	Columns   []string
	Rows      [][]any
	Truncated bool // more rows exist beyond the producer's own cap
	Affected  int64
	// Cut marks the cells (row, column) the producer already cut while
	// reading them; they count in the cut-cells note.
	Cut map[[2]int]bool
}

Table is a tabular result: column labels and rows of values. A table without columns reports Affected rows instead (a write).

func (*Table) MarkCut

func (t *Table) MarkCut(row, col int)

MarkCut records that the producer cut cell (row, col).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL