Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members

FX::FXJSON Class Reference

The FXJSON serializer loads or saves an FXVariant to a JSON text file. More...

#include <FXJSON.h>

Inheritance diagram for FX::FXJSON:
FX::FXParseBuffer FX::FXJSONFile FX::FXJSONString

Public Types

enum  Error {
  ErrOK, ErrSave, ErrLoad, ErrToken,
  ErrColon, ErrComma, ErrBracket, ErrBrace,
  ErrQuotes, ErrQuote, ErrNumber, ErrIdent,
  ErrEnd
}
 JSON deserializer error codes. More...
 
enum  Flow { Stream, Compact, Pretty }
 JSON serializer flow modes. More...
 
- Public Types inherited from FX::FXParseBuffer
enum  Direction { Stop = 0, Save = 1, Load = 2 }
 

Public Member Functions

 FXJSON ()
 Initialize JSON serializer.
 
 FXJSON (FXchar *buffer, FXuval sz=8192, Direction d=Load)
 Initialize JSON serializer with buffer of size and direction. More...
 
FXbool open (FXchar *buffer=nullptr, FXuval sz=8192, Direction d=Load)
 Open JSON parse buffer with given size and direction. More...
 
FXint getLine () const
 Return current line number.
 
FXint getColumn () const
 Return current column number.
 
FXlong getOffset () const
 Return offset from begin of file.
 
virtual Error load (FXVariant &variant)
 Load a variant from JSON stream. More...
 
virtual Error save (const FXVariant &variant)
 Save a variant to JSON stream. More...
 
void setNumericPrecision (FXuchar p)
 Floating point output precision control. More...
 
FXuchar getNumericPrecision () const
 
void setNumericFormat (FXuchar f)
 Floating point output format control. More...
 
FXuchar getNumericFormat () const
 
void setOutputFlow (FXuchar f)
 Change output flow format (Stream, Compact, Pretty). More...
 
FXuchar getOutputFlow () const
 
void setIndentation (FXuchar d)
 Change indentation level for pretty print flow, the amount of indentation applied for each level.
 
FXuchar getIndentation () const
 
void setLineWrap (FXint w)
 Change column at which lines are wrapped.
 
FXint getLineWrap () const
 
void setEscapeMode (FXuchar e)
 Change string escape mode. More...
 
FXuchar getEscapeMode () const
 
void setVersion (FXuchar v)
 Change json version.
 
FXuchar getVersion () const
 
void setQuote (FXchar q)
 Change quote type, either (') or (").
 
FXchar getQuote () const
 
FXbool close ()
 Close stream and delete buffer, if owned. More...
 
virtual ~FXJSON ()
 Close JSON stream and clean up.
 
- Public Member Functions inherited from FX::FXParseBuffer
 FXParseBuffer ()
 Initialize parse buffer to empty.
 
 FXParseBuffer (FXchar *buffer, FXuval sz=4096, Direction d=Load)
 Initialize parse buffer with given size and direction. More...
 
FXbool open (FXchar *buffer=nullptr, FXuval sz=4096, Direction d=Load)
 Open parse buffer with given size and direction.
 
Direction direction () const
 Return current direction.
 
FXuval size () const
 Return current buffer size.
 
virtual FXival fill (FXival count)
 Read at least count bytes into buffer; return bytes available, or -1 for error.
 
virtual FXival flush (FXival count)
 Write at least count bytes from buffer; return space available, or -1 for error.
 
FXbool close ()
 Close parse buffer.
 
virtual ~FXParseBuffer ()
 Clean up and close buffer.
 

Static Public Member Functions

static const FXchar * getError (Error err)
 Returns error for given error code.
 

Protected Types

enum  Token {
  TK_ERROR, TK_EOF, TK_COMMA, TK_COLON,
  TK_IDENT, TK_NAN, TK_INF, TK_NULL,
  TK_FALSE, TK_TRUE, TK_STRING, TK_PLUS,
  TK_MINUS, TK_INT, TK_HEX, TK_REAL,
  TK_LBRACK, TK_LBRACE, TK_RBRACK, TK_RBRACE
}
 

Protected Member Functions

virtual Token next ()
 
Token ident ()
 
Token string ()
 
Error loadMap (FXVariant &var)
 
Error loadArray (FXVariant &var)
 
Error loadVariant (FXVariant &var)
 
Error saveString (const FXString &str)
 
Error saveIdent (const FXString &str)
 
Error saveMap (const FXVariant &var)
 
Error saveArray (const FXVariant &var)
 
Error saveVariant (const FXVariant &var)
 
- Protected Member Functions inherited from FX::FXParseBuffer
FXbool need (FXival count)
 
FXbool emit (FXchar ch, FXint count)
 
FXbool emit (const FXchar *str, FXint count)
 

Static Protected Member Functions

static Token identoken (const FXString &str)
 

Protected Attributes

FXString value
 
FXlong offset
 
Token token
 
FXint column
 
FXint indent
 
FXint line
 
FXint wrap
 
FXchar quote
 
FXuchar flow
 
FXuchar prec
 
FXuchar fmt
 
FXuchar esc
 
FXuchar dent
 
FXuchar ver
 
- Protected Attributes inherited from FX::FXParseBuffer
FXchar * begptr
 
FXchar * endptr
 
FXchar * wptr
 
FXchar * rptr
 
FXchar * sptr
 
Direction dir
 

Static Protected Attributes

static const FXchar *const errors []
 

Detailed Description

The FXJSON serializer loads or saves an FXVariant to a JSON text file.

Since FXVariant can contain an arbitrarily complex data structure, this provides applications with a convenient way to load and save state information in a well-defined and human-readable file format. The base class implements serialization/deserialization to/from an external buffer.

Subclasses FXJSONFile and FXJSONString serialize from/to strings and disk- based files, respectively. The new JSON5 standard may also be parsed, allowing for single- and multi-line nested comments to be embedded in the input, and makes quotation of variable names optional. In addition, JSON5 also allows use of single quotes (') as well as double quotes (").

Syntax errors in the input cause the parser to return an error, and allow diagnosis of the problem and its location in the file by line number, column number, and byte-offset from the start of the file.

When writing a json stream, the generated output may be formatted in different ways. The flow-mode controls the overall layout of the resulting text output; when flow is set to Stream, all output is generated with no formatting to improve human legibility. This is the most space-friendly format possible. If flow is set to Compact, a human readable, compact format, aiming to maximize the amount of information on each line is generated. When flow is set to Pretty, a nicely indented, but extremely "airy" output results, and the resulting document will contain many, many lines with little data.

Numeric values are printed with configurable precision; (default=15 digits which results in minimal information loss for real numbers). For Pretty flow format, output may be indented in multiples of the indent level (default=2). Depending on flow setting, lines may be wrapped at a maximum number of columns (default=80). Output strings containing reserved characters may have to be escaped. For UTF8 characters, there are 3 options for escaping.

  • Escape mode 0: UTF8 characters are passed unescaped.
  • Escape mode 1: UTF8 characters are escaped as .
  • Escape mode 2: UTF8 will be escaed using Unicode escape sequences of the for or (two surrogate-pairs escape codes for code points exceeding 16 bits).

The default setting is to allow UTF8 characters in the output, but be aware that such outputs need UTF8-capable viewer software to be rendered properly. Finally, in JSON5 mode (version set to 5), variable names may be written as unquoted strings if their syntax allows for it; in JSON5 mode, single quotes may be selected to improve human legibility.

Member Enumeration Documentation

◆ Error

JSON deserializer error codes.

Enumerator
ErrSave 

No errors.

ErrLoad 

Unable to save.

ErrToken 

Unable to load.

ErrColon 

Illegal token.

ErrComma 

Expected colon ':'.

ErrBracket 

Expected comma ','.

ErrBrace 

Expected closing bracket.

ErrQuotes 

Expected closing brace.

ErrQuote 

Expected closing quotes.

ErrNumber 

Expected closing quote.

ErrIdent 

Numeric conversion.

ErrEnd 

Unexpected identifier.

Unexpected end of file

◆ Flow

JSON serializer flow modes.

Enumerator
Compact 

Stream-of-consciousness output.

Pretty 

Compact, human readable output (default)

Pretty printed, indented output

Constructor & Destructor Documentation

◆ FXJSON()

FX::FXJSON::FXJSON ( FXchar *  buffer,
FXuval  sz = 8192,
Direction  d = Load 
)

Initialize JSON serializer with buffer of size and direction.

Text location (column, line number, byte offset) is reset.

Member Function Documentation

◆ close()

FXbool FX::FXJSON::close ( )

Close stream and delete buffer, if owned.

To permit diagnostics, text location not reset.

◆ load()

virtual Error FX::FXJSON::load ( FXVariant variant)
virtual

Load a variant from JSON stream.

Return false if stream wasn't opened for loading, or syntax error.

◆ open()

FXbool FX::FXJSON::open ( FXchar *  buffer = nullptr,
FXuval  sz = 8192,
Direction  d = Load 
)

Open JSON parse buffer with given size and direction.

Text location (column, line number, byte offset) is reset.

◆ save()

virtual Error FX::FXJSON::save ( const FXVariant variant)
virtual

Save a variant to JSON stream.

Return false if stream wasn't opened for saving, or disk was full.

◆ setEscapeMode()

void FX::FXJSON::setEscapeMode ( FXuchar  e)
inline

Change string escape mode.

The escape mode is interpreted as follows:

0 Don't escape unicode in strings; 1 Escape unicode as 2 Escape unicode as or .

Default is to escape control characters only.

◆ setNumericFormat()

void FX::FXJSON::setNumericFormat ( FXuchar  f)
inline

Floating point output format control.

The format mode is interpreted as follows:

0 No exponent. 1 Exponent. 2 Output exponent when required.

The default mode is 2.

◆ setNumericPrecision()

void FX::FXJSON::setNumericPrecision ( FXuchar  p)
inline

Floating point output precision control.

This controls the number of significant digits written to the output. The default is 15.

◆ setOutputFlow()

void FX::FXJSON::setOutputFlow ( FXuchar  f)
inline

Change output flow format (Stream, Compact, Pretty).

Stream is the most compact, but pretty much unreadable by humans; it aims to be compact. Compact is very human-readable while at the same time using minimum number of lines to represent the output. Pretty will print one item on each line, with indentation. It is very easily readable but produces large numbers of text lines.


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

Copyright © 1997-2022 Jeroen van der Zijp