builder.h

Go to the documentation of this file.

// Copyright 2024 The Pigweed Authors
//
// 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
//
//     https://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.
#pragma once
 
 
#include <cstddef>
#include <string_view>
#include <type_traits>
 
#include "pw_assert/assert.h"
#include "pw_json/internal/nesting.h"
#include "pw_span/span.h"
#include "pw_status/status.h"
#include "pw_status/status_with_size.h"
 
namespace pw {
 
 
class [[nodiscard]] NestedJsonArray {
 public:
  NestedJsonArray(const NestedJsonArray&) = delete;
  NestedJsonArray& operator=(const NestedJsonArray&) = delete;
 
  constexpr NestedJsonArray(NestedJsonArray&&) = default;
  constexpr NestedJsonArray& operator=(NestedJsonArray&&) = default;
 
  template <typename T>
  constexpr NestedJsonArray& Append(const T& value);
 
  constexpr NestedJsonArray AppendNestedArray();
 
  constexpr NestedJsonObject AppendNestedObject();
 
 private:
  friend class JsonArray;
  friend class JsonObject;
  friend class NestedJsonObject;
 
  constexpr NestedJsonArray(json_impl::NestedJson&& nested)
      : json_(std::move(nested)) {}
 
  json_impl::NestedJson json_;
};
 
class [[nodiscard]] NestedJsonObject {
 public:
  NestedJsonObject(const NestedJsonObject&) = delete;
  NestedJsonObject& operator=(const NestedJsonObject&) = delete;
 
  constexpr NestedJsonObject(NestedJsonObject&&) = default;
  constexpr NestedJsonObject& operator=(NestedJsonObject&&) = default;
 
  template <typename T>
  constexpr NestedJsonObject& Add(std::string_view key, const T& value);
 
  constexpr NestedJsonArray AddNestedArray(std::string_view key);
 
  constexpr NestedJsonObject AddNestedObject(std::string_view key);
 
 private:
  friend class JsonArray;
  friend class JsonObject;
  friend class NestedJsonArray;
 
  constexpr NestedJsonObject(json_impl::NestedJson&& nested)
      : json_(std::move(nested)) {}
 
  json_impl::NestedJson json_;
};
 
class JsonValue {
 public:
  constexpr JsonValue(const JsonValue&) = delete;
  constexpr JsonValue& operator=(const JsonValue&) = delete;
 
  // Functions common to all JSON types.
  [[nodiscard]] constexpr bool IsValue() const;
  [[nodiscard]] constexpr bool IsArray() const;
  [[nodiscard]] constexpr bool IsObject() const;
 
  constexpr operator std::string_view() const;
  constexpr const char* data() const;
  constexpr size_t size() const;
  constexpr size_t max_size() const;
 
  [[nodiscard]] constexpr bool ok() const;
  constexpr Status status() const;
  constexpr Status last_status() const;
  constexpr void clear();
  constexpr void clear_status();
 
  template <typename T>
  constexpr Status Set(const T& value);
 
 private:
  friend class JsonBuilder;
 
  constexpr JsonValue() = default;
};
 
class JsonArray {
 public:
  constexpr JsonArray(const JsonArray&) = delete;
  constexpr JsonArray& operator=(const JsonArray&) = delete;
 
  // Functions common to all JSON types. See documentation for `JsonBuilder`.
  [[nodiscard]] constexpr bool IsValue() const;
  [[nodiscard]] constexpr bool IsArray() const;
  [[nodiscard]] constexpr bool IsObject() const;
 
  constexpr operator std::string_view() const;
  constexpr const char* data() const;
  constexpr size_t size() const;
  constexpr size_t max_size() const;
 
  [[nodiscard]] constexpr bool ok() const;
  constexpr Status status() const;
  constexpr Status last_status() const;
  constexpr void clear();
  constexpr void clear_status();
 
  template <typename T>
  constexpr JsonArray& Append(const T& value);
 
  constexpr NestedJsonArray AppendNestedArray();
 
  constexpr NestedJsonObject AppendNestedObject();
 
  template <typename Iterable>
  constexpr JsonArray& Extend(const Iterable& iterable);
 
  template <typename T, size_t kSize>
  constexpr JsonArray& Extend(const T (&iterable)[kSize]);
 
 private:
  friend class JsonBuilder;
 
  constexpr JsonArray() = default;
};
 
class JsonObject {
 public:
  constexpr JsonObject(const JsonObject&) = delete;
  constexpr JsonObject& operator=(const JsonObject&) = delete;
 
  // Functions common to all JSON types. See documentation for `JsonBuilder`.
  [[nodiscard]] constexpr bool IsValue() const;
  [[nodiscard]] constexpr bool IsArray() const;
  [[nodiscard]] constexpr bool IsObject() const;
 
  constexpr operator std::string_view() const;
  constexpr const char* data() const;
  constexpr size_t size() const;
  constexpr size_t max_size() const;
 
  [[nodiscard]] constexpr bool ok() const;
  constexpr Status status() const;
  constexpr Status last_status() const;
  constexpr void clear();
  constexpr void clear_status();
 
  template <typename T>
  constexpr JsonObject& Add(std::string_view key, const T& value);
 
  template <typename T>
  constexpr JsonObject& Add(std::nullptr_t, const T& value) = delete;
 
  constexpr NestedJsonArray AddNestedArray(std::string_view key);
 
  constexpr NestedJsonObject AddNestedObject(std::string_view key);
 
 private:
  friend class JsonBuilder;
 
  constexpr JsonObject() = default;
};
 
class JsonBuilder : private JsonValue, private JsonArray, private JsonObject {
 public:
  static constexpr size_t MinBufferSize() { return 5; }
 
  constexpr JsonBuilder(span<char> buffer)
      : JsonBuilder(buffer.data(), buffer.size()) {}
 
  constexpr JsonBuilder(char* buffer, size_t buffer_size)
      : JsonBuilder(buffer, buffer_size, Uninitialized{}) {
    PW_ASSERT(buffer_size >= MinBufferSize());  // Must be at least 5 characters
    MakeNull();
  }
 
  [[nodiscard]] constexpr bool IsValue() const {
    return !IsObject() && !IsArray();
  }
 
  [[nodiscard]] constexpr bool IsArray() const { return buffer_[0] == '['; }
 
  [[nodiscard]] constexpr bool IsObject() const { return buffer_[0] == '{'; }
 
  constexpr operator std::string_view() const { return {data(), size()}; }
 
  constexpr const char* data() const { return buffer_; }
 
  constexpr size_t size() const { return json_size_; }
 
  constexpr size_t max_size() const { return max_size_; }
 
  [[nodiscard]] constexpr bool ok() const { return status().ok(); }
 
  constexpr Status status() const { return static_cast<Status::Code>(status_); }
 
  constexpr Status last_status() const {
    return static_cast<Status::Code>(last_status_);
  }
 
  constexpr void clear() { JsonValueClear(); }
 
  constexpr void clear_status() { set_statuses(OkStatus()); }
 
  template <typename T>
  constexpr Status SetValue(const T& value);
 
  [[nodiscard]] constexpr JsonValue& StartValue() {
    JsonValueClear();
    return *this;
  }
 
  [[nodiscard]] constexpr JsonArray& StartArray() {
    JsonArrayClear();
    return *this;
  }
 
  [[nodiscard]] constexpr JsonObject& StartObject() {
    JsonObjectClear();
    return *this;
  }
 
 protected:
  enum class Uninitialized {};
 
  // Constructor that doesn't initialize the buffer.
  constexpr JsonBuilder(char* buffer, size_t buffer_size, Uninitialized)
      : buffer_(buffer),
        max_size_(buffer_size - 1),
        json_size_(0),
        status_(OkStatus().code()),
        last_status_(OkStatus().code()) {}
 
  // Sets the buffer to the null value.
  constexpr void MakeNull() {
    buffer_[0] = 'n';
    buffer_[1] = 'u';
    buffer_[2] = 'l';
    buffer_[3] = 'l';
    buffer_[4] = '\0';
    json_size_ = 4;
  }
 
  constexpr void set_json_size(size_t json_size) { json_size_ = json_size; }
 
  constexpr void set_statuses(Status status, Status last_status) {
    status_ = status.code();
    last_status_ = last_status.code();
  }
 
 private:
  friend class JsonValue;
  friend class JsonArray;
  friend class JsonObject;
 
  friend class NestedJsonArray;
  friend class NestedJsonObject;
 
  constexpr size_t remaining() const { return max_size() - size(); }
 
  // Sets last_status_ and updates status_ if an error occurred.
  constexpr void update_status(Status new_status);
 
  constexpr void set_statuses(Status status) { set_statuses(status, status); }
 
  constexpr void JsonValueClear() {
    MakeNull();
    set_statuses(OkStatus());
  }
 
  constexpr void JsonArrayClear() {
    MakeEmpty('[', ']');
    set_statuses(OkStatus());
  }
 
  constexpr void JsonObjectClear() {
    MakeEmpty('{', '}');
    set_statuses(OkStatus());
  }
 
  template <typename T>
  constexpr Status JsonValueSet(const T& value);
 
  template <typename T>
  constexpr JsonArray& JsonArrayAppend(const T& value);
 
  template <typename Iterator>
  constexpr JsonArray& JsonArrayExtend(Iterator begin, Iterator end);
 
  template <typename T>
  constexpr JsonObject& JsonObjectAdd(std::string_view key, const T& value);
 
  [[nodiscard]] constexpr bool JsonArrayAddElement();
 
  // Adds the key if there's room for the key and at least one more character.
  [[nodiscard]] constexpr bool JsonObjectAddKey(std::string_view key);
 
  constexpr size_t NestedJsonOffset(const json_impl::Nesting& nesting) const {
    // Point to the start of the nested JSON array or object. This will be three
    // characters, plus one for each prior layer of nesting {..., "": []}.
    return json_size_ - 3 - nesting.depth();
  }
 
  constexpr json_impl::Nesting::Type type() const {
    return IsArray() ? json_impl::Nesting::kArray : json_impl::Nesting::kObject;
  }
 
  constexpr json_impl::NestedJson JsonArrayAppendNested(
      const char (&open_close)[2], const json_impl::Nesting& nesting);
 
  constexpr json_impl::NestedJson JsonObjectAddNested(
      std::string_view key,
      const char (&open_close)[2],
      const json_impl::Nesting& nesting);
 
  // Nesting works by shrinking the JsonBuilder to be just the nested structure,
  // then expanding back out when done adding items.
  constexpr void AddNestedStart(const json_impl::Nesting& nesting);
  constexpr void AddNestedFinish(const json_impl::Nesting& nesting);
 
  template <typename T>
  constexpr void NestedJsonArrayAppend(const T& value,
                                       const json_impl::Nesting& nesting);
 
  template <typename T>
  constexpr void NestedJsonObjectAdd(std::string_view key,
                                     const T& value,
                                     const json_impl::Nesting& nesting);
 
  // For a single JSON value, checks if writing succeeded and clears on failure.
  constexpr Status HandleSet(StatusWithSize written);
 
  // For a value added to an array or object, checks if writing the characters
  // succeeds, sets the status, and terminates the buffer as appropriate.
  constexpr void HandleAdd(StatusWithSize written,
                           size_t starting_size,
                           char terminator);
 
  constexpr void MakeEmpty(char open, char close) {
    buffer_[0] = open;
    buffer_[1] = close;
    buffer_[2] = '\0';
    json_size_ = 2;
  }
 
  // TODO: b/326097937 - Use StringBuilder here.
  char* buffer_;
  size_t max_size_;  // max size of the JSON string, excluding the '\0'
  size_t json_size_;
 
  // If any errors have occurred, status_ stores the most recent error Status.
  // last_status_ stores the status from the most recent operation.
  uint8_t status_;
  uint8_t last_status_;
};
 
template <size_t kMaxSize>
class JsonBuffer final : public JsonBuilder {
 public:
  // Constructs a JsonBuffer with the value null.
  constexpr JsonBuffer()
      : JsonBuilder(static_buffer_, sizeof(static_buffer_), Uninitialized{}),
        static_buffer_{} {
    MakeNull();
  }
 
  template <typename T>
  static constexpr JsonBuffer Value(const T& initial_value) {
    JsonBuffer<kMaxSize> json;
    PW_ASSERT(json.SetValue(initial_value).ok());  // Failed serialization.
    return json;
  }
 
  // JsonBuffers may be copied or assigned, as long as the source buffer is not
  // larger than this buffer.
  constexpr JsonBuffer(const JsonBuffer& other) : JsonBuffer() {
    CopyFrom(other);
  }
 
  template <size_t kOtherSize>
  constexpr JsonBuffer(const JsonBuffer<kOtherSize>& other) : JsonBuffer() {
    CopyFrom(other);
  }
 
  constexpr JsonBuffer& operator=(const JsonBuffer& rhs) {
    CopyFrom(rhs);
    return *this;
  }
 
  template <size_t kOtherSize>
  constexpr JsonBuffer& operator=(const JsonBuffer<kOtherSize>& rhs) {
    CopyFrom(rhs);
    return *this;
  }
 
  static constexpr size_t max_size() { return kMaxSize; }
 
 private:
  static_assert(kMaxSize + 1 /* null */ >= JsonBuilder::MinBufferSize(),
                "JsonBuffers require at least 4 bytes");
 
  template <size_t kOtherSize>
  constexpr void CopyFrom(const JsonBuffer<kOtherSize>& other) {
    static_assert(kOtherSize <= kMaxSize,
                  "A JsonBuffer cannot be copied into a smaller buffer");
    CopyFrom(static_cast<const JsonBuilder&>(other));
  }
 
  constexpr void CopyFrom(const JsonBuilder& other) {
    for (size_t i = 0; i < other.size() + 1 /* include null */; ++i) {
      static_buffer_[i] = other.data()[i];
    }
    JsonBuilder::set_json_size(other.size());
    JsonBuilder::set_statuses(other.status(), other.last_status());
  }
 
  char static_buffer_[kMaxSize + 1];
};
 
 
}  // namespace pw
 
// Functions are defined inline in a separate header.
#include "pw_json/internal/builder_impl.h"