jwcc

Documentation

Overview

Package jwcc implements a parser for JSON With Commas and Comments (JWCC) as defined by https://nigeltao.github.io/blog/2021/json-with-commas-comments.html

Index

• func CleanComments(coms ...string) []string
• func Format(w io.Writer, v Value) error
• func FormatToString(v Value) string
• func ValueLocation(v Value) jtree.Location
• type Array
  • func (a *Array) Comments() *Comments
  • func (a Array) JSON() string
  • func (a Array) Len() int
  • func (a Array) String() string
  • func (a *Array) Undecorate() ast.Value
• type Comments
  • func (c *Comments) Clear()
  • func (c Comments) IsEmpty() bool
• type Datum
  • func (d *Datum) Comments() *Comments
  • func (d *Datum) Undecorate() ast.Value
• type Document
  • func Parse(r io.Reader) (*Document, error)
  • func (d *Document) Comments() *Comments
  • func (d *Document) Undecorate() ast.Value
• type Formatter
  • func (f Formatter) Format(w io.Writer, v Value) error
• type Member
  • func Field(key string, value any) *Member
  • func (m *Member) Comments() *Comments
  • func (m Member) JSON() string
  • func (m Member) String() string
  • func (m *Member) Undecorate() ast.Value
• type Object
  • func (o *Object) Comments() *Comments
  • func (o *Object) Find(key string) *Member
  • func (o *Object) FindKey(f func(ast.Text) bool) *Member
  • func (o *Object) IndexKey(f func(ast.Text) bool) int
  • func (o Object) JSON() string
  • func (o Object) Len() int
  • func (o Object) Sort()
  • func (o Object) String() string
  • func (o *Object) Undecorate() ast.Value
• type Value
  • func Decorate(v ast.Value) Value
  • func ToValue(v any) Value

Functions

func CleanComments

func CleanComments(coms ...string) []string

CleanComments combines and removes comment markers from the given comments, returning a slice of plain lines of text. Leading and trailing spaces are removed from the lines.

func Format

func Format(w io.Writer, v Value) error

Format renders a pretty-printed representation of v to w with default settings.

func FormatToString

func FormatToString(v Value) string

FormatToString formats v to a string with default settings. In case of error in formatting, it returns an empty string.

func ValueLocation

func ValueLocation(v Value) jtree.Location

ValueLocation reports the location of the specified value.

Types

type Array

type Array struct {
	Values []Value
	// contains filtered or unexported fields
}

An Array is a commented array of values.

func (*Array) Comments

func (a *Array) Comments() *Comments

func (Array) JSON

func (a Array) JSON() string

func (Array) Len

func (a Array) Len() int

func (Array) String

func (a Array) String() string

func (*Array) Undecorate

func (a *Array) Undecorate() ast.Value

type Comments

type Comments struct {
	Before []string
	Line   string
	End    []string
	// contains filtered or unexported fields
}

Comments records the comments associated with a value. All values have a comment record; use IsEmpty to test whether the value has any actual comment text.

Comments read during parsing are stored as-seen in the input, including comment markers. When adding or editing a comment programmatically, comment markers are optional; the text will be decorated when formatting the output. To include blank space separating multiple chunks of comment text, include an empty string. To include a blank line in the middle of a chunk, include a comment marker.

For example:

c := jtree.Comments{Before: []string{"a", "", "b"}}

renders as:

// a

// b

By contrast:

c := jtree.Comments{Before: []string{"a", "//", "c"}}

renders as:

// a
//
// b

If a comment begins with "//", it will be processed as line comments. If a comment begins with "/*" it will be processed as a block comment. Multiple lines are OK; they will be reformatted as necessary.

func (*Comments) Clear

func (c *Comments) Clear()

Clear discards the contents of c, leaving it empty.

func (Comments) IsEmpty

func (c Comments) IsEmpty() bool

IsEmpty reports whether c is "empty", meaning it has no non-empty comment text for its associated value.

type Datum

type Datum struct {
	ast.Value
	// contains filtered or unexported fields
}

A Datum is a commented base value; a string, number, Boolean, or null.

func (*Datum) Comments

func (d *Datum) Comments() *Comments

func (*Datum) Undecorate

func (d *Datum) Undecorate() ast.Value

type Document

type Document struct {
	Value
	// contains filtered or unexported fields
}

A Document is a single value with optional trailing comments.

func Parse

func Parse(r io.Reader) (*Document, error)

Parse parses and returns a single JWCC value from r. If r contains data after the first value, apart from comments and whitespace, Parse returns the first value along with an ast.ErrExtraInput error.

func (*Document) Comments

func (d *Document) Comments() *Comments

func (*Document) Undecorate

func (d *Document) Undecorate() ast.Value

type Formatter

type Formatter struct{}

A Formatter carries the settings for pretty-printing JWCC values. A zero value is ready for use with default settings.

func (Formatter) Format

func (f Formatter) Format(w io.Writer, v Value) error

Format renders a pretty-printed representation of v to w using the settings from f.

type Member

type Member struct {
	Key   ast.Text
	Value Value
	// contains filtered or unexported fields
}

A Member is a key-value pair in an object.

func Field

func Field(key string, value any) *Member

Field constructs an object member with the given key and value. The value must be a string, int, float, bool, nil, or jwcc.Value.

func (*Member) Comments

func (m *Member) Comments() *Comments

func (Member) JSON

func (m Member) JSON() string

func (Member) String

func (m Member) String() string

func (*Member) Undecorate

func (m *Member) Undecorate() ast.Value

type Object

type Object struct {
	Members []*Member
	// contains filtered or unexported fields
}

An Object is a collection of key-value members.

func (*Object) Comments

func (o *Object) Comments() *Comments

func (*Object) Find

func (o *Object) Find(key string) *Member

Find is shorthand for FindKey with a case-insensitive name match on key.

func (*Object) FindKey

func (o *Object) FindKey(f func(ast.Text) bool) *Member

FindKey returns the first member of o for whose key f reports true, or nil.

func (*Object) IndexKey

func (o *Object) IndexKey(f func(ast.Text) bool) int

IndexKey returns the index of the first member of o for whose key f reports true, or -1.

func (Object) JSON

func (o Object) JSON() string

func (Object) Len

func (o Object) Len() int

func (Object) Sort

func (o Object) Sort()

Sort sorts the object in ascending order by key.

func (Object) String

func (o Object) String() string

func (*Object) Undecorate

func (o *Object) Undecorate() ast.Value

type Value

type Value interface {
	ast.Value

	// Comments returns the comments annotating this value.
	Comments() *Comments

	// Convert this value to an undecorated ast.Value.
	Undecorate() ast.Value
}

A Value is a JSON value optionally decorated with comments. The concrete type is one *Array, *Datum, *Document, or *Object.

func Decorate

func Decorate(v ast.Value) Value

Decorate converts an ast.Value into an equivalent jwcc.Value.

func ToValue

func ToValue(v any) Value

ToValue converts a string, int, float, bool, nil, or ast.Value into a jwcc.Value. It panics if v does not have one of those types.