ataman

package module
Version: v1.0.0-...-e3b73d2 Latest Latest
Warning

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

Go to latest
Published: Dec 23, 2020 License: MIT Imports: 5 Imported by: 4

README

Gopher Ataman

go-ataman

Another Text Attribute Manipulator

GoDoc Build Status Coverage Status Go Report Card License

The goal of the project is to help render colored text in terminal applications with text attribute manipulation contained in text template. The idea is similar to HTML, e.g. <span style="color:green">Hello!</span>

ataman is not a full-featured template processor. It aims only on simple terminal text attribute, graphic mode in ANSI terms, manipulations using ANSI sequences.

Features

  • Parsing and rendering template with single iteration.
  • Minimal memory allocations with pooling.
  • Thread-safe parsing and rendering.
  • Fully customizable decoration of tags.

Installation

To install the package use go get gopkg.in/workanator/go-ataman.v1

Quick Example

The next example shows basic usage of the package. The renderer here uses basic decoration style.

rndr := ataman.NewRenderer(ataman.BasicStyle())
tpl := "<light+green>%s<->, <bg+light+yellow,black,bold> <<%s>> <-><red>!"
fmt.Println(rndr.MustRenderf(tpl, "Hello", "Terminal World"))

This example produces colored text like this.

Example Output

Renderer is able to pre-render templates so in further output operations they can be reused without parsing and rendering. In this example the renderer uses curly brackets decoration style.

rndr := ataman.NewRenderer(ataman.CurlyStyle())
prep := rndr.MustPrepare("{light_green}%s{-}, {bg_light_yellow+black+bold} <%s> {-}{red}!")
fmt.Println(rndr.MustRenderf(tpl, "Hi", "Everybody"))

The pre-rendered template implements fmt.Stringer interface so it can be used in output operations without additional code, e.g.

prep := rndr.MustPrepare("{red}Red {green}Green {blue}Blue{-}")
fmt.Println(prep)

Writing Templates

Templates follow the simple rules.

  • Tag can contain one or more attributes, e.g. {white,bold}, {red}.
  • If template should render open or close tag sequence as regular text then the sequence should be doubled. For example, if tag is enclosed in { and } then in template it should be This rendered as {{regular text}}.
  • Renderer adds reset graphic mode ANSI sequence to the each template if it contains any other ANSI sequences. So visually those templates are equivalent {bold}Bold{-} and {bold}Bold.

Decoration styles use the follows dictionary.

  • - or reset stand for reset graphic mode.
  • b or bold make font bold.
  • u or underscore or underline make font underline.
  • blink makes font blink.
  • reverse swaps text and background colors.
  • conceal makes font concealed (whatever that means).
  • black color.
  • red color.
  • green color.
  • yellow color.
  • blue color.
  • magenta color.
  • cyan color.
  • white color.
  • default reverts to the default color.
  • bg or background should be used in conjunction with color to set background color.
  • intensive or light should be used in conjunction with color to make the color intensive. Could be used with background as well.

Some template examples with curly decoration style.

  • {light_green} - makes text light (intensive) green.
  • {bg_yellow} - makes background yellow.
  • {bold} - makes font bold.
  • {red,bg_blue} - makes text red on blue background.
  • {u,black,bg_intensive_white} - makes text black with underline font on intensive white background.
  • {-} - reset the current graphic mode.

Customizing Renderer

The package allows to customize tag decorations what can be achieved through decorate.Style struct. The struct should be initialized with preferred values. For example with the code below we can define a decoration style like [[bold,yellow]]Warning![[-]] [[intensive_white]]This package is awesome![[-]] :).

style := decorate.Style{
  TagOpen:            decorate.NewMarker("[["),
  TagClose:           decorate.NewMarker("]]"),
  AttributeDelimiter: decorate.NewMarker(","),
  ModDelimiter:       decorate.NewMarker("-"),
  Attributes:         ansi.DefaultDict,
}

rndr := ataman.NewRenderer(style)

The rules of decoration styles are the follows.

  • TagOpen is the sequence of runes which open tag.
  • TagClose is the sequence of runes which close tag.
  • AttributeDelimiter is the sequence of runes which delimits attributes inside tag.
  • ModDelimiter is the sequence of runes which delimits modifiers in attribute.
  • Attributes is the map of attributes, where key is the name of ANSI code user uses in templates and value is the ANSI code used in ANSI sequence.

It's recommended to use attribute codes defined in ansi package with the default Renderer provided by ataman.

Documentation

Overview

Package ataman is a colored terminal text rendering engine using ANSI sequences. The project aims on simple text attribute manipulations with templates.

Here is the couple of examples to introduce the project.

// Rendering with the renderer
rndr := ataman.NewRenderer(ataman.CurlyStyle())
tpl := "{red}Red {green}Green {blue}Blue{-}"
fmt.Println(rndr.MustRender(tpl))

// Rendering pre-rendered template.
prep := rndr.MustPrepare("{light_green}%s{-}, {bg_light_yellow+blue+bold}%s{-}!")
fmt.Println(prep.Format("Hello", "World"))

Customization of decoration styles can be done through `decorate.Style`, e.g.

style := decorate.Style{
  TagOpen:            decorate.NewMarker("["),
  TagClose:           decorate.NewMarker("]"),
  AttributeDelimiter: decorate.NewMarker(","),
  ModDelimiter:       decorate.NewMarker("-"),
  Attributes:         ansi.DefaultDict,
}

rndr := ataman.NewRenderer(style)
tpl := "[bold,yellow]Warning![-] [intensive_white]This package is awesome![-]"
fmt.Println(rndr.MustRender(tpl))

Templates follow the simple rules.

- Tag can contain one or more attributes, e.g. `{white,bold}`, `{red}`.
- If template should render open or close tag sequence as regular text then
  the sequence should be doubled. For example, if tag is enclosed in `{` and `}`
  then in template it should be `This rendered as {{regular text}}`.
- Renderer adds reset graphic mode ANSI sequence to the each template if it
  contains any other ANSI sequences. So visually those templates are equivalent
  `{bold}Bold{-}` and `{bold}Bold`.

Decoration styles use the follows dictionary.

- `-` or `reset` stand for reset graphic mode.
- `b` or `bold` make font bold.
- `u` or `underscore` or `underline` make font underline.
- `blink` makes font blink.
- `reverse` swaps text and background colors.
- `conceal` makes font concealed (whatever that means).
- `black` color.
- `red` color.
- `green` color.
- `yellow` color.
- `blue` color.
- `magenta` color.
- `cyan` color.
- `white` color.
- `default` reverts to the default color.
- `bg` or `background` should be used in conjunction with color to set
  background color.
- `intensive` or `light` should be used in conjunction with color to make
  the color intensive. Could be used with `background` as well.

Some template examples with curly decoration style.

- `{light_green}` - makes text light (intensive) green.
- `{bg_yellow}` - makes background yellow.
- `{bold}` - makes font bold.
- `{red,bg_blue}` - makes text red on blue background.
- `{u,black,bg_intensive_white}` - makes text black with underline font on
  intensive white background.
- `{-}` - reset the current graphic mode.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BasicStyle

func BasicStyle() decorate.Style

BasicStyle returns the basic decoration style. Quick example: `<bold,light+green,bg:black>`

func CurlyStyle

func CurlyStyle() decorate.Style

CurlyStyle returns the curly brackets decoration style. Quick example: `{bold+light_green+bg_black}`

Types

type Renderer

type Renderer interface {
	// Validate validates the template.
	Validate(tpl string) (err error)

	// Render renders the template given. If the template contains errors
	// the error will be returned.
	Render(tpl string) (s string, err error)

	// MustRender renders the template and panics in case of error.
	MustRender(tpl string) (s string)

	// Renderf formats and renders the template given. If the template contains
	// errors the error will be returned.
	Renderf(tpl string, args ...interface{}) (s string, err error)

	// MustRenderf formats and renders the template and panics in case of error.
	MustRenderf(tpl string, args ...interface{}) (s string)

	// Len returns the length of the text the user see in terminal. To achieve
	// that the implementation of the interface can remove all keywords from
	// the original template for example. The method is useful when proper
	// alignemt in terminal is required.
	Len(tpl string) (n int)

	// Lenf calculates and return the length of the formatted template.
	Lenf(tpl string, args ...interface{}) (n int)

	// Prepare pre-renders the template given and returns the prepared render
	// instance which can be used for rendering without direct access to
	// the renderer it was produced with.
	Prepare(tpl string) (pt prepared.Template, err error)

	// MustPrepare pre-renders the template and panics in case of parsing error.
	MustPrepare(tpl string) (pt prepared.Template)
}

Renderer does rendering of the text templates.

func NewRenderer

func NewRenderer(style decorate.Style) Renderer

NewRenderer creates the generic configurable renderer instance with the decoration style given.

Directories

Path Synopsis
Package ansi defines constants of ANSI graphic mode codes and sequences.
Package ansi defines constants of ANSI graphic mode codes and sequences.
Package decorate provides facilities to customizable template styling.
Package decorate provides facilities to customizable template styling.
basic
Package basic defines basic decoration style.
Package basic defines basic decoration style.
curly
Package curly defines curly bracket decoration style.
Package curly defines curly bracket decoration style.
Package generic introduces configurable generic renderer.
Package generic introduces configurable generic renderer.
Package prepared introduces prepared template interface.
Package prepared introduces prepared template interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL