jsonx

package module
v0.0.0-...-1a936bd Latest Latest
Warning

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

Go to latest
Published: Jun 29, 2020 License: MIT Imports: 5 Imported by: 16

README

jsonx

Package jsonx is an extended JSON library for Go. It is highly tolerant of errors, and it supports trailing commas and comments (// and /* ... */).

It is ported from Visual Studio Code's comment-aware JSON parsing and editing APIs in TypeScript, specifically in these files:

Status: Experimental

  • Where the original TypeScript code's API is not idiomatic in Go, this library does not (yet) attempt to provide an idiomatic Go API. This is mainly evident in the error return API for parsing and scanning errors.

Documentation

Overview

Package jsonx is an extended JSON library for Go. It is highly tolerant of errors, and it supports trailing commas and comments (`//` and `/* ... */`).

It is ported from [Visual Studio Code's](https://github.com/Microsoft/vscode) comment-aware JSON parsing and editing APIs in TypeScript.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ApplyEdits

func ApplyEdits(text string, edits ...Edit) (string, error)

ApplyEdits applies the edits to the JSON document and returns the edited document. The edits must be ordered and within the bounds of the document.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/jsonFormatter.ts#L34

func ComputePropertyEdit

func ComputePropertyEdit(text string, path Path, value interface{}, insertionIndex func(properties []string) int, options FormatOptions) ([]Edit, []ParseErrorCode, error)

ComputePropertyEdit returns the edits necessary to set the value at the specified key path to the value. If value is nil, the property's value is set to JSON null; use ComputePropertyRemoval to obtain the edits necessary to remove a property. If value is a json.RawMessage, it is treated as an opaque value to insert (which means it can contain comments, trailing commas, etc.).

If the insertionIndex is non-nil, it is called to determine the index at which to insert the value (given the existing properties, in order).

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/jsonEdit.ts#L14

func ComputePropertyRemoval

func ComputePropertyRemoval(text string, path Path, options FormatOptions) ([]Edit, []ParseErrorCode, error)

ComputePropertyRemoval returns the edits necessary to remove the property at the specified key path.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/jsonEdit.ts#L10

func NodeValue

func NodeValue(node Node) interface{}

NodeValue returns the JSON parse tree node's value.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L782

func ObjectPropertyNames

func ObjectPropertyNames(node Node) []string

ObjectPropertyNames returns property names of the JSON object represented by the specified JSON parse tree node.

func ParseTree

func ParseTree(text string, options ParseOptions) (root *Node, errors []ParseErrorCode)

ParseTree parses the given text and returns a tree representation the JSON content. On invalid input, the parser tries to be as fault tolerant as possible, but still return a result.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L688

func Walk

func Walk(text string, options ParseOptions, visitor Visitor) bool

Walk parses the JSON document text and calls the visitor's funcs for each object, array and literal reached.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L799

Types

type Edit

type Edit struct {
	Offset  int    // the character offset where the edit begins
	Length  int    // the character length of the region to replace with the content
	Content string // the content to insert into the document
}

An Edit represents an edit to a JSON document.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/jsonFormatter.ts#L24

Example
const input = `
/* comment */
{
  "a": 1 // oops! forgot a comma
  /* note the trailing comma */
  "b": 2,
}`

// Insert value 3 at key path c/d.
edits, _, _ := ComputePropertyEdit(input,
	PropertyPath("c", "d"),
	3,
	nil,
	FormatOptions{InsertSpaces: true, TabSize: 2},
)
output, _ := ApplyEdits(input, edits...)
fmt.Println(output)
Output:

/* comment */
{
  "a": 1 // oops! forgot a comma
  /* note the trailing comma */
  "b": 2,
  "c": {
    "d": 3
  },
}

func Format

func Format(text string, options FormatOptions) []Edit

Format returns edits that format the entire JSON document according to the format options. To apply the edits and obtain the formatted document content, use ApplyEdits.

func FormatEdit

func FormatEdit(text string, edit Edit, options FormatOptions) ([]Edit, error)

FormatEdit returns the edits necessary to perform the original edit for maintaining the formatting of the JSON document.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/jsonEdit.ts#L122

func FormatRange

func FormatRange(text string, offset, length int, options FormatOptions) []Edit

FormatRange returns edits that format the JSON document (starting at the character offset and continuing for the character length) according to the format options. To apply the edits and obtain the formatted document content, use ApplyEdits.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/jsonFormatter.ts#L41

type FormatOptions

type FormatOptions struct {
	TabSize      int    // If indentation is based on spaces (InsertSpaces == true), then what is the number of spaces that make an indent?
	InsertSpaces bool   // Is indentation based on spaces?
	EOL          string // The default end of line line character
}

FormatOptions specifies formatting options.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/jsonFormatter.ts#L9

type Node

type Node struct {
	Type         NodeType    // the node's type
	Value        interface{} // the node's value
	Offset       int         // character offset of the node's starting position in the document
	Length       int         // the length (in characters) of the node
	ColumnOffset int         // character offset of the property's separator
	Parent       *Node       // the node's parent or nil if this is the root node
	Children     []*Node     // the node's children
}

Node represents a node in a JSON document's parse tree.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L616

func FindNodeAtLocation

func FindNodeAtLocation(root *Node, path Path) *Node

FindNodeAtLocation returns the node with the given key path under the JSON document parse tree root. If no such node exists, it returns nil.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L750

type NodeType

type NodeType int

NodeType is the type of a JSON node.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L605

const (
	Object NodeType = iota
	Array
	Property
	String
	Number
	Boolean
	Null
)

JSON node types

func (NodeType) String

func (i NodeType) String() string

type ParseError

type ParseError struct {
	Code   ParseErrorCode
	Offset int
	Length int
}

func ParseWithDetailedErrors

func ParseWithDetailedErrors(text string, options ParseOptions) ([]byte, []ParseError)

func (*ParseError) Error

func (pe *ParseError) Error() string

type ParseErrorCode

type ParseErrorCode int

A ParseErrorCode is a category of error that can occur while parsing a JSON document.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L593

const (
	InvalidSymbol ParseErrorCode = iota
	InvalidNumberFormat
	PropertyNameExpected
	ValueExpected
	ColonExpected
	CommaExpected
	CloseBraceExpected
	CloseBracketExpected
	EndOfFileExpected
	InvalidCommentToken

	// These get the ugly ParseError prefix because they conflict with existing
	// ScanErrorCode constants, and the ScanErrorCode constants existed first,
	// so we can't change them for BC reasons.
	ParseErrorUnexpectedEndOfComment
	ParseErrorUnexpectedEndOfString
	ParseErrorUnexpectedEndOfNumber
	ParseErrorInvalidUnicode
	ParseErrorInvalidEscapeCharacter
	ParseErrorInvalidCharacter

	// A catch all for an unexpected ScanErrorCode.
	InvalidScanErrorCode
)

Parse error codes

func Parse

func Parse(text string, options ParseOptions) ([]byte, []ParseErrorCode)

Parse the given text and returns the standard JSON representation of it, excluding the extensions supported by this package (such as comments and trailing commas).

On invalid input, the parser tries to be as fault tolerant as possible, but still return a result. Callers should check the errors list to see if the input was valid.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L638

func (ParseErrorCode) String

func (i ParseErrorCode) String() string

type ParseOptions

type ParseOptions struct {
	Comments       bool // allow comments (`//` and `/* ... */`)
	TrailingCommas bool // allow trailing commas in objects and arrays
}

ParseOptions specifies options for JSON parsing.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L629

type Path

type Path []Segment

A Path is a JSON key path, which describes a path from an ancestor node in a JSON document's parse tree to one of its descendents.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L627

func MakePath

func MakePath(components ...interface{}) Path

MakePath returns a Path consisting of the specified components, each of which may be either a string (which is treated as a property segment) or an int (which is treated as an array index). Any other type causes it to panic.

func PropertyPath

func PropertyPath(properties ...string) Path

PropertyPath returns a Path consisting of the specified property names.

type ScanErrorCode

type ScanErrorCode int

A ScanErrorCode is a category of error that can occur while scanning a JSON document.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L7

const (
	None ScanErrorCode = iota
	UnexpectedEndOfComment
	UnexpectedEndOfString
	UnexpectedEndOfNumber
	InvalidUnicode
	InvalidEscapeCharacter
	InvalidCharacter
)

Scan error codes

func (ScanErrorCode) String

func (i ScanErrorCode) String() string

type ScanOptions

type ScanOptions struct {
	Trivia bool // scan and emit whitespace and comment elements (false to ignore)
}

ScanOptions specifies options for NewScanner.

type Scanner

type Scanner struct {
	// contains filtered or unexported fields
}

A Scanner scans a JSON document.

func NewScanner

func NewScanner(text string, options ScanOptions) *Scanner

NewScanner creates a new scanner for the JSON document.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L78

func (*Scanner) Err

func (s *Scanner) Err() ScanErrorCode

Err returns the error code describing the error (if any) encountered while scanning the last-scanned token.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L72

func (*Scanner) Pos

func (s *Scanner) Pos() int

Pos returns the current character position within the JSON input.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L52

func (*Scanner) Scan

func (s *Scanner) Scan() SyntaxKind

Scan scans and returns the next token from the input.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L48

func (*Scanner) SetPosition

func (s *Scanner) SetPosition(newPosition int)

SetPosition sets the scanner's position and resets its other internal state. Subsequent calls to Scan will start from the new position.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L44

func (*Scanner) Token

func (s *Scanner) Token() SyntaxKind

Token returns the kind of the last-scanned token.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L56

func (*Scanner) TokenLength

func (s *Scanner) TokenLength() int

TokenLength returns the length of the last-scanned token.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L68

func (*Scanner) TokenOffset

func (s *Scanner) TokenOffset() int

TokenOffset returns the character offset of the last-scanned token.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L64

func (*Scanner) Value

func (s *Scanner) Value() string

Value returns the raw JSON-encoded value of the last-scanned token.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L60

type Segment

type Segment struct {
	// IsProperty indicates the type of segment (true for property, false
	// for index). Because the zero values "" and 0 are valid values for the
	// Property and Index fields, this field is necessary to distinguish.
	IsProperty bool

	Property string // an object property name
	Index    int    // an array index
}

A Segment is a component of a JSON key path. It is either an object property name or an array index.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L626

func (Segment) MarshalJSON

func (s Segment) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Segment) UnmarshalJSON

func (s *Segment) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type SyntaxKind

type SyntaxKind int

A SyntaxKind is a kind of syntax element in a JSON document.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L17

const (
	Unknown SyntaxKind = iota
	OpenBraceToken
	CloseBraceToken
	OpenBracketToken
	CloseBracketToken
	CommaToken
	ColonToken
	NullKeyword
	TrueKeyword
	FalseKeyword
	StringLiteral
	NumericLiteral
	LineCommentTrivia
	BlockCommentTrivia
	LineBreakTrivia
	Trivia
	EOF
)

Syntax kinds

func (SyntaxKind) String

func (i SyntaxKind) String() string

type Visitor

type Visitor struct {
	// Invoked when an open brace is encountered and an object is started. The
	// offset and length represent the location of the open brace.
	OnObjectBegin func(offset, length int)

	// Invoked when a property is encountered. The offset and length represent
	// the location of the property name.
	OnObjectProperty func(property string, offset, length int)

	// Invoked when a closing brace is encountered and an object is completed.
	// The offset and length represent the location of the closing brace.
	OnObjectEnd func(offset, length int)

	// Invoked when an open bracket is encountered. The offset and length represent
	// the location of the open bracket.
	OnArrayBegin func(offset, length int)

	// Invoked when a closing bracket is encountered. The offset and length represent
	// the location of the closing bracket.
	OnArrayEnd func(offset, length int)

	// Invoked when a literal value is encountered. The offset and length represent
	// the location of the literal value.
	OnLiteralValue func(value interface{}, offset, length int)

	// Invoked when a comma or colon separator is encountered. The offset and length
	// represent the location of the separator.
	OnSeparator func(character rune, offset, length int)

	// Invoked on an error.
	OnError func(errorCode ParseErrorCode, offset, length int)
}

A Visitor has its funcs invoked by Walk as it traverses the parse tree of a JSON document.

Source: https://github.com/Microsoft/vscode/blob/c0bc1ace7ca3ce2d6b1aeb2bde9d1bb0f4b4bae6/src/vs/base/common/json.ts#L1008

Jump to

Keyboard shortcuts

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