README.md
1# Pretty
2[](https://travis-ci.org/tidwall/prettty)
3[](http://gocover.io/github.com/tidwall/pretty)
4[](https://pkg.go.dev/github.com/tidwall/pretty)
5
6
7Pretty is a Go package that provides [fast](#performance) methods for formatting JSON for human readability, or to compact JSON for smaller payloads.
8
9Getting Started
10===============
11
12## Installing
13
14To start using Pretty, install Go and run `go get`:
15
16```sh
17$ go get -u github.com/tidwall/pretty
18```
19
20This will retrieve the library.
21
22## Pretty
23
24Using this example:
25
26```json
27{"name": {"first":"Tom","last":"Anderson"}, "age":37,
28"children": ["Sara","Alex","Jack"],
29"fav.movie": "Deer Hunter", "friends": [
30 {"first": "Janet", "last": "Murphy", "age": 44}
31 ]}
32```
33
34The following code:
35```go
36result = pretty.Pretty(example)
37```
38
39Will format the json to:
40
41```json
42{
43 "name": {
44 "first": "Tom",
45 "last": "Anderson"
46 },
47 "age": 37,
48 "children": ["Sara", "Alex", "Jack"],
49 "fav.movie": "Deer Hunter",
50 "friends": [
51 {
52 "first": "Janet",
53 "last": "Murphy",
54 "age": 44
55 }
56 ]
57}
58```
59
60## Color
61
62Color will colorize the json for outputing to the screen.
63
64```json
65result = pretty.Color(json, nil)
66```
67
68Will add color to the result for printing to the terminal.
69The second param is used for a customizing the style, and passing nil will use the default `pretty.TerminalStyle`.
70
71## Ugly
72
73The following code:
74```go
75result = pretty.Ugly(example)
76```
77
78Will format the json to:
79
80```json
81{"name":{"first":"Tom","last":"Anderson"},"age":37,"children":["Sara","Alex","Jack"],"fav.movie":"Deer Hunter","friends":[{"first":"Janet","last":"Murphy","age":44}]}```
82```
83
84
85## Customized output
86
87There's a `PrettyOptions(json, opts)` function which allows for customizing the output with the following options:
88
89```go
90type Options struct {
91 // Width is an max column width for single line arrays
92 // Default is 80
93 Width int
94 // Prefix is a prefix for all lines
95 // Default is an empty string
96 Prefix string
97 // Indent is the nested indentation
98 // Default is two spaces
99 Indent string
100 // SortKeys will sort the keys alphabetically
101 // Default is false
102 SortKeys bool
103}
104```
105## Performance
106
107Benchmarks of Pretty alongside the builtin `encoding/json` Indent/Compact methods.
108```
109BenchmarkPretty-8 1000000 1283 ns/op 720 B/op 2 allocs/op
110BenchmarkUgly-8 3000000 426 ns/op 240 B/op 1 allocs/op
111BenchmarkUglyInPlace-8 5000000 340 ns/op 0 B/op 0 allocs/op
112BenchmarkJSONIndent-8 300000 4628 ns/op 1069 B/op 4 allocs/op
113BenchmarkJSONCompact-8 1000000 2469 ns/op 758 B/op 4 allocs/op
114```
115
116*These benchmarks were run on a MacBook Pro 15" 2.8 GHz Intel Core i7 using Go 1.7.*
117
118## Contact
119Josh Baker [@tidwall](http://twitter.com/tidwall)
120
121## License
122
123Pretty source code is available under the MIT [License](/LICENSE).
124
125
){kind=link}
){kind=link}
){kind=link}