A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
document.h
Go to the documentation of this file.
1// Copyright 2026 The A11 Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#ifndef A11_FLOW_DOCUMENT_H_
16#define A11_FLOW_DOCUMENT_H_
17
18#include <cstdint>
19#include <memory>
20#include <optional>
21#include <string>
22#include <string_view>
23#include <utility>
24#include <vector>
25
26#include <absl/status/statusor.h>
27#include <absl/time/time.h>
28#include <nlohmann/json.hpp>
29
30#include "a11/flow/module.h"
31#include "a11/flow/plan.h"
32#include "a11/flow/resolve.h"
33
34namespace a11::flow {
35
36struct CallOptions;
37
40 public:
41 static absl::StatusOr<Expression> Reference(std::string name);
42 static absl::StatusOr<Expression> Literal(nlohmann::json value);
43 static absl::StatusOr<Expression> Invoke(
44 std::string_view action,
45 std::vector<std::pair<std::string, Expression>> arguments = {},
46 bool remote = false, bool tolerant = false,
47 std::string_view node_map = {});
48 static absl::StatusOr<Expression> InvokeWith(
49 std::string_view action,
50 std::vector<std::pair<std::string, Expression>> arguments,
51 const CallOptions& options);
52 static absl::StatusOr<Expression> Object(
53 std::vector<std::pair<std::string, Expression>> fields);
54 static absl::StatusOr<Expression> Array(std::vector<Expression> items);
55 static absl::StatusOr<Expression> Builtin(std::string_view name,
56 std::vector<Expression> arguments);
57 static absl::StatusOr<Expression> Node(std::optional<Expression> id = {},
58 std::string_view node_map = {});
59 static absl::StatusOr<Expression> Completion(std::string_view operation,
60 const Expression& subject);
61 Expression Take(bool optional = false) const;
62 absl::StatusOr<Expression> Transfer(const Expression& destination,
63 bool tolerant = false) const;
64 absl::StatusOr<Expression> Cast(const syntax::TypeExpression& type) const;
65 absl::StatusOr<Expression> Index(const Expression& index) const;
66 absl::StatusOr<Expression> Field(std::string_view name) const;
67 absl::StatusOr<Expression> Pipeline(
68 std::string_view stage, std::optional<Expression> argument = {}) const;
69
70 absl::StatusOr<Expression> PipelineInvoke(
71 std::string_view action,
72 std::vector<std::pair<std::string, Expression>> arguments,
73 const CallOptions& options) const;
74
75 [[nodiscard]] const std::string& source() const { return source_; }
76
77 private:
78 explicit Expression(std::string source) : source_(std::move(source)) {}
79
80 std::string source_;
81};
82
85 bool remote = false;
86 bool tolerant = false;
87 bool tee = false;
88 std::string node_map;
89 std::optional<absl::Duration> timeout;
90 std::optional<Expression> deadline;
91 std::optional<Expression> id;
92 std::vector<Expression> after;
93 std::vector<std::pair<std::string, Expression>> headers;
94 std::vector<std::string> forward;
95};
96
98class Statement {
99 public:
100 static absl::StatusOr<Statement> Initialize(
101 std::string_view name, const Expression& value,
102 std::optional<syntax::TypeExpression> type = {});
103 static absl::StatusOr<Statement> Pipe(const Expression& value,
104 const Expression& destination);
105 static absl::StatusOr<Statement> Wait(const Expression& subject,
106 bool close = false);
107 static absl::StatusOr<Statement> WaitAll();
108 static absl::StatusOr<Statement> Cancel(const Expression& subject);
109 static absl::StatusOr<Statement> Fail(const Expression& code,
110 std::optional<Expression> message = {});
111 static absl::StatusOr<Statement> If(
112 const Expression& condition, const std::vector<Statement>& then_body,
113 const std::vector<Statement>& else_body = {});
114 static absl::StatusOr<Statement> IfSome(
115 std::string_view name, const Expression& option,
116 const std::vector<Statement>& then_body,
117 const std::vector<Statement>& else_body = {});
118 static absl::StatusOr<Statement> For(std::string_view variable,
119 const Expression& source,
120 const std::vector<Statement>& body,
121 int parallel = 1);
122 static absl::StatusOr<Statement> After(
123 const std::vector<Expression>& subjects,
124 const std::vector<Statement>& body, bool tolerant = false);
125 static absl::StatusOr<Statement> Block(const std::vector<Statement>& body,
126 bool tolerant = false);
127
128 const std::string& source() const { return source_; }
129
130 std::string TakeSource() && { return std::move(source_); }
131
132 private:
133 explicit Statement(std::string source) : source_(std::move(source)) {}
134
135 static absl::StatusOr<Statement> Validated(std::string source);
136 static std::string Body(const std::vector<Statement>& statements);
137 std::string source_;
138};
139
142 public:
143 explicit FlowBuilder(std::string name, bool interface_only = false);
144
145 FlowPlan& interface() { return plan_; }
146
147 const FlowPlan& interface() const { return plan_; }
148
149 absl::Status AddPort(
150 std::string name, syntax::TypeExpression type,
152 bool unary = true, bool required = false, std::string description = {});
153 absl::Status AddStatement(Statement statement);
154 absl::Status AddInitialize(std::string_view name, const Expression& value,
155 std::optional<syntax::TypeExpression> type = {});
156 absl::Status AddPipe(const Expression& value, const Expression& destination);
157 absl::Status AddImport(std::string reference, std::string alias,
158 std::string symbol = {});
159 absl::Status AddDeclaration(const FlowPlan& interface);
160 absl::Status AddStruct(DtoPlan shape);
161 absl::StatusOr<std::string> Emit() const;
162
163 private:
164 FlowPlan plan_;
165 std::vector<std::string> statements_;
166 std::vector<syntax::Import> imports_;
167};
168
171 public:
172 explicit StructBuilder(std::string name) { plan_.name = std::move(name); }
173
174 explicit StructBuilder(DtoPlan shape) : plan_(std::move(shape)) {}
175
176 DtoPlan& shape() { return plan_; }
177
178 const DtoPlan& shape() const { return plan_; }
179
180 absl::Status AddField(std::string name, syntax::TypeExpression type,
181 bool required = false,
182 std::optional<Expression> default_value = {},
183 std::string description = {});
184 absl::StatusOr<std::string> Emit() const;
185
186 private:
187 DtoPlan plan_;
188};
189
192 std::string document;
193 uint64_t revision = 0;
194 std::string name;
195 std::string kind;
196 size_t occurrence = 0;
197 size_t start = 0;
198 size_t end = 0;
199};
200
203 uint64_t revision = 0;
204 std::vector<Edit> edits;
205 std::vector<Diagnostic> diagnostics;
206};
207
211 absl::flat_hash_map<std::string, std::vector<Edit>> edits;
212 std::vector<Diagnostic> diagnostics;
213};
214
217 public:
218 explicit ModuleDocument(std::string identity = "<memory>",
219 std::string source = {});
220
221 const std::string& identity() const { return identity_; }
222
223 const std::string& source() const { return source_; }
224
225 uint64_t revision() const { return revision_; }
226
227 std::vector<DocumentSymbolHandle> Symbols() const;
228 absl::StatusOr<DocumentChange> Apply(uint64_t revision,
229 std::vector<Edit> edits);
230 absl::StatusOr<DocumentChange> Insert(const FlowBuilder& flow);
231 absl::StatusOr<DocumentChange> InsertStruct(DtoPlan shape);
232 absl::StatusOr<DocumentChange> UpsertDeclaration(
233 FlowPlan interface, const std::vector<DtoPlan>& types = {},
234 std::optional<DocumentSymbolHandle> symbol = {});
235 absl::StatusOr<DocumentChange> Update(const DocumentSymbolHandle& symbol,
236 const FlowBuilder& flow);
237 absl::StatusOr<DocumentChange> UpdateStruct(
238 const DocumentSymbolHandle& symbol, const DtoPlan& shape);
239 absl::StatusOr<DocumentChange> Remove(const DocumentSymbolHandle& symbol);
240 absl::StatusOr<DocumentChange> SetExported(const DocumentSymbolHandle& symbol,
241 bool value);
242 absl::StatusOr<DocumentChange> UpsertImport(
243 std::string reference, std::string alias,
244 std::optional<DocumentSymbolHandle> scope = {}, std::string symbol = {});
245 absl::StatusOr<DocumentChange> RemoveImport(
246 std::string alias, std::optional<DocumentSymbolHandle> scope = {});
247 absl::StatusOr<DocumentChange> Rename(const DocumentSymbolHandle& symbol,
248 std::string name);
249 absl::StatusOr<ModuleGraphChange> RenameInGraph(
250 const DocumentSymbolHandle& symbol, std::string name,
251 const ModuleSources& sources = {}) const;
252 absl::StatusOr<DocumentChange> RenameImport(
253 std::string alias, std::string name,
254 std::optional<DocumentSymbolHandle> scope = {});
255 absl::StatusOr<FlowPlan> EffectiveSchema(std::string_view name,
256 const ModuleSources& sources = {},
257 ModuleResolver resolver = {},
258 CompilationLimits limits = {}) const;
259 LinkedModule Link(const ModuleSources& sources = {},
260 ModuleResolver resolver = {}, CompilationLimits limits = {},
261 CompilationBudget* absl_nullable budget = nullptr) const;
262 std::vector<Diagnostic> Check(const ModuleSources& sources = {},
263 ModuleResolver resolver = {},
264 CompilationLimits limits = {}) const;
265
266 private:
267 absl::Status Validate(const DocumentSymbolHandle& symbol) const;
268 std::string identity_;
269 std::string source_;
270 uint64_t revision_ = 0;
271};
272
274absl::StatusOr<std::string> DeclarationSource(const FlowPlan& plan);
275} // namespace a11::flow
276#endif // A11_FLOW_DOCUMENT_H_
A native source expression whose emitter supplies required grouping.
Definition document.h:39
static absl::StatusOr< Expression > Builtin(std::string_view name, std::vector< Expression > arguments)
Definition document.cc:388
static absl::StatusOr< Expression > Node(std::optional< Expression > id={}, std::string_view node_map={})
Definition document.cc:406
absl::StatusOr< Expression > Field(std::string_view name) const
Definition document.cc:439
static absl::StatusOr< Expression > InvokeWith(std::string_view action, std::vector< std::pair< std::string, Expression > > arguments, const CallOptions &options)
Definition document.cc:309
static absl::StatusOr< Expression > Reference(std::string name)
Definition document.cc:236
absl::StatusOr< Expression > Pipeline(std::string_view stage, std::optional< Expression > argument={}) const
Definition document.cc:444
static absl::StatusOr< Expression > Completion(std::string_view operation, const Expression &subject)
Definition document.cc:417
static absl::StatusOr< Expression > Invoke(std::string_view action, std::vector< std::pair< std::string, Expression > > arguments={}, bool remote=false, bool tolerant=false, std::string_view node_map={})
Definition document.cc:281
static absl::StatusOr< Expression > Literal(nlohmann::json value)
Definition document.cc:241
static absl::StatusOr< Expression > Object(std::vector< std::pair< std::string, Expression > > fields)
Definition document.cc:368
const std::string & source() const
Definition document.h:75
static absl::StatusOr< Expression > Array(std::vector< Expression > items)
Definition document.cc:380
absl::StatusOr< Expression > Cast(const syntax::TypeExpression &type) const
Definition document.cc:429
absl::StatusOr< Expression > Transfer(const Expression &destination, bool tolerant=false) const
Definition document.cc:228
absl::StatusOr< Expression > PipelineInvoke(std::string_view action, std::vector< std::pair< std::string, Expression > > arguments, const CallOptions &options) const
Definition document.cc:459
Expression Take(bool optional=false) const
Definition document.cc:223
absl::StatusOr< Expression > Index(const Expression &index) const
Definition document.cc:435
An implemented flow or interface, constructed with native typed helpers.
Definition document.h:141
absl::StatusOr< std::string > Emit() const
Definition document.cc:681
absl::Status AddImport(std::string reference, std::string alias, std::string symbol={})
Definition document.cc:634
const FlowPlan & interface() const
Definition document.h:147
absl::Status AddStruct(DtoPlan shape)
Definition document.cc:670
absl::Status AddStatement(Statement statement)
Definition document.cc:584
absl::Status AddInitialize(std::string_view name, const Expression &value, std::optional< syntax::TypeExpression > type={})
Definition document.cc:616
absl::Status AddPipe(const Expression &value, const Expression &destination)
Definition document.cc:624
absl::Status AddPort(std::string name, syntax::TypeExpression type, syntax::PortDirection direction=syntax::PortDirection::kInput, bool unary=true, bool required=false, std::string description={})
Definition document.cc:598
absl::Status AddDeclaration(const FlowPlan &interface)
Definition document.cc:659
FlowPlan & interface()
Definition document.h:145
Editable source, separate from immutable linked and executable snapshots.
Definition document.h:216
LinkedModule Link(const ModuleSources &sources={}, ModuleResolver resolver={}, CompilationLimits limits={}, CompilationBudget *absl_nullable budget=nullptr) const
Definition document.cc:1651
absl::StatusOr< DocumentChange > RemoveImport(std::string alias, std::optional< DocumentSymbolHandle > scope={})
Definition document.cc:1142
absl::StatusOr< DocumentChange > UpsertImport(std::string reference, std::string alias, std::optional< DocumentSymbolHandle > scope={}, std::string symbol={})
Definition document.cc:1061
absl::StatusOr< ModuleGraphChange > RenameInGraph(const DocumentSymbolHandle &symbol, std::string name, const ModuleSources &sources={}) const
Definition document.cc:1235
const std::string & identity() const
Definition document.h:221
absl::StatusOr< DocumentChange > Rename(const DocumentSymbolHandle &symbol, std::string name)
Definition document.cc:1175
uint64_t revision() const
Definition document.h:225
absl::StatusOr< DocumentChange > UpdateStruct(const DocumentSymbolHandle &symbol, const DtoPlan &shape)
Definition document.cc:998
absl::StatusOr< DocumentChange > RenameImport(std::string alias, std::string name, std::optional< DocumentSymbolHandle > scope={})
Definition document.cc:1457
absl::StatusOr< DocumentChange > Apply(uint64_t revision, std::vector< Edit > edits)
Definition document.cc:839
absl::StatusOr< DocumentChange > InsertStruct(DtoPlan shape)
Definition document.cc:891
absl::StatusOr< DocumentChange > UpsertDeclaration(FlowPlan interface, const std::vector< DtoPlan > &types={}, std::optional< DocumentSymbolHandle > symbol={})
Definition document.cc:901
absl::StatusOr< DocumentChange > Remove(const DocumentSymbolHandle &symbol)
Definition document.cc:1021
absl::StatusOr< DocumentChange > Insert(const FlowBuilder &flow)
Definition document.cc:882
std::vector< DocumentSymbolHandle > Symbols() const
Definition document.cc:794
absl::StatusOr< DocumentChange > SetExported(const DocumentSymbolHandle &symbol, bool value)
Definition document.cc:1027
absl::StatusOr< DocumentChange > Update(const DocumentSymbolHandle &symbol, const FlowBuilder &flow)
Definition document.cc:971
absl::StatusOr< FlowPlan > EffectiveSchema(std::string_view name, const ModuleSources &sources={}, ModuleResolver resolver={}, CompilationLimits limits={}) const
Definition document.cc:1625
const std::string & source() const
Definition document.h:223
std::vector< Diagnostic > Check(const ModuleSources &sources={}, ModuleResolver resolver={}, CompilationLimits limits={}) const
Definition document.cc:1659
Typed statements for constructing executable bodies.
Definition document.h:98
static absl::StatusOr< Statement > Initialize(std::string_view name, const Expression &value, std::optional< syntax::TypeExpression > type={})
Definition document.cc:486
static absl::StatusOr< Statement > After(const std::vector< Expression > &subjects, const std::vector< Statement > &body, bool tolerant=false)
Definition document.cc:562
static absl::StatusOr< Statement > Block(const std::vector< Statement > &body, bool tolerant=false)
Definition document.cc:579
static absl::StatusOr< Statement > WaitAll()
Definition document.cc:511
static absl::StatusOr< Statement > If(const Expression &condition, const std::vector< Statement > &then_body, const std::vector< Statement > &else_body={})
Definition document.cc:526
std::string TakeSource() &&
Definition document.h:130
static absl::StatusOr< Statement > Wait(const Expression &subject, bool close=false)
Definition document.cc:503
static absl::StatusOr< Statement > Cancel(const Expression &subject)
Definition document.cc:515
static absl::StatusOr< Statement > IfSome(std::string_view name, const Expression &option, const std::vector< Statement > &then_body, const std::vector< Statement > &else_body={})
Definition document.cc:537
const std::string & source() const
Definition document.h:128
static absl::StatusOr< Statement > For(std::string_view variable, const Expression &source, const std::vector< Statement > &body, int parallel=1)
Definition document.cc:550
static absl::StatusOr< Statement > Pipe(const Expression &value, const Expression &destination)
Definition document.cc:498
static absl::StatusOr< Statement > Fail(const Expression &code, std::optional< Expression > message={})
Definition document.cc:519
Construct a struct using the language's existing shape descriptor.
Definition document.h:170
StructBuilder(DtoPlan shape)
Definition document.h:174
absl::Status AddField(std::string name, syntax::TypeExpression type, bool required=false, std::optional< Expression > default_value={}, std::string description={})
Definition document.cc:710
const DtoPlan & shape() const
Definition document.h:178
StructBuilder(std::string name)
Definition document.h:172
DtoPlan & shape()
Definition document.h:176
absl::StatusOr< std::string > Emit() const
Definition document.cc:749
std::string value
Definition discover.cc:100
std::string type
The type and what follows it: string required, list[a11.Chunk] stream.
Definition format.cc:52
std::string name
The declaration name and its colon.
Definition format.cc:50
std::string direction
in, out or header as written; empty for a shape field.
Definition format.cc:48
std::string description
The description, quoted exactly as it was written.
Definition format.cc:54
CompilationLimits limits
Definition main.cc:148
std::vector< std::string > arguments
argv for the program, [0] = path.
Definition main.cc:136
CompilationBudget budget
Definition lsp.cc:289
PortDirection
Which side of the descriptor a port lands on, spelled as the plan spells it.
Definition syntax.h:624
Definition catalogue.cc:29
std::function< absl::StatusOr< ModuleSource >(std::string_view reference, std::string_view importer)> ModuleResolver
Definition module.h:39
absl::flat_hash_map< std::string, std::string > ModuleSources
Definition module.h:37
absl::StatusOr< std::string > DeclarationSource(const FlowPlan &plan)
Emit a declaration without introducing an action-layer dependency.
Definition document.cc:703
std::string subject
What to call it in the message: ‘'Source’, orthe pattern`.
Definition resolve.cc:6292
bool tolerant
For an outcome: whether a bad one is the flow's business or the subject's.
Definition resolve.cc:812
std::string shape
Declared shape of stream values, retained through compatible stages.
Definition resolve.cc:814
size_t symbol
The symbol this reads through, for the usage counts.
Definition resolve.cc:804
int parallel
How many passes may run at once, so until can refuse to be written on a loop where "the pass that jus...
Definition resolve.cc:6494
stores::ChunkStoreReaderOptions options
Definition runtime_streams.cc:31
Typed modifiers for an invocation expression.
Definition document.h:84
std::vector< Expression > after
Definition document.h:92
bool remote
Definition document.h:85
std::vector< std::string > forward
Definition document.h:94
std::optional< absl::Duration > timeout
Definition document.h:89
std::string node_map
Definition document.h:88
std::vector< std::pair< std::string, Expression > > headers
Definition document.h:93
std::optional< Expression > deadline
Definition document.h:90
bool tee
Definition document.h:87
bool tolerant
Definition document.h:86
std::optional< Expression > id
Definition document.h:91
The source edits committed atomically by one document transaction.
Definition document.h:202
uint64_t revision
Definition document.h:203
std::vector< Diagnostic > diagnostics
Definition document.h:205
std::vector< Edit > edits
Definition document.h:204
A symbol's identity in one revision of an owning document.
Definition document.h:191
size_t occurrence
Definition document.h:196
std::string kind
Definition document.h:195
size_t start
Definition document.h:197
std::string document
Definition document.h:192
std::string name
Definition document.h:194
size_t end
Definition document.h:198
uint64_t revision
Definition document.h:193
One compiled struct: a shape a port may be typed with.
Definition plan.h:87
std::string name
Definition plan.h:88
One compiled flow: what a caller sees, and what the runtime will do.
Definition plan.h:157
A validated rename transaction over the supplied source snapshots.
Definition document.h:209
absl::flat_hash_map< std::string, std::vector< Edit > > edits
Definition document.h:211
ModuleSources sources
Definition document.h:210
std::vector< Diagnostic > diagnostics
Definition document.h:212
Definition syntax.h:105
std::vector< Value > items
Definition values.cc:1824