values.h

Go to the documentation of this file.

/*
 * Copyright 2026 The A11 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
 *
 *     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.
 */
 
#ifndef A11_FLOW_VALUES_H_
#define A11_FLOW_VALUES_H_
 
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
#include <absl/base/nullability.h>
#include <absl/container/flat_hash_map.h>
#include <absl/status/status.h>
#include <absl/status/statusor.h>
#include <absl/time/time.h>
#include <absl/types/span.h>
 
#include "a11/data/types.h"
#include "a11/flow/pattern.h"
#include "a11/flow/plan.h"
#include "a11/flow/syntax.h"
 
namespace a11::flow {
 
class Value;
 
class HostObject {
 public:
  virtual ~HostObject() = default;
 
  [[nodiscard]] virtual std::string Tag() const = 0;
  [[nodiscard]] virtual std::string Text() const = 0;
  [[nodiscard]] virtual bool Truthy() const = 0;
  [[nodiscard]] virtual std::optional<size_t> Size() const = 0;
  [[nodiscard]] virtual Value Field(std::string_view name) const = 0;
  [[nodiscard]] virtual Value Element(const Value& key) const = 0;
  [[nodiscard]] virtual bool Equals(const HostObject& other) const = 0;
};
 
class Value {
 public:
  enum class Kind {
    kNull,
    kBool,
    kInteger,
    kDouble,
    kString,
    kBytes,
    kList,
    kObject,
    kDuration,
    kTime,
    kChunk,
    kHost,
  };
 
  using Pairs = std::vector<std::pair<std::string, Value>>;
 
  Value() = default;
 
  static Value Null() { return {}; }
 
  static Value Bool(bool value);
  static Value Integer(std::int64_t value);
  static Value Double(double value);
  static Value String(std::string value);
  static Value Bytes(data::Bytes value);
  static Value List(std::vector<Value> items);
  static Value Object(Pairs pairs);
  static Value Duration(absl::Duration value);
  static Value Time(absl::Time value);
  static Value Chunk(data::Chunk chunk);
  static Value Host(std::shared_ptr<const HostObject> object);
  static Value Of(const syntax::Constant& constant);
 
  [[nodiscard]] Kind kind() const { return kind_; }
 
  [[nodiscard]] bool IsNull() const { return kind_ == Kind::kNull; }
 
  [[nodiscard]] bool IsNumber() const {
    return kind_ == Kind::kInteger || kind_ == Kind::kDouble;
  }
 
  [[nodiscard]] bool IsTimelike() const {
    return kind_ == Kind::kDuration || kind_ == Kind::kTime;
  }
 
  [[nodiscard]] bool IsTextlike() const {
    return kind_ == Kind::kString || kind_ == Kind::kBytes;
  }
 
  [[nodiscard]] bool boolean() const { return boolean_; }
 
  [[nodiscard]] std::int64_t integer() const { return integer_; }
 
  [[nodiscard]] double number() const { return number_; }
 
  [[nodiscard]] const std::string& text() const { return *text_; }
 
  [[nodiscard]] const std::vector<Value>& items() const { return *items_; }
 
  [[nodiscard]] const Pairs& pairs() const { return *pairs_; }
 
  [[nodiscard]] absl::Duration duration() const { return duration_; }
 
  [[nodiscard]] absl::Time time() const { return time_; }
 
  [[nodiscard]] const data::Chunk& chunk() const { return *chunk_; }
 
  [[nodiscard]] const HostObject& host() const { return *host_; }
 
  [[nodiscard]] const std::shared_ptr<const HostObject>& host_object() const {
    return host_;
  }
 
  [[nodiscard]] const Value* absl_nullable Get(std::string_view key) const;
 
  friend bool operator==(const Value& left, const Value& right);
 
 private:
  Kind kind_ = Kind::kNull;
  bool boolean_ = false;
  std::int64_t integer_ = 0;
  double number_ = 0.0;
  absl::Duration duration_;
  absl::Time time_;
  std::shared_ptr<const std::string> text_;
  std::shared_ptr<const std::vector<Value>> items_;
  std::shared_ptr<const Pairs> pairs_;
  std::shared_ptr<const data::Chunk> chunk_;
  std::shared_ptr<const HostObject> host_;
};
 
class HostBridge {
 public:
  virtual ~HostBridge() = default;
 
  virtual absl::StatusOr<Value> Coerce(std::string_view tag,
                                       const Value& value) = 0;
 
  virtual absl::StatusOr<Value> FromChunk(const data::Chunk& chunk) = 0;
 
  virtual absl::StatusOr<data::Chunk> ToChunk(const Value& value,
                                              std::string_view mimetype) = 0;
 
  virtual std::vector<absl::StatusOr<Value>> FromChunks(
      absl::Span<const data::Chunk* const> chunks) {
    std::vector<absl::StatusOr<Value>> values;
    values.reserve(chunks.size());
    for (const data::Chunk* chunk : chunks) {
      {
        values.push_back(FromChunk(*chunk));
      }
    }
    return values;
  }
 
  virtual std::vector<absl::StatusOr<data::Chunk>> ToChunks(
      absl::Span<const Value* const> values, std::string_view mimetype) {
    std::vector<absl::StatusOr<data::Chunk>> chunks;
    chunks.reserve(values.size());
    for (const Value* value : values) {
      chunks.push_back(ToChunk(*value, mimetype));
    }
    return chunks;
  }
 
  // How this host would rather hold a value of a shape the *language* declared.
  virtual absl::StatusOr<Value> Adopt(const DtoPlan& shape,
                                      const Program& program,
                                      const Value& value) {
    (void)shape;
    (void)program;
    return value;
  }
};
 
std::unique_ptr<HostBridge> NativeHostBridge();
 
// --- Reading values ----------------------------------------------------------
 
Value Lookup(const Value& value, const Value& key);
 
bool Truthy(const Value& value);
 
int Order(const Value& left, const Value& right);
 
absl::StatusOr<Value> Add(const Value& left, const Value& right);
 
std::string AsText(const Value& value);
 
Value AsNumber(const Value& value);
 
absl::StatusOr<Value> MatchPattern(std::string_view pattern,
                                   std::string_view subject);
 
Value MatchCompiled(const pattern::Pattern& pattern, std::string_view subject);
 
double AsDouble(const Value& value);
 
Value AsJson(const Value& value);
 
Value Truncate(const Value& value, std::int64_t size);
 
std::string JsonText(const Value& value);
 
// --- Times and durations -----------------------------------------------------
 
double DurationSeconds(absl::Duration value);
 
absl::Duration SecondsDuration(double total);
 
std::optional<absl::Duration> ParseDuration(std::string_view text);
 
absl::Duration AsDuration(const Value& value);
 
absl::Time AsTime(const Value& value);
 
std::optional<absl::Time> ParseTime(std::string_view text);
 
std::string DurationText(absl::Duration value, std::string_view spec = {});
 
std::string TimeText(absl::Time value, std::string_view spec = {});
 
// --- Formatting --------------------------------------------------------------
 
std::string Strformat(const Value& format, absl::Span<const Value> arguments);
 
// --- Evaluation --------------------------------------------------------------
 
struct CoerceContext {
  HostBridge* absl_nullable bridge = nullptr;
  const Program* absl_nullable shapes = nullptr;
};
 
struct EvalContext {
  const absl::flat_hash_map<const syntax::Node*, Value>* absl_nullable bound =
      nullptr;
  Value it;
  bool has_it = false;
  HostBridge* absl_nullable bridge = nullptr;
  const Program* absl_nullable shapes = nullptr;
 
  [[nodiscard]] CoerceContext Coercion() const { return {bridge, shapes}; }
};
 
absl::StatusOr<Value> Evaluate(const syntax::Node& node,
                               const EvalContext& context);
 
absl::StatusOr<Value> Coerce(const Value& value,
                             const syntax::TypeExpression& type,
                             const CoerceContext& context);
 
// Make `value` a value of `shape`: fill its defaults, check its bounds, and
// coerce every field to the type the shape gives it.
absl::StatusOr<Value> CoerceShape(const DtoPlan& shape, const Value& value,
                                  const CoerceContext& context);
 
absl::StatusOr<Value> CallBuiltin(std::string_view name,
                                  absl::Span<const Value> arguments,
                                  HostBridge* absl_nullable bridge);
 
// --- Statuses as data --------------------------------------------------------
 
Value StatusRecord(const absl::Status& status);
 
absl::Status StatusOfRecord(const Value& record);
 
std::optional<absl::StatusCode> StatusCodeOf(const Value& value);
 
}  // namespace a11::flow
 
#endif  // A11_FLOW_VALUES_H_