README
¶
escaper 
escaper lets you create your own formatting syntax. By design,
expanding a format string with this utility requires no additional arguments
(unlike fmt.Sprinf) by letting you easily register your own escape handlers.
This makes it ideal for configurability, where only a string is
necessary to specify a complex output format.
Motivation
There is often desire to make some program output user-configurable.
A lot of software doesn't bother with configurability and has hard-coded
output formats. This package aims to eliminate this unfortunate paradigm,
and easily permit customizability where it is often disregarded. Inspired by
the style of zsh prompt expansion, escaper makes output formatting a
better abstraction for its users.
Install
go get github.com/lucasem/escaper
Examples
Basics
format := "add some ANSI %F{blue}text color%f easily"
esc := escaper.Default()
output := esc.Expand(format)
Advanced
format := "my name is %n, and the time is %D{3:04PM}"
name := "Ben Bitdiddle"
// use New() if you don't want the default ANSI escapes
esc := escaper.New()
// register a new escape
esc.Register('n', func() string {
return name
})
// register an escape that takes an argument
esc.RegisterArg('D', func(arg string) string {
return time.Now().Format(arg)
})
// "my name is Ben Bitdiddle, and the time is 11:15AM"
output := esc.Expand(format)
The Default
The default escaper (escaper.Default()) supports the following ANSI
escapes:
%F{<color>}text%fcolors the text%K{<color>}text%kcolors the background%Btext%bbolds the text%Utext%uunderlines the text%Stext%sstandouts (color inverts) the text
<color> can be one of:
black (0)
red (1)
green (2)
yellow (3)
blue (4)
magenta (5)
cyan (6)
white (7)
License
The MIT License (MIT) - see LICENSE for details
Documentation
¶
Overview ¶
package escaper provides a utility for creating custom format strings.
By design, expanding a format string with this utility requires no additional arguments (unlike fmt.Sprintf) by letting you easily register your own escape handlers.
Basic usage:
format := "%F{blue}text color%f, %K{red}background color%k, "
+ "%Bbold%b, %Uunderline%u, and %Sstandout%s."
esc := escaper.Default()
output := esc.Expand(format)
Advanced usage:
format := "my name is %n, and the time is %D{3:04PM}"
name := "Ben Bitdiddle"
// use New() if you don't want the default ANSI escapes
esc := escaper.New()
esc.Register('n', func() string {
return name
})
esc.RegisterArg('D', func(arg string) string {
return time.Now().Format(arg)
})
output := esc.Expand(format)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Escaper ¶
type Escaper struct {
// contains filtered or unexported fields
}
Escaper maintains matchers for expanding format strings.
func Default ¶
func Default() *Escaper
Default returns a new escaper that has preloaded ANSI escapes (begin/end):
%F/%f text color (takes arg) %K/%k background color (takes arg) %B/%b bold %U/%u underline %S/%s standout
The color escapes take an argument which can be a word or number as follows:
black (0) red (1) green (2) yellow (3) blue (4) magenta (5) cyan (6) white (7)
func (*Escaper) Expand ¶
Expand performs the programmed escapes, returning the expanded string. The percent sign '%' is the escaping rune. For a literal pecent sign, use '%%'. If no escapes are assigned to a rune that is escaped, the literal rune is used.
For escapes that take an argument, the argument is surrounded in curly braces '{<ARG>}' and immediately follows the escape rune. No expands are performed within the argument, and the '%' still escapes (for the sake of using a literal '}' via '%}'). If the escape rune is not immediately followed by a left curly brace, the argument is set to an empty string.
Example:
esc := Default()
out := esc.Expand("80%% is %decent")
// out == "80% is decent"
out = esc.Expand("%Bthis%b is %F{cyan}colorful%f")
// out is "this is colorful", but with visual style
func (*Escaper) Register ¶
Register adds an escape for a rune with its associated function. It overwrites previous matchers for the given rune.
Example:
esc := New()
esc.Register('n', func() string {
return "I replace '%n'"
})
esc.Expand("%n") // "I replace '%n'"
func (*Escaper) RegisterArg ¶
RegisterArg is like Register, but matches the escaped rune followed by an argument.
Example:
esc := New()
esc.RegisterArg('q', func(arg string) string {
// takes a number, squares it
i, _ := strconv.Atoi(arg)
return strconv.Itoa(i * i)
})
esc.Expand("%q{20}") // "400"
Source Files