jsonpointer.h

#ifndef SOURCEMETA_CORE_JSONPOINTER_H_
#define SOURCEMETA_CORE_JSONPOINTER_H_
 
#ifndef SOURCEMETA_CORE_JSONPOINTER_EXPORT
#include <sourcemeta/core/jsonpointer_export.h>
#endif
 
#include <sourcemeta/core/json.h>
#include <sourcemeta/core/uri.h>
 
// NOLINTBEGIN(misc-include-cleaner)
#include <sourcemeta/core/jsonpointer_error.h>
#include <sourcemeta/core/jsonpointer_pointer.h>
#include <sourcemeta/core/jsonpointer_position.h>
#include <sourcemeta/core/jsonpointer_walker.h>
// NOLINTEND(misc-include-cleaner)
 
#include <cassert>     // assert
#include <functional>  // std::reference_wrapper
#include <memory>      // std::allocator
#include <optional>    // std::optional
#include <ostream>     // std::basic_ostream
#include <string>      // std::basic_string
#include <string_view> // std::string_view

 
namespace sourcemeta::core {

using Pointer = GenericPointer<JSON::String, PropertyHashJSON<JSON::String>>;

using WeakPointer = GenericPointer<
    // We use this instead of a string view as the latter occupies more memory
    std::reference_wrapper<const std::string>, PropertyHashJSON<JSON::String>>;

const Pointer empty_pointer;

const WeakPointer empty_weak_pointer;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto get(const JSON &document, const Pointer &pointer) -> const JSON &;
 
// Constant reference parameters can accept xvalues which will be destructed
// after the call. When the function returns such a parameter also as constant
// reference, then the returned reference can be used after the object it refers
// to has been destroyed.
// https://clang.llvm.org/extra/clang-tidy/checks/bugprone/return-const-ref-from-parameter.html
// This overload avoids mis-uses of retuning const reference parameter as
// constant reference.
auto get(JSON &&document, const Pointer &pointer) -> const JSON & = delete;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto get(const JSON &document, const WeakPointer &pointer) -> const JSON &;
 
// Constant reference parameters can accept xvalues which will be destructed
// after the call. When the function returns such a parameter also as constant
// reference, then the returned reference can be used after the object it refers
// to has been destroyed.
// https://clang.llvm.org/extra/clang-tidy/checks/bugprone/return-const-ref-from-parameter.html
// This overload avoids mis-uses of retuning const reference parameter as
// constant reference.
auto get(JSON &&document, const WeakPointer &pointer) -> const JSON & = delete;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto get(JSON &document, const WeakPointer &pointer) -> JSON &;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto try_get(const JSON &document, const Pointer &pointer) -> const JSON *;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto try_get(const JSON &document, const WeakPointer &pointer) -> const JSON *;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto get(JSON &document, const Pointer &pointer) -> JSON &;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto get(const JSON &document, const Pointer::Token &token) -> const JSON &;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto get(const JSON &document, const WeakPointer::Token &token) -> const JSON &;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto get(JSON &document, const Pointer::Token &token) -> JSON &;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto set(JSON &document, const Pointer &pointer, const JSON &value) -> void;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto set(JSON &document, const Pointer &pointer, JSON &&value) -> void;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto remove(JSON &document, const Pointer &pointer) -> bool;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto remove(JSON &document, const WeakPointer &pointer) -> bool;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_pointer(const JSON &document) -> Pointer;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_pointer(
    const std::basic_string_view<JSON::Char, JSON::CharTraits> input)
    -> Pointer;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto fragment_to_pointer(const URI &uri) -> std::optional<Pointer>;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_pointer(const WeakPointer &pointer) -> Pointer;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto is_pointer(std::string_view input) noexcept -> bool;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto is_relative_pointer(std::string_view input) noexcept -> bool;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_weak_pointer(const Pointer &pointer) -> WeakPointer;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto stringify(const Pointer &pointer,
               std::basic_ostream<JSON::Char, JSON::CharTraits> &stream)
    -> void;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto stringify(const WeakPointer &pointer,
               std::basic_ostream<JSON::Char, JSON::CharTraits> &stream)
    -> void;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_string(const Pointer &pointer)
    -> std::basic_string<JSON::Char, JSON::CharTraits,
                         std::allocator<JSON::Char>>;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_string(const WeakPointer &pointer)
    -> std::basic_string<JSON::Char, JSON::CharTraits,
                         std::allocator<JSON::Char>>;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_uri(const Pointer &pointer) -> URI;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_uri(const Pointer &pointer, const URI &base) -> URI;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_uri(const WeakPointer &pointer) -> URI;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_uri(const WeakPointer &pointer, const URI &base) -> URI;

SOURCEMETA_CORE_JSONPOINTER_EXPORT
auto to_uri(const WeakPointer &pointer, const std::string_view base) -> URI;

using PointerWalker = GenericPointerWalker<WeakPointer>;
 
} // namespace sourcemeta::core
 
#endif