lipgloss

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2024 License: MIT Imports: 9 Imported by: 5,010

README

Lip Gloss

Lip Gloss title treatment
Latest Release GoDoc Build Status phorm.ai

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.

Complete Colors

CompleteColor specifies exact values for True Color, ANSI256, and ANSI color profiles.

lipgloss.CompleteColor{TrueColor: "#0000FF", ANSI256: "86", ANSI: "5"}

Automatic color degradation will not be performed in this case and it will be based on the color specified.

Complete Adaptive Colors

You can use CompleteColor with AdaptiveColor to specify the exact values for light and dark backgrounds without automatic color degradation.

lipgloss.CompleteAdaptiveColor{
    Light: CompleteColor{TrueColor: "#d7ffae", ANSI256: "193", ANSI: "11"},
    Dark:  CompleteColor{TrueColor: "#d75fee", ANSI256: "163", ANSI: "5"},
}

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 style = lipgloss.NewStyle().
    SetString("What’s for lunch?").
    Width(24).
    Height(32).
    Foreground(lipgloss.Color("63"))

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 double border to the top and left 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 assignment:

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

copiedStyle := style // this is a true copy

wildStyle := style.Blink(true) // this is also true copy, with blink added

Since Style data structures contains only primitive types, assigning a style to another effectively creates a new copy of the style without mutating the original.

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")

Tabs

The tab character (\t) is rendered differently in different terminals (often as 8 spaces, sometimes 4). Because of this inconsistency, Lip Gloss converts tabs to 4 spaces at render time. This behavior can be changed on a per-style basis, however:

style := lipgloss.NewStyle() // tabs will render as 4 spaces, the default
style = style.TabWidth(2)    // render tabs as 2 spaces
style = style.TabWidth(0)    // remove tabs entirely
style = style.TabWidth(lipgloss.NoTabConversion) // leave tabs intact

Rendering

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

style := lipgloss.NewStyle().Bold(true).SetString("Hello,")
fmt.Println(style.Render("kitty.")) // Hello, kitty.
fmt.Println(style.Render("puppy.")) // Hello, puppy.

But you could also use the Stringer interface:

var style = lipgloss.NewStyle().SetString("你好，猫咪。").Bold(true)
fmt.Println(style) // 你好，猫咪。
Custom Renderers

Custom renderers allow you to render to a specific outputs. This is particularly important when you want to render to different outputs and correctly detect the color profile and dark background status for each, such as in a server-client situation.

func myLittleHandler(sess ssh.Session) {
    // Create a renderer for the client.
    renderer := lipgloss.NewRenderer(sess)

    // Create a new style on the renderer.
    style := renderer.NewStyle().Background(lipgloss.AdaptiveColor{Light: "63", Dark: "228"})

    // Render. The color profile and dark background state will be correctly detected.
    io.WriteString(sess, style.Render("Heyyyyyyy"))
}

For an example on using a custom renderer over SSH with Wish see the SSH example.

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.

// Render a block of text.
var style = lipgloss.NewStyle().
    Width(40).
    Padding(2)
var block string = style.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.

Rendering Tables

Lip Gloss ships with a table rendering sub-package.

import "github.com/charmbracelet/lipgloss/table"

Define some rows of data.

rows := [][]string{
    {"Chinese", "您好", "你好"},
    {"Japanese", "こんにちは", "やあ"},
    {"Arabic", "أهلين", "أهلا"},
    {"Russian", "Здравствуйте", "Привет"},
    {"Spanish", "Hola", "¿Qué tal?"},
}

Use the table package to style and render the table.

t := table.New().
    Border(lipgloss.NormalBorder()).
    BorderStyle(lipgloss.NewStyle().Foreground(lipgloss.Color("99"))).
    StyleFunc(func(row, col int) lipgloss.Style {
        switch {
        case row == 0:
            return HeaderStyle
        case row%2 == 0:
            return EvenRowStyle
        default:
            return OddRowStyle
        }
    }).
    Headers("LANGUAGE", "FORMAL", "INFORMAL").
    Rows(rows...)

// You can also add tables row-by-row
t.Row("English", "You look absolutely fabulous.", "How's it going?")

Print the table.

fmt.Println(t)

Table Example

For more on tables see the docs and examples.

Rendering Lists

Lip Gloss ships with a list rendering sub-package.

import "github.com/charmbracelet/lipgloss/list"

Define a new list.

l := list.New("A", "B", "C")

Print the list.

fmt.Println(l)

// • A
// • B
// • C

Lists have the ability to nest.

l := list.New(
    "A", list.New("Artichoke"),
    "B", list.New("Baking Flour", "Bananas", "Barley", "Bean Sprouts"),
    "C", list.New("Cashew Apple", "Cashews", "Coconut Milk", "Curry Paste", "Currywurst"),
    "D", list.New("Dill", "Dragonfruit", "Dried Shrimp"),
    "E", list.New("Eggs"),
    "F", list.New("Fish Cake", "Furikake"),
    "J", list.New("Jicama"),
    "K", list.New("Kohlrabi"),
    "L", list.New("Leeks", "Lentils", "Licorice Root"),
)

Print the list.

fmt.Println(l)

image

Lists can be customized via their enumeration function as well as using lipgloss.Styles.

enumeratorStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("99")).MarginRight(1)
itemStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("212")).MarginRight(1)

l := list.New(
    "Glossier",
    "Claire’s Boutique",
    "Nyx",
    "Mac",
    "Milk",
    ).
    Enumerator(list.Roman).
    EnumeratorStyle(enumeratorStyle).
    ItemStyle(itemStyle)

Print the list.

List example

In addition to the predefined enumerators (Arabic, Alphabet, Roman, Bullet, Tree), you may also define your own custom enumerator:

l := list.New("Duck", "Duck", "Duck", "Duck", "Goose", "Duck", "Duck")

func DuckDuckGooseEnumerator(l list.Items, i int) string {
    if l.At(i).Value() == "Goose" {
        return "Honk →"
    }
    return ""
}

l = l.Enumerator(DuckDuckGooseEnumerator)

Print the list:

image

If you need, you can also build lists incrementally:

l := list.New()

for i := 0; i < repeat; i++ {
    l.Item("Lip Gloss")
}

Rendering Trees

Lip Gloss ships with a tree rendering sub-package.

import "github.com/charmbracelet/lipgloss/tree"

Define a new tree.

t := tree.Root(".").
    Child("A", "B", "C")

Print the tree.

fmt.Println(t)

// .
// ├── A
// ├── B
// └── C

Trees have the ability to nest.

t := tree.Root(".").
    Child("macOS").
    Child(
        tree.New().
            Root("Linux").
            Child("NixOS").
            Child("Arch Linux (btw)").
            Child("Void Linux"),
        ).
    Child(
        tree.New().
            Root("BSD").
            Child("FreeBSD").
            Child("OpenBSD"),
    )

Print the tree.

fmt.Println(t)

Tree Example (simple)

Trees can be customized via their enumeration function as well as using lipgloss.Styles.

enumeratorStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("63")).MarginRight(1)
rootStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("35"))
itemStyle := lipgloss.NewStyle().Foreground(lipgloss.Color("212"))

t := tree.
    Root("⁜ Makeup").
    Child(
        "Glossier",
        "Fenty Beauty",
        tree.New().Child(
            "Gloss Bomb Universal Lip Luminizer",
            "Hot Cheeks Velour Blushlighter",
        ),
        "Nyx",
        "Mac",
        "Milk",
    ).
    Enumerator(tree.RoundedEnumerator).
    EnumeratorStyle(enumeratorStyle).
    RootStyle(rootStyle).
    ItemStyle(itemStyle)

Print the tree.

Tree Example (makeup)

The predefined enumerators for trees are DefaultEnumerator and RoundedEnumerator.

If you need, you can also build trees incrementally:

t := tree.New()

for i := 0; i < repeat; i++ {
    t.Child("Lip Gloss")
}

FAQ

Why are things misaligning? Why are borders at the wrong widths?

This is most likely due to your locale and encoding, particularly with regard to Chinese, Japanese, and Korean (for example, zh_CN.UTF-8 or ja_JP.UTF-8). The most direct way to fix this is to set RUNEWIDTH_EASTASIAN=0 in your environment.

For details see https://github.com/charmbracelet/lipgloss/issues/40.

Why isn't Lip Gloss displaying colors?

Lip Gloss automatically degrades colors to the best available option in the given terminal, and if output's not a TTY it will remove color output entirely. This is common when running tests, CI, or when piping output elsewhere.

If necessary, you can force a color profile in your tests with SetColorProfile.

import (
    "github.com/charmbracelet/lipgloss"
    "github.com/muesli/termenv"
)

lipgloss.SetColorProfile(termenv.TrueColor)

Note: this option limits the flexibility of your application and can cause ANSI escape codes to be output in cases where that might not be desired. Take careful note of your use case and environment before choosing to force a color profile.

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.

Contributing

See contributing.

Feedback

We’d love to hear your thoughts on this project. Feel free to drop us a note!

License

MIT

Part of Charm.

The Charm logo

Charm热爱开源 • Charm loves open source

Documentation

Index

Constants

View Source 
const NoTabConversion = -1

NoTabConversion can be passed to Style.TabWidth to disable the replacement of tabs with spaces at render time.

Variables

This section is empty.

Functions

func ColorProfile 

func ColorProfile() termenv.Profile

ColorProfile returns the detected termenv color profile.

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 top, center or bottom 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 its longest line) this will be a noop.

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 its newlines) then this will be a noop.

func SetColorProfile added in v0.3.0 

func SetColorProfile(p termenv.Profile)

SetColorProfile sets the color profile on the default renderer. 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 the color profile 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 SetDefaultRenderer added in v0.7.0 

func SetDefaultRenderer(r *Renderer)

SetDefaultRenderer sets the default global renderer.

func SetHasDarkBackground added in v0.5.0 

func SetHasDarkBackground(b bool)

SetHasDarkBackground sets the background color detection value for the default renderer. 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 the backgrounds value will be automatically detected and cached against 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 apply a given style to runes at the given indices in 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 ANSIColor added in v0.7.0 

type ANSIColor uint

ANSIColor is a color specified by an ANSI color value. It's merely syntactic sugar for the more general Color function. Invalid colors will render as black.

Example usage: 

// These two statements are equivalent.
colorA := lipgloss.ANSIColor(21)
colorB := lipgloss.Color("21")

func (ANSIColor) RGBA added in v0.7.0 

func (ac ANSIColor) 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.

Deprecated.

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.

Deprecated.

type Border 

type Border struct {
	Top          string
	Bottom       string
	Left         string
	Right        string
	TopLeft      string
	TopRight     string
	BottomLeft   string
	BottomRight  string
	MiddleLeft   string
	MiddleRight  string
	Middle       string
	MiddleTop    string
	MiddleBottom string
}

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

func BlockBorder added in v0.7.0 

func BlockBorder() Border

BlockBorder returns a border that takes the whole block.

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 InnerHalfBlockBorder added in v0.7.0 

func InnerHalfBlockBorder() Border

InnerHalfBlockBorder returns a half-block border that sits inside the frame.

func NormalBorder 

func NormalBorder() Border

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

func OuterHalfBlockBorder added in v0.7.0 

func OuterHalfBlockBorder() Border

OuterHalfBlockBorder returns a half-block border that sits outside the frame.

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.

Deprecated.

type CompleteAdaptiveColor added in v0.6.0 

type CompleteAdaptiveColor struct {
	Light CompleteColor
	Dark  CompleteColor
}

CompleteAdaptiveColor specifies exact values for truecolor, ANSI256, and ANSI color profiles, with separate options for light and dark backgrounds. Automatic color degradation will not be performed.

func (CompleteAdaptiveColor) RGBA added in v0.6.0 

func (cac CompleteAdaptiveColor) 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.

Deprecated.

type CompleteColor added in v0.6.0 

type CompleteColor struct {
	TrueColor string
	ANSI256   string
	ANSI      string
}

CompleteColor specifies exact values for truecolor, ANSI256, and ANSI color profiles. Automatic color degradation will not be performed.

func (CompleteColor) RGBA added in v0.6.0 

func (c CompleteColor) 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. CompleteAdaptiveColor specifies exact values for truecolor, ANSI256, and ANSI color

Deprecated.

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.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 black with 100% opacity.

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

Deprecated.

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 Renderer added in v0.7.0 

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

Renderer is a lipgloss terminal renderer.

func DefaultRenderer added in v0.7.0 

func DefaultRenderer() *Renderer

DefaultRenderer returns the default renderer.

func NewRenderer added in v0.7.0 

func NewRenderer(w io.Writer, opts ...termenv.OutputOption) *Renderer

NewRenderer creates a new Renderer.

w will be used to determine the terminal's color capabilities.

func (*Renderer) ColorProfile added in v0.7.0 

func (r *Renderer) ColorProfile() termenv.Profile

ColorProfile returns the detected termenv color profile.

func (*Renderer) HasDarkBackground added in v0.7.0 

func (r *Renderer) HasDarkBackground() bool

HasDarkBackground returns whether or not the renderer will render to a dark background. A dark background can either be auto-detected, or set explicitly on the renderer.

func (*Renderer) NewStyle added in v0.7.0 

func (r *Renderer) 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 in case the underlying implementation changes. It takes an optional string value to be set as the underlying string value for this style.

func (*Renderer) Output added in v0.7.0 

func (r *Renderer) Output() *termenv.Output

Output returns the termenv output.

func (*Renderer) Place added in v0.7.0 

func (r *Renderer) 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 (*Renderer) PlaceHorizontal added in v0.7.0 

func (r *Renderer) 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 its longest line) this will be a noöp.

func (*Renderer) PlaceVertical added in v0.7.0 

func (r *Renderer) 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 its newlines) then this will be a noöp.

func (*Renderer) SetColorProfile added in v0.7.0 

func (r *Renderer) SetColorProfile(p termenv.Profile)

SetColorProfile sets the color profile on the renderer. 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 the color profile 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 (*Renderer) SetHasDarkBackground added in v0.7.0 

func (r *Renderer) SetHasDarkBackground(b bool)

SetHasDarkBackground sets the background color detection value on the renderer. 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 the backgrounds value will be automatically detected and cached against the terminal's current background color setting.

This function is thread-safe.

func (*Renderer) SetOutput added in v0.7.0 

func (r *Renderer) SetOutput(o *termenv.Output)

SetOutput sets the termenv output.

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 in case the underlying implementation changes. It takes an optional string value to be set as the underlying string value for this style.

func (Style) Align 

func (s Style) Align(p ...Position) Style

Align is a shorthand method for setting horizontal and vertical alignment.

With one argument, the position value is applied to the horizontal alignment.

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

func (Style) AlignHorizontal added in v0.6.0 

func (s Style) AlignHorizontal(p Position) Style

AlignHorizontal sets a horizontal text alignment rule.

func (Style) AlignVertical added in v0.6.0 

func (s Style) AlignVertical(p Position) Style

AlignVertical sets a vertical 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 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(), BlockBorder(), OuterHalfBlockBorder(), InnerHalfBlockBorder(), 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 deprecated 

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.

Deprecated: Just use margins and padding.

func (Style) Copy deprecated 

func (s Style) Copy() Style

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

Deprecated: to copy just use assignment (i.e. a := b). All methods also return a new style.

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 horizontal alignment setting. If no alignment is set Position.Left is returned.

func (Style) GetAlignHorizontal added in v0.6.0 

func (s Style) GetAlignHorizontal() Position

GetAlignHorizontal returns the style's implicit horizontal alignment setting. If no alignment is set Position.Left is returned.

func (Style) GetAlignVertical added in v0.6.0 

func (s Style) GetAlignVertical() Position

GetAlignVertical returns the style's implicit vertical alignment setting. If no alignment is set Position.Top is returned.

func (Style) GetBackground added in v0.2.0 

func (s Style) GetBackground() TerminalColor

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

func (s Style) GetBlink() bool

GetBlink returns the style's blink value. If 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. If 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 returned.

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 left 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 left 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) GetBorderTopSize added in v0.7.0 

func (s Style) GetBorderTopSize() int

GetBorderTopSize 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) GetBorderTopWidth deprecated 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.

Deprecated: This function simply calls Style.GetBorderTopSize.

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. If 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. If 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 height 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. If 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. If 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 strikethrough spaces. If not value is set false is returned.

func (Style) GetTabWidth added in v0.8.0 

func (s Style) GetTabWidth() int

GetTabWidth returns the style's tab width setting. If no value is set 4 is returned which is the implicit default.

func (Style) GetTransform added in v0.10.0 

func (s Style) GetTransform() func(string) string

GetTransform returns the transform set on the style. If no transform is set nil is returned.

func (Style) GetUnderline added in v0.2.0 

func (s Style) GetUnderline() bool

GetUnderline returns the style's underline value. If 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 vertical borders. If borders contain runes of varying widths, the widest rune is returned. If no border exists on the vertical 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 vertical 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 margins. 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 height 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 overlays the style in the argument onto this style by copying each explicitly set value from the argument style onto this style if it is not already explicitly set. Existing set values are kept intact and not overwritten.

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 height to a given style. This is useful in enforcing a certain height 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 returns 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(strs ...string) string

Render applies the defined style formatting to a given string.

func (Style) Renderer added in v0.7.0 

func (s Style) Renderer(r *Renderer) Style

Renderer sets the renderer for the style. This is useful for changing the renderer for a style that is being used in a different context.

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(strs ...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 StrikethroughSpaces.

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) TabWidth added in v0.8.0 

func (s Style) TabWidth(n int) Style

TabWidth sets the number of spaces that a tab (/t) should be rendered as. When set to 0, tabs will be removed. To disable the replacement of tabs with spaces entirely, set this to NoTabConversion.

By default, tabs will be replaced with 4 spaces.

func (Style) Transform added in v0.10.0 

func (s Style) Transform(fn func(string) string) Style

Transform applies a given function to a string at render time, allowing for the string being rendered to be manipuated.

Example: 

s := NewStyle().Transform(strings.ToUpper)
fmt.Println(s.Render("raow!") // "RAOW!"

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 UnderlineSpaces.

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 horizontal and vertical text alignment style rule, if set.

func (Style) UnsetAlignHorizontal added in v0.6.0 

func (s Style) UnsetAlignHorizontal() Style

UnsetAlignHorizontal removes the horizontal text alignment style rule, if set.

func (Style) UnsetAlignVertical added in v0.6.0 

func (s Style) UnsetAlignVertical() Style

UnsetAlignVertical removes the vertical 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 blink 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) UnsetBorderTopBackground added in v0.11.1 

func (s Style) UnsetBorderTopBackground() Style

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

func (Style) UnsetBorderTopBackgroundColor deprecated 

func (s Style) UnsetBorderTopBackgroundColor() Style

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

Deprecated: This function simply calls Style.UnsetBorderTopBackground.

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 padding 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) UnsetTabWidth added in v0.8.0 

func (s Style) UnsetTabWidth() Style

UnsetTabWidth removes the tab width style rule, if set.

func (Style) UnsetTransform added in v0.10.0 

func (s Style) UnsetTransform() Style

UnsetTransform removes the value set by Transform.

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.

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

Directories

Path Synopsis
Package list allows you to build lists, as simple or complicated as you need.
 Package list allows you to build lists, as simple or complicated as you need.
Package tree allows you to build trees, as simple or complicated as you need.
 Package tree allows you to build trees, as simple or complicated as you need.

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.