pretty

README

internal/pretty 维护说明

1. 背景

github.com/coder/pretty 已停止维护。为降低外部依赖风险并保证输出样式能力可持续维护，本项目将其迁移为内部实现：internal/pretty。

2. 维护目标

• 保持与当前项目使用场景的 API 兼容。
• 保持帮助输出（help.go）行为稳定。
• 避免引入不必要的功能扩展。

3. 当前提供的能力

3.1 文本结构与格式化接口

• Text
• Formatter
• Style
• String(...)

3.2 常用格式化函数

• FgColor(...)
• BgColor(...)
• CSI(...)
• Wrap(...)
• Bold()
• Italic()
• Underline()
• LineWrap(...)
• XPad(...)

4. 使用约定

• 仅用于本项目命令行输出样式层。
• 首选在 help.go 中集中使用，避免在业务逻辑中散布样式代码。
• 如需扩展接口，优先保证向后兼容，不破坏现有调用。

5. 变更流程

1. 明确变更动机（兼容性、性能、可维护性）。
2. 评估是否影响 help.go 现有输出。
3. 完成代码改动后执行格式化与测试。
4. 更新 docs/CHANGELOG.md 记录变更。

6. 验证建议

• 运行全量测试：go test ./...
• 检查帮助输出关键路径：
  • 命令列表输出
  • 标志列表输出
  • 帮助模板渲染

7. 迁移说明

• 旧导入：github.com/coder/pretty
• 新导入：github.com/pubgo/redant/internal/pretty

迁移策略为“接口兼容优先”，即在不改变上层业务逻辑的前提下完成替换。

Documentation

Index

• func Fprint(w io.Writer, f Formatter, args ...any)
• func Fprintf(w io.Writer, f Formatter, format string, args ...any)
• func Printf(f Formatter, format string, args ...any)
• func Sprint(f Formatter, args ...any) string
• func Sprintf(f Formatter, format string, args ...any) string
• type Formatter
  • func BgColor(c termenv.Color) Formatter
  • func Bold() Formatter
  • func CSI(seq string) Formatter
  • func FgColor(c termenv.Color) Formatter
  • func Italic() Formatter
  • func LineWrap(width int) Formatter
  • func Underline() Formatter
  • func Wrap(prefix, suffix string) Formatter
  • func XPad(left, right int) Formatter
• type Style
  • func (s Style) Format(t *Text)
  • func (s Style) With(fs ...Formatter) Style
• type Text
  • func String(s ...string) *Text
  • func (t *Text) Append(ss ...string) *Text
  • func (t *Text) Bytes(b []byte) []byte
  • func (t *Text) Head() *Text
  • func (t *Text) Insert(s string) *Text
  • func (t *Text) Len() int
  • func (t *Text) Prepend(ss ...string) *Text
  • func (t *Text) Split(n int) *Text
  • func (t *Text) String() string
  • func (t *Text) Tail() *Text
  • func (t *Text) WriteTo(w io.Writer) (int64, error)

Functions

func Fprint

func Fprint(w io.Writer, f Formatter, args ...any)

Fprint formats the given string with the formatter and writes it to the writer.

func Fprintf

func Fprintf(w io.Writer, f Formatter, format string, args ...any)

Fprintf formats the given string with the formatter and writes it to the writer.

func Printf

func Printf(f Formatter, format string, args ...any)

Printf formats the given string with the formatter and prints it to stdout.

func Sprint

func Sprint(f Formatter, args ...any) string

Sprint formats the given string with the formatter.

func Sprintf

func Sprintf(f Formatter, format string, args ...any) string

Sprintf formats the given string with the formatter.

Types

type Formatter

type Formatter interface {
	Format(*Text)
}

Formatter manipulates Text.

var Nop Formatter = formatterFunc(func(t *Text) {})

Nop is a no-op formatter.

func BgColor

func BgColor(c termenv.Color) Formatter

BgColor returns a formatter that sets the background color.

func Bold

func Bold() Formatter

Bold returns a formatter that makes the text bold.

func CSI

func CSI(seq string) Formatter

CSI wraps the text in the given CSI (Control Sequence Introducer) sequence.

func FgColor

func FgColor(c termenv.Color) Formatter

FgColor returns a formatter that sets the foreground color.

func Italic

func Italic() Formatter

Italic returns a formatter that makes the text italic.

func LineWrap

func LineWrap(width int) Formatter

LineWrap wraps the text at the given width. It breaks lines at word boundaries when possible.

func Underline

func Underline() Formatter

Underline returns a formatter that underlines the text.

func Wrap

func Wrap(prefix, suffix string) Formatter

Wrap wraps the text in the given prefix and suffix.

func XPad

func XPad(left, right int) Formatter

XPad pads the text on the left and right.

type Style

type Style []Formatter

Style applies multiple formatters to a text in order.

func (Style) Format

func (s Style) Format(t *Text)

Format applies all formatters in the style to the text.

func (Style) With

func (s Style) With(fs ...Formatter) Style

With returns a new style with the given formatters appended.

type Text

type Text struct {
	S    string
	Next *Text
	Prev *Text
}

Text is a linked-list structure that represents an in-progress text string. Most formatters work by prepending and appending to text, so this structure is far more efficient than manipulating strings directly.

The pointer is intrinsically a cursor that points to the current text segment. So, subsequent appends and prepends are O(1) since the cursor is already at the tail or head respectively.

func String

func String(s ...string) *Text

String creates a new Text object from the given strings.

func (*Text) Append

func (t *Text) Append(ss ...string) *Text

Append appends strings to the end of the text in order.

func (*Text) Bytes

func (t *Text) Bytes(b []byte) []byte

Bytes allocates a new byte slice containing the entire text. It uses the given buffer if it is large enough.

func (*Text) Head

func (t *Text) Head() *Text

Head returns the absolute head of the text. It adjusts the pointer to the head of the text.

func (*Text) Insert

func (t *Text) Insert(s string) *Text

Insert inserts the given text before the current text. It returns the new node.

func (*Text) Len

func (t *Text) Len() int

Len returns the length of the text.

func (*Text) Prepend

func (t *Text) Prepend(ss ...string) *Text

Prepend prepends strings to the beginning of the text in order.

func (*Text) Split

func (t *Text) Split(n int) *Text

Split splits the current text into two parts at the given index. The current node contains the first part, and the new node contains the second part. It returns the new node, and does not adjust the pointer.

func (*Text) String

func (t *Text) String() string

String allocates a new string containing the entire text.

func (*Text) Tail

func (t *Text) Tail() *Text

Tail returns the absolute tail of the text. It adjusts the pointer to the tail of the text.

func (*Text) WriteTo

func (t *Text) WriteTo(w io.Writer) (int64, error)

WriteTo writes the text to the given writer, avoiding string allocations.