A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
navigate.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_NAVIGATE_H_
18#define A11_FLOW_NAVIGATE_H_
19
20#include <cstddef>
21#include <optional>
22#include <string>
23#include <string_view>
24#include <vector>
25
26#include "a11/flow/catalogue.h"
27#include "a11/flow/diagnostic.h"
28#include "a11/flow/limits.h"
29#include "a11/flow/syntax.h"
30#include "a11/flow/vocabulary.h"
31
32namespace a11::flow {
33struct LinkedModule;
34
35// Moving around a document: what is under the caret, what the file declares,
36// and where a name was bound.
37
46enum class SymbolClass {
47 kModule,
48 kFlow,
49 kDto,
50 kField,
51 kPort,
52 kHeader,
54 kNode,
55 kCall,
61};
62
63std::string_view SymbolClassName(SymbolClass kind);
64
67 std::string name;
70 std::string detail;
72 std::string port_direction;
73 std::string port_type;
74 bool port_stream = false;
75 bool port_required = false;
80 std::vector<DocumentSymbol> children;
81};
82
86std::vector<DocumentSymbol> Symbols(
87 std::string_view source, CompilationLimits limits = {},
88 CompilationBudget* absl_nullable budget = nullptr);
89
94 bool found = false;
96 std::string text;
99 std::string summary;
101 std::string detail;
103 std::string markdown;
107 bool has_definition = false;
114 std::optional<catalogue::Origin> origin;
115};
116
119 std::string_view source, size_t offset,
122 CompilationBudget* absl_nullable budget = nullptr,
123 const LinkedModule* absl_nullable linked = nullptr);
124
129std::string ActionMarkdown(const catalogue::ActionInfo& action);
130
134std::string PortMarkdown(std::string_view name, std::string_view type,
135 bool required, bool unary,
136 std::string_view description);
137
140std::string FlowMarkdown(const FlowPlan& flow);
141
143std::string ShapeMarkdown(const DtoPlan& shape);
144
157std::string WordMarkdown(std::string_view name, vocabulary::WordRole role);
158
162std::string StageMarkdown(std::string_view name);
163
165std::string BuiltinMarkdown(std::string_view name);
166
168inline constexpr std::string_view kSymbolsFormat = "flow.symbols/v1";
170inline constexpr std::string_view kHoverFormat = "flow.hover/v1";
172inline constexpr std::string_view kDefinitionFormat = "flow.definition/v1";
173
174} // namespace a11::flow
175
176#endif // A11_FLOW_NAVIGATE_H_
Everything the tools know about the world, in one place.
Definition catalogue.h:91
static const Catalogue & Builtin()
The embedded snapshot: what a standalone tool knows with nothing configured.
Definition catalogue.cc:503
TokenKind kind
Definition format.cc:1372
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 description
The description, quoted exactly as it was written.
Definition format.cc:54
CompilationLimits limits
Definition main.cc:148
LinkedModule linked
Definition lsp.cc:290
CompilationBudget budget
Definition lsp.cc:289
catalogue::Catalogue known
Definition lsp.cc:291
WordRole
The grammar role under which a word is documented.
Definition vocabulary.h:120
Definition catalogue.cc:29
Description Describe(std::string_view source, size_t offset, const catalogue::Catalogue &known, CompilationLimits limits, CompilationBudget *budget, const LinkedModule *linked)
Definition navigate.cc:1217
std::string BuiltinMarkdown(std::string_view name)
A built-in function, the same way.
Definition navigate.cc:902
std::string_view SymbolClassName(SymbolClass kind)
Definition navigate.cc:992
std::vector< DocumentSymbol > Symbols(std::string_view source, CompilationLimits limits, CompilationBudget *budget)
Definition navigate.cc:1055
std::string FlowMarkdown(const FlowPlan &flow)
A flow of the document, written out the same way: what it does, then its ports and which direction ea...
Definition navigate.cc:964
@ kPort
A port of this flow, or of a call.
@ kCall
A bound run/call step.
@ kField
A field of something: a status's code, a node's id.
@ kHeader
A header, under its alias.
@ kNode
A node of the flow's own.
@ kFlow
A flow of this file, offered as a call target.
@ kVariable
A loop variable, the index a loop binds, or what a repeat carries.
@ kBarrier
A bound wait/close.
std::string PortMarkdown(std::string_view name, std::string_view type, bool required, bool unary, std::string_view description)
One port, written out as the Markdown a reader wants beside its name.
Definition navigate.cc:950
std::string WordMarkdown(std::string_view name, vocabulary::WordRole role)
One word or mark of the language, written out as reference: what it does, what it takes,...
Definition navigate.cc:886
std::string ActionMarkdown(const catalogue::ActionInfo &action)
An action, written out as the Markdown a reader wants to see: what it does, then every port it has.
Definition navigate.cc:906
constexpr std::string_view kHoverFormat
The format field of the hover envelope.
Definition navigate.h:170
std::string StageMarkdown(std::string_view name)
A pipeline stage, written out as reference.
Definition navigate.cc:898
constexpr std::string_view kSymbolsFormat
The format field of the symbols envelope.
Definition navigate.h:168
SymbolClass
Moving around a document: what is under the caret, what the file declares, and where a name was bound...
Definition navigate.h:46
@ kExternal
Something the language knows about but the document did not declare: an action, a registered type,...
constexpr std::string_view kDefinitionFormat
The format field of the definition envelope.
Definition navigate.h:172
std::string ShapeMarkdown(const DtoPlan &shape)
A struct, written out the same way: how many fields, then each of them.
Definition navigate.cc:984
std::string shape
Declared shape of stream values, retained through compatible stages.
Definition resolve.cc:814
std::uint32_t offset
Definition runtime_streams.cc:36
Host-controlled bounds shared by parsing, linking and semantic analysis.
Definition limits.h:24
What is at one offset, described.
Definition navigate.h:91
std::optional< catalogue::Origin > origin
Where it was declared, when it was declared in another file and something read that file: an action o...
Definition navigate.h:114
Range definition
Definition navigate.h:108
Range range
What the word covers, so an editor can underline exactly it.
Definition navigate.h:105
std::string text
The word or construct itself, as written.
Definition navigate.h:96
std::string detail
Details such as action ports, shape fields, or stage arguments.
Definition navigate.h:101
std::string summary
One line: what it is. an action, ‘a port of 'search’`.
Definition navigate.h:99
std::string markdown
The same as Markdown, which is what an editor's hover wants.
Definition navigate.h:103
SymbolClass kind
Definition navigate.h:97
bool found
Whether anything is there at all.
Definition navigate.h:94
bool has_definition
Where it was declared, when it was declared in this document.
Definition navigate.h:107
One thing a document declares, and the things declared inside it.
Definition navigate.h:66
std::string name
Definition navigate.h:67
bool port_required
Definition navigate.h:75
std::vector< DocumentSymbol > children
Definition navigate.h:80
SymbolClass kind
Definition navigate.h:68
Range selection
Just the name, for "put the caret here".
Definition navigate.h:79
std::string port_type
Definition navigate.h:73
Range range
The whole construct, for "select this symbol".
Definition navigate.h:77
bool port_stream
Definition navigate.h:74
std::string detail
What an editor shows beside the name: a port's type, a call's action.
Definition navigate.h:70
std::string port_direction
Port metadata, populated only when kind is kPort.
Definition navigate.h:72
Half-open span of source, [start, end).
Definition diagnostic.h:68