richtext

Documentation

Overview

Package richtext renders bracketed tag markup into ANSI-styled terminal output, gated by the terminal's colour capability. A Writer performs the rendering as an io.Writer.

Index

• Variables
• func Len(s string) int
• func Strip(s string) string
• type TagError
  • func (e *TagError) Error() string
  • func (e *TagError) Unwrap() error
• type Theme
  • func NewTheme(styles map[string]style.Style) *Theme
  • func (t *Theme) New(styles map[string]style.Style) *Theme
• type Writer
  • func NewWriter(dst io.Writer, theme *Theme) *Writer
  • func (w *Writer) Close() error
  • func (w *Writer) EnableColour(b bool)
  • func (w *Writer) Flush() error
  • func (w *Writer) ForceColour()
  • func (w *Writer) Write(p []byte) (int, error)
  • func (w *Writer) Writer() io.Writer

Variables

var (
	// ErrUnbalancedTag reports a closing tag that does not match the most
	// recently opened tag.
	ErrUnbalancedTag = errors.New("unbalanced closing tag")

	// ErrUnclosedTag reports that input ended while tags were still open.
	ErrUnclosedTag = errors.New("unclosed tag")
)

var DefaultTheme = &Theme{
	styles: map[string]style.Style{
		"title":    {Foreground: style.Green},
		"heading":  {Foreground: style.Yellow},
		"label":    {Foreground: style.Cyan},
		"value":    {Foreground: style.White},
		"emphasis": {Foreground: style.White, Attributes: style.Bold},
		"error":    {Foreground: style.Red},
		"warning":  {Foreground: style.Yellow},
		"info":     {Foreground: style.Green},
		"debug":    {Foreground: style.Cyan},
		"quote":    {Foreground: style.BrightBlack},
		"gutter":   {Foreground: style.White},
		"url":      {Foreground: style.BrightWhite, Attributes: style.Underline},
	},
}

DefaultTheme is the standard colour scheme used by the go-cli project. Users can derive themes from this to override basic stylings by using Theme.New.

Functions

func Len

func Len(s string) int

Len returns the number of runes in the visible text of s, ignoring valid tags. It is intended for alignment and width calculations.

func Strip

func Strip(s string) string

Strip returns s with every valid tag removed, leaving only the visible text. An unknown namespace is not a valid tag, so it and its closing tag are kept verbatim, matching how Writer treats them.

Types

type TagError

type TagError struct {
	Namespace string
	Err       error
}

TagError describes a problem with a specific tag encountered while writing. It wraps one of the package's sentinel errors.

func (*TagError) Error

func (e *TagError) Error() string

Error implements [error].

func (*TagError) Unwrap

func (e *TagError) Unwrap() error

Unwrap returns the wrapped sentinel error.

type Theme

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

Theme maps theme names to their styles. It is consulted by a Writer to resolve [theme:name] tags and is safe for concurrent reads. A Theme may derive from a parent (see Theme.New), falling back to it for names it does not define itself.

func NewTheme

func NewTheme(styles map[string]style.Style) *Theme

NewTheme builds a Theme that maps each name in styles to its style. A name is referenced by a [theme:name] tag, so it must be non-empty and must not contain a ']'; NewTheme panics if any name violates this.

func (*Theme) New

func (t *Theme) New(styles map[string]style.Style) *Theme

New derives a Theme from styles that overrides the receiver: names declared in styles take precedence, and any other name falls back to the receiver and its ancestors. It follows the same naming rules and panic behaviour as NewTheme.

type Writer

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

Writer renders bracketed tag markup to an underlying writer as ANSI escapes.

Tags take the form [ns:field] and close with [/ns]. The namespaces are:

• fg / bg: a foreground or background colour, either one of the sixteen named ANSI colours or rgb(r,g,b);
• attr: a text attribute such as bold or italic, which accumulates while nested;
• theme: a named style registered in the Theme passed to NewWriter;
• richtext: with the field "off", opens a passthrough region whose contents are written verbatim without being parsed as tags, closed by [/richtext].

Tags must close in the reverse of the order they were opened. A known namespace with an unrecognised field renders as a reset. An unknown namespace is not a tag: it and its closing tag are emitted verbatim.

Colour output is governed by a term.ColourEnabler, term.DefaultEnabler by default; see Writer.EnableColour and Writer.ForceColour. When colour is disabled, text is written through unchanged and no escapes are emitted.

func NewWriter

func NewWriter(dst io.Writer, theme *Theme) *Writer

NewWriter returns a Writer that renders to dst, resolving [theme:name] tags against theme. theme may be nil, in which case every theme tag renders as a reset. The default colour policy is term.DefaultEnabler.

func (*Writer) Close

func (w *Writer) Close() error

Close flushes any trailing partial tag as literal text and reports whether the markup was balanced. It returns a *TagError wrapping ErrUnclosedTag if any tags remain open.

func (*Writer) EnableColour

func (w *Writer) EnableColour(b bool)

EnableColour selects the default colour policy when b is true, or disables colour entirely when b is false.

func (*Writer) Flush

func (w *Writer) Flush() error

Flush drains any partial fragment buffered by the scanner to the destination as literal text, leaving the open-tag stack untouched. Unlike Writer.Close it never reports an unclosed tag.

func (*Writer) ForceColour

func (w *Writer) ForceColour()

ForceColour emits colour unconditionally, regardless of the destination.

func (*Writer) Write

func (w *Writer) Write(p []byte) (int, error)

Write implements io.Writer. It returns a *TagError wrapping ErrUnbalancedTag when a closing tag does not match the open tag.

func (*Writer) Writer

func (w *Writer) Writer() io.Writer

Writer returns an io.Writer that writes verbatim to the destination without interpreting the bytes as tag markup.

This is the escape hatch for emitting untrusted text between an open and close tag: the active style is preserved and embedded closing tags cannot end the formatting early.