Another Text Attribute Manipulator
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.
- Parsing and rendering template with single iteration.
- Minimal memory allocations with pooling.
- Thread-safe parsing and rendering.
- Fully customizable decoration of tags.
To install the package use go get gopkg.in/workanator/go-ataman.v1
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.
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)
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 beThis 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.
-
orreset
stand for reset graphic mode.b
orbold
make font bold.u
orunderscore
orunderline
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
orbackground
should be used in conjunction with color to set background color.intensive
orlight
should be used in conjunction with color to make the color intensive. Could be used withbackground
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.
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.