Skip to content
Another Text Attribute Manupulator
Go
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ansi Move ANSI attributes used in styles into default dict May 24, 2017
decorate Fix import to be gopkg.in Sep 25, 2017
generic Fix import to be gopkg.in Sep 25, 2017
prepared Fix import to be gopkg.in Sep 25, 2017
.gitignore Add gitignore Sep 25, 2017
.travis.yml Fix Travis build script Sep 25, 2017
LICENSE Update LICENSE May 17, 2017
README.md Fix template example May 27, 2017
doc.go Fix template example May 27, 2017
new.go Fix import to be gopkg.in Sep 25, 2017
renderer.go Fix import to be gopkg.in Sep 25, 2017
styles.go Fix import to be gopkg.in Sep 25, 2017

README.md

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.

You can’t perform that action at this time.