lipgloss

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Feb 14, 2022 License: MIT Imports: 11 Imported by: 3,249

README

Lip Gloss

Lip Gloss Title Treatment
Latest Release GoDoc Build Status

Style definitions for nice terminal layouts. Built with TUIs in mind.

Lip Gloss example

Lip Gloss takes an expressive, declarative approach to terminal rendering. Users familiar with CSS will feel at home with Lip Gloss.


import "github.com/charmbracelet/lipgloss"

var style = lipgloss.NewStyle().
    Bold(true).
    Foreground(lipgloss.Color("#FAFAFA")).
    Background(lipgloss.Color("#7D56F4")).
    PaddingTop(2).
    PaddingLeft(4).
    Width(22)

fmt.Println(style.Render("Hello, kitty."))

Colors

Lip Gloss supports the following color profiles:

ANSI 16 colors (4-bit)
lipgloss.Color("5")  // magenta
lipgloss.Color("9")  // red
lipgloss.Color("12") // light blue
ANSI 256 Colors (8-bit)
lipgloss.Color("86")  // aqua
lipgloss.Color("201") // hot pink
lipgloss.Color("202") // orange
True Color (16,777,216 colors; 24-bit)
lipgloss.Color("#0000FF") // good ol' 100% blue
lipgloss.Color("#04B575") // a green
lipgloss.Color("#3C3C3C") // a dark gray

...as well as a 1-bit Ascii profile, which is black and white only.

The terminal's color profile will be automatically detected, and colors outside the gamut of the current palette will be automatically coerced to their closest available value.

Adaptive Colors

You can also specify color options for light and dark backgrounds:

lipgloss.AdaptiveColor{Light: "236", Dark: "248"}

The terminal's background color will automatically be detected and the appropriate color will be chosen at runtime.

Inline Formatting

Lip Gloss supports the usual ANSI text formatting options:

var style = lipgloss.NewStyle().
    Bold(true).
    Italic(true).
    Faint(true).
    Blink(true).
    Strikethrough(true).
    Underline(true).
    Reverse(true)

Block-Level Formatting

Lip Gloss also supports rules for block-level formatting:

// Padding
var style = lipgloss.NewStyle().
    PaddingTop(2).
    PaddingRight(4).
    PaddingBottom(2).
    PaddingLeft(4)

// Margins
var style = lipgloss.NewStyle().
    MarginTop(2).
    MarginRight(4).
    MarginBottom(2).
    MarginLeft(4)

There is also shorthand syntax for margins and padding, which follows the same format as CSS:

// 2 cells on all sides
lipgloss.NewStyle().Padding(2)

// 2 cells on the top and bottom, 4 cells on the left and right
lipgloss.NewStyle().Margin(2, 4)

// 1 cell on the top, 4 cells on the sides, 2 cells on the bottom
lipgloss.NewStyle().Padding(1, 4, 2)

// Clockwise, starting from the top: 2 cells on the top, 4 on the right, 3 on
// the bottom, and 1 on the left
lipgloss.NewStyle().Margin(2, 4, 3, 1)

Aligning Text

You can align paragraphs of text to the left, right, or center.

var style = lipgloss.NewStyle().
    Width(24).
    Align(lipgloss.Left).  // align it left
    Align(lipgloss.Right). // no wait, align it right
    Align(lipgloss.Center) // just kidding, align it in the center

Width and Height

Setting a minimum width and height is simple and straightforward.

var str = lipgloss.NewStyle().
    Width(24).
    Height(32).
    Foreground(lipgloss.Color("63")).
    Render("What’s for lunch?")

Borders

Adding borders is easy:

// Add a purple, rectangular border
var style = lipgloss.NewStyle().
    BorderStyle(lipgloss.NormalBorder()).
    BorderForeground(lipgloss.Color("63"))

// Set a rounded, yellow-on-purple border to the top and left
var anotherStyle = lipgloss.NewStyle().
    BorderStyle(lipgloss.RoundedBorder()).
    BorderForeground(lipgloss.Color("228")).
    BorderBackground(lipgloss.Color("63")).
    BorderTop(true).
    BorderLeft(true)

// Make your own border
var myCuteBorder = lipgloss.Border{
    Top:         "._.:*:",
    Bottom:      "._.:*:",
    Left:        "|*",
    Right:       "|*",
    TopLeft:     "*",
    TopRight:    "*",
    BottomLeft:  "*",
    BottomRight: "*",
}

There are also shorthand functions for defining borders, which follow a similar pattern to the margin and padding shorthand functions.

// Add a thick border to the top and bottom
lipgloss.NewStyle().
    Border(lipgloss.ThickBorder(), true, false)

// Add a thick border to the right and bottom sides. Rules are set clockwise
// from top.
lipgloss.NewStyle().
    Border(lipgloss.DoubleBorder(), true, false, false, true)

For more on borders see the docs.

Copying Styles

Just use Copy():

var style = lipgloss.NewStyle().Foreground(lipgloss.Color("219"))

var wildStyle = style.Copy().Blink(true)

Copy() performs a copy on the underlying data structure ensuring that you get a true, dereferenced copy of a style. Without copying it's possible to mutate styles.

Inheritance

Styles can inherit rules from other styles. When inheriting, only unset rules on the receiver are inherited.

var styleA = lipgloss.NewStyle().
    Foreground(lipgloss.Color("229")).
    Background(lipgloss.Color("63"))

// Only the background color will be inherited here, because the foreground
// color will have been already set:
var styleB = lipgloss.NewStyle().
    Foreground(lipgloss.Color("201")).
    Inherit(styleA)

Unsetting Rules

All rules can be unset:

var style = lipgloss.NewStyle().
    Bold(true).                        // make it bold
    UnsetBold().                       // jk don't make it bold
    Background(lipgloss.Color("227")). // yellow background
    UnsetBackground()                  // never mind

When a rule is unset, it won't be inherited or copied.

Enforcing Rules

Sometimes, such as when developing a component, you want to make sure style definitions respect their intended purpose in the UI. This is where Inline and MaxWidth, and MaxHeight come in:

// Force rendering onto a single line, ignoring margins, padding, and borders.
someStyle.Inline(true).Render("yadda yadda")

// Also limit rendering to five cells
someStyle.Inline(true).MaxWidth(5).Render("yadda yadda")

// Limit rendering to a 5x5 cell block
someStyle.MaxWidth(5).MaxHeight(5).Render("yadda yadda")

Rendering

Generally, you just call the Render(string) method on a lipgloss.Style:

fmt.Println(lipgloss.NewStyle().Bold(true).Render("Hello, kitty."))

But you could also use the Stringer interface:

var style = lipgloss.NewStyle().SetString("你好，猫咪。").Bold(true)

fmt.Printf("%s\n", style)

Utilities

In addition to pure styling, Lip Gloss also ships with some utilities to help assemble your layouts.

Joining Paragraphs

Horizontally and vertically joining paragraphs is a cinch.

// Horizontally join three paragraphs along their bottom edges
lipgloss.JoinHorizontal(lipgloss.Bottom, paragraphA, paragraphB, paragraphC)

// Vertically join two paragraphs along their center axes
lipgloss.JoinVertical(lipgloss.Center, paragraphA, paragraphB)

// Horizontally join three paragraphs, with the shorter ones aligning 20%
// from the top of the tallest
lipgloss.JoinHorizontal(0.2, paragraphA, paragraphB, paragraphC)
Measuring Width and Height

Sometimes you’ll want to know the width and height of text blocks when building your layouts.

var block string = lipgloss.NewStyle().
    Width(40).
    Padding(2).
    Render(someLongString)

// Get the actual, physical dimensions of the text block.
width := lipgloss.Width(block)
height := lipgloss.Height(block)

// Here's a shorthand function.
w, h := lipgloss.Size(block)
Placing Text in Whitespace

Sometimes you’ll simply want to place a block of text in whitespace.

// Center a paragraph horizontally in a space 80 cells wide. The height of
// the block returned will be as tall as the input paragraph.
block := lipgloss.PlaceHorizontal(80, lipgloss.Center, fancyStyledParagraph)

// Place a paragraph at the bottom of a space 30 cells tall. The width of
// the text block returned will be as wide as the input paragraph.
block := lipgloss.PlaceVertical(30, lipgloss.Bottom, fancyStyledParagraph)

// Place a paragraph in the bottom right corner of a 30x80 cell space.
block := lipgloss.Place(30, 80, lipgloss.Right, lipgloss.Bottom, fancyStyledParagraph)

You can also style the whitespace. For details, see the docs.

What about Bubble Tea?

Lip Gloss doesn’t replace Bubble Tea. Rather, it is an excellent Bubble Tea companion. It was designed to make assembling terminal user interface views as simple and fun as possible so that you can focus on building your application instead of concerning yourself with low-level layout details.

In simple terms, you can use Lip Gloss to help build your Bubble Tea views.

Under the Hood

Lip Gloss is built on the excellent Termenv and Reflow libraries which deal with color and ANSI-aware text operations, respectively. For many use cases Termenv and Reflow will be sufficient for your needs.

Rendering Markdown

For a more document-centric rendering solution with support for things like lists, tables, and syntax-highlighted code have a look at Glamour, the stylesheet-based Markdown renderer.

License

MIT

Part of Charm.

The Charm logo

Charm热爱开源 • Charm loves open source

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ColorProfile 

func ColorProfile() termenv.Profile

ColorProfile returns the detected termenv color profile. It will perform the actual check only once.

func HasDarkBackground added in v0.1.1 

func HasDarkBackground() bool

HasDarkBackground returns whether or not the terminal has a dark background.

func Height 

func Height(str string) int

Height returns height of a string in cells. This is done simply by counting \n characters. If your strings use \r\n for newlines you should convert them to \n first, or simply write a separate function for measuring height.

func JoinHorizontal 

func JoinHorizontal(pos Position, strs ...string) string

JoinHorizontal is a utility function for horizontally joining two potentially multi-lined strings along a vertical axis. The first argument is the position, with 0 being all the way at the top and 1 being all the way at the bottom.

If you just want to align to the left, right or center you may as well just use the helper constants Top, Center, and Bottom.

Example: 

blockB := "...\n...\n..."
blockA := "...\n...\n...\n...\n..."

// Join 20% from the top
str := lipgloss.JoinHorizontal(0.2, blockA, blockB)

// Join on the top edge
str := lipgloss.JoinHorizontal(lipgloss.Top, blockA, blockB)

func JoinVertical 

func JoinVertical(pos Position, strs ...string) string

JoinVertical is a utility function for vertically joining two potentially multi-lined strings along a horizontal axis. The first argument is the position, with 0 being all the way to the left and 1 being all the way to the right.

If you just want to align to the left, right or center you may as well just use the helper constants Left, Center, and Right.

Example: 

blockB := "...\n...\n..."
blockA := "...\n...\n...\n...\n..."

// Join 20% from the top
str := lipgloss.JoinVertical(0.2, blockA, blockB)

// Join on the right edge
str := lipgloss.JoinVertical(lipgloss.Right, blockA, blockB)

func Place 

func Place(width, height int, hPos, vPos Position, str string, opts ...WhitespaceOption) string

Place places a string or text block vertically in an unstyled box of a given width or height.

func PlaceHorizontal 

func PlaceHorizontal(width int, pos Position, str string, opts ...WhitespaceOption) string

PlaceHorizontal places a string or text block horizontally in an unstyled block of a given width. If the given width is shorter than the max width of the string (measured by it's longest line) this will be a noöp.

func PlaceVertical 

func PlaceVertical(height int, pos Position, str string, opts ...WhitespaceOption) string

PlaceVertical places a string or text block vertically in an unstyled block of a given height. If the given height is shorter than the height of the string (measured by it's newlines) then this will be a noöp.

func SetColorProfile added in v0.3.0 

func SetColorProfile(p termenv.Profile)

SetColorProfile sets the color profile on a package-wide context. This function exists mostly for testing purposes so that you can assure you're testing against a specific profile.

Outside of testing you likely won't want to use this function as ColorProfile() will detect and cache the terminal's color capabilities and choose the best available profile.

Available color profiles are:

termenv.Ascii (no color, 1-bit) termenv.ANSI (16 colors, 4-bit) termenv.ANSI256 (256 colors, 8-bit) termenv.TrueColor (16,777,216 colors, 24-bit)

This function is thread-safe.

func SetHasDarkBackground added in v0.5.0 

func SetHasDarkBackground(b bool)

SetHasDarkBackground sets the value of the background color detection on a package-wide context. This function exists mostly for testing purposes so that you can assure you're testing against a specific background color setting.

Outside of testing you likely won't want to use this function as HasDarkBackground() will detect and cache the terminal's current background color setting.

This function is thread-safe.

func Size added in v0.2.1 

func Size(str string) (width, height int)

Size returns the width and height of the string in cells. ANSI sequences are ignored and characters wider than one cell (such as Chinese characters and emojis) are appropriately measured.

func StyleRunes added in v0.3.0 

func StyleRunes(str string, indices []int, matched, unmatched Style) string

StyleRunes applys a given style to runes at the given indicesin the string. Note that you must provide styling options for both matched and unmatched runes. Indices out of bounds will be ignored.

func Width 

func Width(str string) (width int)

Width returns the cell width of characters in the string. ANSI sequences are ignored and characters wider than one cell (such as Chinese characters and emojis) are appropriately measured.

You should use this instead of len(string) len([]rune(string) as neither will give you accurate results.

Types

type AdaptiveColor 

type AdaptiveColor struct {
	Light string
	Dark  string
}

AdaptiveColor provides color options for light and dark backgrounds. The appropriate color will be returned at runtime based on the darkness of the terminal background color.

Example usage: 

color := lipgloss.AdaptiveColor{Light: "#0000ff", Dark: "#000099"}

func (AdaptiveColor) RGBA 

func (ac AdaptiveColor) RGBA() (r, g, b, a uint32)

RGBA returns the RGBA value of this color. This satisfies the Go Color interface. Note that on error we return black with 100% opacity, or:

Red: 0x0, Green: 0x0, Blue: 0x0, Alpha: 0xFFFF

This is inline with go-colorful's default behavior.

type Border 

type Border struct {
	Top         string
	Bottom      string
	Left        string
	Right       string
	TopLeft     string
	TopRight    string
	BottomRight string
	BottomLeft  string
}

Border contains a series of values which comprise the various parts of a border.

func DoubleBorder 

func DoubleBorder() Border

DoubleBorder returns a border comprised of two thin strokes.

func HiddenBorder added in v0.4.0 

func HiddenBorder() Border

HiddenBorder returns a border that renders as a series of single-cell spaces. It's useful for cases when you want to remove a standard border but maintain layout positioning. This said, you can still apply a background color to a hidden border.

func NormalBorder 

func NormalBorder() Border

NormalBorder returns a standard-type border with a normal weight and 90 degree corners.

func RoundedBorder 

func RoundedBorder() Border

RoundedBorder returns a border with rounded corners.

func ThickBorder 

func ThickBorder() Border

ThickBorder returns a border that's thicker than the one returned by NormalBorder.

func (Border) GetBottomSize added in v0.4.0 

func (b Border) GetBottomSize() int

GetBottomSize returns the width of the bottom border. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the bottom edge, 0 is returned.

func (Border) GetLeftSize added in v0.4.0 

func (b Border) GetLeftSize() int

GetLeftSize returns the width of the left border. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the left edge, 0 is returned.

func (Border) GetRightSize added in v0.4.0 

func (b Border) GetRightSize() int

GetRightSize returns the width of the right border. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the right edge, 0 is returned.

func (Border) GetTopSize added in v0.4.0 

func (b Border) GetTopSize() int

GetTopSize returns the width of the top border. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the top edge, 0 is returned.

type Color 

type Color string

Color specifies a color by hex or ANSI value. For example: 

ansiColor := lipgloss.Color("21")
hexColor := lipgloss.Color("#0000ff")

func (Color) RGBA 

func (c Color) RGBA() (r, g, b, a uint32)

RGBA returns the RGBA value of this color. This satisfies the Go Color interface. Note that on error we return black with 100% opacity, or:

Red: 0x0, Green: 0x0, Blue: 0x0, Alpha: 0xFFFF

This is inline with go-colorful's default behavior.

type NoColor 

type NoColor struct{}

NoColor is used to specify the absence of color styling. When this is active foreground colors will be rendered with the terminal's default text color, and background colors will not be drawn at all.

Example usage: 

var style = someStyle.Copy().Background(lipgloss.NoColor{})

func (NoColor) RGBA 

func (n NoColor) RGBA() (r, g, b, a uint32)

RGBA returns the RGBA value of this color. Because we have to return something, despite this color being the absence of color, we're returning the same value that go-colorful returns on error:

Red: 0x0, Green: 0x0, Blue: 0x0, Alpha: 0xFFFF.

type Position 

type Position float64

Position represents a position along a horizontal or vertical axis. It's in situations where an axis is involved, like alignment, joining, placement and so on.

A value of 0 represents the start (the left or top) and 1 represents the end (the right or bottom). 0.5 represents the center.

There are constants Top, Bottom, Center, Left and Right in this package that can be used to aid readability. 

const (
	Top    Position = 0.0
	Bottom Position = 1.0
	Center Position = 0.5
	Left   Position = 0.0
	Right  Position = 1.0
)

Position aliases.

type Style 

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

Style contains a set of rules that comprise a style as a whole.

func NewStyle 

func NewStyle() Style

NewStyle returns a new, empty Style. While it's syntactic sugar for the Style{} primitive, it's recommended to use this function for creating styles incase the underlying implementation changes.

func (Style) Align 

func (s Style) Align(p Position) Style

Align sets a text alignment rule.

func (Style) Background 

func (s Style) Background(c TerminalColor) Style

Background sets a background color. 

func (s Style) Blink(v bool) Style

Blink sets a rule for blinking foreground text.

func (Style) Bold 

func (s Style) Bold(v bool) Style

Bold sets a bold formatting rule.

func (Style) Border 

func (s Style) Border(b Border, sides ...bool) Style

Border is shorthand for setting a the border style and which sides should have a border at once. The variadic argument sides works as follows:

With one value, the value is applied to all sides.

With two values, the values are applied to the vertical and horizontal sides, in that order.

With three values, the values are applied to the top side, the horizontal sides, and the bottom side, in that order.

With four values, the values are applied clockwise starting from the top side, followed by the right side, then the bottom, and finally the left.

With more than four arguments the border will be applied to all sides.

Examples: 

// Applies borders to the top and bottom only
lipgloss.NewStyle().Border(lipgloss.NormalBorder(), true, false)

// Applies rounded borders to the right and bottom only
lipgloss.NewStyle().Border(lipgloss.RoundedBorder(), false, true, true, false)

func (Style) BorderBackground added in v0.1.2 

func (s Style) BorderBackground(c ...TerminalColor) Style

BorderBackground is a shorthand function for setting all of the background colors of the borders at once. The arguments work as follows:

With one argument, the argument is applied to all sides.

With two arguments, the arguments are applied to the vertical and horizontal sides, in that order.

With three arguments, the arguments are applied to the top side, the horizontal sides, and the bottom side, in that order.

With four arguments, the arguments are applied clockwise starting from the top side, followed by the right side, then the bottom, and finally the left.

With more than four arguments nothing will be set.

func (Style) BorderBottom 

func (s Style) BorderBottom(v bool) Style

BorderBottom determines whether or not to draw a bottom border.

func (Style) BorderBottomBackground added in v0.1.2 

func (s Style) BorderBottomBackground(c TerminalColor) Style

BorderBottomBackground sets the background color of the bottom of the border.

func (Style) BorderBottomForeground added in v0.1.2 

func (s Style) BorderBottomForeground(c TerminalColor) Style

BorderBottomForeground sets the foreground color for the bottom of the border.

func (Style) BorderForeground added in v0.1.2 

func (s Style) BorderForeground(c ...TerminalColor) Style

BorderForeground is a shorthand function for setting all of the foreground colors of the borders at once. The arguments work as follows:

With one argument, the argument is applied to all sides.

With two arguments, the arguments are applied to the vertical and horizontal sides, in that order.

With three arguments, the arguments are applied to the top side, the horizontal sides, and the bottom side, in that order.

With four arguments, the arguments are applied clockwise starting from the top side, followed by the right side, then the bottom, and finally the left.

With more than four arguments nothing will be set.

func (Style) BorderLeft 

func (s Style) BorderLeft(v bool) Style

BorderLeft determines whether or not to draw a left border.

func (Style) BorderLeftBackground added in v0.1.2 

func (s Style) BorderLeftBackground(c TerminalColor) Style

BorderLeftBackground set the background color of the left side of the border.

func (Style) BorderLeftForeground added in v0.1.2 

func (s Style) BorderLeftForeground(c TerminalColor) Style

BorderLeftForeground sets the foreground color for the left side of the border.

func (Style) BorderRight 

func (s Style) BorderRight(v bool) Style

BorderRight determines whether or not to draw a right border.

func (Style) BorderRightBackground added in v0.1.2 

func (s Style) BorderRightBackground(c TerminalColor) Style

BorderRightBackground sets the background color of right side the border.

func (Style) BorderRightForeground added in v0.1.2 

func (s Style) BorderRightForeground(c TerminalColor) Style

BorderRightForeground sets the foreground color for the right side of the border.

func (Style) BorderStyle 

func (s Style) BorderStyle(b Border) Style

BorderStyle defines the Border on a style. A Border contains a series of definitions for the sides and corners of a border.

Note that if border visibility has not been set for any sides when setting the border style, the border will be enabled for all sides during rendering.

You can define border characters as you'd like, though several default styles are included: NormalBorder(), RoundedBorder(), ThickBorder(), and DoubleBorder().

Example: 

lipgloss.NewStyle().BorderStyle(lipgloss.ThickBorder())

func (Style) BorderTop 

func (s Style) BorderTop(v bool) Style

BorderTop determines whether or not to draw a top border.

func (Style) BorderTopBackground added in v0.1.2 

func (s Style) BorderTopBackground(c TerminalColor) Style

BorderTopBackground sets the background color of the top of the border.

func (Style) BorderTopForeground added in v0.1.2 

func (s Style) BorderTopForeground(c TerminalColor) Style

BorderTopForeground set the foreground color for the top of the border.

func (Style) ColorWhitespace 

func (s Style) ColorWhitespace(v bool) Style

ColorWhitespace determines whether or not the background color should be applied to the padding. This is true by default as it's more than likely the desired and expected behavior, but it can be disabled for certain graphic effects.

func (Style) Copy 

func (s Style) Copy() Style

Copy returns a copy of this style, including any underlying string values.

func (Style) Faint 

func (s Style) Faint(v bool) Style

Faint sets a rule for rendering the foreground color in a dimmer shade.

func (Style) Foreground 

func (s Style) Foreground(c TerminalColor) Style

Foreground sets a foreground color. 

// Sets the foreground to blue
s := lipgloss.NewStyle().Foreground(lipgloss.Color("#0000ff"))

// Removes the foreground color
s.Foreground(lipgloss.NoColor)

func (Style) GetAlign added in v0.2.0 

func (s Style) GetAlign() Position

GetAlign returns the style's implicit alignment setting. If no alignment is set Position.AlignLeft is returned.

func (Style) GetBackground added in v0.2.0 

func (s Style) GetBackground() TerminalColor

GetBackground returns the style's back color. If no value is set NoColor{} is returned. 

func (s Style) GetBlink() bool

GetBlink returns the style's blink value. It no value is set false is returned.

func (Style) GetBold added in v0.2.0 

func (s Style) GetBold() bool

GetBold returns the style's bold value It no value is set false is returned.

func (Style) GetBorder added in v0.2.0 

func (s Style) GetBorder() (b Border, top, right, bottom, left bool)

GetBorder returns the style's border style (type Border) and value for the top, right, bottom, and left in that order. If no value is set for the border style, Border{} is returned. For all other unset values false is returend.

func (Style) GetBorderBottom added in v0.2.0 

func (s Style) GetBorderBottom() bool

GetBorderBottom returns the style's bottom border setting. If no value is set false is returned.

func (Style) GetBorderBottomBackground added in v0.2.0 

func (s Style) GetBorderBottomBackground() TerminalColor

GetBorderBottomBackground returns the style's border bottom background color. If no value is set NoColor{} is returned.

func (Style) GetBorderBottomForeground added in v0.2.0 

func (s Style) GetBorderBottomForeground() TerminalColor

GetBorderBottomForeground returns the style's border bottom foreground color. If no value is set NoColor{} is returned.

func (Style) GetBorderBottomSize added in v0.4.0 

func (s Style) GetBorderBottomSize() int

GetBorderBottomSize returns the width of the bottom border. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the left edge, 0 is returned.

func (Style) GetBorderLeft added in v0.2.0 

func (s Style) GetBorderLeft() bool

GetBorderLeft returns the style's left border setting. If no value is set false is returned.

func (Style) GetBorderLeftBackground added in v0.2.0 

func (s Style) GetBorderLeftBackground() TerminalColor

GetBorderLeftBackground returns the style's border bottom background color. If no value is set NoColor{} is returned.

func (Style) GetBorderLeftForeground added in v0.2.0 

func (s Style) GetBorderLeftForeground() TerminalColor

GetBorderLeftForeground returns the style's border bottom foreground color. If no value is set NoColor{} is returned.

func (Style) GetBorderLeftSize added in v0.4.0 

func (s Style) GetBorderLeftSize() int

GetBorderLeftSize returns the width of the left border. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the left edge, 0 is returned.

func (Style) GetBorderRight added in v0.2.0 

func (s Style) GetBorderRight() bool

GetBorderRight returns the style's right border setting. If no value is set false is returned.

func (Style) GetBorderRightBackground added in v0.2.0 

func (s Style) GetBorderRightBackground() TerminalColor

GetBorderRightBackground returns the style's border right background color. If no value is set NoColor{} is returned.

func (Style) GetBorderRightForeground added in v0.2.0 

func (s Style) GetBorderRightForeground() TerminalColor

GetBorderRightForeground returns the style's border right foreground color. If no value is set NoColor{} is returned.

func (Style) GetBorderRightSize added in v0.4.0 

func (s Style) GetBorderRightSize() int

GetBorderRightSize returns the width of the right border. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the right edge, 0 is returned.

func (Style) GetBorderStyle added in v0.2.0 

func (s Style) GetBorderStyle() Border

GetBorderStyle returns the style's border style (type Border). If no value is set Border{} is returned.

func (Style) GetBorderTop added in v0.2.0 

func (s Style) GetBorderTop() bool

GetBorderTop returns the style's top border setting. If no value is set false is returned.

func (Style) GetBorderTopBackground added in v0.2.0 

func (s Style) GetBorderTopBackground() TerminalColor

GetBorderTopBackground returns the style's border top background color. If no value is set NoColor{} is returned.

func (Style) GetBorderTopForeground added in v0.2.0 

func (s Style) GetBorderTopForeground() TerminalColor

GetBorderTopForeground returns the style's border top foreground color. If no value is set NoColor{} is returned.

func (Style) GetBorderTopWidth added in v0.4.0 

func (s Style) GetBorderTopWidth() int

GetBorderTopWidth returns the width of the top border. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the top edge, 0 is returned.

func (Style) GetColorWhitespace added in v0.2.0 

func (s Style) GetColorWhitespace() bool

GetColorWhitespace returns the style's whitespace coloring setting. If no value is set false is returned.

func (Style) GetFaint added in v0.2.0 

func (s Style) GetFaint() bool

GetFaint returns the style's faint value. It no value is set false is returned.

func (Style) GetForeground added in v0.2.0 

func (s Style) GetForeground() TerminalColor

GetForeground returns the style's foreground color. If no value is set NoColor{} is returned.

func (Style) GetFrameSize added in v0.4.0 

func (s Style) GetFrameSize() (x, y int)

GetFrameSize returns the sum of the margins, padding and border width for both the horizontal and vertical margins.

func (Style) GetHeight added in v0.2.0 

func (s Style) GetHeight() int

GetHeight returns the style's height setting. If no height is set 0 is returned.

func (Style) GetHorizontalBorderSize added in v0.4.0 

func (s Style) GetHorizontalBorderSize() int

GetHorizontalBorderSize returns the width of the horizontal borders. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the horizontal edges, 0 is returned.

func (Style) GetHorizontalFrameSize added in v0.4.0 

func (s Style) GetHorizontalFrameSize() int

GetHorizontalFrameSize returns the sum of the style's horizontal margins, padding and border widths.

Provisional: this method may be renamed.

func (Style) GetHorizontalMargins added in v0.4.0 

func (s Style) GetHorizontalMargins() int

GetHorizontalMargins returns the style's left and right margins. Unset values are measured as 0.

func (Style) GetHorizontalPadding added in v0.4.0 

func (s Style) GetHorizontalPadding() int

GetHorizontalPadding returns the style's left and right padding. Unset values are measured as 0.

func (Style) GetInline added in v0.2.0 

func (s Style) GetInline() bool

GetInline returns the style's inline setting. If no value is set false is returned.

func (Style) GetItalic added in v0.2.0 

func (s Style) GetItalic() bool

GetItalic returns the style's italic value. It no value is set false is returned.

func (Style) GetMargin added in v0.2.0 

func (s Style) GetMargin() (top, right, bottom, left int)

GetMargin returns the style's top, right, bottom, and left margins, in that order. 0 is returned for unset values.

func (Style) GetMarginBottom added in v0.2.0 

func (s Style) GetMarginBottom() int

GetMarginBottom returns the style's bottom margin. If no value is set 0 is returned.

func (Style) GetMarginLeft added in v0.2.0 

func (s Style) GetMarginLeft() int

GetMarginLeft returns the style's left margin. If no value is set 0 is returned.

func (Style) GetMarginRight added in v0.2.0 

func (s Style) GetMarginRight() int

GetMarginRight returns the style's right margin. If no value is set 0 is returned.

func (Style) GetMarginTop added in v0.2.0 

func (s Style) GetMarginTop() int

GetMarginTop returns the style's top margin. If no value is set 0 is returned.

func (Style) GetMaxHeight added in v0.2.0 

func (s Style) GetMaxHeight() int

GetMaxHeight returns the style's max width setting. If no value is set 0 is returned.

func (Style) GetMaxWidth added in v0.2.0 

func (s Style) GetMaxWidth() int

GetMaxWidth returns the style's max width setting. If no value is set 0 is returned.

func (Style) GetPadding added in v0.2.0 

func (s Style) GetPadding() (top, right, bottom, left int)

GetPadding returns the style's top, right, bottom, and left padding values, in that order. 0 is returned for unset values.

func (Style) GetPaddingBottom added in v0.2.0 

func (s Style) GetPaddingBottom() int

GetPaddingBottom returns the style's bottom padding. If no value is set 0 is returned.

func (Style) GetPaddingLeft added in v0.2.0 

func (s Style) GetPaddingLeft() int

GetPaddingLeft returns the style's left padding. If no value is set 0 is returned.

func (Style) GetPaddingRight added in v0.2.0 

func (s Style) GetPaddingRight() int

GetPaddingRight returns the style's right padding. If no value is set 0 is returned.

func (Style) GetPaddingTop added in v0.2.0 

func (s Style) GetPaddingTop() int

GetPaddingTop returns the style's top padding. If no value is set 0 is returned.

func (Style) GetReverse added in v0.2.0 

func (s Style) GetReverse() bool

GetReverse returns the style's reverse value. It no value is set false is returned.

func (Style) GetStrikethrough added in v0.2.0 

func (s Style) GetStrikethrough() bool

GetStrikethrough returns the style's strikethrough value. It no value is set false is returned.

func (Style) GetStrikethroughSpaces added in v0.2.0 

func (s Style) GetStrikethroughSpaces() bool

GetStrikethroughSpaces returns whether or not the style is set to underline spaces. If not value is set false is returned.

func (Style) GetUnderline added in v0.2.0 

func (s Style) GetUnderline() bool

GetUnderline returns the style's underline value. It no value is set false is returned.

func (Style) GetUnderlineSpaces added in v0.2.0 

func (s Style) GetUnderlineSpaces() bool

GetUnderlineSpaces returns whether or not the style is set to underline spaces. If not value is set false is returned.

func (Style) GetVerticalBorderSize added in v0.4.0 

func (s Style) GetVerticalBorderSize() int

GetVerticalBorderSize returns the width of the horizontal borders. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the horizontal edges, 0 is returned.

func (Style) GetVerticalFrameSize added in v0.4.0 

func (s Style) GetVerticalFrameSize() int

GetVerticalFrameSize returns the sum of the style's horizontal margins, padding and border widths.

Provisional: this method may be renamed.

func (Style) GetVerticalMargins added in v0.4.0 

func (s Style) GetVerticalMargins() int

GetVerticalMargins returns the style's top and bottom padding. Unset values are measured as 0.

func (Style) GetVerticalPadding added in v0.4.0 

func (s Style) GetVerticalPadding() int

GetVerticalPadding returns the style's top and bottom padding. Unset values are measured as 0.

func (Style) GetWidth added in v0.2.0 

func (s Style) GetWidth() int

GetWidth returns the style's width setting. If no width is set 0 is returned.

func (Style) Height 

func (s Style) Height(i int) Style

Height sets the width of the block before applying margins. If the height of the text block is less than this value after applying padding (or not), the block will be set to this height.

func (Style) Inherit 

func (s Style) Inherit(i Style) Style

Inherit takes values from the style in the argument applies them to this style, overwriting existing definitions. Only values explicitly set on the style in argument will be applied.

Margins, padding, and underlying string values are not inherited.

func (Style) Inline 

func (s Style) Inline(v bool) Style

Inline makes rendering output one line and disables the rendering of margins, padding and borders. This is useful when you need a style to apply only to font rendering and don't want it to change any physical dimensions. It works well with Style.MaxWidth.

Because this in intended to be used at the time of render, this method will not mutate the style and instead return a copy.

Example: 

var userInput string = "..."
var userStyle = text.Style{ /* ... */ }
fmt.Println(userStyle.Inline(true).Render(userInput))

func (Style) Italic 

func (s Style) Italic(v bool) Style

Italic sets an italic formatting rule. In some terminal emulators this will render with "reverse" coloring if not italic font variant is available.

func (Style) Margin 

func (s Style) Margin(i ...int) Style

Margin is a shorthand method for setting margins on all sides at once.

With one argument, the value is applied to all sides.

With two arguments, the value is applied to the vertical and horizontal sides, in that order.

With three arguments, the value is applied to the top side, the horizontal sides, and the bottom side, in that order.

With four arguments, the value is applied clockwise starting from the top side, followed by the right side, then the bottom, and finally the left.

With more than four arguments no margin will be added.

func (Style) MarginBackground 

func (s Style) MarginBackground(c TerminalColor) Style

MarginBackground sets the background color of the margin. Note that this is also set when inheriting from a style with a background color. In that case the background color on that style will set the margin color on this style.

func (Style) MarginBottom 

func (s Style) MarginBottom(i int) Style

MarginBottom sets the value of the bottom margin.

func (Style) MarginLeft 

func (s Style) MarginLeft(i int) Style

MarginLeft sets the value of the left margin.

func (Style) MarginRight 

func (s Style) MarginRight(i int) Style

MarginRight sets the value of the right margin.

func (Style) MarginTop 

func (s Style) MarginTop(i int) Style

MarginTop sets the value of the top margin.

func (Style) MaxHeight 

func (s Style) MaxHeight(n int) Style

MaxHeight applies a max width to a given style. This is useful in enforcing a certain width at render time, particularly with arbitrary strings and styles.

Because this in intended to be used at the time of render, this method will not mutate the style and instead return a copy.

func (Style) MaxWidth 

func (s Style) MaxWidth(n int) Style

MaxWidth applies a max width to a given style. This is useful in enforcing a certain width at render time, particularly with arbitrary strings and styles.

Because this in intended to be used at the time of render, this method will not mutate the style and instead return a copy.

Example: 

var userInput string = "..."
var userStyle = text.Style{ /* ... */ }
fmt.Println(userStyle.MaxWidth(16).Render(userInput))

func (Style) Padding 

func (s Style) Padding(i ...int) Style

Padding is a shorthand method for setting padding on all sides at once.

With one argument, the value is applied to all sides.

With two arguments, the value is applied to the vertical and horizontal sides, in that order.

With three arguments, the value is applied to the top side, the horizontal sides, and the bottom side, in that order.

With four arguments, the value is applied clockwise starting from the top side, followed by the right side, then the bottom, and finally the left.

With more than four arguments no padding will be added.

func (Style) PaddingBottom 

func (s Style) PaddingBottom(i int) Style

PaddingBottom adds padding to the bottom of the block.

func (Style) PaddingLeft 

func (s Style) PaddingLeft(i int) Style

PaddingLeft adds padding on the left.

func (Style) PaddingRight 

func (s Style) PaddingRight(i int) Style

PaddingRight adds padding on the right.

func (Style) PaddingTop 

func (s Style) PaddingTop(i int) Style

PaddingTop adds padding to the top of the block.

func (Style) Render 

func (s Style) Render(str string) string

Render applies the defined style formatting to a given string.

func (Style) Reverse 

func (s Style) Reverse(v bool) Style

Reverse sets a rule for inverting foreground and background colors.

func (Style) SetString 

func (s Style) SetString(str string) Style

SetString sets the underlying string value for this style. To render once the underlying string is set, use the Style.String. This method is a convenience for cases when having a stringer implementation is handy, such as when using fmt.Sprintf. You can also simply define a style and render out strings directly with Style.Render.

func (Style) Strikethrough 

func (s Style) Strikethrough(v bool) Style

Strikethrough sets a strikethrough rule. By default, strikes will not be drawn on whitespace like margins and padding. To change this behavior set renderStrikethroughOnSpaces.

func (Style) StrikethroughSpaces 

func (s Style) StrikethroughSpaces(v bool) Style

StrikethroughSpaces determines whether to apply strikethroughs to spaces between words. By default this is true. Spaces can also be struck without underlining the text itself.

func (Style) String 

func (s Style) String() string

String implements stringer for a Style, returning the rendered result based on the rules in this style. An underlying string value must be set with Style.SetString prior to using this method.

func (Style) Underline 

func (s Style) Underline(v bool) Style

Underline sets an underline rule. By default, underlines will not be drawn on whitespace like margins and padding. To change this behavior set renderUnderlinesOnSpaces.

func (Style) UnderlineSpaces 

func (s Style) UnderlineSpaces(v bool) Style

UnderlineSpaces determines whether to underline spaces between words. By default this is true. Spaces can also be underlined without underlining the text itself.

func (Style) UnsetAlign 

func (s Style) UnsetAlign() Style

UnsetAlign removes the text alignment style rule, if set.

func (Style) UnsetBackground 

func (s Style) UnsetBackground() Style

UnsetBackground removes the background style rule, if set. 

func (s Style) UnsetBlink() Style

UnsetBlink removes the bold style rule, if set.

func (Style) UnsetBold 

func (s Style) UnsetBold() Style

UnsetBold removes the bold style rule, if set.

func (Style) UnsetBorderBackground added in v0.1.2 

func (s Style) UnsetBorderBackground() Style

UnsetBorderBackground removes all border background color styles, if set.

func (Style) UnsetBorderBottom 

func (s Style) UnsetBorderBottom() Style

UnsetBorderBottom removes the border bottom style rule, if set.

func (Style) UnsetBorderBottomBackground added in v0.1.2 

func (s Style) UnsetBorderBottomBackground() Style

UnsetBorderBottomBackground removes the bottom border background color rule, if set.

func (Style) UnsetBorderBottomForeground added in v0.1.2 

func (s Style) UnsetBorderBottomForeground() Style

UnsetBorderBottomForeground removes the bottom border foreground color rule, if set.

func (Style) UnsetBorderForeground added in v0.1.2 

func (s Style) UnsetBorderForeground() Style

UnsetBorderForeground removes all border foreground color styles, if set.

func (Style) UnsetBorderLeft 

func (s Style) UnsetBorderLeft() Style

UnsetBorderLeft removes the border left style rule, if set.

func (Style) UnsetBorderLeftBackground added in v0.1.2 

func (s Style) UnsetBorderLeftBackground() Style

UnsetBorderLeftBackground removes the left border color rule, if set.

func (Style) UnsetBorderLeftForeground added in v0.1.2 

func (s Style) UnsetBorderLeftForeground() Style

UnsetBorderLeftForeground removes the left border foreground color rule, if set.

func (Style) UnsetBorderRight 

func (s Style) UnsetBorderRight() Style

UnsetBorderRight removes the border right style rule, if set.

func (Style) UnsetBorderRightBackground added in v0.1.2 

func (s Style) UnsetBorderRightBackground() Style

UnsetBorderRightBackground removes the right border background color rule, if set.

func (Style) UnsetBorderRightForeground added in v0.1.2 

func (s Style) UnsetBorderRightForeground() Style

UnsetBorderRightForeground removes the right border foreground color rule, if set.

func (Style) UnsetBorderStyle 

func (s Style) UnsetBorderStyle() Style

UnsetBorderStyle removes the border style rule, if set.

func (Style) UnsetBorderTop 

func (s Style) UnsetBorderTop() Style

UnsetBorderTop removes the border top style rule, if set.

func (Style) UnsetBorderTopBackgroundColor 

func (s Style) UnsetBorderTopBackgroundColor() Style

UnsetBorderTopBackgroundColor removes the top border background color rule, if set.

func (Style) UnsetBorderTopForeground added in v0.1.2 

func (s Style) UnsetBorderTopForeground() Style

UnsetBorderTopForeground removes the top border foreground color rule, if set.

func (Style) UnsetColorWhitespace 

func (s Style) UnsetColorWhitespace() Style

UnsetColorWhitespace removes the rule for coloring padding, if set.

func (Style) UnsetFaint 

func (s Style) UnsetFaint() Style

UnsetFaint removes the faint style rule, if set.

func (Style) UnsetForeground 

func (s Style) UnsetForeground() Style

UnsetForeground removes the foreground style rule, if set.

func (Style) UnsetHeight 

func (s Style) UnsetHeight() Style

UnsetHeight removes the height style rule, if set.

func (Style) UnsetInline 

func (s Style) UnsetInline() Style

UnsetInline removes the inline style rule, if set.

func (Style) UnsetItalic 

func (s Style) UnsetItalic() Style

UnsetItalic removes the italic style rule, if set.

func (Style) UnsetMarginBackground 

func (s Style) UnsetMarginBackground() Style

UnsetMarginBackground removes the margin's background color. Note that the margin's background color can be set from the background color of another style during inheritance.

func (Style) UnsetMarginBottom 

func (s Style) UnsetMarginBottom() Style

UnsetMarginBottom removes the bottom margin style rule, if set.

func (Style) UnsetMarginLeft 

func (s Style) UnsetMarginLeft() Style

UnsetMarginLeft removes the left margin style rule, if set.

func (Style) UnsetMarginRight 

func (s Style) UnsetMarginRight() Style

UnsetMarginRight removes the right margin style rule, if set.

func (Style) UnsetMarginTop 

func (s Style) UnsetMarginTop() Style

UnsetMarginTop removes the top margin style rule, if set.

func (Style) UnsetMargins 

func (s Style) UnsetMargins() Style

UnsetMargins removes all margin style rules.

func (Style) UnsetMaxHeight 

func (s Style) UnsetMaxHeight() Style

UnsetMaxHeight removes the max height style rule, if set.

func (Style) UnsetMaxWidth 

func (s Style) UnsetMaxWidth() Style

UnsetMaxWidth removes the max width style rule, if set.

func (Style) UnsetPadding 

func (s Style) UnsetPadding() Style

UnsetPadding removes all padding style rules.

func (Style) UnsetPaddingBottom 

func (s Style) UnsetPaddingBottom() Style

UnsetPaddingBottom removes the bottom style rule, if set.

func (Style) UnsetPaddingLeft 

func (s Style) UnsetPaddingLeft() Style

UnsetPaddingLeft removes the left padding style rule, if set.

func (Style) UnsetPaddingRight 

func (s Style) UnsetPaddingRight() Style

UnsetPaddingRight removes the right padding style rule, if set.

func (Style) UnsetPaddingTop 

func (s Style) UnsetPaddingTop() Style

UnsetPaddingTop removes the top padding style rule, if set.

func (Style) UnsetReverse 

func (s Style) UnsetReverse() Style

UnsetReverse removes the reverse style rule, if set.

func (Style) UnsetStrikethrough 

func (s Style) UnsetStrikethrough() Style

UnsetStrikethrough removes the strikethrough style rule, if set.

func (Style) UnsetStrikethroughSpaces 

func (s Style) UnsetStrikethroughSpaces() Style

UnsetStrikethroughSpaces removes the value set by StrikethroughSpaces.

func (Style) UnsetString 

func (s Style) UnsetString() Style

UnsetString sets the underlying string value to the empty string.

func (Style) UnsetUnderline 

func (s Style) UnsetUnderline() Style

UnsetUnderline removes the underline style rule, if set.

func (Style) UnsetUnderlineSpaces 

func (s Style) UnsetUnderlineSpaces() Style

UnsetUnderlineSpaces removes the value set by UnderlineSpaces.

func (Style) UnsetWidth 

func (s Style) UnsetWidth() Style

UnsetWidth removes the width style rule, if set.

func (Style) Value added in v0.5.0 

func (s Style) Value() string

Value returns the raw, unformatted, underlying string value for this style.

func (Style) Width 

func (s Style) Width(i int) Style

Width sets the width of the block before applying margins. The width, if set, also determines where text will wrap.

type TerminalColor 

type TerminalColor interface {
	RGBA() (r, g, b, a uint32)
	// contains filtered or unexported methods
}

TerminalColor is a color intended to be rendered in the terminal. It satisfies the Go color.Color interface.

type WhitespaceOption 

type WhitespaceOption func(*whitespace)

WhitespaceOption sets a styling rule for rendering whitespace.

func WithWhitespaceBackground 

func WithWhitespaceBackground(c TerminalColor) WhitespaceOption

WithWhitespaceBackground sets the background color of the whitespace.

func WithWhitespaceChars 

func WithWhitespaceChars(s string) WhitespaceOption

WithWhitespaceChars sets the characters to be rendered in the whitespace.

func WithWhitespaceForeground 

func WithWhitespaceForeground(c TerminalColor) WhitespaceOption

WithWhitespaceForeground sets the color of the characters in the whitespace.

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.