ojson

package
v0.1.0-alpha.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 18 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var DisableEscapeHTML = false

DisableEscapeHTML stops AppendJSONString and @tostr from escaping '<', '>' and '&'.

View Source
var DisableModifiers = false

DisableModifiers turns off modifiers: an '@name' path component is then read as a plain key.

Functions

func AddModifier

func AddModifier(name string, fn func(json, arg string) string)

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

func AppendJSONString(dst []byte, s string) []byte

AppendJSONString appends s to dst as a JSON string. Invalid UTF-8 becomes U+FFFD, and '<', '>' and '&' are escaped unless DisableEscapeHTML is set.

func Delete

func Delete(json, path string) (string, error)

Delete removes the value at path. A missing value is not an error.

func DeleteBytes

func DeleteBytes(json []byte, path string) ([]byte, error)

DeleteBytes is Delete for a byte slice. When nothing is deleted the input slice is returned.

func Escape

func Escape(comp string) string

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

func ForEachLine(json string, iterator func(line Result) bool)

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

func ModifierExists(name string, fn func(json, arg string) string) bool

ModifierExists reports whether a modifier with the name exists, built in or added with AddModifier. fn is not used.

func Set

func Set(json, path string, value interface{}) (string, error)

Set sets the value at path, creating missing objects and arrays.

func SetBytes

func SetBytes(json []byte, path string, value interface{}) ([]byte, error)

SetBytes is Set for a byte slice. The input is not modified.

func SetBytesOptions

func SetBytesOptions(json []byte, path string, value interface{}, opts *Options) ([]byte, error)

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

func SetOptions(json, path string, value interface{}, opts *Options) (string, error)

SetOptions is Set with options.

func SetRaw

func SetRaw(json, path, value string) (string, error)

SetRaw sets the raw JSON text value at path. value is not validated.

func SetRawBytes

func SetRawBytes(json []byte, path string, value []byte) ([]byte, error)

SetRawBytes is SetRaw for byte slices.

func SetRawBytesOptions

func SetRawBytesOptions(json []byte, path string, value []byte, opts *Options) ([]byte, error)

SetRawBytesOptions is SetRawBytes with options, which it treats as SetBytesOptions does.

func SetRawOptions

func SetRawOptions(json, path, value string, opts *Options) (string, error)

SetRawOptions is SetRaw with options.

func Valid

func Valid(json string) bool

Valid reports whether json is valid JSON: one value (RFC 8259) surrounded only by whitespace, at any depth.

func ValidBytes

func ValidBytes(json []byte) bool

ValidBytes is Valid for a byte slice.

func ValidReader

func ValidReader(r io.Reader) (bool, error)

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 NewDoc

func NewDoc(json []byte) *Doc

NewDoc returns a Doc for json.

func NewDocString

func NewDocString(json string) *Doc

NewDocString returns a Doc for json.

func (*Doc) AppendTo

func (d *Doc) AppendTo(dst []byte) []byte

AppendTo appends the current document to dst.

func (*Doc) Bytes

func (d *Doc) Bytes() []byte

Bytes returns the current document in a new slice.

func (*Doc) Delete

func (d *Doc) Delete(path string) error

Delete removes the value at path, like DeleteBytes.

func (*Doc) Get

func (d *Doc) Get(path string) Result

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) Len

func (d *Doc) Len() int

Len returns the length of the current document in bytes.

func (*Doc) Set

func (d *Doc) Set(path string, value interface{}) error

Set sets the value at path, like SetBytes.

func (*Doc) SetRaw

func (d *Doc) SetRaw(path, value string) error

SetRaw sets the raw JSON text value at path, like SetRawBytes. value is not validated.

func (*Doc) SetRawBytes

func (d *Doc) SetRawBytes(path string, value []byte) error

SetRawBytes is SetRaw for a byte slice. The bytes are copied.

func (*Doc) String

func (d *Doc) String() string

String returns the current document.

func (*Doc) WriteTo

func (d *Doc) WriteTo(w io.Writer) (int64, error)

WriteTo writes the current document to w. Short pieces are gathered in a buffer; long runs of the input are written to w directly.

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

func Get(json, path string) Result

Get searches json for path and returns the value it finds. A missing value returns a Result whose Exists method reports false.

func GetBytes

func GetBytes(json []byte, path string) Result

GetBytes is Get for a byte slice. The result does not share memory with json.

func GetBytesNoCopy

func GetBytesNoCopy(json []byte, path string) Result

GetBytesNoCopy is GetBytes without the copy. The result shares memory with json, so it is valid only while json is not modified.

func GetMany

func GetMany(json string, path ...string) []Result

GetMany returns the values for several paths, in order.

func GetManyBytes

func GetManyBytes(json []byte, path ...string) []Result

GetManyBytes is GetMany for a byte slice. The results do not share memory with json.

func GetManyBytesNoCopy

func GetManyBytesNoCopy(dst []Result, json []byte, path ...string) []Result

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

func GetManyReaderAt(r io.ReaderAt, size int64, paths ...string) ([]Result, error)

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 Parse

func Parse(json string) Result

Parse parses json and returns its root value. It does not validate json.

func ParseBytes

func ParseBytes(json []byte) Result

ParseBytes is Parse for a byte slice.

func (Result) All

func (t Result) All() iter.Seq2[Result, Result]

All returns an iterator over the members of an object or the elements of an array, as ForEach visits them.

func (Result) Array

func (t Result) Array() []Result

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) Bool

func (t Result) Bool() bool

Bool returns a boolean form of the value.

func (Result) Exists

func (t Result) Exists() bool

Exists reports whether the value exists in the document.

func (Result) Float

func (t Result) Float() float64

Float returns a float64 form of the value.

func (Result) ForEach

func (t Result) ForEach(iterator func(key, value Result) bool)

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

func (t Result) Get(path string) Result

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) Int

func (t Result) Int() int64

Int returns an integer form of the value.

func (Result) IsArray

func (t Result) IsArray() bool

IsArray reports whether the value is a JSON array.

func (Result) IsBool

func (t Result) IsBool() bool

IsBool reports whether the value is true or false.

func (Result) IsObject

func (t Result) IsObject() bool

IsObject reports whether the value is a JSON object.

func (Result) Keys

func (t Result) Keys() iter.Seq[Result]

Keys returns an iterator over the keys that ForEach visits.

func (Result) Less

func (t Result) Less(token Result, caseSensitive bool) bool

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) Map

func (t Result) Map() map[string]Result

Map returns the members of an object. Duplicate keys keep the first value.

func (Result) Path

func (t Result) Path(json string) string

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

func (t Result) Paths(json string) []string

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) String

func (t Result) String() string

String returns a string form of the value.

func (Result) Time

func (t Result) Time() time.Time

Time parses the string form of the value as an RFC 3339 time. It returns the zero time when that fails.

func (Result) Uint

func (t Result) Uint() uint64

Uint returns an unsigned integer form of the value.

func (Result) Value

func (t Result) Value() interface{}

Value returns the value as a Go value: map[string]interface{}, []interface{}, float64, string, bool or nil. Of duplicate keys, the first wins.

func (Result) Values

func (t Result) Values() iter.Seq[Result]

Values returns an iterator over the values that ForEach visits.

type Type

type Type int

Type is the type of a JSON value.

const (
	// Null is a null JSON value, or a missing one.
	Null Type = iota
	// False is the JSON false literal.
	False
	// Number is a JSON number.
	Number
	// String is a JSON string.
	String
	// True is the JSON true literal.
	True
	// JSON is a raw object or array.
	JSON
)

func (Type) String

func (t Type) String() string

String returns the type name.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL