baljsn_decoderoptionsutil.h

Go to the documentation of this file.

/// @file baljsn_decoderoptionsutil.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// baljsn_decoderoptionsutil.h                                        -*-C++-*-
#ifndef INCLUDED_BALJSN_DECODEROPTIONSUTIL
#define INCLUDED_BALJSN_DECODEROPTIONSUTIL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup baljsn_decoderoptionsutil baljsn_decoderoptionsutil
/// @brief  Provide a utility for configuring `baljsn::DecoderOptions`.
/// @addtogroup bal
/// @{
/// @addtogroup baljsn
/// @{
/// @addtogroup baljsn_decoderoptionsutil
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#baljsn_decoderoptionsutil-purpose"> Purpose</a>
/// * <a href="#baljsn_decoderoptionsutil-classes"> Classes </a>
/// * <a href="#baljsn_decoderoptionsutil-description"> Description </a>
///   * <a href="#baljsn_decoderoptionsutil-modes"> Modes </a>
///   * <a href="#baljsn_decoderoptionsutil-usage"> Usage </a>
///     * <a href="#baljsn_decoderoptionsutil-example-1-setting-baljsn-decoderoptions-for-strictness"> Example 1: Setting baljsn::DecoderOptions for Strictness </a>
///
/// # Purpose {#baljsn_decoderoptionsutil-purpose}
/// Provide a utility for configuring `baljsn::DecoderOptions`.
///
/// # Classes {#baljsn_decoderoptionsutil-classes}
///
/// -  baljsn::DecoderOptionsUtil: utility for setting `baljsn::DecoderOptions`
///
/// @see  baljsn_decoder, baljsn_decoderoptions
///
/// # Description {#baljsn_decoderoptionsutil-description}
/// This component provides a `struct` of utility functions,
/// `baljsn::DecoderOptionsUtil`, for configuring `baljsn::DecoderOptions`
/// object.  In particular, this utility can be used to set the combination of
/// options needed for strict compliance with the JSON grammar (see
/// @ref baljsn_decoder-strict-conformance ).  This utility can also be used to
/// set a `baljsn::DecoderOptions` object to its default state.
///
/// ## Modes {#baljsn_decoderoptionsutil-modes}
///
///
/// When a default constructed `baljsn::DecoderOptions` object is passed to the
/// `decode` methods of a `baljsn::Decoder`, several convenient variances from
/// the JSON grammar are tolerated in the JSON document without causing failure.
/// Specifically:
/// @code
/// validateInputIsUtf8              false
/// allowConsecutiveSeparators       true
/// allowFormFeedAsWhitespace        true
/// allowUnescapedControlCharacters  true
/// @endcode
/// See @ref baljsn_decoderoptions-attributes  for examples.  Should any of these
/// variances be unacceptable, then one can flip individual options.  Strict
/// compliance (see @ref bdljsn_jsontestsuiteutil ) with the JSON grammar requires
/// that each option named above be flipped to the opposite value:
/// @code
/// validateInputIsUtf8              true
/// allowConsecutiveSeparators       false
/// allowFormFeedAsWhitespace        false
/// allowUnescapedControlCharacters  false
/// @endcode
/// This utility defines the mode
/// `baljsn::DecoderOptionsUtil::e_STRICT_20240423` to allow all four options to
/// be set with a single call.
///
/// Note that `baljsn::DecoderOptions` defines other options besides the four
/// cited above.  Those are *not* changed by setting the
/// `baljsn::DecoderOptionsUtil::e_STRICT_20240423` combination but are set when
/// setting the options object using `baljsn::DecoderOptionsUtil::e_DEFAULT`.
///
/// ## Usage {#baljsn_decoderoptionsutil-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Setting baljsn::DecoderOptions for Strictness {#baljsn_decoderoptionsutil-example-1-setting-baljsn-decoderoptions-for-strictness}
///
///
/// Every call to one of the (non-deprecated) `decode` functions of
/// `baljsn::Decoder` requires the user to provide a `baljsn::DecoderOptions`
/// object that allows the user to fine-tune the rules used when decoding the
/// JSON document.  The `setMode` function of this utility provides a convenient
/// way to set the option attributes to a combination that is deemed "strict"
/// (i.e., strictly complying with the rules of the JSON grammar).
///
/// First, create a `baljsn::DecoderOptions` object:
/// @code
/// baljsn::DecoderOptions options;
/// @endcode
/// Now, set the option values for strict compliance:
/// @code
/// baljsn::DecoderOptionsUtil::setMode(
///                             &options,
///                             baljsn::DecoderOptionsUtil::e_STRICT_20240423);
/// @endcode
/// Finally, should there be a need, `options` can be adjusted to a laxer set of
/// rules by adjusting individual attributes or, if the original set of default
/// attributes is needed, by using `setMode`:
/// @code
/// baljsn::DecoderOptionsUtil::setMode(&options,
///                                     baljsn::DecoderOptionsUtil::e_DEFAULT);
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup baljsn
 * @{
 */
/** @addtogroup baljsn_decoderoptionsutil
 * @{
 */
 
#include <balscm_version.h>
 
 
namespace baljsn {
 
class DecoderOptions;
 
                              // ========================
                              // class DecoderOptionsUtil
                              // ========================
 
/// This `struct` provides a namespace for functions that set
/// `DecoderOptions` to particular configurations.
///
/// See @ref baljsn_decoderoptionsutil 
struct DecoderOptionsUtil {
 
  public:
    // TYPES
    enum Mode {
        e_DEFAULT         = 0  // set to default state
      , e_STRICT_20240423 = 1  // set for strictness conformance per 2024-04-23
    };
 
    // CLASS METHODS
 
    /// Set the attributes of the specified `options` to the configuration
    /// associated with the specified `mode`.  See {Modes} for details.
    static void setMode(DecoderOptions *options, Mode mode);
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2024 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */