wxJSONWriter Class Reference

The JSON document writer. More...

#include <jsonwriter.h>

List of all members.

Public Member Functions

 wxJSONWriter (int style=wxJSONWRITER_STYLED, int indent=0, int step=3)
 Ctor.
 ~wxJSONWriter ()
 Dtor - does nothing.
void Write (const wxJSONValue &value, wxString &str)
 Write the JSONvalue object to a JSON text.
void Write (const wxJSONValue &value, wxOutputStream &os)

Protected Member Functions

int DoWrite (wxOutputStream &os, const wxJSONValue &value, const wxString *key, bool comma)
 Perform the real write operation.
int WriteIndent (wxOutputStream &os)
 Writes the indentation to the JSON text.
int WriteIndent (wxOutputStream &os, int num)
 Write the specified number of indentation (spaces or tabs).
bool IsSpace (wxChar ch)
 Returns TRUE if the character is a space character.
bool IsPunctuation (wxChar ch)
 Returns TRUE if the character if a puctuation character.
int WriteString (wxOutputStream &os, const wxString &str)
 Write a generic string.
int WriteStringValue (wxOutputStream &os, const wxString &str)
 Write the provided string to the output object.
int WriteNullValue (wxOutputStream &os)
 Write the NULL JSON value to the output stream.
int WriteIntValue (wxOutputStream &os, const wxJSONValue &v)
 Writes a value of type INT.
int WriteUIntValue (wxOutputStream &os, const wxJSONValue &v)
 Writes a value of type UNSIGNED INT.
int WriteBoolValue (wxOutputStream &os, const wxJSONValue &v)
 Writes a value of type BOOL.
int WriteDoubleValue (wxOutputStream &os, const wxJSONValue &v)
 Writes a value of type DOUBLE.
int WriteInvalid (wxOutputStream &os)
 Write the invalid JSON value to the output stream.
int WriteSeparator (wxOutputStream &os)
 Writes the separator between values.
int WriteKey (wxOutputStream &os, const wxString &key)
 Write the key of a key/value element to the output stream.
int WriteComment (wxOutputStream &os, const wxJSONValue &value, bool indent)
 Write the comment strings, if any.
int WriteError (const wxString &err)
 Writes an error string to the output JSON text (not used).

Detailed Description

The JSON document writer.

This class is a JSON document writer and it is used to write a wxJSONValue object to an output stream or to a string object. The ctor accepts some parameters which can be used to change the style of the output. The default output is in human-readable format that uses a three-space indentation for object / array sub-items.

Here is an example on how to use this class:

   // construct the JSON value object and add values to it
   wxJSONValue root;
   root["key1"] = "some value";
   ...

   // construct the string that will contain the JSON text
   wxString     str;

   // construct a JSON writer: use the default writer's settings
   wxJSONWriter jsw;

   // call the writer's Write() memberfunction
   jsw.Write( root, str );

output objects
You can write JSON text to two different kind of objects:

When writing to a string object, the output is platform- and mode-dependent. In ANSI builds, the JSON text output in the string object will contain one-byte characters: the actual characters represented is locale dependent. In Unicode builds, the JSON text output in the string contains wide characters which encoding format is platform dependent: UCS-2 in Windows, UCS-4 in GNU/Linux.

When writing to a stream object, the JSON text output is always encoded in UTF-8 in both ANSI and Unicode builds.

efficiency
In versions up to 1.0 the JSON writer wrote every character to the output object (the string or the stream). This is very inefficient becuase the writer converted each char to UTF-8 when writing to streams but we have to note that only string values have to be actually converted. Special JSON characters, numbers and literals do not need the conversion because for characters in the US-ASCII plane (0x00-0x7F) no conversion is needed as they only take one byte.

For more info about the unicode topic see Unicode support in wxJSON.

Constructor & Destructor Documentation

wxJSONWriter::wxJSONWriter ( int  style = wxJSONWRITER_STYLED,
int  indent = 0,
int  step = 3 
)

Ctor.

Construct the JSON writer object with the specified parameters. Note that if styled is FALSE the indentation is totally suppressed and the values of the other two parameters are simply ignored.

Parameters:
indent the initial indentation in number of spaces. Default is ZERO. If you specify the wxJSONWRITER_TAB_INDENT flag for the style, this value referes to the number of TABs in the initial indentation
step the indentation increment for new objects/arrays in number of spaces (default is 3). This value is ignored if you specify the wxJSONWRITER_TAB_INDENT flag for the style: the indentation increment is only one TAB character.
style this is a combination of the following constants OR'ed togheter:
  • wxJSONWRITER_NONE: no indentation is performed and no LF character is written between values. This style produces strict JSON text but it is hard to read by humans
  • wxJSONWRITER_STYLED: output is human-readable: values are separated by LF characters and sub-items are indented. This style produces strict JSON text that is easy to read by humans.
  • wxJSONWRITER_WRITE_COMMENTS: this flag force the writer to write C/C++ comment strings, if any. The comments will be written in their original position. C/C++ comments may not be recognized by other JSON implementations because they are not strict JSON text.
  • wxJSONWRITER_COMMENTS_BEFORE: this flag force the writer to write C/C++ comments always before the value they refer to. In order for this style to take effect, you also have to specify the wxJSONWRITER_WRITE_COMMENTS flag.
  • wxJSONWRITER_COMMENTS_AFTER: this flag force the writer to write C/C++ comments always after the value they refer to. In order for this style to take effect, you also have to specify the wxJSONWRITER_WRITE_COMMENTS flag.
  • wxJSONWRITER_SPLIT_STRINGS: this flag cause the writer to split strings in more than one line if they are too long.
  • wxJSONWRITER_NO_LINEFEEDS: this flag cause the JSON writer to not add newlines between values. It is ignored if wxJSONWRITER_STYLED is not set. This style produces strict JSON text.
  • wxJSONWRITER_ESCAPE_SOLIDUS: the solidus character (/) should only be escaped if the JSON text is meant for embedding in HTML. Unlike in older 0.x versions, it is disabled by default and this flag cause the solidus char to be escaped. This style produces strict JSON text.
  • wxJSONWRITER_MULTILINE_STRING:this is a multiline-string mode where newlines and tabs are not escaped. This is not strict JSON, but it helps immensely when manually editing json files with multiline strings
  • wxJSONWRITER_RECOGNIZE_UNSIGNED: this flag cause the JSON writer to prepend a plus sign (+) to unsigned integer values. This is used by the wxJSON reader to force the integer to be stored in an unsigned int. Note that this feature may be incompatible with other JSON implementations.
  • wxJSONWRITER_TAB_INDENT: this flag cause the indentation of sub-objects / arrays to be done using a TAB character instead of SPACES. In order for this style to take effect, you also have to specify the wxJSONWRITER_STYLED flag. This style produces strict JSON text.
  • wxJSONWRITER_NO_INDENTATION: this flag cause the JSON writer to not add indentation. It is ignored if wxJSONWRITER_STYLED is not set. This style produces strict JSON text.
  • wxJSONWRITER_NOUTF8_STREAM: suppress UTF-8 conversion when writing string values to the stream thus producing ANSI text output; only meaningfull in ANSI builds, this flag is simply ignored in Unicode builds.
Note that for the style wxJSONWRITER_NONE the JSON text output is a bit different from that of old 0.x versions although it is syntactically equal. If you rely on the old JSON output formatting read the following page The wxJSONWRITER_NONE flag. To know more about the writer's styles see The wxJSON writer's styles
Examples

To write a JSON value object using a four-spaces indentation and forcing all comment strings to apear before the value they refer to, use the following code: 

  wxJSONWriter writer( wxJSONWRITER_STYLED |   // want a styled output
                wxJSONWRITER_WRITE_COMMENTS |  // want comments in the document
                wxJSONWRITER_COMMENTS_BEFORE,  // force comments before value
                0,                             // initial indentation
                4);                            // indentation step
  writer.Write( value, document );

The following code construct a JSON writer that produces hard-to-read output: indentation is suppressed and no comment lines are written and the values in the JSON text are not separated by LF.

  wxJSONWriter writer( wxJSONWRITER_NO_LINEFEEDS );
  writer.Write( value, document );

wxJSONWriter::~wxJSONWriter (  ) 

Dtor - does nothing.

Member Function Documentation

void wxJSONWriter::Write ( const wxJSONValue &  value,
wxString &  str 
)

Write the JSONvalue object to a JSON text.

The two overloaded versions of this function let the user choose the output object which can be:

  • a string object (wxString)
  • a stream object ( wxOutputStream)
The two types of output object are very different because the text outputted is encoded in different formats depending on the build mode. When writing to a string object, the JSON text output is encoded differently depending on the build mode and the platform. Writing to a stream always produce UTF-8 encoded text. To know more about this topic read Unicode support in wxJSON.

Also note that the Write() function does not return a status code. If you are writing to a string, you do not have to warry about this issue: no errors can occur when writing to strings. On the other hand, wehn writing to a stream there could be errors in the write operation. If an error occurs, the Write(9 function immediatly returns without trying further output operations. You have to check the status of the stream by calling the stream's memberfunctions. Example:

   // construct the JSON value object and add values to it
   wxJSONValue root;
   root["key1"] = "some value";

   // write to a stream
   wxMemoryOutputStream mem;
   wxJSONWriter writer;
   writer.Write( root, mem );
   wxStreamError err = mem.GetLastError();
   if ( err != wxSTREAM_NO_ERROR )  {
     MessageBox( _T("ERROR: cannot write the JSON text output"));
   }

void wxJSONWriter::Write ( const wxJSONValue &  value,
wxOutputStream &  os 
)

int wxJSONWriter::DoWrite ( wxOutputStream &  os,
const wxJSONValue &  value,
const wxString *  key,
bool  comma 
) [protected]

Perform the real write operation.

This is a recursive function. The function calls:

  • WritePrimitiveValue() for null, boolean, integer and double types
  • WriteStringValue() for string and C-string types
  • for maps and arrays, the function calls itself for all elements in the array / hashmap after incrementing the m_level data member.

int wxJSONWriter::WriteIndent ( wxOutputStream &  os  )  [protected]

Writes the indentation to the JSON text.

The two functions write the indentation as spaces in the JSON output text. When called with a int parameter, the function writes the specified number of spaces. If no parameter is given, the function computes the number of spaces using the following formula: If the wxJSONWRITER_TAB_INDENT flag is used in the writer's cnstructor, the function calls WriteTabIndent().

The function also checks that wxJSONWRITER_STYLED is set and the wxJSONWRITER_NO_INDENTATION is not set.

int wxJSONWriter::WriteIndent ( wxOutputStream &  os,
int  num 
) [protected]

Write the specified number of indentation (spaces or tabs).

The function is called by WriteIndent() and other writer's functions. It writes the indentation as specified in the num parameter which is the actual level of annidation. The function checks if wxJSONWRITER_STYLED is set: if not, no indentation is performed. Also, the function checks if wxJSONWRITER_TAB_INDENT is set: if it is, indentation is done by writing num TAB characters otherwise, it is performed by writing a number of spaces computed as: 

  numSpaces = m_indent + ( m_step * num )

bool wxJSONWriter::IsSpace ( wxChar  ch  )  [protected]

Returns TRUE if the character is a space character.

bool wxJSONWriter::IsPunctuation ( wxChar  ch  )  [protected]

Returns TRUE if the character if a puctuation character.

int wxJSONWriter::WriteString ( wxOutputStream &  os,
const wxString &  str 
) [protected]

Write a generic string.

The function writes the wxString object str to the output object. The string is written as is; you cannot use it to write JSON strings to the output text. The function converts the string str to UTF-8 and writes the buffer..

int wxJSONWriter::WriteStringValue ( wxOutputStream &  os,
const wxString &  str 
) [protected]

Write the provided string to the output object.

The function writes the string str to the output object that was specified in the wxJSONWriter::Write() function. The function may split strings in two or more lines if the string contains LF characters if the m_style data member contains the wxJSONWRITER_SPLIT_STRING flag.

The function does not actually write the string: for every character in the provided string the function calls WriteChar() which does the actual character output.

The function returns ZERO on success or -1 in case of errors.

int wxJSONWriter::WriteNullValue ( wxOutputStream &  os  )  [protected]

Write the NULL JSON value to the output stream.

The function writes the null literal string to the output stream.

int wxJSONWriter::WriteIntValue ( wxOutputStream &  os,
const wxJSONValue &  value 
) [protected]

Writes a value of type INT.

This function is called for every value objects of INT type. This function uses the
snprintf function to get the US-ASCII representation of the integer and simply copy it to the output stream. Returns -1 on stream errors or ZERO if no errors.

int wxJSONWriter::WriteUIntValue ( wxOutputStream &  os,
const wxJSONValue &  value 
) [protected]

Writes a value of type UNSIGNED INT.

This function is called for every value objects of UINT type. This function uses the
snprintf function to get the US-ASCII representation of the integer and simply copy it to the output stream. The function prepends a plus sign if the wxJSONWRITER_RECOGNIZE_UNSIGNED flag is set in the m_flags data member. Returns -1 on stream errors or ZERO if no errors.

int wxJSONWriter::WriteBoolValue ( wxOutputStream &  os,
const wxJSONValue &  value 
) [protected]

Writes a value of type BOOL.

This function is called for every value objects of BOOL type. This function prints the literals true or false depending on the value in value. Returns -1 on stream errors or ZERO if no errors.

int wxJSONWriter::WriteDoubleValue ( wxOutputStream &  os,
const wxJSONValue &  value 
) [protected]

Writes a value of type DOUBLE.

This function is called for every value objects of DOUBLE type. This function uses the
snprintf function to get the US-ASCII representation of the integer and simply copy it to the output stream. Returns -1 on stream errors or ZERO if no errors.

int wxJSONWriter::WriteInvalid ( wxOutputStream &  os  )  [protected]

Write the invalid JSON value to the output stream.

An invalid wxJSONValue is a value that was not initialized and it is an error. You should never write invalid values to JSON text because the output is not valid JSON text. Note that the NULL value is a legal JSON text and it is written: 

  null

This function writes a non-JSON text to the output stream: 

  <invalid JSON value>
In debug mode, the function always fails with an wxFAIL_MSG failure.

int wxJSONWriter::WriteSeparator ( wxOutputStream &  os  )  [protected]

Writes the separator between values.

The function is called when a value has been written to the JSON text output and it writes the separator character: LF. The LF char is actually written only if the wxJSONWRITER_STYLED flag is specified and wxJSONWRITER_NO_LINEFEEDS is not set.

Returns the last character written which is LF itself or -1 in case of errors. Note that LF is returned even if the character is not actually written.

int wxJSONWriter::WriteKey ( wxOutputStream &  os,
const wxString &  key 
) [protected]

Write the key of a key/value element to the output stream.

int wxJSONWriter::WriteComment ( wxOutputStream &  os,
const wxJSONValue &  value,
bool  indent 
) [protected]

Write the comment strings, if any.

int wxJSONWriter::WriteError ( const wxString &  err  )  [protected]

Writes an error string to the output JSON text (not used).

The function just writes the provided string prepended with the ERROR word to the output JSON text. This could be usefull for signalling errors but not much reliable if the error occurs for the stream itself

The documentation for this class was generated from the following files:
Generated on Fri Nov 13 22:52:30 2009 for wxJSON by  doxygen 1.5.5