go-ataman.v1: gopkg.in/workanator/go-ataman.v1 Index | Files | Directories

package ataman

import "gopkg.in/workanator/go-ataman.v1"

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{-}"

// 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![-]"

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.


Package Files

doc.go new.go renderer.go styles.go

func BasicStyle Uses

func BasicStyle() decorate.Style

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

func CurlyStyle Uses

func CurlyStyle() decorate.Style

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

type Renderer Uses

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 Uses

func NewRenderer(style decorate.Style) Renderer

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


ansiPackage ansi defines constants of ANSI graphic mode codes and sequences.
decoratePackage decorate provides facilities to customizable template styling.
decorate/basicPackage basic defines basic decoration style.
decorate/curlyPackage curly defines curly bracket decoration style.
genericPackage generic introduces configurable generic renderer.
preparedPackage prepared introduces prepared template interface.

Package ataman imports 5 packages (graph). Updated 2017-09-25. Refresh now. Tools for package owners.