folly::DynamicParser Class Reference

#include <DynamicParser.h>

Classes
struct	ParserStack

Public Types
enum	OnError { OnError::RECORD, OnError::THROW }

Public Member Functions
	DynamicParser (OnError on_error, const folly::dynamic *d)
folly::dynamic	releaseErrors ()
template<typename Fn >
void	optional (const folly::dynamic &key, Fn)
template<typename Fn >
void	required (const folly::dynamic &key, Fn)
template<typename Fn >
void	objectItems (Fn)
template<typename Fn >
void	arrayItems (Fn)
const folly::dynamic &	key () const
const folly::dynamic &	value () const
DynamicParser &	setAllowNonStringKeyErrors (bool b)

Private Member Functions
template<typename Fn >
void	wrapError (const folly::dynamic *lookup_key, Fn)
void	reportError (const folly::dynamic *lookup_k, const std::exception &ex)
template<typename Fn >
void	parse (const folly::dynamic &key, const folly::dynamic &value, Fn fn)

Private Attributes
OnError	onError_
ParserStack	stack_
bool	allowNonStringKeyErrors_ {false}

Detailed Description

Definition at line 229 of file DynamicParser.h.

Member Enumeration Documentation

enum folly::DynamicParser::OnError

strong

Enumerator
RECORD
THROW

Definition at line 231 of file DynamicParser.h.

                     {
    // After parsing, releaseErrors() reports all parse errors.
    // Throws DynamicParserLogicError on programmer errors.
    RECORD,
    // Throws DynamicParserParseError on the first parse error, or
    // DynamicParserLogicError on programmer errors.
    THROW,
  };

Constructor & Destructor Documentation

folly::DynamicParser::DynamicParser ( OnError  on_error, const folly::dynamic *  d  )

inline

Definition at line 241 of file DynamicParser.h.

      : onError_(on_error), stack_(d) {} // Always access input through stack_

Member Function Documentation

template<typename Fn >

void folly::DynamicParser::arrayItems

(

Fn

fn

)

Like objectItems() – arrays are treated identically to objects with integer keys from 0 to size() - 1.

Definition at line 280 of file DynamicParser-inl.h.

References i, parse(), and folly::value().

Referenced by TEST().

                                    {
  wrapError(nullptr, [&]() {
    size_t i = 0;
    for (const auto& v : value()) { // Iteration can throw
      parse(i, v, fn); // i => dynamic cannot throw
      ++i;
    }
  });
}

const folly::dynamic& folly::DynamicParser::key ( ) const

inline

The key currently being parsed (integer if inside an array). Throws if called outside of a parser callback.

Definition at line 283 of file DynamicParser.h.

References stack_.

Referenced by TEST().

                                         {
    return stack_.key();
  }

template<typename Fn >

void folly::DynamicParser::objectItems

(

Fn

fn

)

Iterate over the current object's keys and values. Report each item's errors under its own key in a matching sub-object of "errors".

Definition at line 271 of file DynamicParser-inl.h.

References parse(), and folly::value().

Referenced by TEST().

                                     {
  wrapError(nullptr, [&]() {
    for (const auto& kv : value().items()) { // .items() can throw
      parse(kv.first, kv.second, fn);
    }
  });
}

template<typename Fn >

void folly::DynamicParser::optional	(	const folly::dynamic &	key,
		Fn	fn
	)

Error-wraps fn(auto-converted key & value) if d[key] is set. The top-of-file docblock explains the auto-conversion.

Definition at line 244 of file DynamicParser-inl.h.

References folly::get_ptr(), parse(), and folly::value().

Referenced by TEST().

                                                           {
  wrapError(&key, [&]() {
    if (auto vp = value().get_ptr(key)) {
      parse(key, *vp, fn);
    }
  });
}

template<typename Fn >

void folly::DynamicParser::parse ( const folly::dynamic &  key, const folly::dynamic &  value, Fn  fn  )

private

Definition at line 307 of file DynamicParser-inl.h.

References folly::gen::guard(), folly::detail::invokeForKeyValue(), and stack_.

           {
  auto guard = stack_.push(k, v); // User code can nest parser calls.
  wrapError(nullptr, [&]() { detail::invokeForKeyValue(fn, k, v); });
}

folly::dynamic folly::DynamicParser::releaseErrors ( )

inline

Once you finished the entire parse, returns a structured description of all parse errors (see top-of-file docblock). May ONLY be called once. May NOT be called if the parse threw any kind of exception. Returns an empty object for successful OnError::THROW parsers.

Definition at line 250 of file DynamicParser.h.

References stack_.

Referenced by checkItemParseError(), checkMaybeCoercedKeys(), checkXYKeyErrorsAndParseError(), and TEST().

                               {
    return stack_.releaseErrors();
  }

void folly::DynamicParser::reportError ( const folly::dynamic *  lookup_k, const std::exception &  ex  )

private

Definition at line 53 of file DynamicParser.cpp.

References allowNonStringKeyErrors_, folly::DynamicParser::ParserStack::errors(), folly::FATAL, folly::dynamic::object(), onError_, RECORD, stack_, THROW, folly::DynamicParser::ParserStack::throwErrors(), folly::detail::toPseudoJson(), and value().

                            {
  // If descendants of this item, or other keys on it, already reported an
  // error, the error object would already exist.
  auto& e = stack_.errors(allowNonStringKeyErrors_);

  // Save the original, unparseable value of the item causing the error.
  //
  // value() can throw here, but if it does, it is due to programmer error,
  // so we don't want to report it as a parse error anyway.
  if (auto* e_val_ptr = e.get_ptr("value")) {
    // Failing to access distinct keys on the same value can generate
    // multiple errors, but the value should remain the same.
    if (*e_val_ptr != value()) {
      throw DynamicParserLogicError(
          "Overwriting value: ",
          detail::toPseudoJson(*e_val_ptr),
          " with ",
          detail::toPseudoJson(value()),
          " for error ",
          ex.what());
    }
  } else {
    // The e["value"].isNull() trick cannot be used because value().type()
    // *can* be folly::dynamic::Type::NULLT, so we must hash again.
    e["value"] = value();
  }

  // Differentiate between "parsing value" and "looking up key" errors.
  auto& e_msg = [&]() -> folly::dynamic& {
    if (lookup_k == nullptr) { // {object,array}Items, or post-key-lookup
      return e["error"];
    }
    // Multiple key lookups can report errors on the same collection.
    auto& key_errors = e["key_errors"];
    if (key_errors.isNull()) {
      // Treat arrays as integer-keyed objects.
      key_errors = folly::dynamic::object();
    }
    return insertAtKey(&key_errors, allowNonStringKeyErrors_, *lookup_k);
  }();
  if (!e_msg.isNull()) {
    throw DynamicParserLogicError(
        "Overwriting error: ",
        detail::toPseudoJson(e_msg),
        " with: ",
        ex.what());
  }
  e_msg = ex.what();

  switch (onError_) {
    case OnError::RECORD:
      break; // Continue parsing
    case OnError::THROW:
      stack_.throwErrors(); // Package releaseErrors() into an exception.
    default:
      LOG(FATAL) << "Bad onError_: " << static_cast<int>(onError_);
  }
}

template<typename Fn >

void folly::DynamicParser::required	(	const folly::dynamic &	key,
		Fn	fn
	)

Definition at line 257 of file DynamicParser-inl.h.

References parse(), folly::detail::toPseudoJson(), and folly::value().

Referenced by checkMaybeCoercedKeys(), and TEST().

                                                           {
  wrapError(&key, [&]() {
    auto vp = value().get_ptr(key);
    if (!vp) {
      throw std::runtime_error(folly::to<std::string>(
          "Couldn't find key ",
          detail::toPseudoJson(key),
          " in dynamic object"));
    }
    parse(key, *vp, fn);
  });
}

DynamicParser& folly::DynamicParser::setAllowNonStringKeyErrors ( bool  b )

inline

By default, DynamicParser's "nested" object coerces all keys to strings, whether from arrayItems() or from p.optional(some_int, ...), to allow errors be serialized to JSON. If you are parsing non-JSON dynamic objects with non-string keys, this is problematic. When set to true, "nested" objects will report integer keys for errors coming from inside arrays, or the original key type from inside values of objects.

Definition at line 302 of file DynamicParser.h.

References b, parse(), and folly::value().

Referenced by checkMaybeCoercedKeys().

                                                    {
    allowNonStringKeyErrors_ = b;
    return *this;
  }

const folly::dynamic& folly::DynamicParser::value ( ) const

inline

The value currently being parsed (initially, the input dynamic). Throws if parsing nullptr, or parsing after releaseErrors().

Definition at line 290 of file DynamicParser.h.

References stack_.

Referenced by reportError(), and TEST().

                                           {
    return stack_.value();
  }

template<typename Fn >

void folly::DynamicParser::wrapError ( const folly::dynamic *  lookup_key, Fn  fn  )

private

If fn throws an exception, wrapError() catches it and inserts an enriched description into stack_.errors_. If lookup_key is non-null, reports a key lookup error in "key_errors", otherwise reportse a value error in "error".

Not public because that would encourage users to report multiple errors per input part, which is currently unsupported. It does not currently seem like normal user code should need this.

Definition at line 291 of file DynamicParser-inl.h.

                                                                 {
  try {
    fn();
  } catch (DynamicParserLogicError&) {
    // When the parser is misused, we throw all the way up to the user,
    // instead of reporting it as if the input is invalid.
    throw;
  } catch (DynamicParserParseError&) {
    // We are just bubbling up a parse error for OnError::THROW.
    throw;
  } catch (const std::exception& ex) {
    reportError(lookup_k, ex);
  }
}

Member Data Documentation

bool folly::DynamicParser::allowNonStringKeyErrors_ {false}

private

Definition at line 408 of file DynamicParser.h.

Referenced by reportError().

OnError folly::DynamicParser::onError_

private

Definition at line 406 of file DynamicParser.h.

Referenced by reportError().

ParserStack folly::DynamicParser::stack_

private

Definition at line 407 of file DynamicParser.h.

Referenced by reportError().

---

The documentation for this class was generated from the following files:

• proxygen/folly/folly/experimental/DynamicParser.h
• proxygen/folly/folly/experimental/DynamicParser-inl.h
• proxygen/folly/folly/experimental/DynamicParser.cpp