Documentation
¶
Overview ¶
Package ojson reads and edits JSON without reordering it. Its package-level functions match github.com/tidwall/gjson v1.19.0 and github.com/tidwall/sjson v1.2.5, so code can switch by changing the import:
import gjson "github.com/MoeForge/moego/ojson" import sjson "github.com/MoeForge/moego/ojson"
On valid JSON the results are the same as those of gjson and sjson, except in these cases, where those libraries fail:
- An array index more than 16,777,216 past the end returns an error, where sjson pads the array with nulls until memory runs out.
- Valid keeps its own stack, so deep nesting cannot overflow the goroutine stack.
- With the Optimistic and ReplaceInPlace options, a string value that needs escaping is set, where sjson leaves the document unchanged.
- Set, SetRaw and Delete never turn a valid document into invalid JSON. On a query path, sjson writes the value at the offsets of whatever Get finds there, including the output of modifiers, counts and offsets that do not point at a value of the document. ojson sets only values that stand at those offsets, and otherwise leaves the document unchanged without an error. Where a plain path runs into a string, sjson edits the text inside the string; ojson replaces the string.
- Set and SetRaw never add a member under a key its object already has. sjson finds members by reading each path component as a Get path, so it misses a member whose key starts with '[', '{' or '!' and adds a second one. ojson replaces the member the key names.
- The @pretty, @dig and @group modifiers return an empty value when their output would exceed 64 MiB plus 16 times the size of their input, which bounds the memory a path can make them use.
On malformed JSON, which Valid reports as invalid, the results may differ from those of gjson and sjson. The only promise there is that no call panics, overflows the stack or uses unbounded memory.
Edits keep every untouched byte and the order of members. For several edits to one document, use a Doc: it applies them in memory and writes the result once.
doc := ojson.NewDoc(body)
doc.Set("temperature", 0.2)
doc.Set("messages.0.content", "hello")
body = doc.Bytes()
Index ¶
- Variables
- func AddModifier(name string, fn func(json, arg string) string)
- func AppendJSONString(dst []byte, s string) []byte
- func Delete(json, path string) (string, error)
- func DeleteBytes(json []byte, path string) ([]byte, error)
- func Escape(comp string) string
- func ForEachLine(json string, iterator func(line Result) bool)
- func ModifierExists(name string, fn func(json, arg string) string) bool
- func Set(json, path string, value interface{}) (string, error)
- func SetBytes(json []byte, path string, value interface{}) ([]byte, error)
- func SetBytesOptions(json []byte, path string, value interface{}, opts *Options) ([]byte, error)
- func SetOptions(json, path string, value interface{}, opts *Options) (string, error)
- func SetRaw(json, path, value string) (string, error)
- func SetRawBytes(json []byte, path string, value []byte) ([]byte, error)
- func SetRawBytesOptions(json []byte, path string, value []byte, opts *Options) ([]byte, error)
- func SetRawOptions(json, path, value string, opts *Options) (string, error)
- func Valid(json string) bool
- func ValidBytes(json []byte) bool
- func ValidReader(r io.Reader) (bool, error)
- type Doc
- func (d *Doc) AppendTo(dst []byte) []byte
- func (d *Doc) Bytes() []byte
- func (d *Doc) Delete(path string) error
- func (d *Doc) Get(path string) Result
- func (d *Doc) Len() int
- func (d *Doc) Set(path string, value interface{}) error
- func (d *Doc) SetRaw(path, value string) error
- func (d *Doc) SetRawBytes(path string, value []byte) error
- func (d *Doc) String() string
- func (d *Doc) WriteTo(w io.Writer) (int64, error)
- type Options
- type Result
- func Get(json, path string) Result
- func GetBytes(json []byte, path string) Result
- func GetBytesNoCopy(json []byte, path string) Result
- func GetMany(json string, path ...string) []Result
- func GetManyBytes(json []byte, path ...string) []Result
- func GetManyBytesNoCopy(dst []Result, json []byte, path ...string) []Result
- func GetManyReaderAt(r io.ReaderAt, size int64, paths ...string) ([]Result, error)
- func Parse(json string) Result
- func ParseBytes(json []byte) Result
- func (t Result) All() iter.Seq2[Result, Result]
- func (t Result) Array() []Result
- func (t Result) Bool() bool
- func (t Result) Exists() bool
- func (t Result) Float() float64
- func (t Result) ForEach(iterator func(key, value Result) bool)
- func (t Result) Get(path string) Result
- func (t Result) Int() int64
- func (t Result) IsArray() bool
- func (t Result) IsBool() bool
- func (t Result) IsObject() bool
- func (t Result) Keys() iter.Seq[Result]
- func (t Result) Less(token Result, caseSensitive bool) bool
- func (t Result) Map() map[string]Result
- func (t Result) Path(json string) string
- func (t Result) Paths(json string) []string
- func (t Result) String() string
- func (t Result) Time() time.Time
- func (t Result) Uint() uint64
- func (t Result) Value() interface{}
- func (t Result) Values() iter.Seq[Result]
- type Type
Constants ¶
This section is empty.
Variables ¶
var DisableEscapeHTML = false
DisableEscapeHTML stops AppendJSONString and @tostr from escaping '<', '>' and '&'.
var DisableModifiers = false
DisableModifiers turns off modifiers: an '@name' path component is then read as a plain key.
Functions ¶
func AddModifier ¶
AddModifier binds a custom modifier command to the path syntax: '@name' or '@name:arg' calls fn with the JSON of the current value and the argument text. A custom modifier replaces a built-in one with the same name. Unlike in gjson, AddModifier is safe to call while other goroutines read.
func AppendJSONString ¶
AppendJSONString appends s to dst as a JSON string. Invalid UTF-8 becomes U+FFFD, and '<', '>' and '&' are escaped unless DisableEscapeHTML is set.
func DeleteBytes ¶
DeleteBytes is Delete for a byte slice. When nothing is deleted the input slice is returned.
func Escape ¶
Escape returns comp with a backslash before every character that has a meaning in a path, so that it matches as one literal key.
Get(json, "user."+Escape("first.name"))
func ForEachLine ¶
ForEachLine calls iterator for each value of a JSON Lines document, in order, until it returns false. Values may be separated by any whitespace. Objects and arrays carry their offset in Index; other values have Index 0. Like gjson, bytes that cannot start a value are skipped.
func ModifierExists ¶
ModifierExists reports whether a modifier with the name exists, built in or added with AddModifier. fn is not used.
func SetBytesOptions ¶
SetBytesOptions is SetBytes with options. With Optimistic and ReplaceInPlace both set, the result is written into json's memory when its capacity allows, and json must not be used afterwards.
func SetOptions ¶
SetOptions is Set with options.
func SetRawBytes ¶
SetRawBytes is SetRaw for byte slices.
func SetRawBytesOptions ¶
SetRawBytesOptions is SetRawBytes with options, which it treats as SetBytesOptions does.
func SetRawOptions ¶
SetRawOptions is SetRaw with options.
func Valid ¶
Valid reports whether json is valid JSON: one value (RFC 8259) surrounded only by whitespace, at any depth.
func ValidReader ¶
ValidReader reports whether the bytes r returns until io.EOF are valid JSON, as Valid does for the same bytes, and returns an error other than io.EOF that r returned. It reads through a fixed buffer and stops at the first byte that makes the input invalid, so it uses memory for the nesting of the input and not for its size, unless a single number or literal is longer than the buffer.
Types ¶
type Doc ¶
type Doc struct {
// contains filtered or unexported fields
}
Doc is a JSON document for a batch of edits. The first edit is kept as one splice of the input, so a single edit costs what SetBytes does. From the second edit on, the objects and arrays that edits and reads walk through are split into members, front to back and only as far as each lookup needs; everything else stays a slice of the input, and new text goes into blocks the Doc owns. Set and Delete give the same document, byte for byte, as SetBytes and DeleteBytes called in sequence, and the output is built once.
A Doc reads its input without copying it, so the caller must not modify the input while the Doc is in use.
func (*Doc) Get ¶
Get returns the value at path in the current document, as Get on String would. The result may share memory with the Doc's input.
func (*Doc) SetRaw ¶
SetRaw sets the raw JSON text value at path, like SetRawBytes. value is not validated.
func (*Doc) SetRawBytes ¶
SetRawBytes is SetRaw for a byte slice. The bytes are copied.
type Options ¶
type Options struct {
// Optimistic is a hint that the value likely exists. The edit first
// looks for it the way Get does, though taking the first of duplicate
// keys as Set does, and replaces it when found.
Optimistic bool
// ReplaceInPlace asks SetBytesOptions and SetRawBytesOptions to write
// the result into the input's memory when its capacity holds it, after
// which the input must not be used. As in sjson, it needs Optimistic.
ReplaceInPlace bool
}
Options matches sjson.Options. On valid JSON the options never change the document an edit produces, only how fast and where it is written.
type Result ¶
type Result struct {
// Type is the JSON type.
Type Type
// Raw is the raw JSON text of the value.
Raw string
// Str is the decoded value of a String.
Str string
// Num is the value of a Number.
Num float64
// Index is the byte offset of Raw in the original document, or 0 when
// unknown.
Index int
// Indexes holds the offsets of the elements produced by a '#' query.
Indexes []int
}
Result is a value found in a JSON document.
func Get ¶
Get searches json for path and returns the value it finds. A missing value returns a Result whose Exists method reports false.
func GetBytesNoCopy ¶
GetBytesNoCopy is GetBytes without the copy. The result shares memory with json, so it is valid only while json is not modified.
func GetManyBytes ¶
GetManyBytes is GetMany for a byte slice. The results do not share memory with json.
func GetManyBytesNoCopy ¶
GetManyBytesNoCopy is GetManyBytes without copies. It stores the results in dst, reusing its memory when it has room, and returns them. The results share memory with json, so they are valid only while json is not modified.
func GetManyReaderAt ¶
GetManyReaderAt is GetMany for the size bytes at the start of r: the results are the ones GetMany returns for those bytes, and they do not share memory with r.
When each path is a chain of member names and array indexes, made of letters, digits, '_' and '-', GetManyReaderAt reads r through a fixed buffer, stops once every path is resolved, and keeps only the values that the paths name. Any other path, and malformed JSON that it meets on the way, make it read all size bytes into memory.
func (Result) All ¶
All returns an iterator over the members of an object or the elements of an array, as ForEach visits them.
func (Result) Array ¶
Array returns the elements of an array. A non-array value is returned as a one-element slice, and a null value as an empty one.
func (Result) ForEach ¶
ForEach calls iterator for each member of an object or element of an array, in document order, until it returns false. The key of an array element is a Number holding its position. For any other existing value it calls iterator once with an empty key.
func (Result) Get ¶
Get searches the value with path, as package-level Get does. Index and Indexes are offsets in the document t came from: like gjson, Index is shifted even when nothing is found.
func (Result) Less ¶
Less reports whether t sorts before token. Values of different types sort as Null < False < Number < String < True < JSON. Strings compare by bytes, or with ASCII letters folded to lower case when caseSensitive is false; numbers compare by value, and other values by their raw text.
func (Result) Path ¶
Path returns a path that finds t in json, the document t came from, with every key escaped, or "" when Raw is not at Index in json. The root value has the path "@this".
func (Result) Paths ¶
Paths returns, for a result with Indexes such as one from "friends.#.first", the path of each element in json, the document the result came from. An element whose path cannot be found gets "". The result is nil when t has no Indexes.
func (Result) Time ¶
Time parses the string form of the value as an RFC 3339 time. It returns the zero time when that fails.