baljsn Package

Provide components for encoding/decoding in the JSON format. More...

Components
	Component baljsn_datumdecoderoptions
	Provide options for decoding JSON into a `Datum` object.
	Component baljsn_datumencoderoptions
	Provide an attribute class for specifying Datum<->JSON options.
	Component baljsn_datumutil
	Provide utilities converting between `bdld::Datum` and JSON data.
	Component baljsn_decoder
	Provide a JSON decoder for `bdeat` compatible types.
	Component baljsn_decoderoptions
	Provide an attribute class for specifying JSON decoding options.
	Component baljsn_encoder
	Provide a JSON encoder for `bdlat`-compatible types.
	Component baljsn_encoder_testtypes: PRIVATE
	Provide value-semantic attribute classes.
	Component baljsn_encoderoptions
	Provide an attribute class for specifying JSON encoding options.
	Component baljsn_encodingstyle
	Provide value-semantic attribute classes.
	Component baljsn_formatter
	Provide a formatter for encoding data in the JSON format.
	Component baljsn_parserutil
	Provide a utility for decoding JSON data into simple types.
	Component baljsn_printutil
	Provide a utility for encoding simple types in the JSON format.
	Component baljsn_simpleformatter
	Provide a simple formatter for encoding data in the JSON format.
	Component baljsn_tokenizer
	Provide a tokenizer for extracting JSON data from a `streambuf`.

Detailed Description

Outline

Purpose
MNEMONIC: Basic Application Library JSoN (baljsn)
Description

Purpose:: Provide components for encoding/decoding in the JSON format.

MNEMONIC: Basic Application Library JSoN (baljsn):

Description:: The baljsn package provides facilities for encoding and decoding value-semantic objects in the JSON encoding format. Currently, the encoder and decoder provided in this package work with types that support the bdeat framework (see the bdlat package for details), which is a compile-time interface for manipulating struct-like and union-like objects.

Hierarchical Synopsis:

The baljsn package currently has 14 components having 5 levels of physical dependency. The list below shows the hierarchical ordering of the components. The order of components within each level is not architecturally significant, just alphabetical.

  5. baljsn_datumutil
     baljsn_encoder

  4. baljsn_formatter
     baljsn_simpleformatter

  3. baljsn_printutil

  2. baljsn_datumdecoderoptions
     baljsn_datumencoderoptions
     baljsn_decoder
     baljsn_encoderoptions

  1. baljsn_decoderoptions
     baljsn_encoder_testtypes                                         !PRIVATE!
     baljsn_encodingstyle
     baljsn_parserutil
     baljsn_tokenizer

Component Synopsis:

: baljsn_datumdecoderoptions:
Provide options for decoding JSON into a Datum object.

: baljsn_datumencoderoptions:
Provide an attribute class for specifying Datum<->JSON options.

: baljsn_datumutil:
Provide utilities converting between bdld::Datum and JSON data.

: baljsn_decoder:
Provide a JSON decoder for bdeat compatible types.

: baljsn_decoderoptions:
Provide an attribute class for specifying JSON decoding options.

: baljsn_encoder:
Provide a JSON encoder for bdlat-compatible types.

: baljsn_encoder_testtypes: PRIVATE
Provide value-semantic attribute classes

: baljsn_encoderoptions:
Provide an attribute class for specifying JSON encoding options.

: baljsn_encodingstyle:
Provide value-semantic attribute classes.

: baljsn_formatter:
Provide a formatter for encoding data in the JSON format.

: baljsn_parserutil:
Provide a utility for decoding JSON data into simple types.

: baljsn_printutil:
Provide a utility for encoding simple types in the JSON format.

: baljsn_simpleformatter:
Provide a simple formatter for encoding data in the JSON format.

: baljsn_tokenizer:
Provide a tokenizer for extracting JSON data from a streambuf.

Encoding Format:

: The following table provides a mapping between an element's bdem elem type (as specified in bdem_elemtype), its XSD type, its C++ type, its corresponding JSON type, and the encoding used.

BDEM type         XSD type      C++ Type         JSON type       Format
---------         --------      --------         ---------       ------
BDEM_VOID         N/A           N/A              null            Encoding error

BDEM_BOOL         boolean       bool             true/false      <BOOLEAN>

BDEM_CHAR         byte          char             number          <NUMBER>

BDEM_SHORT        short         short            number          <NUMBER>

                  unsignedByte  unsigned char    number          <NUMBER>

BDEM_INT          int           int              number          <NUMBER>

                  unsignedShort unsigned short   number          <NUMBER>

BDEM_INT64        integer       Int64            number          <NUMBER>

                  long          Int64            number          <NUMBER>

                  unsignedInt   unsigned int     number          <NUMBER>

                  unsignedLong  unsigned Uint64  number          <NUMBER>

BDEM_FLOAT        float         float            number/string   <DOUBLE>

BDEM_DOUBLE       decimal       double           number/string   <DOUBLE>

                  double        double           number/string   <DOUBLE>

BDEM_STRING       string        bsl::string      string          <STRING>

BDEM_DATETIME     dateTime      bdlt::Datetime   string          "<DATETIME>"

BDEM_DATETIMETZ   dateTime      bdlt::DatetimeTz string          "<DATETIMETZ>"

BDEM_DATE         date          bdlt::Date       string          "<DATE>"

BDEM_DATETZ       date          bdlt::DateTz     string          "<DATETZ>"

BDEM_TIME         time          bdlt::Time       string          "<TIME>"

BDEM_TIMETZ       time          bdlt::TimeTz     string          "<TIMETZ>"

BDEM_CHAR_ARRAY   base64Binary  vector<char>     string          "<BASE64STR>"

                  hexBinary     vector<char>     string          "<BASE64STR>"

BDEM_TYPE_ARRAY   maxOccurs > 1 vector<TYPE>     array           <SIMPLE_ARRAY>

BDEM_LIST         sequence      bcem_Aggregate   object          <SEQUENCE>

BDEM_TABLE        maxOccurs > 1 bcem_Aggregate   array of objs   <SEQ_ARRAY>

BDEM_CHOICE       choice        bcem_Aggregate   object          <CHOICE>

BDEM_CHOICE_ARRAY maxOccurs > 1 bcem_Aggregate   array of objs   <CHOICE_ARRAY>

BDEM_INT/STRING   enumeration   C++ enumeration  string          <STRING>

BDEM_*            minOccurs = 0 NullableValue    null            <NULL_VALUE>

* The exact syntax of the format is specified below.

: * BDEM_TYPE_ARRAY refers to all the types supported by bdem (such as BDEM_INT_ARRAY, BDEM_STRING_ARRAY etc) including BDEM_CHAR_ARRAY. A vector<char> that is not specified with the xs:base64Binary or xs:hexBinary is treated similarly to vector of any scalar type. Vectors of nullable scalar types (specified via the xs:nillable attribute) are encoded similar to their vector of non-nullable scalar types except that their elements could also be specified as null.

: The format grammar specified below uses the Extended BNF notation (except that , is not used for concatenation to enhance readability). A quick reference of EBNF is provided below (refer here for more details):

|       is used to select between alternate options
[ ... ] (square brackets) are used to specify an optional item
{ ... } (curly brackets) are used to specify an item that can be repeated zero
         or more times
( ... ) (parenthesis) are used to group elements

<VOID>            Results in an encoding error

<BOOLEAN>         'true' | 'false';

<STRING>          Same as the spec for 'string' on http://www.json.org;

<NUMBER>          Same as the spec for 'number' on http://www.json.org;

<DOUBLE_STRING>   "NaN" | "+INF" | "-INF";

<DOUBLE>          <NUMBER> | <DOUBLE_STRING>; (1)

<DATE>            <YEAR>'-'<MONTH>'-'<DAY>; (2)

<DATETZ>          <DATE><TZ>;

<TIME>            <HOUR>':'<MINUTES>':'<SECONDS>[<MILLISEC>]; (2)

<TIMETZ>          <TIME><TZ>;

<DATETIME>        <DATE>'T'<TIME>; (2)

<DATETIMETZ>      <DATETIME><TZ>;

<BASE64STR>       Strings encoded in base 64 encoding;

<SEQUENCE>        '{' '}' | '{' <MEMBER> {',' <MEMBER> } '}';

<CHOICE>          '{' <MEMBER> '}';

<SIMPLE_ARRAY>    '[' ']' | '[' <VALUE> {',' <VALUE> } ']';

<SEQ_ARRAY>       '[' ']' | '[' <SEQUENCE> {',' <SEQUENCE> } ']';

<CHOICE_ARRAY>    '[' ']' | '[' <CHOICE> {',' <CHOICE> } ']';

<NULL>            'null';

<NULL_VALUE>      <NULL> | ''; (3)

<NAME>            <STRING>; (4)

<SIMPLE>          <NUMBER> | <STRING> | '"' <DATE> '"' | '"' <DATETZ> '"'
                           | '"' <TIME> '"' | '"' <TIMETZ> '"'
                           | '"' <DATETIME> '"' | '"' <DATETIMETZ> '"'
                           | '"' <BASE64STR> '"';

<VALUE>           <NULL> | <SIMPLE> | <SEQUENCE> | <CHOICE> | <SIMPLE_ARRAY>
                         | <COMPLEX_ARRAY>;

<MEMBER>          <NAME>':'<VALUE>;

<SIGN>            '+' | '-';

<POSITIVE_DIGIT>  '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';

<DIGIT>           '0' | <POSITIVE_DIGIT>;

<YEAR>            <DIGIT><DIGIT><DIGIT><POSITIVE_DIGIT>;

<MONTH>           '0' <POSITIVE_DIGIT> | '1' ( '0' | '1' | '2' );

<DAY>             ( '0' | '1' | '2' ) <POSITIVE_DIGIT> | '3' ( '0' | '1' );

<HOUR>            ( '0' | '1' ) <DIGIT> | '2' ( '0' | '1' | '2' | '3');

<MINUTES>         ( '0' | '1' | '2' | '3' | '4' | '5' ) <DIGIT>;

<SECONDS>         ( '0' | '1' | '2' | '3' | '4' | '5' ) <DIGIT>;

<MILLISEC>        '.' <DIGIT> { <DIGIT> };

<TZ>              <SIGN><HOUR>':'<MINUTES> | 'Z' | 'z';

: (1) Double types (float, decimal, and double) are encoded in the number format by default with the values NaN, +INF and -INF resulting in an encoding error. These values can be printed as strings by setting the encodeInfAndNaNAsStrings encoder option to true.

: (2) In practice only the timezone-enabled components are used by bcem_Aggregate and generated types. The supported format is a subset of the ISO 8601 standard. For further details refer to the bdepu_iso8601 component.

: (3) Null values are not encoded on the wire by default. The encodeNullElements options can be set to true to ensure that null values are encoded.

: (4) The name of an element corresponds to that element's name in the provided xsd.

validateInputIsUtf8 Option:: The baljsn::DecoderOption parameter of the decode function has a configuration option named validateInputIsUtf8. If this option is true, the decode function will succeed only if the encoding of the JSON data is UTF-8, which the JSON specification requires. If the option is false, decode will not validate that the encoding of the JSON data is UTF-8, and may succeed even if the data does not satisfy the UTF-8 validity requirement of the JSON specification. This option primarily affects the acceptance of string literals, which are the parts of JSON documents that may have rational justification for having non-UTF-8, and therefore invalid, content.

: Ideally, users should set validateInputIsUtf8 to true. However, some legacy applications currently might be trafficking in JSON that contains non-UTF-8 with no adverse effects to their clients. Consequently, this option is false by default to maintain backward compatibility.

Package baljsn [Package Group bal]

Components

Detailed Description

Package baljsn
[Package Group bal]