Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/workanator/Go-ataman
Another Text Attribute Manupulator
https://github.com/workanator/Go-ataman
Last synced: about 2 months ago
JSON representation
Another Text Attribute Manupulator
- Host: GitHub
- URL: https://github.com/workanator/Go-ataman
- Owner: workanator
- License: mit
- Created: 2017-05-17T19:04:57.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2020-12-23T05:36:05.000Z (over 3 years ago)
- Last Synced: 2024-06-19T23:19:12.523Z (3 months ago)
- Language: Go
- Size: 43.9 KB
- Stars: 16
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# go-ataman
**Another Text Attribute Manipulator**
[](https://godoc.org/gopkg.in/workanator/go-ataman.v1)
[](https://travis-ci.org/workanator/go-ataman)
[](https://coveralls.io/github/workanator/go-ataman?branch=master)
[](https://goreportcard.com/report/github.com/workanator/go-ataman)
[](https://github.com/workanator/go-ataman/blob/master/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. `Hello!`
**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.
```go
rndr := ataman.NewRenderer(ataman.BasicStyle())
tpl := "%s<->, <<%s>> <->!"
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.
```go
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.
```go
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![[-]] :)`.
```go
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**.