libescapes

package module
v0.3.7 Latest Latest
Warning

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

 Go to latest Published: Feb 2, 2026 License: MIT Imports: 5 Imported by: 1

README

ansi-scapes GoDoc

ansi-scapes is a minimal Go library for ANSI escape sequences. It handles the small differences in the Apple's Terminal app, as well as enable and disable escape sequences on Windows 10 v1511 and later.

🚧 ansi-escapes is still under development, and is subject to change 🚧

Features

  • Constants for simple escape sequences
  • Functions for sequences with parameters
  • Correct functionality across terminal emulators
  • Ability to enable/disable escape sequence processing on Windows v1511 and later

Installation

With the Go Programming Language,

$ go get -u github.com/snugfox/ansi-escapes

Usage

Go's import mechanism does not allow package names to contain hyphens, so import the package as escapes.

import escapes "github.com/snugfox/ansi-escapes"

Example

package main

import (
  "bytes"
  "fmt"
  "os"

  escapes "github.com/snugfox/ansi-escapes"
)

func main() {
  // Enable support on Windows for this application. It is safe to include on
  // OSes other than Windows, as the functions will only return nil; thus
  // compiled out.
  escapes.EnableVirtualTerminal(escapes.Stdout)
  defer escapes.DisableVirtualTerminal(escapes.Stdout)

  // Erase the screen. Remember that fmt.Println would print the newline *after*
  // the escape sequence.
  fmt.Print(escapes.EraseScreen)

  // Move the cursor one column to the right
  fmt.Print(escapes.CursorForward)

  // Move the cursor to (1, 1)
  fmt.Print(escapes.CursorPos(1, 1))

  // Display a super secret image
  var buf bytes.Buffer
  file, _ := os.Open("meow.jpg")
  buf.ReadFrom(file)
  fmt.Print(escapes.Image(buf.Bytes()))
}

License

MIT (c) Snug_Fox

Documentation

Index

Constants

View Source 
const (
	// ASCII control characters (character code 0-31)
	AsciiNull = iota
	AsciiStartOfHeading
	AsciiStartOfText
	AsciiEndOfText
	AsciiEndOfTransmission
	AsciiEnquiry
	AsciiAcknowledge
	AsciiBell
	AsciiBackspace
	AsciiHorizontalTab
	AsciiLineFeed
	AsciiVerticalTab
	AsciiFormFeed
	AsciiCarriageReturn
	AsciiShiftOut
	AsciiShiftIn
	AsciiDataLinkEscape
	AsciiDeviceControlOne
	AsciiDeviceControlTwo
	AsciiDeviceControlThree
	AsciiDeviceControlFour
	AsciiNegativeAcknowledge
	AsciiSyncIdle
	AsciiEndOfTransmissionBlock
	AsciiCancel
	AsciiEndOfMedium
	AsciiSubstitute
	AsciiEscape
	AsciiFileSeparator
	AsciiGroupSeparator
	AsciiRecordSeparator
	AsciiUnitSeparaTOR

	AsciiDelete = 127
)

https://www.ascii-code.com/

View Source 
const (
	Esc = "\u001B["
	Osc = "\u001B]"
	Bel = "\u0007"
)

Common fragments of escape sequences

View Source 
const (
	CursorUp       = Esc + "A"
	CursorDown     = Esc + "B"
	CursorForward  = Esc + "C"
	CursorBackward = Esc + "D"
	CursorNextLine = Esc + "E"
	CursorPrevLine = Esc + "F"
	CursorLeft     = Esc + "G"
	CursorTop      = Esc + "d"
	CursorTopLeft  = Esc + "H"
	CursorSave     = Esc + "s"
	CursorRestore  = Esc + "u"

	CursorBlinkEnable  = Esc + "?12h"
	CursorBlinkDisable = Esc + "?12I"
	CursorShow         = Esc + "?25h"
	CursorHide         = Esc + "?25l"

	ScrollUp   = Esc + "S"
	ScrollDown = Esc + "T"

	TextInsertChar = Esc + "@"
	TextDeleteChar = Esc + "P"
	TextEraseChar  = Esc + "X"
	TextInsertLine = Esc + "L"
	TextDeleteLine = Esc + "M"

	EraseRight  = Esc + "K"
	EraseLeft   = Esc + "1K"
	EraseLine   = Esc + "2K"
	EraseDown   = Esc + "J"
	EraseUp     = Esc + "1J"
	EraseScreen = Esc + "2J"

	TextColorBlack         = Esc + "30m"
	TextColorRed           = Esc + "31m"
	TextColorGreen         = Esc + "32m"
	TextColorYellow        = Esc + "33m"
	TextColorBlue          = Esc + "34m"
	TextColorMagenta       = Esc + "35m"
	TextColorCyan          = Esc + "36m"
	TextColorWhite         = Esc + "37m"
	TextColorBrightBlack   = Esc + "90m"
	TextColorBrightRed     = Esc + "91m"
	TextColorBrightGreen   = Esc + "92m"
	TextColorBrightYellow  = Esc + "93m"
	TextColorBrightBlue    = Esc + "94m"
	TextColorBrightMagenta = Esc + "95m"
	TextColorBrightCyan    = Esc + "96m"
	TextColorBrightWhite   = Esc + "97m"

	BackgroundColorBlack         = Esc + "40m"
	BackgroundColorRed           = Esc + "41m"
	BackgroundColorGreen         = Esc + "42m"
	BackgroundColorYellow        = Esc + "43m"
	BackgroundColorBlue          = Esc + "44m"
	BackgroundColorMagenta       = Esc + "45m"
	BackgroundColorCyan          = Esc + "46m"
	BackgroundColorWhite         = Esc + "47m"
	BackgroundColorBrightBlack   = Esc + "100m"
	BackgroundColorBrightRed     = Esc + "101m"
	BackgroundColorBrightGreen   = Esc + "102m"
	BackgroundColorBrightYellow  = Esc + "103m"
	BackgroundColorBrightBlue    = Esc + "104m"
	BackgroundColorBrightMagenta = Esc + "105m"
	BackgroundColorBrightCyan    = Esc + "106m"
	BackgroundColorBrightWhite   = Esc + "107m"

	ColorReset = Esc + "0m"

	ClearScreen = "\u001Bc"
)

Common ANSI escapes sequences. These should be used when the desired action is only needed once; otherwise, use the functions (e.g. moving a cursor several lines/columns). See: https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences

View Source 
const (
	CursorSavePosition    = Esc + "s"
	CursorRestorePosition = Esc + "u"
)

ANSI escape sequences for saving and restoring the cursor position

Variables

View Source 
var AllowANSI bool
View Source 
var IsTerminal bool

Functions

func CursorMove 

func CursorMove(x, y int) string

CursorMove returns an escape sequence to move the cursor relative to its current position.

func CursorPos 

func CursorPos(x, y int) string

CursorPos returns an escape sequence to move the cursor to a coordinate pair, where (0, 0) is the origin (top-left corner).

func CursorPosX 

func CursorPosX(x int) string

CursorPosX returns an escape sequence to move the cursor to an x-coordinate (column) at the current y-coordinate (row), where 0 is the leftmost.

func CursorPosY 

func CursorPosY(y int) string

CursorPosY returns an escape sequence to move the cursor to an y-coordinate (row) at the current x-coordinate (column), where 0 is the topmost.

func DisableVirtualTerminal 

func DisableVirtualTerminal(fd uintptr) error

DisableVirtualTerminal disables virtual terminal escapes sequences for a console handle. It is only effective when built for Windows. On other OSes, it will simply return nil.

func EnableVirtualTerminal 

func EnableVirtualTerminal(fd uintptr) error

EnableVirtualTerminal enables virtual terminal escapes sequences for a console handle. It is only effective when built for Windows. On other OSes, it will simply return nil.

func Image 

func Image(img []byte) string

Image returns an escape sequence to display an image, preserving the original height and width.

func ImageWidthHeight 

func ImageWidthHeight(img []byte, height, width int, preserveAspectRatio bool) string

ImageWidthHeight returns an escape sequence to display an image. 

func Link(url, text string) string

Link returns an escape sequence to represent linked text.

func Optional added in v0.3.7 

func Optional(sequence string) string

func Scroll 

func Scroll(n int) string

Scroll returns an escape sequence to scroll the current window. A positive number of lines indicates scrolling up, while a negative number of lines indicates scrolling down.

func SetCwd 

func SetCwd(dir string) string

SetCwd returns an escape sequence to set the current working directory.

func TextDeleteChars 

func TextDeleteChars(n int) string

TextDeleteChars returns an escape sequence to delete characters to the right of, and including, the current cursor position, shifting existing characters to the left.

func TextDeleteLines 

func TextDeleteLines(n int) string

TextDeleteLines returns an escape sequence to delete the lines below, and including, the current cursor row.

func TextEraseChars 

func TextEraseChars(n int) string

TextEraseChars returns an escape sequence to insert spaces to the right of, and including, the current cursor position, overwriting existing characters to the right.

func TextInsertChars 

func TextInsertChars(n int) string

TextInsertChars returns an escape sequence to insert spaces to the right of, and including, the current cursor position, shifting existing characters to the right.

func TextInsertLines 

func TextInsertLines(n int) string

TextInsertLines returns an escape sequence to insert blank lines below, and including the current cursor row, shifting existing lines downwards.

func TrueColor added in v0.3.6 

func TrueColor(r, g, b uint64) string

TrueColor returns the ansi escape sequence to set foreground RGB. each number must be 0..255.

Types

type ConsoleDim 

type ConsoleDim struct {
	Rows int
	Cols int
}

ConsoleDim represents the dimensions of a console in rows and columns.

func GetConsoleSize 

func GetConsoleSize(fd uintptr) (*ConsoleDim, error)

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.