baljsn_decoderoptionsutil

Detailed Description

Provide a utility for configuring baljsn::DecoderOptions.

Outline

• Purpose
• Classes
• Description
  • Modes
  • Usage
    • Example 1: Setting baljsn::DecoderOptions for Strictness

Purpose

Provide a utility for configuring baljsn::DecoderOptions.

Classes

• baljsn::DecoderOptionsUtil: utility for setting baljsn::DecoderOptions

See also

baljsn_decoder, baljsn_decoderoptions

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 Strict Conformance ). This utility can also be used to set a baljsn::DecoderOptions object to its default state.

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:

validateInputIsUtf8              false
allowConsecutiveSeparators       true
allowFormFeedAsWhitespace        true
allowUnescapedControlCharacters  true

See Attributes for examples. Should any of these variances be unacceptable, then one can flip individual options. Strict compliance (see bdljsn_jsontestsuiteutil ) with the JSON grammar requires that each option named above be flipped to the opposite value:

validateInputIsUtf8              true
allowConsecutiveSeparators       false
allowFormFeedAsWhitespace        false
allowUnescapedControlCharacters  false

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

This section illustrates intended use of this component.

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:

baljsn::DecoderOptions options;

Now, set the option values for strict compliance:

baljsn::DecoderOptionsUtil::setMode(
                            &options,
                            baljsn::DecoderOptionsUtil::e_STRICT_20240423);

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:

baljsn::DecoderOptionsUtil::setMode(&options,
                                    baljsn::DecoderOptionsUtil::e_DEFAULT);