A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
vocabulary.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_VOCABULARY_H_
18#define A11_FLOW_VOCABULARY_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_set.h>
27#include <absl/types/span.h>
28
29namespace a11::flow {
30
33namespace vocabulary {
34
37std::string Canonical(std::string_view word);
38
40bool IsShouted(std::string_view word);
41
75
77struct EntryPort {
78 std::string_view name;
79 std::string_view type;
81 bool unary;
82 std::string_view description;
83};
84
86absl::Span<const EntryPort> EntryPorts();
87
88absl::Span<const std::string_view> Stages();
89
91std::optional<StageArgument> StageTakes(std::string_view canonical_name);
92
94std::string_view StageArgumentName(StageArgument argument);
95
97struct WordDoc {
99 std::string_view summary;
101 std::string_view takes;
103 std::string_view detail;
106 std::string_view example;
107};
108
110const WordDoc* absl_nullable StageDocumentation(
111 std::string_view canonical_name);
112
115const WordDoc* absl_nullable BuiltinDocumentation(
116 std::string_view canonical_name);
117
120enum class WordRole {
122 kStage,
125 kBuiltin,
132 kClause,
134 kModifier,
137 kSource,
144 kType,
146 kConstant,
152 kLogLevel,
159 kSymbol,
160};
161
163bool IsPrimitiveType(std::string_view name);
164
166const WordDoc* absl_nullable AnyDocumentation(std::string_view canonical_name);
167
169absl::Span<const WordRole> WordRoles();
170
172std::string_view WordRoleName(WordRole role);
173
175std::vector<std::string_view> WordsOf(WordRole role);
176
181const WordDoc* absl_nullable Documentation(WordRole role,
182 std::string_view canonical_name);
183
185absl::Span<const std::string_view> OrderedSymbols();
186
188const absl::flat_hash_set<std::string_view>& BareStages();
189
191const absl::flat_hash_set<std::string_view>& ParallelStages();
192
194const absl::flat_hash_set<std::string_view>& ReducingStages();
195
197const absl::flat_hash_set<std::string_view>& PositionalStages();
198
200const absl::flat_hash_set<std::string_view>& Builtins();
201
203const absl::flat_hash_set<std::string_view>& TypeNames();
204bool IsNumericType(std::string_view name);
205
207absl::Span<const int> TypeParameters(std::string_view canonical_name);
208
210absl::Span<const std::string_view> OrderedTypeNames();
211
213absl::Span<const std::string_view> OrderedBuiltins();
214
216const absl::flat_hash_set<std::string_view>& StatementWords();
217
219absl::Span<const std::string_view> OrderedStatements();
220
222const absl::flat_hash_set<std::string_view>& ClauseWords();
223
225absl::Span<const std::string_view> OrderedClauseWords();
226
228const absl::flat_hash_set<std::string_view>& DeclarationWords();
229
231absl::Span<const std::string_view> OrderedDeclarations();
232
234const absl::flat_hash_set<std::string_view>& ModifierWords();
235
237absl::Span<const std::string_view> OrderedModifiers();
238
240const absl::flat_hash_set<std::string_view>& SourceWords();
241
243const absl::flat_hash_set<std::string_view>& PortModifierWords();
244
246absl::Span<const std::string_view> OrderedPortModifiers();
247
249const absl::flat_hash_set<std::string_view>& FieldModifierWords();
250
252absl::Span<const std::string_view> OrderedFieldModifiers();
253
255absl::Span<const std::string_view> StatusCodes();
256
258bool IsStatusCode(std::string_view word);
259
261absl::Span<const std::string_view> LogLevels();
262
264bool IsLogLevel(std::string_view word);
265
267const absl::flat_hash_set<std::string_view>& StatusFields();
268
270absl::Span<const std::string_view> OrderedStatusFields();
271
273const absl::flat_hash_set<std::string_view>& ConstantWords();
274
276const absl::flat_hash_set<std::string_view>& OperatorWords();
277
279absl::Span<const std::string_view> DurationUnits();
280
282std::optional<double> DurationUnitSeconds(std::string_view unit);
283
284} // namespace vocabulary
285} // namespace a11::flow
286
287#endif // A11_FLOW_VOCABULARY_H_
std::string name
The declaration name and its colon.
Definition format.cc:50
size_t unit
Definition module.cc:40
const absl::flat_hash_set< std::string_view > & StatementWords()
Words that open a statement, and so are not read as a name there.
absl::Span< const std::string_view > OrderedDeclarations()
The declarations in the order they are written in a flow.
absl::Span< const std::string_view > OrderedModifiers()
Call modifiers in source order, including forward headers.
std::string_view WordRoleName(WordRole role)
Role name used by flow.vocabulary/v1, such as port_modifier.
bool IsStatusCode(std::string_view word)
Whether a word names a canonical status code, in either case.
bool IsShouted(std::string_view word)
Whether the word, canonicalised, is written entirely in upper case.
std::vector< std::string_view > WordsOf(WordRole role)
Words documented under role, in listing order.
const absl::flat_hash_set< std::string_view > & StatusFields()
The fields of a status record: what reading an outcome gives.
std::string_view StageArgumentName(StageArgument argument)
The spelling of a stage argument kind in the output formats.
absl::Span< const std::string_view > StatusCodes()
Abseil's canonical status codes, lower case, which is what fail names.
absl::Span< const std::string_view > OrderedStatements()
Statement starters in completion order, most common first.
absl::Span< const std::string_view > OrderedStatusFields()
The same, in the order a status record is written and read.
const WordDoc *absl_nullable AnyDocumentation(std::string_view canonical_name)
Returns documentation under any role, or null when none exists.
const WordDoc *absl_nullable BuiltinDocumentation(std::string_view canonical_name)
Built-in function documentation, or null for an unknown function.
const absl::flat_hash_set< std::string_view > & ClauseWords()
Words inside statements, such as else, parallel, and max.
std::optional< double > DurationUnitSeconds(std::string_view unit)
The seconds one of that unit is, or nullopt if it is not a unit.
const absl::flat_hash_set< std::string_view > & PortModifierWords()
What a port says about itself after its type: stream, required.
absl::Span< const EntryPort > EntryPorts()
Implicit entry-flow ports in declaration order.
const WordDoc *absl_nullable Documentation(WordRole role, std::string_view canonical_name)
What one word of role does, or nullptr where that table has no entry.
const absl::flat_hash_set< std::string_view > & ParallelStages()
Stages that accept parallel n for concurrent value processing.
bool IsLogLevel(std::string_view word)
Whether a word names a log level, in either case.
bool IsPrimitiveType(std::string_view name)
Whether a standard type and its conversion are in the primitive prelude.
const absl::flat_hash_set< std::string_view > & SourceWords()
Words that open a pipeline source rather than naming one: status, zip.
const absl::flat_hash_set< std::string_view > & OperatorWords()
Operators that are words: and, or, not.
absl::Span< const std::string_view > OrderedSymbols()
Punctuation and non-word operators, in listing order.
const absl::flat_hash_set< std::string_view > & Builtins()
Built-in functions available to flow expressions.
absl::Span< const std::string_view > OrderedTypeNames()
The built-in port type names, in the order a listing reads them.
absl::Span< const std::string_view > OrderedFieldModifiers()
Field modifiers in required source order.
const absl::flat_hash_set< std::string_view > & DeclarationWords()
Words that declare something inside a flow.
const absl::flat_hash_set< std::string_view > & ReducingStages()
Stages that reduce a whole stream to one value.
const absl::flat_hash_set< std::string_view > & FieldModifierWords()
Modifiers after a struct field's type.
absl::Span< const std::string_view > OrderedPortModifiers()
The same, in the order a port writes them.
absl::Span< const std::string_view > DurationUnits()
Duration suffixes a number may carry, shortest unit first.
const absl::flat_hash_set< std::string_view > & ConstantWords()
Literals that are words: true, false, null, it.
const absl::flat_hash_set< std::string_view > & PositionalStages()
Stages that select or group stream values.
WordRole
The grammar role under which a word is documented.
Definition vocabulary.h:120
@ kConstant
A literal that is a word: true, it. [ConstantWords].
@ kDeclaration
A word that declares something: flow, in, header.
@ kStatement
A word that opens a statement: run, value, for. [StatementWords].
@ kSymbol
Punctuation and the operators that are not words, keyed by the symbol itself: |, ->,...
@ kClause
A word that continues a statement: else, parallel. [ClauseWords].
@ kFieldModifier
What a struct field says about itself after its type.
@ kLogLevel
The severity a log or logf may name. [LogLevels].
@ kDurationUnit
A duration suffix: ms, h. [DurationUnits].
@ kStage
A pipeline stage: | first 3. Same table as [StageDocumentation].
@ kModifier
A word that may follow a call's ): via, timeout. [ModifierWords].
@ kOperatorWord
An operator that is a word: and, not. [OperatorWords].
@ kSource
A word that opens a pipeline source rather than naming one: status, zip.
@ kBuiltin
A built-in function, where it is called.
@ kStatusCode
One of Abseil's canonical status codes. [StatusCodes].
@ kStatusField
A field of a status record, read after a .. [StatusFields].
@ kPortModifier
What a port says about itself after its type. [PortModifierWords].
absl::Span< const std::string_view > OrderedBuiltins()
The fixed function set, in the order a listing reads it.
const absl::flat_hash_set< std::string_view > & BareStages()
Stages accepted without a leading |, such as hits where it.ok.
const absl::flat_hash_set< std::string_view > & ModifierWords()
Words that may follow a call's closing parenthesis.
bool IsNumericType(std::string_view name)
const WordDoc *absl_nullable StageDocumentation(std::string_view canonical_name)
Stage documentation, or null for an unknown stage.
absl::Span< const WordRole > WordRoles()
Every role, for something walking all of them.
const absl::flat_hash_set< std::string_view > & TypeNames()
Built-in port type names. Ports also accept registered tags and media types.
std::optional< StageArgument > StageTakes(std::string_view canonical_name)
What a stage takes, or nullopt if the name is not a stage.
absl::Span< const std::string_view > OrderedClauseWords()
The same, in the order they read.
absl::Span< const int > TypeParameters(std::string_view canonical_name)
Allowed type-parameter counts for a built-in type; empty means none.
std::string Canonical(std::string_view word)
Lowercases uniformly upper-case words; leaves mixed-case words unchanged.
absl::Span< const std::string_view > LogLevels()
Log levels accepted by log and logf, quietest first.
StageArgument
What a stage takes after its name.
Definition vocabulary.h:43
@ kOptionalExpression
An expression, optional, with it bound: | sum, | sum it.price.
@ kLogFormat
An optional level word, a format string, and the values to fill it with, with it bound to the value i...
@ kString
A string, required: | strformat "took {}".
@ kFold
A literal to start from, a name for what is carried, and the expression that folds one value into it:...
@ kNone
Nothing: | collect, | count.
@ kSortKey
An optional by key with it bound, and an optional desc: | sort, | sort by it.score desc.
@ kNumber
A whole number of values: | first 3.
@ kDuration
A length of time: | timeout 30s, | pace 100ms.
@ kStream
Another stream to read after this one: | then other.
@ kOptionalString
A string, optional: | join, | join ", ".
@ kType
A named type: | as i32.
@ kExpression
An expression, with it bound to the value in hand: | where it.ok.
@ kLog
An optional level word and an optional expression, with it bound to the value in hand: | log,...
absl::Span< const std::string_view > Stages()
Definition catalogue.cc:29
One implicit port of the entry flow.
Definition vocabulary.h:77
std::string_view type
Definition vocabulary.h:79
std::string_view name
Definition vocabulary.h:78
std::string_view description
Definition vocabulary.h:82
bool unary
Whether it carries one value rather than a stream.
Definition vocabulary.h:81
Documentation for a language word, shared by editor and CLI surfaces.
Definition vocabulary.h:97
std::string_view example
Single-line examples use newlines; multiline examples use blank lines.
Definition vocabulary.h:106
std::string_view takes
Argument description in source terms, or empty for no argument.
Definition vocabulary.h:101
std::string_view detail
Behavior description as a short Markdown paragraph.
Definition vocabulary.h:103
std::string_view summary
One-line description shown in a summary.
Definition vocabulary.h:99