json

Documentation

Overview

The json package implements a simple parser and representation for JSON (JavaScript Object Notation), as defined at http://www.json.org/.

Index

• func Decode(s string) (data interface{}, err os.Error)
• func Marshal(w io.Writer, val interface{}) os.Error
• func Parse(s string, builder Builder) (ok bool, errindx int, errtok string)
• func Quote(s string) string
• func Unmarshal(s string, val interface{}) (ok bool, errtok string)
• func Unquote(s string) (t string, ok bool)
• type Builder
• type MarshalError
  • func (e *MarshalError) String() string
• type ParseError
  • func (pe *ParseError) String() string
• Bugs

Functions

func Decode

func Decode(s string) (data interface{}, err os.Error)

Decode parses the string s as a JSON-syntax string and returns the generic JSON object representation. The object representation is a tree of Go data types. The data return value may be one of float64, string, bool, nil, []interface{} or map[string]interface{}. The array and map elements may in turn contain any of the types listed above and so on.

If Decode encounters a syntax error, it returns with err set to an instance of ParseError. See ParseError documentation for details.

func Marshal

func Marshal(w io.Writer, val interface{}) os.Error

Marshal writes the JSON encoding of val to w.

Due to limitations in JSON, val cannot include cyclic data structures, channels, functions, or maps.

func Parse

func Parse(s string, builder Builder) (ok bool, errindx int, errtok string)

Parse parses the JSON syntax string s and makes calls to the builder to construct a parsed representation. On success, it returns with ok set to true. On error, it returns with ok set to false, errindx set to the byte index in s where a syntax error occurred, and errtok set to the offending token.

func Quote

func Quote(s string) string

Quote quotes the raw string s using JSON syntax, so that Unquote(Quote(s)) = s, true.

func Unmarshal

func Unmarshal(s string, val interface{}) (ok bool, errtok string)

Unmarshal parses the JSON syntax string s and fills in an arbitrary struct or slice pointed at by val. It uses the reflect package to assign to fields and arrays embedded in val. Well-formed data that does not fit into the struct is discarded.

For example, given these definitions:

type Email struct {
	Where string;
	Addr string;
}

type Result struct {
	Name string;
	Phone string;
	Email []Email
}

var r = Result{ "name", "phone", nil }

unmarshalling the JSON syntax string

{
  "email": [
    {
      "where": "home",
      "addr": "gre@example.com"
    },
    {
      "where": "work",
      "addr": "gre@work.com"
    }
  ],
  "name": "Grace R. Emlin",
  "address": "123 Main Street"
}

via Unmarshal(s, &r) is equivalent to assigning

r = Result{
	"Grace R. Emlin",	// name
	"phone",		// no phone given
	[]Email{
		Email{ "home", "gre@example.com" },
		Email{ "work", "gre@work.com" }
	}
}

Note that the field r.Phone has not been modified and that the JSON field "address" was discarded.

Because Unmarshal uses the reflect package, it can only assign to upper case fields. Unmarshal uses a case-insensitive comparison to match JSON field names to struct field names.

To unmarshal a top-level JSON array, pass in a pointer to an empty slice of the correct type.

On success, Unmarshal returns with ok set to true. On a syntax error, it returns with ok set to false and errtok set to the offending token.

func Unquote

func Unquote(s string) (t string, ok bool)

Unquote unquotes the JSON-quoted string s, returning a raw string t. If s is not a valid JSON-quoted string, Unquote returns with ok set to false.

Types

type Builder

type Builder interface {
	// Set value
	Int64(i int64)
	Uint64(i uint64)
	Float64(f float64)
	String(s string)
	Bool(b bool)
	Null()
	Array()
	Map()

	// Create sub-Builders
	Elem(i int) Builder
	Key(s string) Builder

	// Flush changes to parent Builder if necessary.
	Flush()
}

A Builder is an interface implemented by clients and passed to the JSON parser. It gives clients full control over the eventual representation returned by the parser.

type MarshalError

type MarshalError struct {
	T reflect.Type
}

func (*MarshalError) String

func (e *MarshalError) String() string

type ParseError

type ParseError struct {
	Index int    // A byte index in JSON string where the error occurred
	Token string // An offending token
}

ParseError aggregates information about a JSON parse error. It is compatible with the os.Error interface.

func (*ParseError) String

func (pe *ParseError) String() string

Produce a string representation of this ParseError.

Notes

Bugs

• The json Builder interface needs to be reconciled with the xml Builder interface.