Component bdljsn_readoptions [Package bdljsn]

Provide options for reading a JSON document. More...

Namespaces
namespace	bdljsn

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Usage
    • Example 1: Creating and Populating an Options Object

Purpose:

Provide options for reading a JSON document.

Classes:

bdljsn::ReadOptions

options for reading a JSON document

See also:

Component bdljsn_jsonutil, Component bdljsn_json

Description:

This component provides a single, simply constrained (value-semantic) attribute class, bdljsn::ReadOptions, that is used to specify options for reading a JSON document (see bdljsn_jsonutil).

Attributes:

  Name                Type           Default         Simple Constraints
  ------------------  -----------    -------         ------------------
  maxNestedDepth      int            64              > 0
  allowTrailingText   bool           false

• maxNestedDepth: the maximum depth to which JSON objects and arrays are allowed to be nested before the JSON decoder reports an error. For example, if maxNestedDepth is 8, and a JSON text has 9 consecutive open brackets ([) then decoding will return an error. This option can be used to prevent poorly formed (or malicious) JSON text from causing a stack overflow.
• allowTrailingText: whether a read operation will report an error if any non-white space text follows a valid JSON document. By default this option is false, indicating the user expects the input to contain a single valid JSON document (without any subsequent text). When set to true a read operation will return success if there is text following a valid JSON document, assuming that text is separated by a delimeter. See bdljsn_jsonutil for details.

Usage:

This section illustrates intended use of this component.

Example 1: Creating and Populating an Options Object:

This component is designed to be used at a higher level to set the options for decoding Datum objects in the JSON format. This example shows how to create and populate an options object.

First, we default-construct a bdljsn::ReadOptions object:

  const int MAX_NESTED_DEPTH = 16;

  bdljsn::ReadOptions options;
  assert(64    == options.maxNestedDepth());
  assert(false == options.allowTrailingText());

Finally, we populate that object to limit the maximum nested depth using a pre-defined limit:

  options.setMaxNestedDepth(MAX_NESTED_DEPTH);
  assert(MAX_NESTED_DEPTH == options.maxNestedDepth());