You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
jsonc is a Go package for working with JSONC files.
9
+
`jsonc` is a light and dependency-free package for working with JSON with comments data built on top of `encoding/json`.
10
+
It allows to remove comments converting to valid JSON-encoded data and to unmarshal JSON with comments into Go values.
6
11
7
-
JSONC is an extension to JSON that allows comments. This package provides functions to:
12
+
The dependencies listed in [go.mod](/go.mod) are only used for testing and benchmarking or to support [alternative libraries](#alternative-libraries).
8
13
9
-
- Sanitize JSONC data by removing comments
10
-
- Unmarshal JSONC into Go values
14
+
## Features
15
+
16
+
- Full support for comment lines and block comments
17
+
- Preserve the content of strings that contain comment characters
18
+
- Sanitize JSON with comments data by removing comments
19
+
- Unmarshal JSON with comments into Go values
11
20
12
21
## Installation
13
22
14
-
Install the jsonc package:
23
+
Install the `jsonc` package:
15
24
16
-
`go get github.com/marcozac/go-jsonc`
25
+
```bash
26
+
go get github.com/marcozac/go-jsonc
27
+
```
17
28
18
29
## Usage
19
30
20
-
### Sanitize JSON with comments
31
+
### Sanitize - Remove comments from JSON data
32
+
33
+
`Sanitize` removes all comments from JSON data, returning valid JSON-encoded byte slice that is compatible with standard library's json.Unmarshal.
34
+
35
+
It works with comment lines and block comments anywhere in the JSONC data, preserving the content of strings that contain comment characters.
21
36
22
-
Remove comments making the data compatible to JSON.
37
+
#### Example
23
38
24
39
```go
25
40
package main
@@ -33,7 +48,11 @@ import (
33
48
funcmain() {
34
49
invalidData:= []byte(`{
35
50
// a comment
36
-
"foo": "bar"
51
+
"foo": "bar" /* a comment in a weird place */,
52
+
/*
53
+
a block comment
54
+
*/
55
+
"hello": "world" // another comment
37
56
}`)
38
57
39
58
// Remove comments from JSONC
@@ -42,19 +61,37 @@ func main() {
42
61
...
43
62
}
44
63
45
-
varvstruct{ Foo string }
64
+
varvstruct{
65
+
Foo string
66
+
Hello string
67
+
}
46
68
47
69
// Unmarshal using any other library
48
-
err = json.Unmarshal(data, &v)
49
-
if err != nil {
70
+
iferr:= json.Unmarshal(data, &v); err != nil {
50
71
...
51
72
}
52
73
}
53
74
```
54
75
55
-
### Unmarshal JSON with comments data into a Go value
76
+
### Unmarshal - Parse JSON with comments into a Go value
56
77
57
-
The Unmarshal function takes JSONC data and a pointer to the target Go value to unmarshal into.
78
+
`Unmarshal` replicates the behavior of the standard library's json.Unmarshal function, with the addition of support for comments.
79
+
80
+
It is optimized to avoid calling [`Sanitize`](#sanitize---remove-comments-from-json-data) unless it detects comments in the data.
81
+
This avoids the overhead of removing comments when they are not present, improving performance on small data sets.
82
+
83
+
It first checks if the data contains comment characters as `//` or `/*` using [`HasCommentRunes`](https://pkg.go.dev/github.com/marcozac/go-jsonc#HasCommentRunes).
84
+
If no comment characters are found, it directly unmarshals the data.
85
+
86
+
Only if comments are detected it calls [`Sanitize`](#sanitize---remove-comments-from-json-data) before unmarshaling to remove them.
87
+
So, `Unmarshal` tries to skip unnecessary work when possible, but currently it is not possible to detect false positives as `//` or `/*` inside strings.
88
+
89
+
Since the comment detection is based on a simple rune check, it is not recommended to use `Unmarshal` on large data sets unless you are not sure whether they contain comments.
90
+
Indeed, `HasCommentRunes` needs to checks every single byte before to return `false` and may drastically slow down the process.
91
+
92
+
In this case, it is more efficient to call [`Sanitize`](#sanitize---remove-comments-from-json-data) before to unmarshal the data.
93
+
94
+
#### Example
58
95
59
96
```go
60
97
package main
@@ -76,6 +113,45 @@ func main() {
76
113
}
77
114
```
78
115
116
+
## Alternative libraries
117
+
118
+
By default, `jsonc` uses the standard library's `encoding/json` to unmarshal JSON data and has no external dependencies.
119
+
120
+
It is possible to use build tags to use alternative libraries instead of the standard library's `encoding/json`:
This library aims to have performance comparable to the standard library's `encoding/json`.
131
+
Unfortunately, comments removal is not free and it is not possible to avoid the overhead of removing comments when they are present.
132
+
133
+
Currently `jsonc` performs worse than the standard library's `encoding/json` on small data sets about 27% on data with comments in strings and 16% on data without comments.
134
+
On medium data sets, the performance gap is increased to about 30% on data with comments in strings and reduced to 12% on data without comments.
135
+
136
+
However, using one of the [alternative libraries](#alternative-libraries), it is possible to achieve better performance than the standard library's `encoding/json` even considering the overhead of removing comments.
137
+
138
+
See [benchmarks](/benchmarks) for the full results.
139
+
140
+
The benchmarks are run on a MacBook Pro (16-inch, 2021), Apple M1 Max, 32 GB RAM.
141
+
142
+
## Contributing
143
+
144
+
:heart: Contributions are ~~needed~~ welcome!
145
+
146
+
Please open an issue or submit a pull request if you would like to contribute.
147
+
148
+
To submit a pull request:
149
+
150
+
- Fork this repository
151
+
- Create a new branch
152
+
- Make changes and commit
153
+
- Push to your fork and submit a pull request
154
+
79
155
## License
80
156
81
-
This project is licensed under the Apache 2.0 license. See LICENSE file for details.
157
+
This project is licensed under the Apache 2.0 license. See [LICENSE](/LICENSE) file for details.
The tables below show the performance of [`Unmarshal`](#unmarshal---parse-json-with-comments-into-a-go-value) compared to the standard library's `encoding/json` and other alternative libraries on small and medium data sets.
| Set reference | result (Δ% on reference / reference result) | same | same |
10
+
11
+
See the files in this directory for the full report.
12
+
13
+
### Standard library
14
+
15
+
The tables below show the performance of [`Unmarshal`](#unmarshal---parse-json-with-comments-into-a-go-value) compared to the standard library's `encoding/json` on small and medium data sets.
0 commit comments