syntax.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_SYNTAX_H_
#define A11_FLOW_SYNTAX_H_
 
#include <cstddef>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
#include <absl/time/time.h>
 
#include "a11/flow/token.h"
#include "a11/flow/vocabulary.h"
 
namespace a11::flow::syntax {
 
struct Location {
  size_t start = 0;
  size_t end = 0;
  int line = 1;
  int column = 1;
};
 
Location LocationOf(const Token& token);
 
struct Word {
  std::string text;
  Location location;
 
  [[nodiscard]] bool Empty() const { return text.empty(); }
};
 
// A value the language can write out in full: what a literal is, and what
// folding a literal expression gives.
struct Constant {
  enum class Kind {
    kNull,
    kBool,
    kInteger,
    kDouble,
    kString,
    kDuration,
    kList,
    kObject,
  };
 
  Kind kind = Kind::kNull;
  bool boolean = false;
  long long integer = 0;
  double number = 0.0;
  std::string text;
  absl::Duration duration;
  std::vector<Constant> items;
  std::vector<std::pair<std::string, Constant>> pairs;
 
  static Constant Null() { return {}; }
 
  static Constant Bool(bool value);
  static Constant Integer(long long value);
  static Constant Double(double value);
  static Constant String(std::string value);
  static Constant Duration(absl::Duration value);
 
  [[nodiscard]] double AsDouble() const;
};
 
std::string_view ConstantKindName(Constant::Kind kind);
 
// The type of a port, or of a value being made one: `string`,
// `list[a11.NodeFragment]`, `"audio/wav"`.
struct TypeExpression {
  Location location = {};
  std::string name;
  std::vector<TypeExpression> parameters = {};
  bool quoted = false;
  bool sugared = false;
 
  [[nodiscard]] std::string ToString() const;
};
 
enum class NodeKind {
  kError,
 
  kLiteral,
  kListLiteral,
  kObjectLiteral,
  kSpread,
  kIt,
  kDiscard,
  kName,
  kAttr,
  kIndex,
  kBuiltin,
  kZip,
  kTypedValue,
  kUnary,
  kBinary,
 
  kStage,
  kPipeline,
  kOutcome,
  kPipelineValue,
 
  kCallModifiers,
  kCallExpression,
 
  kBind,
  kLet,
  kAdvance,
  kBlock,
  kCallStatement,
  kPipe,
  kSkip,
  kWait,
  kDrain,
  kCancel,
  kAbort,
  kFail,
  kLog,
  kForEach,
  kRepeat,
  kCarry,
  kUntil,
  kIf,
  kNodes,
  kNodeExpression,
 
  kPortDeclaration,
  kHeaderDeclaration,
  kFlowDeclaration,
  kFieldDeclaration,
  kDtoDeclaration,
};
 
std::string_view NodeKindName(NodeKind kind);
 
struct Node {
  virtual ~Node() = default;
 
  NodeKind kind = NodeKind::kError;
  Location location;
};
 
using NodePtr = std::unique_ptr<Node>;
 
template <NodeKind K>
struct NodeOf : Node {
  static constexpr NodeKind kNodeKind = K;
 
  NodeOf() { kind = K; }
};
 
// `node` as a `T`, or `nullptr` if it is something else.
template <typename T>
const T* As(const Node* node) {
  if (node == nullptr || node->kind != T::kNodeKind) {
    {
      return nullptr;
    }
  }
  return static_cast<const T*>(node);
}
 
template <typename T>
T* As(Node* node) {
  if (node == nullptr || node->kind != T::kNodeKind) {
    {
      return nullptr;
    }
  }
  return static_cast<T*>(node);
}
 
bool IsAnyOf(const Node* node, std::initializer_list<NodeKind> kinds);
 
// --- Expressions -------------------------------------------------------------
 
struct ErrorNode : NodeOf<NodeKind::kError> {
  std::string expected;
};
 
struct Literal : NodeOf<NodeKind::kLiteral> {
  Constant value;
};
 
struct Spread : NodeOf<NodeKind::kSpread> {
  NodePtr value;
};
 
struct ListLiteral : NodeOf<NodeKind::kListLiteral> {
  std::vector<NodePtr> items;
};
 
struct ObjectLiteral : NodeOf<NodeKind::kObjectLiteral> {
  std::vector<std::pair<std::string, NodePtr>> pairs;
};
 
struct It : NodeOf<NodeKind::kIt> {};
 
struct Discard : NodeOf<NodeKind::kDiscard> {};
 
struct Name : NodeOf<NodeKind::kName> {
  std::string name;
};
 
struct Attr : NodeOf<NodeKind::kAttr> {
  NodePtr base;
  std::string name;
};
 
struct Index : NodeOf<NodeKind::kIndex> {
  NodePtr base;
  NodePtr index;
};
 
struct Builtin : NodeOf<NodeKind::kBuiltin> {
  std::string name;
  std::vector<NodePtr> args;
};
 
struct Zip : NodeOf<NodeKind::kZip> {
  std::string name = "zip";
  std::vector<NodePtr> sources;
};
 
struct TypedValue : NodeOf<NodeKind::kTypedValue> {
  TypeExpression type;
  NodePtr value;
};
 
struct Unary : NodeOf<NodeKind::kUnary> {
  std::string op;
  NodePtr operand;
};
 
struct Binary : NodeOf<NodeKind::kBinary> {
  std::string op;
  NodePtr left;
  NodePtr right;
};
 
// --- Pipelines ---------------------------------------------------------------
 
struct LogTail {
  Word level;
  std::string format;
  bool has_format = false;
  std::vector<NodePtr> arguments;
};
 
struct Stage : NodeOf<NodeKind::kStage> {
  std::string name;
  vocabulary::StageArgument takes = vocabulary::StageArgument::kNone;
  double number = 0.0;
  bool is_integer = false;
  std::string text;
  NodePtr argument;
  absl::Duration duration;
  bool descending = false;
  Constant start;
  Word carried;
  bool tolerant = false;
  NodePtr failures;
  int parallel = 1;
  // Whether the values leave in the order they arrived.
  bool ordered = true;
  LogTail log;
};
 
using StagePtr = std::unique_ptr<Stage>;
 
struct Pipeline : NodeOf<NodeKind::kPipeline> {
  NodePtr source;
  std::vector<StagePtr> stages;
};
 
using PipelinePtr = std::unique_ptr<Pipeline>;
 
struct Outcome : NodeOf<NodeKind::kOutcome> {
  NodePtr subject;
};
 
struct PipelineValue : NodeOf<NodeKind::kPipelineValue> {
  PipelinePtr pipeline;
};
 
// --- Calls -------------------------------------------------------------------
 
struct CallModifiers : NodeOf<NodeKind::kCallModifiers> {
  bool tee = false;
  Word node_map;
  std::optional<absl::Duration> timeout;
  std::vector<Word> after;
  std::vector<std::pair<std::string, NodePtr>> headers;
  NodePtr action_id;
  std::vector<std::string> forward;
};
 
using CallModifiersPtr = std::unique_ptr<CallModifiers>;
 
struct CallExpression : NodeOf<NodeKind::kCallExpression> {
  struct Argument {
    Word port;
    PipelinePtr pipeline;
  };
 
  std::string action;
  std::string mode;
  std::vector<Argument> args;
  CallModifiersPtr modifiers;
  bool tolerant = false;
};
 
using CallExpressionPtr = std::unique_ptr<CallExpression>;
 
// --- Statements --------------------------------------------------------------
 
struct Bind : NodeOf<NodeKind::kBind> {
  Word name;
  NodePtr value;
};
 
struct Let : NodeOf<NodeKind::kLet> {
  // One name is the value; several take it apart -- `let name, age = user` by
  // field, `let first, second = pair` by position.
  std::vector<Word> names;
  PipelinePtr pipeline;
 
  [[nodiscard]] const Word& name() const {
    static const Word kNone;
    return names.empty() ? kNone : names.front();
  }
};
 
// `[try] { ...
struct Block : NodeOf<NodeKind::kBlock> {
  bool tolerant = false;
  std::vector<NodePtr> body;
};
 
struct Advance : NodeOf<NodeKind::kAdvance> {
  Word name;
};
 
struct CallStatement : NodeOf<NodeKind::kCallStatement> {
  CallExpressionPtr call;
};
 
struct Pipe : NodeOf<NodeKind::kPipe> {
  PipelinePtr pipeline;
  std::vector<NodePtr> targets;
  std::vector<Word> after;
  // `try source -> dest`: a failure arriving from the source, or refused by the
  // destination, is a value this flow reads rather than the end of it.
  bool tolerant = false;
};
 
struct SkipTarget {
  PipelinePtr pipeline;
  Word call;
  std::vector<Word> outputs;
};
 
struct Skip : NodeOf<NodeKind::kSkip> {
  std::vector<SkipTarget> targets;
  std::vector<Word> after;
  std::optional<long long> count;
};
 
// `wait subject` -- hold until a call, or a node this flow writes, is finished.
struct Wait : NodeOf<NodeKind::kWait> {
  NodePtr subject;
  std::vector<NodePtr> subjects;
  bool race = false;
  std::optional<absl::Duration> timeout;
  std::vector<Word> after;
  // `wait first of a, b -> n`: where the winner's number goes.
  std::vector<NodePtr> targets;
};
 
struct Drain : NodeOf<NodeKind::kDrain> {
  NodePtr target;
  std::vector<Word> after;
};
 
struct Cancel : NodeOf<NodeKind::kCancel> {
  Word name;
  std::vector<Word> after;
};
 
struct Abort : NodeOf<NodeKind::kAbort> {
  NodePtr target;
  NodePtr code;
  NodePtr message;
  std::vector<Word> after;
};
 
struct Fail : NodeOf<NodeKind::kFail> {
  NodePtr code;
  NodePtr message;
  std::vector<Word> after;
};
 
struct Log : NodeOf<NodeKind::kLog> {
  LogTail tail;
  std::vector<Word> after;
};
 
// `for name[, name...] in pipeline [parallel n] { ...
struct ForEach : NodeOf<NodeKind::kForEach> {
  std::vector<Word> variables;
  PipelinePtr pipeline;
  int parallel = 1;
  std::vector<NodePtr> body;
  std::vector<Word> after;
 
  [[nodiscard]] const Word& variable() const {
    static const Word kNone;
    return variables.empty() ? kNone : variables.front();
  }
};
 
struct Repeat : NodeOf<NodeKind::kRepeat> {
  Word variable;
  NodePtr start;
  // `max n`, where one was written.
  std::optional<int> max_iterations;
  std::vector<NodePtr> body;
  std::vector<Word> after;
};
 
struct Carry : NodeOf<NodeKind::kCarry> {
  Word name;
  PipelinePtr pipeline;
};
 
struct Until : NodeOf<NodeKind::kUntil> {
  NodePtr condition;
  bool stop_when = true;
};
 
struct If : NodeOf<NodeKind::kIf> {
  NodePtr condition;
  std::vector<NodePtr> then_body;
  std::vector<NodePtr> else_body;
};
 
struct Nodes : NodeOf<NodeKind::kNodes> {
  Word name;
  std::vector<NodePtr> body;
  bool has_body = false;
};
 
struct NodeExpression : NodeOf<NodeKind::kNodeExpression> {
  NodePtr id;
  Word node_map;
};
 
// --- Declarations ------------------------------------------------------------
 
enum class PortDirection { kInput, kOutput };
 
std::string_view PortDirectionName(PortDirection direction);
 
struct PortDeclaration : NodeOf<NodeKind::kPortDeclaration> {
  Word name;
  PortDirection direction = PortDirection::kInput;
  TypeExpression type;
  bool unary = true;
  bool required = false;
  std::string description;
};
 
using PortDeclarationPtr = std::unique_ptr<PortDeclaration>;
 
struct HeaderDeclaration : NodeOf<NodeKind::kHeaderDeclaration> {
  std::string name;
  Word alias;
  Constant default_value;
  bool has_default = false;
  std::string description;
};
 
using HeaderDeclarationPtr = std::unique_ptr<HeaderDeclaration>;
 
struct FlowDeclaration : NodeOf<NodeKind::kFlowDeclaration> {
  Word name;
  bool entry = false;
  std::string description;
  std::vector<PortDeclarationPtr> ports;
  std::vector<HeaderDeclarationPtr> headers;
  std::vector<NodePtr> body;
};
 
using FlowDeclarationPtr = std::unique_ptr<FlowDeclaration>;
 
struct FieldRange {
  bool has_minimum = false;
  bool has_maximum = false;
  Constant minimum;
  Constant maximum;
 
  [[nodiscard]] bool Empty() const { return !has_minimum && !has_maximum; }
};
 
struct FieldDeclaration : NodeOf<NodeKind::kFieldDeclaration> {
  Word name;
  TypeExpression type;
  bool required = false;
  bool unique = false;
  FieldRange range;
  std::string pattern;
  bool has_pattern = false;
  std::vector<Constant> enumeration;
  bool has_enumeration = false;
  Constant default_value;
  bool has_default = false;
  std::string description;
};
 
using FieldDeclarationPtr = std::unique_ptr<FieldDeclaration>;
 
// One `struct name { ...
struct DtoDeclaration : NodeOf<NodeKind::kDtoDeclaration> {
  Word name;
  std::string description;
  std::vector<FieldDeclarationPtr> fields;
};
 
using DtoDeclarationPtr = std::unique_ptr<DtoDeclaration>;
 
// The constant `node` folds to, or `nullopt` where it is not one all the way
// down.
std::optional<Constant> ConstantValue(const Node* node);
 
void VisitChildren(const Node& node,
                   const std::function<void(const Node&)>& visit);
 
void VisitSubtree(const Node& node,
                  const std::function<void(const Node&)>& visit);
 
std::optional<std::string> DottedName(const Node* node);
 
}  // namespace a11::flow::syntax
 
#endif  // A11_FLOW_SYNTAX_H_