instyle

README

inStyle

inStyle is a small library for quickly decorating strings with ANSI escape codes.

Try It!

go run github.com/coldfgirl/instyle/cmd/...@latest '[~italic]you can [~cyan]style[/] text with [~bold+magenta]inStyle[/]!!!'

Or even install it as a CLI tool:

go install github.com/coldfgirl/instyle/cmd/...@latest

Syntax

The tags follow the following format:

[~style]text to be styled[/]

Style can be a named style, or a raw value to be used in an ANSI escape code. For example, both of these will turn the text red:

[~red]this text will show up as red[/]
[~31]this text will show up as red[/]

The ending sequence of [/] can be fully omitted for minor performance gains like so:

[~italic]ending tags need not be included

Multiple Styles

Multiple styles can be added by using the + character between each style desired.

[~magenta+bold]this text has two styles[/]

Nesting & Sequential Tags

Up to 5 tags can be nested. All unclosed tags are terminated at the end of a string.

[~cyan]i never said [~bold]you[/] did that[/]... [~italic]somebody else[/] did

Named Styles

Complete list of default styles.

Text Styling

• plain
• reset
• bold
• faint
• italic
• underline
• blink
• strike

Basic Colors

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• default

Basic Backgrounds

• bg-black
• bg-red
• bg-green
• bg-yellow
• bg-blue
• bg-magenta
• bg-cyan
• bg-white
• bg-default

Light Colors

• light-black
• light-red
• light-green
• light-yellow
• light-blue
• light-magenta
• light-cyan
• light-white

Light Backgrounds

• bg-light-black
• bg-light-red
• bg-light-green
• bg-light-yellow
• bg-light-blue
• bg-light-magenta
• bg-light-cyan
• bg-light-white

Aside from the named styles, additional styles can be added to a Styler instance by using the Register method. This can be used to associated more than one ANSI escape code to a name.

s := instyle.NewStyler()
s.Register("error", "1;31") // Bold and red

A style name can only be a maximum of 15 characters long.

Performance

While applying a set of styles, this code runs ~2-3x slower than an unbuffered copy of an array of runes:

// ideal performance goal:
var dst []rune
for _, r := range []rune("...") {
    dst = append(dst, r)
}

However, when compared a regex solution or using Lip Gloss directly this will perform about 5-10x faster.

Running on a M2 2022 MacBook Air, the truncated / formatted benchmark results look like:

BenchmarkBaseline/BestCase-8              15542974      70 ns/op
BenchmarkBaseline/PerformanceGoal-8        4497812     266 ns/op
BenchmarkApply/NoStyle-8                   4112559     291 ns/op
BenchmarkApply/WithStyle-8                 1775058     677 ns/op
BenchmarkApply/WithStyleToFromString-8      747465    1581 ns/op
BenchmarkSimilarLipGloss-8                  129320    9212 ns/op

Documentation

Index

• func Apply(format string, args ...any) string
• type Styler
  • func NewStyler() Styler

Functions

func Apply

func Apply(format string, args ...any) string

Apply is a helper method to call Styler.ApplyStrf on a new Styler instance.

Types

type Styler

type Styler interface {
	// Apply will parse and replace any valid style tags in the original rune array and return the result.
	//
	// Style tags are applied to a maximum depth of 5 nested tags.
	Apply(original []rune) (output []rune)

	// ApplyStr will call Apply while casting the arguments to/from strings.
	// There is a reasonable performance hit to this over Apply.
	ApplyStr(original string) (output string)

	// ApplyStrf will call Apply while casting the arguments to/from strings and using fmt.Sprintf.
	// Only the format string will be parsed for style tags.
	//
	// There is a reasonable performance hit to this over Apply.
	ApplyStrf(format string, args ...any) (output string)

	// Register will add a new named style which can be used in future calls of Apply.
	// The value expected is an ANSI escape code such as `31` for red.
	// To have a style map to multiple ANSI escape codes, separate them with a semicolon.
	//
	// Names have a maximum length of 16 characters.
	//
	// For example:
	//
	//    s := instyle.NewStyler()
	//    s.Register("error", "1;31")
	//    _ = s.Apply([]rune("[~error]Something unexpected happened"))
	Register(name string, value string) (self Styler)

	// RegisterLipGlossStyle will extract the text styling from a [lipgloss.Style] and register it under the name provided.
	// Specifically, the following will be captured if set on the style:
	//
	//  - Foreground color
	//  - Background color
	//  - Text styling of bold / faint / italic / underline / blink / strikethrough
	//
	// [lipgloss.Style]: https://github.com/charmbracelet/lipgloss
	RegisterLipGlossStyle(name string, value lipgloss.Style) (self Styler)
}

func NewStyler

func NewStyler() Styler