baljsn.h

Go to the documentation of this file.

/// @file baljsn.h
///
///
/// @defgroup baljsn Package baljsn
/// @brief  Basic Application Library JSoN (baljsn)
/// @addtogroup bal
/// @{
/// @addtogroup baljsn
/// @{
/// * <a href="#baljsn-purpose"> Purpose</a>
/// * <a href="#baljsn-mnemonic"> Mnemonic </a>
/// * <a href="#baljsn-description"> Description </a>
///   * <a href="#baljsn-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#baljsn-component-synopsis"> Component Synopsis </a>
///   * <a href="#baljsn-encoding-format"> Encoding Format </a>
///   * <a href="#baljsn-validateinputisutf8-option"> validateInputIsUtf8 Option </a>
///
/// # Purpose {#baljsn-purpose}
/// Provide components for encoding/decoding in the JSON format.
///
/// # Mnemonic {#baljsn-mnemonic}
/// Basic Application Library JSoN (baljsn)
///
/// # Description {#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.
/// Typical usage is illustrated in the @ref baljsn_encoder  and @ref baljsn_decoder 
/// components documentation.
///
/// There are 2 sets of the encoding/decoding member functions:
///
/// 1. `encode` & `decode`, and
/// 2. `encodeAny` & `decodeAny` (referred as "any-functions" below).
///
/// The first set uses templates and compile-time metaprogramming to generate the
/// encoding/decoding C++ code.  The second set uses the runtime dispatch
/// approach - base classes and virtual functions - to provide the same
/// functionality.  The result does not depend on the functions you use - their
/// functionality is absolutely identical.  The difference is not in **what**
/// they do, but in **how** they do it.
///
/// As usual, the compile-time approach can be faster, but generates a lot of
/// code.  And since this code is in the headers, this causes big load on the
/// compiler and linker - the generated code is in each translation unit and in
/// the object file generated from it.  As a result, slow compilation, huge
/// memory and CPU consumption during the compilation and linking, and a larger
/// resulting executable file size.
///
/// All the above mentioned shortcomings (except the final runtime performance)
/// can be mitigated by using the "any-functions", at the cost of a small runtime
/// slowdown.  All the encoding/decoding code is pre-compiled and located in one
/// place - the BDE library (archive) files.  But how big is the execution
/// slowdown?  Our benchmarks show that the slowdown is less than 10%.
///
/// ## Hierarchical Synopsis {#baljsn-hierarchical-synopsis}
///
/// The 'baljsn' package currently has 20 components having 8 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.
/// @code
///  8. baljsn_jsonconverter
///
///  7. baljsn_decoder
///
///  6. baljsn_encoder
///
///  5. baljsn_datumutil
///     baljsn_encodeimplutil
///     baljsn_jsonformatter
///     baljsn_jsonparserutil
///
///  4. baljsn_formatter
///     baljsn_parserutil
///     baljsn_simpleformatter
///
///  3. baljsn_printutil
///
///  2. baljsn_datumdecoderoptions
///     baljsn_datumencoderoptions
///     baljsn_decoderoptionsutil
///     baljsn_encoderoptions
///     baljsn_jsontokenizer
///
///  1. baljsn_decoderoptions
///     baljsn_encoder_testtypes                                         !PRIVATE!
///     baljsn_encodingstyle
///     baljsn_tokenizer
/// @endcode
///
/// ## Component Synopsis {#baljsn-component-synopsis}
///
///  @ref baljsn_datumdecoderoptions :
///       Provide options for decoding JSON into a `Datum` object.
/// 
///  @ref baljsn_datumencoderoptions :
///       Provide an attribute class for specifying Datum<->JSON options.
/// 
///  @ref baljsn_datumutil :
///       Provide utilities converting between `bdld::Datum` and JSON data.
/// 
///  @ref baljsn_decoder :
///       Provide a JSON decoder for `bdeat` compatible types.
/// 
///  @ref baljsn_decoderoptions :
///       Provide an attribute class for specifying JSON decoding options.
/// 
///  @ref baljsn_decoderoptionsutil :
///       Provide a utility for configuring `baljsn::DecoderOptions`.
/// 
///  @ref baljsn_encodeimplutil :
///       Provide a utility to encode `bdlat`-compatible types as JSON.
/// 
///  @ref baljsn_encoder :
///       Provide a JSON encoder for `bdlat`-compatible types.
/// 
///  @ref baljsn_encoder_testtypes :                                         !PRIVATE!
///       Provide value-semantic attribute classes
/// 
///  @ref baljsn_encoderoptions :
///       Provide an attribute class for specifying JSON encoding options.
/// 
///  @ref baljsn_encodingstyle :
///       Provide value-semantic attribute classes.
/// 
///  @ref baljsn_formatter :
///       Provide a formatter for encoding data in the JSON format.
/// 
///  @ref baljsn_jsonconverter :
///       Provide conversions between JSON and `bdlat`-compatible types.
/// 
///  @ref baljsn_jsonformatter :
///       Provide a formatter for converting `bdlat` object to `Json` analog.
/// 
///  @ref baljsn_jsonparserutil :
///       Provide a utility to get simple types from `bdl::json` objects
/// 
///  @ref baljsn_jsontokenizer :
///       Provide a tokenizer for viewing parts of a `bdljsn::Json` object.
/// 
///  @ref baljsn_parserutil :
///       Provide a utility for decoding JSON data into simple types.
/// 
///  @ref baljsn_printutil :
///       Provide a utility for encoding simple types in the JSON format.
/// 
///  @ref baljsn_simpleformatter :
///       Provide a simple formatter for encoding data in the JSON format.
/// 
///  @ref baljsn_tokenizer :
///       Provide a tokenizer for extracting JSON data from a `streambuf`.
///
/// ## Encoding Format {#baljsn-encoding-format}
///
///
///The following table provides a mapping between an element's 'bdem' elem type
///(as specified in @ref bdem_elemtype ), its XSD type, its C++ type, its
///corresponding JSON type, and the encoding used.
///
/// @code
///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/string   <NUMBER>
///
///BDEM_SHORT        short         short            number/string   <NUMBER>
///
///                  unsignedByte  unsigned char    number/string   <NUMBER>
///
///BDEM_INT          int           int              number/string   <NUMBER>
///
///                  unsignedShort unsigned short   number/string   <NUMBER>
///
///BDEM_INT64        integer       Int64            number/string   <NUMBER>
///
///                  long          Int64            number/string   <NUMBER>
///
///                  unsignedInt   unsigned int     number/string   <NUMBER>
///
///                  unsignedLong  unsigned Uint64  number/string   <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          enumeration   C++ enumeration  string/number   "<NUMBER>"
///
///BDEM_STRING       enumeration   C++ enumeration  string          <STRING>
///
///BDEM_*            minOccurs = 0 NullableValue    null            <NULL_VALUE>
/// @endcode
///* 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'.
///
///* Integral types are always encoded in the <NUMBER> format and int-valued
///enumerations are always encoded in the "<NUMBER>" format, but during decoding
///both of these formats are supported for both of these categories of types.
///This flexibility applies to all integral types, including ones that do not
///support an enumeration constraint.
///
///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):
///
/// @code
///|       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';
/// @endcode
///
///(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 @ref 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 {#baljsn-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.
///
/// @}
/** @} */