tango.text.json.Json

License:
BSD style:

Version:
July 2008: Initial release

Authors:
Aaron, Kris

class Json(T): JsonParser!T;
Parse json text into a set of inter-related structures. Typical usage is as follows:
auto json = new Json!(char);
json.parse (`{"t": true, "n":null, "array":["world", [4, 5]]}`);


Converting back to text format employs a delegate. This one emits document content to the console:
json.print ((char[] s) {Stdout(s);});


Constructing json within your code leverages a handful of factories within a document instance. This example creates a document from an array of values:
auto json = new Json!(char);

// [true, false, null, "text"]
with (json)
      value = array (true, false, null, "text");


Setting the document to contain a simple object instead:
// {"a" : 10}
with (json)
      value = object (pair("a", value(10)));


Objects may be constructed with multiple attribute pairs like so:
// {"a" : 10, "b" : true}
with (json)
      value = object (pair("a", value(10)), pair("b", value(true)));


Substitute arrays, or other objects as values where appropriate:
// {"a" : [10, true, {"b" : null}]}
with (json)
      value = object (pair("a", array(10, true, object(pair("b")))));


TODO:
document how to extract content

Big thanks to dhasenan for suggesting the construction notation. We can't make effective use of operator-overloading, due to the use of struct pointers, so this syntax turned out to be the next best thing.

Examples:
with (new Json!(char))
     {
     root = object
          (
          pair ("edgar", value("friendly")),
          pair ("count", value(11.5)),
          pair ("array", value(array(1, 2)))
          );

     auto value = toString();
     assert (value == `{"edgar":"friendly","count":11.5,"array":[1, 2]}`, value);
     }


Examples:
// check with a separator of the tab character
with (new Json!(char))
     {
     root = object
          (
          pair ("edgar", value("friendly")),
          pair ("count", value(11.5)),
          pair ("array", value(array(1, 2)))
          );

     auto value = toString ("\t");
     assert (value == "{\n\t\"edgar\":\"friendly\",\n\t\"count\":11.5,\n\t\"array\":[\n\t\t1, \n\t\t2\n\t]\n}", value);
     }


Examples:
// check with a separator of five spaces
with (new Json!(dchar))
     {
     root = object
          ( 
          pair ("edgar", value("friendly")),
          pair ("count", value(11.5)),
          pair ("array", value(array(1, 2)))
          );

     auto value = toString ("     ");
     assert (value == "{\n     \"edgar\":\"friendly\",\n     \"count\":11.5,\n     \"array\":[\n          1, \n          2\n     ]\n}");
     }


alias Value = JsonValue*;
use these types for external references

enum Type;
enumerates the seven acceptable JSON value types

this();
Construct a json instance, with a default value of null

Value parse(const(T)[] json);
Parse the given text and return a resultant Value type. Also sets the document value.

T[] toString(const(T)[] space, int decimals = 2);
Return a text representation of this document

Value value();
Returns the root value of this document

Value value(Value v);
Set the root value of this document

Value value(const(T)[] v);
Create a text value

Value value(bool v);
Create a boolean value

Value value(double v);
Create a numeric value

Value value(Value[] vals);
Create a single Value from an array of Values

Value array(...);
Create an array of values

Attribute pair(const(T)[] name, Value value = null);
Create an attribute/value pair, where value defaults to null

Value object(Attribute[] set...);
Create a composite from zero or more pairs, and return as a value

Value createValue();
Internal factory to create values

Composite createObject();
Internal factory to create composites

Attribute createAttribute();
Internal factory to create attributes

void exception(immutable(char)[] msg);
Throw a generic exception

Value parseValue();
Parse an instance of a value

Composite parseObject();
Parse an object declaration

Value[] parseArray();
Parse an array declaration

struct NameValue;
Represents an attribute/value pair. Aliased as Attribute

Attribute set(const(T)[] key, Value val);
Set a name and a value for this attribute

Returns itself, for use with Composite.add()

struct JsonObject;
Represents a single json Object (a composite of named attribute/value pairs).

This is aliased as Composite

Composite reset();


Composite append(Attribute a);
Append an attribute/value pair

Composite add(Attribute[] set...);
Add a set of attribute/value pairs

Value[T[]] hashmap();
Construct and return a hashmap of Object attributes. This will be a fairly costly operation, so consider alternatives where appropriate

Value value(const(T)[] name);
Return a corresponding value for the given attribute name. Does a linear lookup across the attribute set

Iterator attributes();
Iterate over our attribute names and values

struct Iterator;
Iterate over our attribute names. Note that we use a Fruct to handle this, since foreach does not operate cleanly with pointers (it doesn't automatically dereference them), whereas using x.attributes() does.

We may also use this to do some name filtering

struct JsonValue;
Represents a json value that is one of the seven types specified via the Json.Type enum

Type type;
the type of this node

alias set = reset;
alternate name for reset

bool equals(Type t);
return true if this node is of the given type

bool toBool();
Return true if this value represent True

const(T)[] toString(T[] dst);
Return the string content. Returns null if this value is not a string.

Uses dst for escape conversion where possible.

bool toString(scope void delegate(const(T)[]) dg);
Emit the string content to the given delegate, with escape conversion as required.

Returns false if this is not a String value

Composite toObject();
Return the content as a Composite/Object. Returns null if this value is not a Composite.

real toNumber();
Return the content as a double. Returns nan where the value is not numeric.

Value[] toArray();
Return the content as an array. Returns null where the value is not an array.

Value set(const(T)[] str, bool escaped = false);
Set this value to represent a string. If 'escaped' is set, the string is assumed to have pre-converted escaping of reserved characters (such as \t).

Value set(Composite obj);
Set this value to represent an object.

Value set(real num);
Set this value to represent a number.

Value set(bool b);
Set this value to represent a boolean.

Value set(Value[] a);
Set this value to represent an array of values.

Value reset();
Set this value to represent null

T[] print(const(T)[] space = null, int decimals = 2);
Return a text representation of this value

Value print(OutputStream s, const(T)[] space = null, int decimals = 2);
Emit a text representation of this value to the given OutputStream

Value print(void delegate(const(T)[]) append, const(T)[] space = null, int decimals = 2);
Emit a text representation of this value to the provided delegate

Value set(Type type);
Set to a specified type

Value set(Json host, TypeInfo[] info, va_list args);
Set a variety of values into an array type

struct Allocator(T);
Internal allocation mechanism

struct Array;
Internal use for parsing array values

alias Attrib = Allocator!NameValue;
Internal document representation


Page generated by Ddoc. Copyright (C) 2008 Aaron Craelius & Kris Bell All rights reserved