G3D::Any Class Reference

Easy loading and saving of human-readable configuration files. More...

#include <Any.h>

Classes
class	Data
class	IndexOutOfBounds
class	KeyNotFound
union	SimpleValue
class	Source

Public Types
enum	Type {   NIL, BOOLEAN, NUMBER, STRING,   ARRAY, TABLE, EMPTY_CONTAINER }
typedef Array< Any >	AnyArray
typedef Table< std::string, Any >	AnyTable

Public Member Functions
	Any ()
	Any (TextInput &t)
	Any (const Any &x)
	Any (double x)
	Any (float x)
	Any (long x)
	Any (int x)
	Any (char x)
	Any (short x)
	Any (bool x)
	Any (const std::string &x)
	Any (const char *x)
	Any (Type t, const std::string &name="", const std::string &brackets="", const char separator= '\0')
template<class T >
	Any (const T &v)
	~Any ()
Any &	operator= (const Any &x)
Any &	operator= (Type t)
template<class T >
Any &	operator= (const Array< T > &array)
template<class T >
Any &	operator= (const T &v)
Type	type () const
std::string	unparse (const TextOutput::Settings &s=TextOutput::Settings()) const
std::string	unparseJSON (const TextOutput::Settings &s=TextOutput::Settings(), bool allowCoercion=true) const
const std::string &	comment () const
void	setComment (const std::string &c)
bool	isNil () const
double	number () const
float	floatValue () const
const std::string &	string () const
bool	boolean () const
std::string	resolveStringAsFilename (bool errorIfNotFound=true) const
const std::string &	name () const
bool	nameBeginsWith (const std::string &s) const
bool	nameBeginsWith (const char *s) const
bool	nameEquals (const std::string &s) const
bool	nameEquals (const char *s) const
void	setName (const std::string &name)
	Set the name used when serializing an ARRAY or TABLE. More...
int	size () const
int	length () const
const Any &	operator[] (int i) const
Any &	operator[] (int i)
const Any &	last () const
Any &	last ()
const Array< Any > &	array () const
template<class T0 >
void	append (const T0 &v0)
template<class T0 , class T1 >
void	append (const T0 &v0, const T1 &v1)
template<class T0 , class T1 , class T2 >
void	append (const T0 &v0, const T1 &v1, const T2 &v2)
template<class T0 , class T1 , class T2 , class T3 >
void	append (const T0 &v0, const T1 &v1, const T2 &v2, const T3 &v3)
const Table< std::string, Any > &	table () const
const Any &	operator[] (const std::string &key) const
const Any &	operator[] (const char *key) const
Any &	operator[] (const std::string &key)
Any &	operator[] (const char *key)
template<class T >
Any	get (const std::string &key, const T &defaultVal) const
bool	containsKey (const std::string &key) const
template<class T >
void	set (const std::string &key, const T &val)
Any &	next ()
std::string	sourceDirectory () const
bool	operator== (const Any &x) const
bool	operator== (const std::string &s) const
bool	operator== (const double &v) const
bool	operator== (int v) const
bool	operator== (bool v) const
bool	operator!= (const Any &x) const
bool	operator!= (const std::string &s) const
bool	operator!= (const double &v) const
bool	operator!= (int v) const
bool	operator!= (bool v) const
	operator int () const
	operator uint32 () const
	operator float () const
	operator double () const
	operator bool () const
	operator std::string () const
	operator char () const
	operator uint8 () const
	operator int16 () const
	operator uint16 () const
void	resize (int n)
void	clear ()
void	load (const std::string &filename)
void	loadIfExists (const std::string &filename)
void	save (const std::string &filename) const
void	serialize (TextOutput &to, bool json=false, bool coerce=false) const
void	serialize (class BinaryOutput &b) const
void	deserialize (TextInput &ti)
void	deserialize (class BinaryInput &b)
const Source &	source () const
void	remove (const std::string &key)
void	remove (int index)
void	verify (bool value, const std::string &message="") const
void	verifyName (const std::string &n) const
void	verifyName (const std::string &n, const std::string &m) const
void	verifyName (const std::string &n, const std::string &m, const std::string &p) const
void	verifyName (const std::string &n, const std::string &m, const std::string &p, const std::string &q) const
void	verifyNameBeginsWith (const std::string &n) const
void	verifyNameBeginsWith (const std::string &n, const std::string &m) const
void	verifyNameBeginsWith (const std::string &n, const std::string &m, const std::string &p) const
void	verifyNameBeginsWith (const std::string &n, const std::string &m, const std::string &p, const std::string &q) const
void	verifyNameBeginsWith (const std::string &n, const std::string &m, const std::string &p, const std::string &q, const std::string &r) const
void	verifyNameBeginsWith (const std::string &n, const std::string &m, const std::string &p, const std::string &q, const std::string &r, const std::string &s) const
void	verifyNameBeginsWith (const std::string &n, const std::string &m, const std::string &p, const std::string &q, const std::string &r, const std::string &s, const std::string &t) const
void	verifyType (Type t) const
void	verifyType (Type t0, Type t1) const
void	verifySize (int low, int high) const
void	verifySize (int s) const
template<class T >
	Any (const Array< T > &array, const std::string &name="")
template<class T >
void	getArray (Array< T > &array) const
template<class T >
void	getTable (Table< std::string, T > &table) const

Static Public Member Functions
static std::string	toString (Type t)
static Any	parse (const std::string &src)
static Any	fromFile (const std::string &filename)

Private Member Functions
void	beforeRead () const
void	beforeWrite ()
void	dropReference ()
void	ensureData ()
void	ensureMutable ()
void	deserializeBody (TextInput &ti, Token &token)
void	deserialize (TextInput &ti, Token &token)
	Any (const std::string &key, Data *data)
bool	isPlaceholder () const
void	_append (const Any &v0)
void	_append (const Any &v0, const Any &v1)
void	_append (const Any &v0, const Any &v1, const Any &v2)
void	_append (const Any &v0, const Any &v1, const Any &v2, const Any &v3)
Any	_get (const std::string &key, const Any &defaultVal) const
void	_set (const std::string &key, const Any &val)
void	_parse (const std::string &src)
void	deserializeTable (TextInput &ti)
void	deserializeArray (TextInput &ti, const std::string &term)
void	become (const Type &t)

Static Private Member Functions
static void	deserializeComment (TextInput &ti, Token &token, std::string &comment)
static void	deserializeName (TextInput &ti, Token &token, std::string &name)
static void	readUntilSeparatorOrClose (TextInput &ti, Token &token)

Private Attributes
std::string	m_placeholderName
Type	m_type
SimpleValue	m_simpleValue
Data *	m_data

Static Private Attributes
static const char *	PAREN = "()"
static const char *	BRACKET = "[]"
static const char *	BRACE = "{}"

Detailed Description

Easy loading and saving of human-readable configuration files.

Any encodes typed, structured data and can serialize it to a human readable format that is very similar to the Python language's data syntax, and fully supports Python's data syntax as well. It is well-suited for quickly creating human-readable file formats, especially since deserialization and serialization preserve comments and an Any can tell you what file and line it came from. The syntax allows most C++ editors to properly highlight Any files, and makes it easy to design little ad-hoc C-like languages in configuration files.

The class is designed so that copying Anys generally is fast, even if it is a large array or table. This is because data is shared between copies until it is mutated, at which point an actual copy occurs.

Example

Sample File:

{
   shape = "round",

   // in meters
   radius = 3.7,

   position = Vector3(1.0, -1.0, 0.0),
   video = { format = "RGB8", size = (320, 200)},

   material = #include("rocks.mat")
}

Sample code using Any:

Any x;
x.load("ball.txt");
if (x["shape"].string() == "round") {
    x["density"] = 3;
}
x.save("ball.txt");

The custom serialization format was chosen to be terse, easy for humans to read, and easy for machines to parse. It was specifically chosen over formats like XML, YAML, JSON, S-expressions, and Protocol Buffers, although there is no reason you could not write readers and writers for G3D::Any that support those. Any also currently supports the JSON format.

G3D::Any assumes that structures do not contain cycles; it is an error to create a structure like:

Any x(Any::ARRAY);
x.array().append(x);    // don't do this!

although no exception will be thrown at runtime during that append.

includes

When parsing an Any from a file, the syntax #include(filename) allows subsitution of the contents of filename for any single expression in an Any. The filename is interpreted relative to the file being parsed, and inside of the included file, relative filenames are interpreted with respect to the included file (and so on, recursively for nested inclusion).

Filenames are resolved with System::resolve and then System::findDataFile if not found, so they may contain environment variables.

Parsing

The primary use of Any is to create your own text file formats. The Vector3 constructor is a good example of how to use the Any::verify methods to provide good error checking while parsing such formats:

Vector3::Vector3(const Any& any) {
    any.verifyName("Vector3");
    any.verifyType(Any::TABLE, Any::ARRAY);
    any.verifySize(3);

    if (any.type() == Any::ARRAY) {
        x = any[0];
        y = any[1];
        z = any[2];
    } else {
        // Table
        x = any["x"];
        y = any["y"];
        z = any["z"];
    }
}

It is often convenient to iterate through the table portion using G3D::AnyTableReader.

BNF

Serialized format BNF:

identifier  ::= (letter | "_") (letter | digit | "_")*
identifier-op ::= "::" | "->" | "."

identifier-exp ::= [identifier-op] identifier (identifier-op identifier)*

comment     ::= C++ single or multi-line comments
separator   ::= "," | ";"

number      ::= 
string      ::= 
boolean     ::= "True" | "False"
nil         ::= "Nil"  | "None" 
array       ::= ("(" | "[" | "{") [value (separator value)* [separator] ] (")" | "]" | "}")
pair        ::= (identifier | string) ("=" | ":") value
table       ::= ("(" | "[" | "{") [ pair (separator pair)* [separator] ] (")" | "]" | "}")
named-array ::= identifier-exp array
named-table ::= identifier-exp table
include     ::= "#" "include" "(" string ")"

value       ::= [comment] (nil | number | boolean | string | array | table | named-array | named-table | include)

Except for single-line comments, whitespace is not significant. All parsing is case-insensitive.

The include expression pastes the contents of the named file in as if they appeared in the original source. Note that an include expression can only appear in the locations where a value is expected. This means that it cannot yield more than one element of an array and cannot serve as the pair in a table.

The deserializer allows the substitution of [] or {} for () when writing tuples and ";" for ",". These are convenient when mimicing a programming language, e.g., "[ printf("hello world."); clearScreen();]" parses as an array containing two named arrays within it. The deserializer also allows a trailing comma inside any array or table, which also convenient when commenting out the last element.

The serializer indents four spaces for each level of nesting. Tables are written with the keys in alphabetic order.

See also

G3D::AnyTableReader

Member Typedef Documentation

typedef Array<Any> G3D::Any::AnyArray

typedef Table<std::string, Any> G3D::Any::AnyTable

Member Enumeration Documentation

enum G3D::Any::Type

Enumerator
NIL
BOOLEAN
NUMBER
STRING
ARRAY
TABLE
EMPTY_CONTAINER

{NIL, BOOLEAN, NUMBER, STRING, ARRAY, TABLE, EMPTY_CONTAINER};

Constructor & Destructor Documentation

G3D::Any::Any ( const std::string &  key, Data *  data  )

private

Construct an Any that is a proxy for a table fetch from data. This proxy can be copied exactly once on return from operator[].

G3D::Any::Any

(

)

NIL constructor

         : m_type(NIL), m_data(NULL) {
}

Here is the caller graph for this function:

G3D::Any::Any ( TextInput &  t )

explicit

Deserialize

                     : m_type(NIL), m_data(NULL) {
    deserialize(t);
}

Here is the call graph for this function:

G3D::Any::Any

(

const Any &

x

)

                     : m_type(NIL), m_data(NULL) {
    x.beforeRead();
    *this = x;
}

Here is the call graph for this function:

G3D::Any::Any ( double  x )

explicit

NUMBER constructor

                 : m_type(NUMBER), m_simpleValue(x), m_data(NULL) {
}

G3D::Any::Any ( float  x )

explicit

                : m_type(NUMBER), m_simpleValue(double(x)), m_data(NULL) {
}

G3D::Any::Any ( long  x )

explicit

NUMBER constructor

               : m_type(NUMBER), m_simpleValue((double)x), m_data(NULL) {
}

G3D::Any::Any ( int  x )

explicit

NUMBER constructor

              : m_type(NUMBER), m_simpleValue((double)x), m_data(NULL) {
}

G3D::Any::Any ( char  x )

explicit

NUMBER constructor

               : m_type(NUMBER), m_simpleValue(double(x)), m_data(NULL) {
}

G3D::Any::Any ( short  x )

explicit

NUMBER constructor

                : m_type(NUMBER), m_simpleValue((double)x), m_data(NULL) {
}

G3D::Any::Any ( bool  x )

explicit

BOOLEAN constructor

               : m_type(BOOLEAN), m_simpleValue(x), m_data(NULL) {
}

G3D::Any::Any ( const std::string &  x )

explicit

STRING constructor

                           : m_type(STRING), m_data(Data::create(STRING)) {
    *(m_data->value.s) = s;
}

G3D::Any::Any ( const char *  x )

explicit

STRING constructor

                      : m_type(STRING), m_data(NULL) {
    if (s == NULL) {
        m_type = NIL;
    } else {
        ensureData();
        *(m_data->value.s) = s;
    }
}

Here is the call graph for this function:

G3D::Any::Any ( Type  t, const std::string &  name = "", const std::string &  brackets = "", const char  separator = '\0'  )

explicit

t must be ARRAY or TABLE

Parameters

brackets	must be "" (defaults to {} for table, () for array), "[]", "()", or "{}"
separator	must be ';', ',', or '\0' (defaults to ',' for array and ';' for table)

                                                                                 : m_type(t), m_data(NULL) {
    alwaysAssertM(isContainerType(t), "Can only create ARRAY or TABLE from Type enum.");

    ensureData();
    if (name != "") {
        m_data->name = name;
    }

    if (brackets == "") {
        if (t == ARRAY) {
            m_data->bracket = PAREN;
        } else {
            m_data->bracket = BRACE;
        }
    } else if (brackets == PAREN) {
        m_data->bracket = PAREN;
    } else if (brackets == BRACE) {
        m_data->bracket = BRACE;
    } else if (brackets == BRACKET) {
        m_data->bracket = BRACKET;
    } else {
        alwaysAssertM(false, std::string("illegal brackets: ") + brackets);
    }

    if (separator == '\0') {
        if (t == ARRAY) {
            m_data->separator = ',';
        } else {
            m_data->separator = ';';
        }
    } else if (separator == ',' || separator == ';') {
        m_data->separator = separator;
    } else {
        alwaysAssertM(false, std::string("illegal separator: ") + separator);
    }
}

Here is the call graph for this function:

template<class T >

G3D::Any::Any ( const T &  v )

inlineexplicit

Extensible constructor: call the toAny() method of any class.

                             : m_type(NIL), m_data(NULL) {
        *this = v.toAny();
    }

G3D::Any::~Any

(

)

          {
    dropReference();
}

Here is the call graph for this function:

Here is the caller graph for this function:

template<class T >

G3D::Any::Any ( const Array< T > &  array, const std::string &  name = ""  )

inlineexplicit

Assumes that Any(T) is well-defined, e.g., by T defining a T::toAny() method.

                                                                    : m_type(ARRAY), m_data(NULL) {
        setName(name);
        resize(array.size());
        for (int i = 0; i < array.size(); ++i) {
            (*this)[i] = Any(array[i]);
        }
    }

Here is the call graph for this function:

Member Function Documentation

void G3D::Any::_append ( const Any &  v0 )

private

                               {
    beforeRead();
    verifyType(ARRAY);
    debugAssert(m_data != NULL);
    if (type() == EMPTY_CONTAINER) {
        become(ARRAY);
    }
    m_data->value.a->append(x0);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::_append ( const Any &  v0, const Any &  v1  )

private

                                              {
    beforeRead();
    append(x0);
    append(x1);
}

Here is the call graph for this function:

void G3D::Any::_append ( const Any &  v0, const Any &  v1, const Any &  v2  )

private

                                                             {
    beforeRead();
    append(x0);
    append(x1);
    append(x2);
}

Here is the call graph for this function:

void G3D::Any::_append ( const Any &  v0, const Any &  v1, const Any &  v2, const Any &  v3  )

private

                                                                            {
    beforeRead();
    append(x0);
    append(x1);
    append(x2);
    append(x3);
}

Here is the call graph for this function:

Any G3D::Any::_get ( const std::string &  key, const Any &  defaultVal  ) const

private

                                                             {
    beforeRead();
    defaultVal.beforeRead();
    try {
        return operator[](x);
    } catch(KeyNotFound) {
        return defaultVal;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::_parse ( const std::string &  src )

private

                                     {
    beforeRead();
    TextInput::Settings settings;
    getDeserializeSettings(settings);

    TextInput ti(TextInput::FROM_STRING, src, settings);
    deserialize(ti);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::_set ( const std::string &  key, const Any &  val  )

private

                                               {
    beforeRead();
    v.beforeRead();
    verifyType(TABLE);
    debugAssert(m_data != NULL);
    if ( type() == EMPTY_CONTAINER) {
        become(TABLE);
    }
    Table<std::string, Any>& table = *(m_data->value.t);
    table.set(k, v);
}

Here is the call graph for this function:

Here is the caller graph for this function:

template<class T0 >

void G3D::Any::append ( const T0 &  v0 )

inline

                              {
        _append(Any(v0));
    }

Here is the call graph for this function:

Here is the caller graph for this function:

template<class T0 , class T1 >

void G3D::Any::append ( const T0 &  v0, const T1 &  v1  )

inline

                                            {
        _append(Any(v0), Any(v1));
    }

Here is the call graph for this function:

template<class T0 , class T1 , class T2 >

void G3D::Any::append ( const T0 &  v0, const T1 &  v1, const T2 &  v2  )

inline

                                                          {
        _append(Any(v0), Any(v1), Any(v2));
    }

Here is the call graph for this function:

template<class T0 , class T1 , class T2 , class T3 >

void G3D::Any::append ( const T0 &  v0, const T1 &  v1, const T2 &  v2, const T3 &  v3  )

inline

                                                                        {
        _append(Any(v0), Any(v1), Any(v2), Any(v3));
    }

Here is the call graph for this function:

const Array< Any > & G3D::Any::array

(

)

const

Directly exposes the underlying data structure for an ARRAY.

                                   {
    beforeRead();
    verifyType(ARRAY);
    debugAssert(m_data != NULL);
    return *(m_data->value.a);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::become ( const Type &  t )

private

Turns an empty container into a table or an array

                              {
    if ((t == ARRAY) || (t == TABLE)) {
        debugAssert(m_type == EMPTY_CONTAINER);
        m_type = t;
        m_data->type = m_type;
        if(t == ARRAY) {
            m_data->value.a = new AnyArray();
        } else {
            m_data->value.t = new AnyTable();
        }
    }
}

Here is the caller graph for this function:

void G3D::Any::beforeRead ( ) const

private

Called before every read operation.

                           {
    if (isPlaceholder()) {
        // Tried to read from a placeholder--throw an exception as if
        // the original operator[] had failed.
        alwaysAssertM(m_data, "Corrupt placeholder");
        KeyNotFound e(m_data);

        e.key       = m_placeholderName;
        e.message   = "Key \"" + m_placeholderName + "\" not found in operator[] lookup.";

        throw e;
    } 
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::beforeWrite ( )

private

Called before every write operation to this Any. Wipes the placeholder status and includedFrom entry.

                      {
    if (isPlaceholder()) {
        // This is no longer a placeholder
        m_placeholderName.clear();
    }

    if (m_data && ! m_data->includeLine.empty()) {
        // Forget where this Any was included from...it no
        // longer matches the contents there.
        m_data->includeLine = "";
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool G3D::Any::boolean

(

)

const

                        {
    beforeRead();
    verifyType(BOOLEAN);
    return m_simpleValue.b;
}

Here is the call graph for this function:

void G3D::Any::clear

(

)

Clears all entries. This must be a TABLE or ARRAY

                {
    beforeRead();
    verifyType(ARRAY, TABLE);
    switch (m_type) {
    case ARRAY:
        m_data->value.a->clear();
        break;

    case TABLE:
        m_data->value.t->clear();
        break;
    default:;
    }
}

Here is the call graph for this function:

const std::string & G3D::Any::comment

(

)

const

Comments appear before values when they are in serialized form.

                                    {
    beforeRead();

    static const std::string blank;
    if (m_data != NULL) {
        return m_data->comment;
    } else {
        return blank;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool G3D::Any::containsKey

(

const std::string &

key

)

const

Returns true if this key is in the TABLE. Illegal to call on an object that is not a TABLE.

                                              {
    beforeRead();
    verifyType(TABLE);
    if (size() == 0) {
        //catches the case of an empty container, where value.t is null
        return false;
    }
    Any* a = m_data->value.t->getPointer(x);

    // Don't return true for placeholder objects
    return (a != NULL) && (! a->isPlaceholder());
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::deserialize ( TextInput &  ti, Token &  token  )

private

                                                 {
    // Deallocate old data
    dropReference();
    m_type = NIL;
    m_simpleValue.b = false;

    // Skip leading newlines
    while (token.type() == Token::NEWLINE) {
        token = ti.read();
    } 

    std::string comment;
    if (token.type() == Token::COMMENT) {
        deserializeComment(ti, token, comment);
    }

    if (token.type() == Token::END) {
        // There should never be a comment without an Any following it; even
        // if the file ends with some commented out stuff,
        // that should not happen after a comma, so we'd never read that 
        // far in a proper file.
        throw ParseError(ti.filename(), token.line(), token.character(), 
            "File ended without a properly formed Any");
    }

    // Do we need to read one more token after the end? 
    bool needRead = true;

    switch (token.type()) {
    case Token::STRING:
        m_type = STRING;
        ensureData();
        *(m_data->value.s) = token.string();
        m_data->source.set(ti, token);
        break;

    case Token::NUMBER:
        m_type = NUMBER;
        m_simpleValue.n = token.number();
        ensureData();
        m_data->source.set(ti, token);
        break;

    case Token::BOOLEAN:
        m_type = BOOLEAN;
        m_simpleValue.b = token.boolean();
        ensureData();
        m_data->source.set(ti, token);
        break;

    case Token::SYMBOL:
        // Pragma, Named Array, Named Table, Array, Table, or NIL
        if (token.string() == "#") {
            // Pragma
            
            // Currently, "include" is the only pragma allowed
            token = ti.read();
            if (! ((token.type() == Token::SYMBOL) &&
                   (token.string() == "include"))) {
                throw ParseError(ti.filename(), token.line(), token.character(),
                                 "Expected 'include' pragma after '#'");
            }
            
            ti.readSymbol("(");
            // The string typed into the file, which may be relative
            const std::string& includeName = ti.readString();

            // Find the include file
            const std::string& myPath = FilePath::parent(ti.filename());

            std::string t = FileSystem::resolve(includeName, myPath);

            if (! FileSystem::exists(t)) {
                // Try and find the path, starting with the cwd
                t = System::findDataFile(includeName);
            }

            // Read the included file
            load(t);

            // Update the source information
            ensureData();
            if (! comment.empty()) {
                m_data->includeLine = format("\n/* %s */\n", comment.c_str());
            }
            m_data->includeLine += format("#include(\"%s\")", includeName.c_str());
            m_data->source.filename +=
                format(" [included from %s:%d(%d)]", ti.filename().c_str(), token.line(), token.character());
            
            ti.readSymbol(")");

        } else if (toUpper(token.string()) == "NIL" || token.string() == "None") {
            // Nothing left to do; we initialized to NIL originally
            ensureData();
            m_data->source.set(ti, token);
        } else if (isValidIdentifier(token.string()) && !isOpen(ti.peek().string()[0]) && ti.peek().string() != "::") {
            // Valid unquoted string
            m_type = STRING;
            ensureData();
            *(m_data->value.s) = token.string();
            m_data->source.set(ti, token);
        } else {
            // Array or Table

            // Parse the name
            // s must have at least one element or this would not have
            // been parsed as a symbol
            std::string name;
            deserializeName(ti, token, name);
            if (token.type() != Token::SYMBOL) {
                throw ParseError(ti.filename(), token.line(), token.character(), 
                    "Malformed Any TABLE or ARRAY; must start with [, (, or {");
            }

            if (isOpen(token.string()[0])) {
                // Array or table
                deserializeBody(ti, token);
            } else {
                throw ParseError(ti.filename(), token.line(), token.character(), 
                    "Malformed Any TABLE or ARRAY; must start with [, (, or {");
            }

            if (! name.empty()) {
                ensureData();
                m_data->name = name;
            }
            needRead = false;
        } // if NIL
        break;

    default:
        throw ParseError(ti.filename(), token.line(), token.character(), 
            "Unexpected token");

    } // switch

    if (! comment.empty()) {
        ensureData();
        m_data->comment = comment;
    }

    if (needRead) {
        // Array and table already consumed their last token
        token = ti.read();
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::deserialize

(

TextInput &

ti

)

Parse from a stream.

See also

load, parse

                                   {
    beforeRead();
    Token token = ti.read();
    deserialize(ti, token);
    // Restore the last token
    ti.push(token);
}

Here is the call graph for this function:

void G3D::Any::deserialize

(

class BinaryInput &

b

)

                                    {
    const int version = b.readInt32();
    alwaysAssertM(version == 1, "Wrong Any serialization version");
    _parse(b.readString32());
}

Here is the call graph for this function:

void G3D::Any::deserializeArray ( TextInput &  ti, const std::string &  term  )

private

void G3D::Any::deserializeBody ( TextInput &  ti, Token &  token  )

private

Read an unnamed a TABLE or ARRAY. Token should be the open paren token; it is the next token after the close on return. Called from deserialize().

                                                     {
    char closeSymbol = '\0';
    m_type = TABLE;
    
    const char c = token.string()[0];

    // Chose the appropriate close symbol based on the open symbol
    const char* bracket;
    if (c == '(') {
        bracket = PAREN;
    } else if (c == '[') {
        bracket = BRACKET;
    } else if (c == '{') {
        bracket = BRACE;
    } else {
        debugAssertM(false, "Illegal bracket type");
    bracket = PAREN;
    }
    closeSymbol = bracket[1];

    // We must set the type before we allocate m_data in ensureData().
    m_type = findType(ti, closeSymbol);

    // Allocate the underlying data structure
    ensureData();
    m_data->source.set(ti, token);
    m_data->bracket = bracket;

    debugAssert(m_data->type == m_type);
    debugAssert(m_data->separator != '\0');

    // Consume the open token
    token = ti.read();

    while (! ((token.type() == Token::SYMBOL) && (token.string()[0] == closeSymbol))) {

        // Read any leading comment.  This must be done here (and not in the recursive deserialize
        // call) in case the body contains only a comment.
        std::string comment;
        deserializeComment(ti, token, comment);

        if ((token.type() == Token::SYMBOL) && (token.string()[0] == closeSymbol)) {
            // We're done; this catches the case where the container is empty
            break;
        }

        // Pointer the value being read
        Any a;
        std::string key;
        
        if (m_type == TABLE) {
            // Read the key
            if (token.type() != Token::SYMBOL && token.type() != Token::STRING) {
                throw ParseError(ti.filename(), token.line(), token.character(), "Expected a name");
            } 
            
            key = token.string();
            // Consume everything up to the = sign, returning the "=" sign.
            token = ti.readSignificant();

            if ((token.type() != Token::SYMBOL) || ((token.string() != "=") && token.string() != ":")) {
                throw ParseError(ti.filename(), token.line(), token.character(), "Expected = or :");
            } else {
                // Read the next token, which is the value (don't consume comments--we want the value pointed to by a to get those).
                token = ti.read();
            }
        }
        a.deserialize(ti, token);

        if (! comment.empty()) {
            // Prepend the comment we read earlier
            a.ensureData();
            a.m_data->comment = trimWhitespace(comment + "\n" + a.m_data->comment);
        }
        
        if (m_type == TABLE) {
            set(key, a);
        } else {
            append(a);
        }

        // Read until the separator or close paren, discarding trailing comments and newlines
        readUntilSeparatorOrClose(ti, token);

        char s = token.string()[0];

        // Consume the separator
        if (isSeparator(s)) {
            token = ti.read();
            m_data->separator = s;
            debugAssert(m_data->separator != '\0');
        }
    }

    // Consume the close paren (to match other deserialize methods)
    token = ti.read();
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::deserializeComment ( TextInput &  ti, Token &  token, std::string &  comment  )

staticprivate

Called from deserialize()

                                                                            {
    // Parse comments
    while (token.type() == Token::COMMENT) {
        comment += trimWhitespace(token.string());

        // Allow comments to contain newlines.
        do {
            token = ti.read();
            comment += "\n";
        } while (token.type() == Token::NEWLINE);
    }

    comment = trimWhitespace(comment);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::deserializeName ( TextInput &  ti, Token &  token, std::string &  name  )

staticprivate

Read the name of a named Array or Table.

                                                                      {
    debugAssert(token.type() == Token::SYMBOL);
    std::string s = token.string();
    while (! isOpen(s[0])) {
        name += s;

        // Skip newlines and comments
        token = ti.readSignificant();

        if (token.type() != Token::SYMBOL) {
            throw ParseError(ti.filename(), token.line(), token.character(), 
                "Expected symbol while parsing Any");
        }
        s = token.string();
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::deserializeTable ( TextInput &  ti )

private

void G3D::Any::dropReference ( )

private

Decrements the reference count (if there is one). If the reference count is zero after decrement, calls delete on m_data and sets it to NULL.

                        {
    if (m_data && m_data->referenceCount.decrement() <= 0) {
        // This was the last reference to the shared data
        Data::destroy(m_data);
    }
    m_data = NULL;
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::ensureData ( )

private

Allocate the Data object if it does not exist

                     {
    if (m_data == NULL) {
        m_data = Data::create(m_type);
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::ensureMutable ( )

private

If m_data is not NULL, ensure that it has a unique reference and contains a valid m_data. This has a race condition if two threads are both trying to modify the same Any simultaneously.

                        {
    if (m_data && (m_data->referenceCount.value() >= 1)) {
        // Copy the data.  We must do this before dropping the reference
        // to avoid a race condition
        Data* d = Data::create(m_data);
        dropReference();
        m_data = d;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

float G3D::Any::floatValue

(

)

const

                            {
    beforeRead();
    verifyType(NUMBER);
    return (float)m_simpleValue.n;
}

Here is the call graph for this function:

Any G3D::Any::fromFile ( const std::string &  filename )

static

Load a new Any from filename.

See also

load, save, loadIfExists

                                           {
    Any a;
    a.load(filename);
    return a;
}

Here is the call graph for this function:

template<class T >

Any G3D::Any::get ( const std::string &  key, const T &  defaultVal  ) const

inline

For a table, returns the element for key x and defaultVal if it does not exist.

                                                             {
        return _get(key, Any(defaultVal));
    }

Here is the call graph for this function:

template<class T >

void G3D::Any::getArray ( Array< T > &  array ) const

inline

Assumes that T defines T(const Any&)

                                         {
        verifyType(ARRAY);
        array.resize(size());
        for (int i = 0; i < array.size(); ++i) {
            array[i] = T((*this)[i]);
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

template<class T >

void G3D::Any::getTable ( Table< std::string, T > &  table ) const

inline

Assumes that T defines T(const Any&)

                                                    {
        verifyType(TABLE);
        for (Table<std::string, Any>::Iterator it = this->table().begin(); it.isValid(); ++it) {
            table.set(it.key(), T(it.value()));
        }
    }

Here is the call graph for this function:

Here is the caller graph for this function:

bool G3D::Any::isNil

(

)

const

True if this is the NIL value

                      {
    beforeRead();
    return (m_type == NIL);
}

Here is the call graph for this function:

bool G3D::Any::isPlaceholder ( ) const

inlineprivate

                               {
        return ! m_placeholderName.empty();
    }

Here is the caller graph for this function:

const Any& G3D::Any::last ( ) const

inline

                            {
        return (*this)[size() - 1];
    }

Here is the call graph for this function:

Any& G3D::Any::last ( )

inline

                {
        return (*this)[size() - 1];
    }

Here is the call graph for this function:

int G3D::Any::length

(

)

const

                      {
    beforeRead();
    return size();
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::load

(

const std::string &

filename

)

Parse from a file.

See also

deserialize, parse, fromFile, loadIfExists

                                        {
    beforeRead();
    TextInput::Settings settings;
    getDeserializeSettings(settings);

    TextInput ti(FileSystem::resolve(filename), settings);
    deserialize(ti);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::loadIfExists

(

const std::string &

filename

)

Load filename file if it exists, otherwise do not modify this

                                                {
    if (FileSystem::exists(filename)) {
        load(filename);
    }
}

Here is the call graph for this function:

const std::string & G3D::Any::name

(

)

const

If this is named ARRAY or TABLE, returns the name.

                                 {
    beforeRead();
    static const std::string blank;
    if (m_data != NULL) {
        return m_data->name;
    } else {
        return blank;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool G3D::Any::nameBeginsWith

(

const std::string &

s

)

const

If this is named ARRAY or TABLE, returns true if the name begins with s. The comparision is case insensitive.

                                                 {
    return nameBeginsWith(s.c_str());
}

bool G3D::Any::nameBeginsWith

(

const char *

s

)

const

If this is named ARRAY or TABLE, returns true if the name begins with s. The comparision is case insensitive.

                                            {
    verifyType(Any::ARRAY, Any::TABLE);

    const char* n = name().c_str();
    // Walk through character-by-character
    while ((*s != '\0') && (*n != '\0')) {
        if (toLower(*s) != toLower(*n)) {
            // Mismatch
            return false;
        }
        ++s; ++n;
    }
    // Make sure s ran out no later than n
    return (*s == '\0');
}

Here is the call graph for this function:

bool G3D::Any::nameEquals

(

const std::string &

s

)

const

If this is named ARRAY or TABLE, returns true if the name is s. The comparision is case insensitive.

                                             {
    // If std::string has a fast hash compare, use it first
    return (name() == s) || nameEquals(s.c_str());
}

Here is the call graph for this function:

Here is the caller graph for this function:

bool G3D::Any::nameEquals

(

const char *

s

)

const

If this is named ARRAY or TABLE, returns true if the name iss. The comparision is case insensitive.

                                        {
    verifyType(Any::ARRAY, Any::TABLE);
#ifdef G3D_WINDOWS
    return stricmp(name().c_str(), s) == 0;
#else
    return strcasecmp(name().c_str(), s) == 0;
#endif

}

Here is the call graph for this function:

Any & G3D::Any::next

(

)

for an ARRAY, resizes and returns the last element

               {
    beforeRead();
    verifyType(ARRAY);
    int n = size();
    resize(n + 1);
    return (*this)[n];
}

Here is the call graph for this function:

double G3D::Any::number

(

)

const

Throws a ParseError exception if this is not a number

                         {
    beforeRead();
    verifyType(NUMBER);
    return m_simpleValue.n;
}

Here is the call graph for this function:

G3D::Any::operator bool

(

)

const

                         {
    beforeRead();
    return boolean();
}

G3D::Any::operator char ( ) const

inline

                          {
        return char(int(*this));
    }

G3D::Any::operator double

(

)

const

                           {
    beforeRead();
    return number();
}

G3D::Any::operator float

(

)

const

                          {
    beforeRead();
    return float(number());
}

G3D::Any::operator int

(

)

const

                        {
    beforeRead();
    return iRound(number());
}

Here is the call graph for this function:

G3D::Any::operator int16 ( ) const

inline

                           {
        return int16(int(*this));
    }

G3D::Any::operator std::string

(

)

const

                              {
    beforeRead();
    return string();
}

G3D::Any::operator uint16 ( ) const

inline

                            {
        return uint16(int(*this));
    }

G3D::Any::operator uint32

(

)

const

                           {
    beforeRead();
    return uint32(number() + 0.5);
}

G3D::Any::operator uint8 ( ) const

inline

                           {
        return uint8(int(*this));
    }

bool G3D::Any::operator!=

(

const Any &

x

)

const

                                       {
    return ! operator==(x);
}

Here is the call graph for this function:

bool G3D::Any::operator!= ( const std::string &  s ) const

inline

                                              {
        return *this != Any(s);
    }

Here is the call graph for this function:

bool G3D::Any::operator!= ( const double &  v ) const

inline

                                           {
        return *this != Any(v);
    }

Here is the call graph for this function:

bool G3D::Any::operator!= ( int  v ) const

inline

                                 {
        return *this != Any(v);
    }

Here is the call graph for this function:

bool G3D::Any::operator!= ( bool  v ) const

inline

                                  {
        return *this != Any(v);
    }

Here is the call graph for this function:

Any & G3D::Any::operator=

(

const Any &

x

)

Removes the comment and name

                                {
    x.beforeRead();

    if (this == &x) {
        return *this;
    }

    beforeWrite();

    dropReference();

    m_type        = x.m_type;
    m_simpleValue = x.m_simpleValue;

    if (x.m_data != NULL) {
        x.m_data->referenceCount.increment();
        m_data = x.m_data;
    }

    return *this;
}

Here is the call graph for this function:

Any & G3D::Any::operator=

(

Type

t

)

t must be ARRAY, TABLE, or NIL. Removes the comment and name

                          {
    switch (t) {
    case NIL:  
        *this = Any();
        break;

    case TABLE: // All 3 cases intentionally fall through
    case ARRAY:
    case EMPTY_CONTAINER:
        *this = Any(t);
        break;

    default:
        alwaysAssertM(false, "Can only assign NIL, TABLE, or ARRAY Type enum.");
    }

    return *this;
}

Here is the call graph for this function:

template<class T >

Any& G3D::Any::operator= ( const Array< T > &  array )

inline

Assigns from an array. Assumes that T can be converted to Any. Removes the comment and name

                                          {
        *this = Any::ARRAY;
        resize(array.size());
        for (int i = 0; i < array.size(); ++i) {
            this->operator [](i) = array[i];
        }
        return *this;
    }

Here is the call graph for this function:

template<class T >

Any& G3D::Any::operator= ( const T &  v )

inline

Removes the comment and name

                               {
        *this = Any(v);
        return *this;
    }

Here is the call graph for this function:

bool G3D::Any::operator==

(

const Any &

x

)

const

True if the Anys are exactly equal, ignoring comments. Applies deeply on arrays and tables.

                                       {
    beforeRead();
    x.beforeRead();

    if (m_type != x.m_type) {
        return false;
    }

    switch (m_type) {
    case NIL:
        return true;

    case BOOLEAN:
        return (m_simpleValue.b == x.m_simpleValue.b);

    case NUMBER:
        return (m_simpleValue.n == x.m_simpleValue.n);

    case STRING:
        debugAssert(m_data != NULL);
        return (*(m_data->value.s) == *(x.m_data->value.s));

    case TABLE: {
        if (size() != x.size()) {
            return false;
        }
        debugAssert(m_data != NULL);
        if (m_data->name != x.m_data->name) {
            return false;
        }
        const Table<std::string, Any>& table1 = table();
        const Table<std::string, Any>& table2 = x.table();
        for (Table<std::string, Any>::Iterator it = table1.begin(); it.isValid(); ++it) {
            const Any* p2 = table2.getPointer(it->key);
            if (p2 == NULL) {
                // Key not found
                return false;
            } else if (*p2 != it->value) {
                // Different value
                return false;
            }                
        }
        return true;
    }

    case ARRAY: {
        if (size() != x.size()) {
            return false;
        }
        debugAssert(m_data != NULL);
        if (m_data->name != x.m_data->name) {
            return false;
        }

        Array<Any>& cmparray  = *(  m_data->value.a);
        Array<Any>& xcmparray = *(x.m_data->value.a);

        for (int ii = 0; ii < size(); ++ii) {
            if (cmparray[ii] != xcmparray[ii]) {
                return false;
            }
        }
        return true;
    }
    
    case EMPTY_CONTAINER:
        return true;
    default:
        alwaysAssertM(false, "Unknown type.");
        return false;
    }

}

Here is the call graph for this function:

Here is the caller graph for this function:

bool G3D::Any::operator== ( const std::string &  s ) const

inline

                                              {
        return *this == Any(s);
    }

Here is the call graph for this function:

bool G3D::Any::operator== ( const double &  v ) const

inline

                                           {
        return *this == Any(v);
    }

Here is the call graph for this function:

bool G3D::Any::operator== ( int  v ) const

inline

                                 {
        return *this == Any(v);
    }

Here is the call graph for this function:

bool G3D::Any::operator== ( bool  v ) const

inline

                                  {
        return *this == Any(v);
    }

Here is the call graph for this function:

const Any & G3D::Any::operator[]

(

int

i

)

const

For an array, returns the ith element

                                      {
    beforeRead();
    verifyType(ARRAY);
    debugAssert(m_data != NULL);
    Array<Any>& array = *(m_data->value.a);
    if (i < 0 || i >= array.size()) {
        throw IndexOutOfBounds(m_data, i, array.size());
    }
    return array[i];
}

Here is the call graph for this function:

Here is the caller graph for this function:

Any & G3D::Any::operator[]

(

int

i

)

                          {
    beforeRead();
    ensureMutable();
    verifyType(ARRAY);
    debugAssert(m_data != NULL);
    Array<Any>& array = *(m_data->value.a);
    if (i < 0 || i >= array.size()) {
        throw IndexOutOfBounds(m_data, i, array.size());
    }
    return array[i];
}

Here is the call graph for this function:

const Any & G3D::Any::operator[]

(

const std::string &

key

)

const

For a table, returns the element for key. Throws KeyNotFound exception if the element does not exist.

                                                   {
    beforeRead();
    verifyType(TABLE);
    debugAssert(m_data != NULL);
    const Table<std::string, Any>& table = *(m_data->value.t);
    Any* value = table.getPointer(x);
    if (value == NULL) {
        KeyNotFound e(m_data);
        e.key = x;
        e.message = "Key not found in operator[] lookup.";
        throw e;
    }
    return *value;
}

Here is the call graph for this function:

const Any& G3D::Any::operator[] ( const char *  key ) const

inline

                                                 {
        return operator[](std::string(key));
    }

Here is the call graph for this function:

Any & G3D::Any::operator[]

(

const std::string &

key

)

Fetch an element from a table. This can be used as:

a["key"] = value;  (create the key if it did not exist)

or

value = a["key"];  (throw an error if the key did not exist)

Note: In order to cause elements to be correctly created in the first case while still providing "key not found" errors in the second case, the Any returned is a special object that delays the actual fetch until the following assignment or method call. This means that in the event of an error, the exception may be thrown from a line other than the actual fetch. Use the Any::get() or the const Any::operator[]() methods to avoid this behavior and ensure error-checking at fetch time.

                                         {
    beforeRead();
    ensureMutable();
    verifyType(TABLE);

    bool created = false;
    Any& value = m_data->value.t->getCreate(key, created);

    if (created) {
        // The entry was created by this method; do not allow it to be
        // read before it is written.
        value.m_placeholderName = key;

        // Write source data for the value
        value.ensureData();
        value.m_data->source = source();
    }

    return value;
}

Here is the call graph for this function:

Any& G3D::Any::operator[] ( const char *  key )

inline

Fetch an element from a table. This can be used as:

a["key"] = value;  (create the key if it did not exist)

or

value = a["key"];  (throw an error if the key did not exist)

Note: In order to cause elements to be correctly created in the first case while still providing "key not found" errors in the second case, the Any returned is a special object that delays the actual fetch until the following assignment or method call. This means that in the event of an error, the exception may be thrown from a line other than the actual fetch. Use the Any::get() or the const Any::operator[]() methods to avoid this behavior and ensure error-checking at fetch time.

                                            {
        return operator[](std::string(key));
    }

Here is the call graph for this function:

Any G3D::Any::parse ( const std::string &  src )

static

Same as deserialize or load, but operates on a string instead of a stream or file.

See also

deserialize, load, unparse

                                   {
    Any a;
    a._parse(src);
    return a;    
}

Here is the call graph for this function:

void G3D::Any::readUntilSeparatorOrClose ( TextInput &  ti, Token &  token  )

staticprivate

Read until a separator is consumed or a close paren is hit, and return that token. Considers the passed in token to be the first value read.

                                                               {
    bool atClose = (token.type() == Token::SYMBOL) && isClose(token.string()[0]);
    bool atSeparator = isSeparator(token.string()[0]);

    while (! (atClose || atSeparator)) {
        switch (token.type()) {
        case Token::NEWLINE:
        case Token::COMMENT:
            // Consume
            token = ti.read();
            break;

        default:
            throw ParseError(ti.filename(), token.line(), token.character(), 
                "Expected a comma or close paren");
        }

        // Update checks
        atSeparator = isSeparator(token.string()[0]);
        atClose = (token.type() == Token::SYMBOL) && isClose(token.string()[0]);
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::remove

(

const std::string &

key

)

Removes this key from the Any, which must be a table.

                                     {
    verifyType(TABLE);
    ensureMutable();
    m_data->value.t->remove(key);
}

Here is the call graph for this function:

void G3D::Any::remove

(

int

index

)

Removes this key from the Any, which must be an array, and shifts other elements down to maintain order.

                      {
    verifyType(ARRAY);
    ensureMutable();
    m_data->value.a->remove(i);
}

Here is the call graph for this function:

void G3D::Any::resize

(

int

n

)

Resize to n elements, where new elements are NIL It is an error to call this method if this is not an Any::ARRAY

                      {
    beforeRead();
    alwaysAssertM(n >= 0, "Cannot resize less than 0.");
    verifyType(ARRAY);
    if (type() == EMPTY_CONTAINER) {
        become(ARRAY);
    }
    m_data->value.a->resize(n);
}

Here is the call graph for this function:

Here is the caller graph for this function:

std::string G3D::Any::resolveStringAsFilename

(

bool

errorIfNotFound = true

)

const

If a valid string, takes the string value and creates a fully qualified filename.

The file is searched for the following ways:

• In the directory from which the Any was loaded.
• By calling System::findDataFile as you would with other data files.

Strings that begin with '<' and end with '>' are treated as escape sequences and are returned unmodifed.

                                                                 {
    verifyType(STRING);
    if ((string().length() > 0) && (string()[0] == '<') && (string()[string().length() - 1] == '>')) {
        return string();
    }

    const std::string& f = FileSystem::resolve(string(), sourceDirectory());
    if (FileSystem::exists(f)) {
        return f;
    } else {
        const std::string& s = System::findDataFile(string(), errorIfNotFound);
        if (s.empty()) {
            return string();
        } else {
            return s;
        }
    }
}

Here is the call graph for this function:

void G3D::Any::save

(

const std::string &

filename

)

const

Uses the serialize method.

                                              {
    beforeRead();
    TextOutput::Settings settings;
    settings.wordWrap = TextOutput::Settings::WRAP_NONE;

    TextOutput to(filename,settings);
    serialize(to);
    to.commit();
}

Here is the call graph for this function:

void G3D::Any::serialize	(	TextOutput &	to,
		bool	json = false,
		bool	coerce = false
	)		const

                                                                {
    beforeRead();

    if (m_data && ! m_data->includeLine.empty()) {
        if (json) {
            if (! coerce) {
                throw "Could not coerce to JSON";
            }

            // Silently fall through
        } else {
            // This value came from a #include...preserve it.  This includes the comment
            // if any.
            to.printf("%s", m_data->includeLine.c_str());
            return;
        }
    }

    if (m_data && ! m_data->comment.empty()) {
        if (json) {
            if (! coerce) {
                throw "Could not coerce to JSON";
            }
        } else {
            to.printf("\n/* %s */\n", m_data->comment.c_str());
        }
    }

    switch (m_type) {
    case NIL:
        if (json) {
            to.writeSymbol("null");
        } else {
            to.writeSymbol("NIL");
        }
        break;

    case BOOLEAN:
        to.writeBoolean(m_simpleValue.b);
        break;

    case NUMBER:
        if (json) {
            // Specials have no legal syntax in JSON, so insert values that will parse 
            // to something close to what we want (there is no good solution for NaN, unfortunately)
            if (m_simpleValue.n == inf()) {
                to.writeSymbol("1e10000");
            } else if (m_simpleValue.n == -inf()) {
                to.writeSymbol("-1e10000");
            } else if (isNaN(m_simpleValue.n)) {
                if (! coerce) {
                    throw "There is no way to represent NaN in JSON";
                }
                to.writeSymbol("null");
            } else {
                to.writeNumber(m_simpleValue.n);
            }
        } else {
            to.writeNumber(m_simpleValue.n);
        }
        break;

    case STRING:
        debugAssert(m_data != NULL);
        to.writeString(*(m_data->value.s));
        break;

    case TABLE: {
        debugAssert(m_data != NULL);
        debugAssert(m_data->separator != '\0');

        if (! m_data->name.empty()) {
            if (json) {
                if (! coerce) {
                    throw "Could not coerce to JSON";
                }
            } else {
                if (needsQuotes(m_data->name)) {
                    to.writeString(m_data->name);
                } else {
                    to.writeSymbol(m_data->name);
                }
            }
        }
        if (json) {
            to.writeSymbol("{");
        } else {
            to.writeSymbol(m_data->bracket[0]);
        }
        to.writeNewline();
        to.pushIndent();
        AnyTable& table = *(m_data->value.t);
        Array<std::string> keys;
        table.getKeys(keys);
        keys.sort();

        for (int i = 0; i < keys.size(); ++i) {

            int prevLine = to.line();
            if (needsQuotes(keys[i]) || json) {
                to.writeString(keys[i]);
            } else {
                to.writeSymbol(keys[i]);
            }

            if (json) {
                to.writeSymbol(":");
            } else {
                to.writeSymbol("=");
            }
            table[keys[i]].serialize(to, json, coerce);

            to.deleteSpace();
            if (json) {
                // Don't put a separator after the last
                if (i != keys.size() - 1) {
                    to.writeSymbol(",");
                }
            } else {
                to.writeSymbol(m_data->separator);
            }

            // Skip an extra line between table entries that are longer than a line
            if (prevLine != to.line()) {
                to.writeNewline();
            }

            to.writeNewline();
        }

        to.popIndent();
        to.writeSymbol(m_data->bracket[1]);
        break;
    }

    case ARRAY: {
        debugAssert(m_data != NULL);
        debugAssert(m_data->separator != '\0');

        if (! m_data->name.empty()) {
            if (json) {
                if (! coerce) {
                    throw "Could not coerce to JSON";
                }
                to.writeSymbol("[");
            } else {
                // For arrays, leave no trailing space between the name and the paren
                to.printf("%s%c", m_data->name.c_str(), m_data->bracket[0]);
            }
        } else {
            if (json) {
                to.writeSymbol("[");
            } else {
                to.writeSymbol(m_data->bracket[0]);
            }
        }
        const Array<Any>& array = *(m_data->value.a);
        const bool longForm = (array.size() > 0) && ((array[0].type() == ARRAY) || (array[0].type() == TABLE));

        if (longForm) {
            to.writeNewline();
        }

        to.pushIndent();
        for (int ii = 0; ii < size(); ++ii) {
            array[ii].serialize(to, json, coerce);
            if (ii < size() - 1) {
                to.deleteSpace();
                if (longForm) {
                    // Probably a long-form array
                    if (json) {
                        to.writeSymbol(",");
                    } else {
                        to.writeSymbol(m_data->separator);
                    }
                    to.writeNewline();
                } else {
                    // Probably a short-form array
                    if (json) {
                        to.writeSymbol(",");
                    } else {
                        to.writeSymbol(m_data->separator);
                    }
                }
            }
            
            // Put the close paren on an array right behind the last element
        }
        to.popIndent();
        if (json) {
            to.writeSymbol("]");
        } else {
            to.writeSymbol(m_data->bracket[1]);
        }
        break;
    }

    case EMPTY_CONTAINER: {
        debugAssert(m_data != NULL);
        debugAssert(m_data->separator != '\0');

        if (json) {
            if (! coerce) {
                throw "Cannot strictly convert the ambiguous Any empty container to JSON";
            }
            to.writeSymbols("[", "]");
        } else {
            if (! m_data->name.empty()) {
                // Leave no trailing space between the name and the paren
                to.printf("%s%c", m_data->name.c_str(), m_data->bracket[0]);
            } else {
                to.writeSymbol(m_data->bracket[0]);
            }
            to.writeSymbol(m_data->bracket[1]);
        }
        break;
    }
    }
    
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::serialize

(

class BinaryOutput &

b

)

const

                                         {
    TextOutput::Settings s;
    s.wordWrap = TextOutput::Settings::WRAP_NONE;
    b.writeInt32(1);
    b.writeString32(unparse(s));
}

Here is the call graph for this function:

template<class T >

void G3D::Any::set ( const std::string &  key, const T &  val  )

inline

For a table, assigns the element for key k.

                                                 {
        _set(key, Any(val));
    }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::setComment

(

const std::string &

c

)

                                       {
    beforeRead();
    ensureData();
    m_data->comment = c;
}

Here is the call graph for this function:

void G3D::Any::setName

(

const std::string &

name

)

Set the name used when serializing an ARRAY or TABLE.

Only legal for ARRAY or TABLE. The name must begin with a letter and contain only letters, numbers, underscores and scope operators.

 a2z
 hello
 Foo::bar
 color.red
 this->that
 __x
 

The scope operators "::", "->", and ".", may have spaces around them. The name may not contain parentheses.

                                    {
    beforeRead();
    ensureData();
    m_data->name = n;
}

Here is the call graph for this function:

Here is the caller graph for this function:

int G3D::Any::size

(

)

const

Number of elements if this is an ARRAY or TABLE

                    {
    beforeRead();
    verifyType(ARRAY, TABLE);
    switch (m_type) {
    case TABLE:
        return (int)m_data->value.t->size();

    case ARRAY:
        return m_data->value.a->size();

    default:
        return 0;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

const Any::Source & G3D::Any::source

(

)

const

                                   {
    static Source s;
    if (m_data) {
        return m_data->source;
    } else {
        return s;
    }
}

Here is the caller graph for this function:

std::string G3D::Any::sourceDirectory

(

)

const

The parent directory of the location from which this Any was loaded. This is useful for interpreting filenames relative to the Any's source location, which may not match the current directory if the Any was from an included file.

                                     {
    if (m_data) {
        return FilePath::parent(m_data->source.filename);
    } else {
        return "";
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

const std::string & G3D::Any::string

(

)

const

                                   {
    beforeRead();
    verifyType(STRING);
    return *(m_data->value.s);
}

Here is the call graph for this function:

Here is the caller graph for this function:

const Table< std::string, Any > & G3D::Any::table

(

)

const

Directly exposes the underlying data structure for table.

See also

G3D::AnyTableReader

                                              {
    beforeRead();
    verifyType(TABLE);
    debugAssert(m_data != NULL);

    if (type() == Any::EMPTY_CONTAINER) {
        // if empty, m_data->value.t will not be initialized as it is unknown whether this is supposed to be an array or a table
        static const Table<std::string, Any> emptyTable;
        return emptyTable;
    }
    return *(m_data->value.t);
}

Here is the call graph for this function:

Here is the caller graph for this function:

std::string G3D::Any::toString ( Type  t )

static

                              {
    switch(t) {
    case NIL:    return "NIL";
    case BOOLEAN: return "BOOLEAN";
    case NUMBER:  return "NUMBER";
    case STRING:  return "STRING";
    case ARRAY:   return "ARRAY";
    case TABLE:   return "TABLE";
    default:
        alwaysAssertM(false, "Illegal Any::Type");
        return "";
    }
}

Here is the caller graph for this function:

Any::Type G3D::Any::type

(

)

const

                        {
    beforeRead();
    return m_type;
}

Here is the call graph for this function:

Here is the caller graph for this function:

std::string G3D::Any::unparse

(

const TextOutput::Settings &

s = TextOutput::Settings()

)

const

                                                               {
    beforeRead();
    TextOutput to(settings);
    serialize(to);
    return to.commitString();
}

Here is the call graph for this function:

Here is the caller graph for this function:

std::string G3D::Any::unparseJSON	(	const TextOutput::Settings &	s = TextOutput::Settings(),
		bool	allowCoercion = true
	)		const

Parameters

allowCoercion

If false, throws an error if the Any uses features that are not supported by JSON such as named arrays. Otherwise, silently coerces to JSON.

                                                                                       {
    beforeRead();
    TextOutput to(settings);
    serialize(to, true, allowCoercion);
    return to.commitString();
}

Here is the call graph for this function:

void G3D::Any::verify	(	bool	value,
		const std::string &	message = ""
	)		const

Throws a ParseError if value is false. Useful for quickly creating parse rules in classes that deserialize from Any.

                                                           {
    beforeRead();
    if (! value) {
        ParseError p;
        if (m_data) {
            p.filename  = m_data->source.filename;
            p.line      = m_data->source.line;
            p.character = m_data->source.character;
        }

        if (name().empty()) {
            p.message = "Parse error";
        } else {
            p.message = "Parse error while reading the contents of " + name();
        }

        if (! message.empty()) {
            p.message = p.message + ": " + message;
        }

        throw p;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::verifyName

(

const std::string &

n

)

const

Verifies that the name is identifier n (case sensitive). It may contain identifier operators after this

                                             {
    beforeRead();
    verify(name() == n, "Name must be " + n);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::verifyName	(	const std::string &	n,
		const std::string &	m
	)		const

Verifies that the name is identifier n or m (case sensitive). It may contain identifier operators after this

                                                                 {
    beforeRead();
    const std::string& x = name();
    verify(x == n ||
           x == m, "Name must be " + n + " or " + m);
}

Here is the call graph for this function:

void G3D::Any::verifyName	(	const std::string &	n,
		const std::string &	m,
		const std::string &	p
	)		const

Verifies that the name is identifier n or m or p (case sensitive). It may contain identifier operators after this

                                                                                     {
    beforeRead();
    const std::string& x = name();
    verify(x == n ||
           x == m ||
           x == p, "Name must be " + n + ", " + m + ", or " + p);
}

Here is the call graph for this function:

void G3D::Any::verifyName	(	const std::string &	n,
		const std::string &	m,
		const std::string &	p,
		const std::string &	q
	)		const

Verifies that the name is identifier n or m or p or q (case sensitive). It may contain identifier operators after this

                                                                                                         {
    beforeRead();
    const std::string& x = name();
    verify(x == n ||
           x == m ||
           x == p ||
           x == q, "Name must be " + n + ", " + m + ", " + p + ", or " + q);
}

Here is the call graph for this function:

void G3D::Any::verifyNameBeginsWith

(

const std::string &

n

)

const

Verifies that the name begins with identifier n (case sensitive). It may contain identifier operators after this

                                                       {
    beforeRead();
    verify(beginsWith(name(), n), "Name must begin with " + n);
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::verifyNameBeginsWith	(	const std::string &	n,
		const std::string &	m
	)		const

Verifies that the name begins with identifier n or m (case sensitive). It may contain identifier operators after this

                                                                           {
    beforeRead();
    const std::string& x = name();
    verify(beginsWith(x, n) ||
           beginsWith(x, m), "Name must be " + n + " or " + m);
}

Here is the call graph for this function:

void G3D::Any::verifyNameBeginsWith	(	const std::string &	n,
		const std::string &	m,
		const std::string &	p
	)		const

Verifies that the name begins with identifier n or m or p (case sensitive). It may contain identifier operators after this

                                                                                               {
    beforeRead();
    const std::string& x = name();
    verify(beginsWith(x, n) ||
           beginsWith(x, m) ||
           beginsWith(x, p), "Name must be " + n + ", " + m + ", or " + p);
}

Here is the call graph for this function:

void G3D::Any::verifyNameBeginsWith	(	const std::string &	n,
		const std::string &	m,
		const std::string &	p,
		const std::string &	q
	)		const

Verifies that the name begins with identifier n or m or p or q (case sensitive). It may contain identifier operators after this

                                                                                                                   {
    beforeRead();
    const std::string& x = name();
    verify(beginsWith(x, n) ||
           beginsWith(x, m) ||
           beginsWith(x, p) ||
           beginsWith(x, q), "Name must be " + n + ", " + m + ", " + p + ", or " + q);
}

Here is the call graph for this function:

void G3D::Any::verifyNameBeginsWith	(	const std::string &	n,
		const std::string &	m,
		const std::string &	p,
		const std::string &	q,
		const std::string &	r
	)		const

Verifies that the name begins with identifier n or m or p or q or r (case sensitive). It may contain identifier operators after this

                                                                                                                                       {
    beforeRead();
    const std::string& x = name();
    verify(beginsWith(x, n) ||
           beginsWith(x, m) ||
           beginsWith(x, p) ||
           beginsWith(x, q) ||
           beginsWith(x, r), "Name must be " + n + ", " + m + ", " + p + ", or " + q + ", or " + r);
}

Here is the call graph for this function:

void G3D::Any::verifyNameBeginsWith	(	const std::string &	n,
		const std::string &	m,
		const std::string &	p,
		const std::string &	q,
		const std::string &	r,
		const std::string &	s
	)		const

Verifies that the name begins with identifier n or m or p or q or r or s (case sensitive). It may contain identifier operators after this

                                                                                                                                                           {
    beforeRead();
    const std::string& x = name();
    verify(beginsWith(x, n) ||
           beginsWith(x, m) ||
           beginsWith(x, p) ||
           beginsWith(x, q) ||
           beginsWith(x, r) ||
           beginsWith(x, s), "Name must be " + n + ", " + m + ", " + p + ", or " + q + ", or " + r + ", or " + s);
}

Here is the call graph for this function:

void G3D::Any::verifyNameBeginsWith	(	const std::string &	n,
		const std::string &	m,
		const std::string &	p,
		const std::string &	q,
		const std::string &	r,
		const std::string &	s,
		const std::string &	t
	)		const

Verifies that the name begins with identifier n or m or p or q or r or s or t(case sensitive). It may contain identifier operators after this

                                                                                                                                                                               {
    beforeRead();
    const std::string& x = name();
    verify(beginsWith(x, n) ||
           beginsWith(x, m) ||
           beginsWith(x, p) ||
           beginsWith(x, q) ||
           beginsWith(x, r) ||
           beginsWith(x, s) ||
           beginsWith(x, t), "Name must be " + n + ", " + m + ", " + p + ", or " + q + ", or " + r + ", or " + s + ", or " + t);
}

Here is the call graph for this function:

void G3D::Any::verifySize	(	int	low,
		int	high
	)		const

Verifies that the size is between low and high, inclusive

                                            {
    beforeRead();
    verifyType(ARRAY, TABLE);
    if (size() < low || size() > high) {
        verify(false, format("Size must be between %d and %d", low, high));
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::verifySize

(

int

s

)

const

Verifies that the size is exactly s

                                {
    beforeRead();
    verifyType(ARRAY, TABLE);
    if (size() != s) {
        verify(false, format("Size must be %d", s));
    }
}

Here is the call graph for this function:

void G3D::Any::verifyType

(

Type

t

)

const

Verifies that the type is t.

                                 {
    beforeRead();
    if ((type() != t) && ! ((type() == EMPTY_CONTAINER) && isContainerType(t))) {
        verify(false, "Must have type " + toString(t));
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::Any::verifyType	(	Type	t0,
		Type	t1
	)		const

Throws an exception if the type is not t0 or t1.

                                           {
    beforeRead();
    if ((type() != t0 && !((type() == EMPTY_CONTAINER) && isContainerType(t0))) &&
        (type() != t1 && !((type() == EMPTY_CONTAINER) && isContainerType(t1)))) {
        verify(false, "Must have type " + toString(t0) + " or " + toString(t1));
    }
}

Here is the call graph for this function:

Member Data Documentation

const char * G3D::Any::BRACE = "{}"

staticprivate

const char * G3D::Any::BRACKET = "[]"

staticprivate

Data* G3D::Any::m_data

mutableprivate

std::string G3D::Any::m_placeholderName

private

If not empty, this Any was created from operator[] on a table and perhaps was not intended to exist. The name is needed to format the error message if it is read from before it is written to.

The source of a placeholder object is that of the parent object until it is written.

SimpleValue G3D::Any::m_simpleValue

private

Type G3D::Any::m_type

private

const char * G3D::Any::PAREN = "()"

staticprivate

The three options for Data::bracket

---

The documentation for this class was generated from the following files:

• dep/g3dlite/include/G3D/Any.h
• dep/g3dlite/source/Any.cpp