format

README

String formatting package using Rust-style formatting directives, geared specifcally towards formatting arguments for key-value log output. Provides ONLY default, key, value and verbose formatting directives. For most formatting cases you will be best served by "fmt".

Generally more visually friendly than "fmt" and performance is much improved.

Documentation

Index

• Constants
• func Append(buf *byteutil.Buffer, v ...interface{})
• func AppendEscape(dst []byte, str string) []byte
• func Appendf(buf *byteutil.Buffer, s string, a ...interface{})
• func Byte2Str(c byte) string
• func ContainsDoubleQuote(s string) bool
• func ContainsSpaceOrTab(s string) bool
• func IsSafeASCII(str string) bool
• type Formatter
  • func (f *Formatter) Append(buf *byteutil.Buffer, v ...interface{})
  • func (f *Formatter) Appendf(buf *byteutil.Buffer, s string, a ...interface{})

Constants

const (
	// Flag bit constants, note they are prioritised in this order.
	IsKeyBit = uint8(1) << 0 // set to indicate key formatting
	VboseBit = uint8(1) << 1 // set to indicate verbose formatting
	IsValBit = uint8(1) << 2 // set to indicate value formatting
	PanicBit = uint8(1) << 3 // set after panic to prevent recursion
)

const (
	// SingleTermLine: beyond a certain length of string, all of the
	// extra checks to handle quoting/not-quoting add a significant
	// amount of extra processing time. Quoting in this manner only really
	// effects readability on a single line, so a max string length that
	// encompasses the maximum number of columns on *most* terminals was
	// selected. This was chosen using the metric that 1080p is one of the
	// most common display resolutions, and that a relatively small font size
	// of 7 requires 223 columns. So 256 should be >= $COLUMNS (fullscreen)
	// in 99% of usecases (these figures all pulled out of my ass).
	SingleTermLine = 256
)

Functions

func Append

func Append(buf *byteutil.Buffer, v ...interface{})

Append will append formatted form of supplied values into 'buf' using default formatter. See Formatter.Append() for more documentation.

func AppendEscape

func AppendEscape(dst []byte, str string) []byte

AppendEscape will append 's' to 'dst' and escape any double quotes. EXPECTS ASCII.

func Appendf

func Appendf(buf *byteutil.Buffer, s string, a ...interface{})

Appendf will append the formatted string with supplied values into 'buf' using default formatter. See Formatter.Appendf() for more documentation.

func Byte2Str

func Byte2Str(c byte) string

Byte2Str returns 'c' as a string, escaping if necessary.

func ContainsDoubleQuote

func ContainsDoubleQuote(s string) bool

ContainsDoubleQuote checks if "s" contains a double quote. EXPECTS ASCII.

func ContainsSpaceOrTab

func ContainsSpaceOrTab(s string) bool

ContainsSpaceOrTab checks if "s" contains space or tabs. EXPECTS ASCII.

func IsSafeASCII

func IsSafeASCII(str string) bool

IsSafeASCII checks whether string is printable (i.e. non-control char) ASCII text.

Types

type Formatter

type Formatter struct {
	// MaxDepth specifies the max depth of fields the formatter will iterate.
	// Once max depth is reached, value will simply be formatted as "...".
	// e.g.
	//
	// MaxDepth=1
	// type A struct{
	//     Nested B
	// }
	// type B struct{
	//     Nested C
	// }
	// type C struct{
	//     Field string
	// }
	//
	// Append(&buf, A{}) => {Nested={Nested={Field=...}}}
	MaxDepth uint8
}

Formatter allows configuring value and string formatting.

func (*Formatter) Append

func (f *Formatter) Append(buf *byteutil.Buffer, v ...interface{})

Append will append formatted form of supplied values into 'buf'.

func (*Formatter) Appendf

func (f *Formatter) Appendf(buf *byteutil.Buffer, s string, a ...interface{})

Appendf will append the formatted string with supplied values into 'buf'. Supported format directives: - '{}' => format supplied arg, in place - '{0}' => format arg at index 0 of supplied, in place - '{:?}' => format supplied arg verbosely, in place - '{:k}' => format supplied arg as key, in place - '{:v}' => format supplied arg as value, in place

To escape either of '{}' simply append an additional brace e.g. - '{{' => '{' - '}}' => '}' - '{{}}' => '{}' - '{{:?}}' => '{:?}'

More formatting directives might be included in the future.