pretty

README

Pretty

Pretty is a Go package that provides fast methods for formatting JSON for human readability, or to compact JSON for smaller payloads.

Getting Started

Installing

To start using Pretty, install Go and run go get:

$ go get -u github.com/tidwall/pretty

This will retrieve the library.

Pretty

Using this example:

{"name":  {"first":"Tom","last":"Anderson"},  "age":37,
"children": ["Sara","Alex","Jack"],
"fav.movie": "Deer Hunter", "friends": [
    {"first": "Janet", "last": "Murphy", "age": 44}
  ]}

The following code:

result = pretty.Pretty(example)

Will format the json to:

{
  "name": {
    "first": "Tom",
    "last": "Anderson"
  },
  "age": 37,
  "children": ["Sara", "Alex", "Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
    {
      "first": "Janet",
      "last": "Murphy",
      "age": 44
    }
  ]
}

Color

Color will colorize the json for outputing to the screen.

result = pretty.Color(json, nil)

Will add color to the result for printing to the terminal. The second param is used for a customizing the style, and passing nil will use the default pretty.TerminalStyle.

Ugly

The following code:

result = pretty.Ugly(example)

Will format the json to:

{"name":{"first":"Tom","last":"Anderson"},"age":37,"children":["Sara","Alex","Jack"],"fav.movie":"Deer Hunter","friends":[{"first":"Janet","last":"Murphy","age":44}]}```

Customized output

There's a PrettyOptions(json, opts) function which allows for customizing the output with the following options:

type Options struct {
	// Width is an max column width for single line arrays
	// Default is 80
	Width int
	// Prefix is a prefix for all lines
	// Default is an empty string
	Prefix string
	// Indent is the nested indentation
	// Default is two spaces
	Indent string
	// SortKeys will sort the keys alphabetically
	// Default is false
	SortKeys bool
}

Performance

Benchmarks of Pretty alongside the builtin encoding/json Indent/Compact methods.

BenchmarkPretty-8            1000000     1283 ns/op      720 B/op      2 allocs/op
BenchmarkUgly-8              3000000      426 ns/op      240 B/op      1 allocs/op
BenchmarkUglyInPlace-8       5000000      340 ns/op        0 B/op      0 allocs/op
BenchmarkJSONIndent-8         300000     4628 ns/op     1069 B/op      4 allocs/op
BenchmarkJSONCompact-8       1000000     2469 ns/op      758 B/op      4 allocs/op

These benchmarks were run on a MacBook Pro 15" 2.8 GHz Intel Core i7 using Go 1.7.

Contact

Josh Baker @tidwall

License

Pretty source code is available under the MIT License.

Documentation

Index

• Variables
• func Color(src []byte, style *Style) []byte
• func Pretty(json []byte) []byte
• func PrettyOptions(json []byte, opts *Options) []byte
• func Ugly(json []byte) []byte
• func UglyInPlace(json []byte) []byte
• type Options
• type Style

Variables

var DefaultOptions = &Options{Width: 80, Prefix: "", Indent: "  ", SortKeys: false}

DefaultOptions is the default options for pretty formats.

var TerminalStyle = &Style{
	Key:    [2]string{"\x1B[94m", "\x1B[0m"},
	String: [2]string{"\x1B[92m", "\x1B[0m"},
	Number: [2]string{"\x1B[93m", "\x1B[0m"},
	True:   [2]string{"\x1B[96m", "\x1B[0m"},
	False:  [2]string{"\x1B[96m", "\x1B[0m"},
	Null:   [2]string{"\x1B[91m", "\x1B[0m"},
	Append: func(dst []byte, c byte) []byte {
		if c < ' ' && (c != '\r' && c != '\n' && c != '\t' && c != '\v') {
			dst = append(dst, "\\u00"...)
			dst = append(dst, hexp((c>>4)&0xF))
			return append(dst, hexp((c)&0xF))
		}
		return append(dst, c)
	},
}

TerminalStyle is for terminals

Functions

func Color

func Color(src []byte, style *Style) []byte

Color will colorize the json. The style parma is used for customizing the colors. Passing nil to the style param will use the default TerminalStyle.

func Pretty

func Pretty(json []byte) []byte

Pretty converts the input json into a more human readable format where each element is on it's own line with clear indentation.

func PrettyOptions

func PrettyOptions(json []byte, opts *Options) []byte

PrettyOptions is like Pretty but with customized options.

func Ugly

func Ugly(json []byte) []byte

Ugly removes insignificant space characters from the input json byte slice and returns the compacted result.

func UglyInPlace

func UglyInPlace(json []byte) []byte

UglyInPlace removes insignificant space characters from the input json byte slice and returns the compacted result. This method reuses the input json buffer to avoid allocations. Do not use the original bytes slice upon return.

Types

type Options

type Options struct {
	// Width is an max column width for single line arrays
	// Default is 80
	Width int
	// Prefix is a prefix for all lines
	// Default is an empty string
	Prefix string
	// Indent is the nested indentation
	// Default is two spaces
	Indent string
	// SortKeys will sort the keys alphabetically
	// Default is false
	SortKeys bool
}

Options is Pretty options

type Style

type Style struct {
	Key, String, Number [2]string
	True, False, Null   [2]string
	Append              func(dst []byte, c byte) []byte
}

Style is the color style