A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
catalogue.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 The A11 Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef A11_FLOW_CATALOGUE_H_
18#define A11_FLOW_CATALOGUE_H_
19
20#include <optional>
21#include <string>
22#include <string_view>
23#include <vector>
24
25#include <absl/base/nullability.h>
26#include <absl/container/flat_hash_map.h>
27#include <nlohmann/json_fwd.hpp>
28
29#include "a11/flow/plan.h"
30
31namespace a11::flow {
32
36namespace catalogue {
37
39struct Origin {
41 std::string file;
42 int line = 1;
43 int column = 1;
44
45 friend bool operator==(const Origin&, const Origin&) = default;
46};
47
49struct PortInfo {
50 std::string name;
53 std::string type;
54 std::string description;
55 bool required = false;
57 bool unary = true;
58};
59
61struct ActionInfo {
62 std::string name;
63 std::string description;
64 std::vector<PortInfo> inputs;
65 std::vector<PortInfo> outputs;
67 std::vector<PortInfo> headers;
69 std::optional<Origin> origin;
70
72 std::vector<Origin> schema_origins;
74 bool schema_complete = true;
75
76 [[nodiscard]] const PortInfo* absl_nullable Port(
77 std::string_view port_name, syntax::PortDirection direction) const;
78 [[nodiscard]] std::vector<std::string> PortNames(
80};
81
83struct TypeInfo {
84 std::string tag;
87 std::optional<Origin> origin;
88};
89
91class Catalogue {
92 public:
95 static const Catalogue& Builtin();
96
98 static Catalogue Of(
99 std::vector<ActionInfo> actions, std::vector<TypeInfo> types = {},
100 absl::flat_hash_map<std::string, std::string> intrinsics = {});
101
106 static Catalogue FromJson(const nlohmann::json& value);
107
113 [[nodiscard]] Catalogue MergedWith(const Catalogue& other) const;
114
116 [[nodiscard]] Program SchemaProgram() const;
117
118 [[nodiscard]] const ActionInfo* absl_nullable Action(
119 std::string_view name) const;
120 [[nodiscard]] const TypeInfo* absl_nullable Type(std::string_view tag) const;
121
122 [[nodiscard]] const std::vector<ActionInfo>& actions() const {
123 return actions_;
124 }
125
126 [[nodiscard]] const std::vector<TypeInfo>& types() const { return types_; }
127
128 const absl::flat_hash_map<std::string, std::string>& intrinsics() const {
129 return intrinsics_;
130 }
131
132 [[nodiscard]] bool Empty() const {
133 return actions_.empty() && types_.empty() && intrinsics_.empty();
134 }
135
136 [[nodiscard]] nlohmann::json ToJson() const;
137
138 private:
139 std::vector<ActionInfo> actions_;
140 std::vector<TypeInfo> types_;
141 absl::flat_hash_map<std::string, std::string> intrinsics_;
142};
143
145inline constexpr std::string_view kCatalogueFormat = "flow.catalogue/v1";
146
147} // namespace catalogue
148} // namespace a11::flow
149
150#endif // A11_FLOW_CATALOGUE_H_
Everything the tools know about the world, in one place.
Definition catalogue.h:91
bool Empty() const
Definition catalogue.h:132
static Catalogue Of(std::vector< ActionInfo > actions, std::vector< TypeInfo > types={}, absl::flat_hash_map< std::string, std::string > intrinsics={})
Builds a catalogue from action and type entries.
Definition catalogue.cc:283
static Catalogue FromJson(const nlohmann::json &value)
The catalogue value describes, in the shape [ToJson] writes.
Definition catalogue.cc:293
const TypeInfo *absl_nullable Type(std::string_view tag) const
Definition catalogue.cc:494
const ActionInfo *absl_nullable Action(std::string_view name) const
Definition catalogue.cc:485
const std::vector< TypeInfo > & types() const
Definition catalogue.h:126
const std::vector< ActionInfo > & actions() const
Definition catalogue.h:122
const absl::flat_hash_map< std::string, std::string > & intrinsics() const
Definition catalogue.h:128
Catalogue MergedWith(const Catalogue &other) const
This catalogue with other laid over it.
Definition catalogue.cc:442
Program SchemaProgram() const
Interfaces and shapes used as analysis evidence by the native resolver.
Definition catalogue.cc:404
static const Catalogue & Builtin()
The embedded snapshot: what a standalone tool knows with nothing configured.
Definition catalogue.cc:503
nlohmann::json ToJson() const
Definition catalogue.cc:355
std::string value
Definition discover.cc:100
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
constexpr std::string_view kCatalogueFormat
The format field of the catalogue envelope.
Definition catalogue.h:145
PortDirection
Which side of the descriptor a port lands on, spelled as the plan spells it.
Definition syntax.h:624
Definition catalogue.cc:29
One compiled struct: a shape a port may be typed with.
Definition plan.h:87
Every flow and shape one source file declares.
Definition plan.h:200
One action a flow may run or call.
Definition catalogue.h:61
std::string name
Definition catalogue.h:62
std::vector< PortInfo > headers
Header names the action declares, with what each is for.
Definition catalogue.h:67
std::vector< PortInfo > inputs
Definition catalogue.h:64
std::vector< std::string > PortNames(syntax::PortDirection direction) const
Definition catalogue.cc:271
std::string description
Definition catalogue.h:63
std::optional< Origin > origin
Where the declaration is, when it was found by reading source.
Definition catalogue.h:69
std::vector< PortInfo > outputs
Definition catalogue.h:65
bool schema_complete
Source discovery may omit computed members; live schemas are complete.
Definition catalogue.h:74
std::vector< Origin > schema_origins
All interfaces contributing to the effective schema.
Definition catalogue.h:72
const PortInfo *absl_nullable Port(std::string_view port_name, syntax::PortDirection direction) const
Definition catalogue.cc:259
Source location of a discovered entry, with 1-based line and column.
Definition catalogue.h:39
int column
Definition catalogue.h:43
int line
Definition catalogue.h:42
std::string file
Path supplied to the scanner, retaining its absolute or relative form.
Definition catalogue.h:41
friend bool operator==(const Origin &, const Origin &)=default
One port of an action, as a tool needs to show it.
Definition catalogue.h:49
std::string description
Definition catalogue.h:54
std::string type
The type as the action's schema spells it: a Python type name, a serialisation tag,...
Definition catalogue.h:53
std::string name
Definition catalogue.h:50
bool unary
Whether the port carries one value rather than a stream.
Definition catalogue.h:57
bool required
Definition catalogue.h:55
A registered type, identified by its Flow tag and described as a [DtoPlan].
Definition catalogue.h:83
std::optional< Origin > origin
Where the declaration is, when it was found by reading source.
Definition catalogue.h:87
DtoPlan shape
Definition catalogue.h:85
std::string tag
Definition catalogue.h:84