balxml.h

Go to the documentation of this file.

/// @file balxml.h
///
///
/// @defgroup balxml Package balxml
/// @brief  Basic Application Library XML (balxml)
/// @addtogroup bal
/// @{
/// @addtogroup balxml
/// @{
/// * <a href="#balxml-purpose"> Purpose</a>
/// * <a href="#balxml-mnemonic"> Mnemonic </a>
/// * <a href="#balxml-description"> Description </a>
///   * <a href="#balxml-code-generation"> Code Generation </a>
///   * <a href="#balxml-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#balxml-component-synopsis"> Component Synopsis </a>
///
/// # Purpose {#balxml-purpose}
/// Provide utility components for using XML and XSD.
///
/// # Mnemonic {#balxml-mnemonic}
/// Basic Application Library XML (balxml)
///
/// @see  a_xercesc, a_xml2
///
/// # Description {#balxml-description}
/// The `balxml` package provides utilities for working with XML and
/// XSD.  Clients can use the components provided by `balxml` for parsing and
/// printing fundamental types, XML schema, and XML data documents.  Typical
/// usage is illustrated in the @ref balxml_encoder  and @ref balxml_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%.
///
/// ## Code Generation {#balxml-code-generation}
///
/// The script 'code_from_xsd.pl' will automatically generate several components
/// from the file 'balxml.xsd'.  It will refuse to run in the 'balxml' source
/// directory.  Create a separate, temporary directory and copy 'balxml.xsd' and
/// 'code_from_xsd.sh' into it, 'cd' into that directory, and run
/// 'code_from_xsd.sh' there will no command-line arguments.
///
/// Note that the @ref balxml_encodingstyle  component will need hand-editing due to
/// redundant, synonymous enum values.
///
/// ## Hierarchical Synopsis {#balxml-hierarchical-synopsis}
///
/// The 'balxml' package currently has 24 components having 6 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
///  6. balxml_decoder
///     balxml_encoder
///
///  5. balxml_formatter
///     balxml_minireader
///     balxml_utf8readerwrapper
///     balxml_validatingreader
///
///  4. balxml_formatter_compactimpl                                     !PRIVATE!
///     balxml_formatter_prettyimpl                                      !PRIVATE!
///     balxml_reader
///     balxml_typesparserutil
///
///  3. balxml_elementattribute
///     balxml_typesprintutil
///
///  2. balxml_encoderoptions
///     balxml_prefixstack
///
///  1. balxml_base64parser                                 !DEPRECATED!
///     balxml_configschema
///     balxml_decoderoptions
///     balxml_encodingstyle
///     balxml_errorinfo
///     balxml_formatterwhitespacetype
///     balxml_hexparser
///     balxml_listparser
///     balxml_namespaceregistry
///     balxml_util
/// @endcode
///
/// ## Component Synopsis {#balxml-component-synopsis}
///
///  @ref balxml_base64parser :                                 !DEPRECATED!
///       Provide push parser for Base64 types.
/// 
///  @ref balxml_configschema :
///       Provide the service configuration schema
/// 
///  @ref balxml_decoder :
///       Provide a generic translation from XML into C++ objects.
/// 
///  @ref balxml_decoderoptions :
///       Provide value-semantic attribute classes
/// 
///  @ref balxml_elementattribute :
///       Provide the properties of an attribute in an XML element tag.
/// 
///  @ref balxml_encoder :
///       Provide an XML encoder utility.
/// 
///  @ref balxml_encoderoptions :
///       Provide value-semantic attribute classes
/// 
///  @ref balxml_encodingstyle :
///       Provide value-semantic attribute classes
/// 
///  @ref balxml_errorinfo :
///       Provide common error information for XML components.
/// 
///  @ref balxml_formatter :
///       Provide a simple interface for writing formatted XML.
/// 
///  @ref balxml_formatter_compactimpl :                                     !PRIVATE!
///       Provide a minimal-whitespace implementation for @ref balxml_formatter .
/// 
///  @ref balxml_formatter_prettyimpl :                                      !PRIVATE!
///       Provide pretty-printing implementation for @ref balxml_formatter .
/// 
///  @ref balxml_formatterwhitespacetype :
///       Enumerate the set of whitespace options for @ref balxml_formatter .
/// 
///  @ref balxml_hexparser :
///       Provide push parser for hex types.
/// 
///  @ref balxml_listparser :
///       Provide push parser for lists.
/// 
///  @ref balxml_minireader :
///       Provide light-weight implementation of `balxml::Reader` protocol.
/// 
///  @ref balxml_namespaceregistry :
///       Provide a unique integer ID for each XML namespace.
/// 
///  @ref balxml_prefixstack :
///       Provide a unique integer ID for each XML namespace.
/// 
///  @ref balxml_reader :
///       Provide common reader protocol for parsing XML documents.
/// 
///  @ref balxml_typesparserutil :
///       Provide a utility for parsing types using XML formatting.
/// 
///  @ref balxml_typesprintutil :
///       Provide a utility for printing types using XML formatting.
/// 
///  @ref balxml_utf8readerwrapper :
///       Provide wrapper for `Reader` to check input UTF-8 validity.
/// 
///  @ref balxml_util :
///       Provide a suite of common XML utilities.
/// 
///  @ref balxml_validatingreader :
///       Provide a common reader protocol for parsing and validating XML.
///
/// @}
/** @} */