DynamicParser.h

Go to the documentation of this file.

/*
 * Copyright 2016-present Facebook, Inc.
 *
 * 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.
 */
/*
 *  Copyright (c) 2015, Facebook, Inc.
 *  All rights reserved.
 *
 *  This source code is licensed under the BSD-style license found in the
 *  LICENSE file in the root directory of this source tree. An additional grant
 *  of patent rights can be found in the PATENTS file in the same directory.
 *
 */
#pragma once

#include <folly/CPortability.h>
#include <folly/ScopeGuard.h>
#include <folly/dynamic.h>

namespace folly {

namespace detail {
// Why do DynamicParser error messages use folly::dynamic pseudo-JSON?
// Firstly, the input dynamic need not correspond to valid JSON.  Secondly,
// wrapError() uses integer-keyed objects to report arrary-indexing errors.
std::string toPseudoJson(const folly::dynamic& d);
} // namespace detail

struct FOLLY_EXPORT DynamicParserParseError : public std::runtime_error {
  explicit DynamicParserParseError(folly::dynamic error)
      : std::runtime_error(folly::to<std::string>(
            "DynamicParserParseError: ",
            detail::toPseudoJson(error))),
        error_(std::move(error)) {}
  const folly::dynamic& error() const {
    return error_;
  }

 private:
  folly::dynamic error_;
};

struct FOLLY_EXPORT DynamicParserLogicError : public std::logic_error {
  template <typename... Args>
  explicit DynamicParserLogicError(Args&&... args)
      : std::logic_error(folly::to<std::string>(std::forward<Args>(args)...)) {}
};

class DynamicParser {
 public:
  enum class OnError {
    // 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,
  };

  // You MUST NOT destroy `d` before the parser.
  DynamicParser(OnError on_error, const folly::dynamic* d)
      : onError_(on_error), stack_(d) {} // Always access input through stack_

  folly::dynamic releaseErrors() {
    return stack_.releaseErrors();
  }

  template <typename Fn>
  void optional(const folly::dynamic& key, Fn);

  // Like optional(), but reports an error if d[key] does not exist.
  template <typename Fn>
  void required(const folly::dynamic& key, Fn);

  template <typename Fn>
  void objectItems(Fn);

  template <typename Fn>
  void arrayItems(Fn);

  inline const folly::dynamic& key() const {
    return stack_.key();
  }
  inline const folly::dynamic& value() const {
    return stack_.value();
  }

  DynamicParser& setAllowNonStringKeyErrors(bool b) {
    allowNonStringKeyErrors_ = b;
    return *this;
  }

 private:
  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);

  // All of the above business logic obtains the part of the folly::dynamic
  // it is examining (and the location for reporting errors) via this class,
  // which lets it correctly handle nesting.
  struct ParserStack {
    struct Pop {
      explicit Pop(ParserStack* sp)
          : key_(sp->key_), value_(sp->value_), stackPtr_(sp) {}
      void operator()() noexcept; // ScopeGuard requires noexcept
     private:
      const folly::dynamic* key_;
      const folly::dynamic* value_;
      ParserStack* stackPtr_;
    };
    struct PopGuard {
      explicit PopGuard(ParserStack* sp) : pop_(in_place, sp) {}
      ~PopGuard() {
        pop_ && ((*pop_)(), true);
      }

     private:
      Optional<Pop> pop_;
    };

    explicit ParserStack(const folly::dynamic* input)
        : value_(input),
          errors_(folly::dynamic::object()),
          subErrors_({&errors_}) {}

    // Not copiable or movable due to numerous internal pointers
    ParserStack(const ParserStack&) = delete;
    ParserStack& operator=(const ParserStack&) = delete;
    ParserStack(ParserStack&&) = delete;
    ParserStack& operator=(ParserStack&&) = delete;

    // Lets user code nest parser calls by recording current key+value and
    // returning an RAII guard to restore the old one.  `noexcept` since it
    // is used unwrapped.
    PopGuard push(const folly::dynamic& k, const folly::dynamic& v) noexcept;

    // Throws DynamicParserLogicError if used outside of a parsing function.
    inline const folly::dynamic& key() const;
    // Throws DynamicParserLogicError if used after releaseErrors().
    inline const folly::dynamic& value() const;

    // Lazily creates new "nested" sub-objects in errors_.
    folly::dynamic& errors(bool allow_non_string_keys) noexcept;

    // The user invokes this at most once after the parse is done.
    folly::dynamic releaseErrors();

    // Invoked on error when using OnError::THROW.
    [[noreturn]] void throwErrors();

   private:
    friend struct Pop;

    folly::dynamic releaseErrorsImpl(); // for releaseErrors() & throwErrors()

    // Null outside of a parsing function.
    const folly::dynamic* key_{nullptr};
    // Null on errors: when the input was nullptr, or after releaseErrors().
    const folly::dynamic* value_;

    // An object containing some of these keys:
    //   "key_errors" -- {"key": "description of error looking up said key"}
    //   "error" -- why did we fail to parse this value?
    //   "value" -- a copy of the input causing the error, and
    //   "nested" -- {"key" or integer for arrays: <another errors_ object>}
    //
    // "nested" will contain identically structured objects with keys (array
    // indices) identifying the origin of the errors.  Of course, "input"
    // would no longer refer to the whole input, but to a part.
    folly::dynamic errors_;
    // We only materialize errors_ sub-objects when needed. This stores keys
    // for unmaterialized errors, from outermost to innermost.
    std::vector<const folly::dynamic*> unmaterializedSubErrorKeys_;
    // Materialized errors, from outermost to innermost
    std::vector<folly::dynamic*> subErrors_; // Point into errors_
  };

  OnError onError_;
  ParserStack stack_;
  bool allowNonStringKeyErrors_{false}; // See the setter's docblock.
};

} // namespace folly

#include <folly/experimental/DynamicParser-inl.h>