navigate.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_NAVIGATE_H_
#define A11_FLOW_NAVIGATE_H_
 
#include <cstddef>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
#include "a11/flow/catalogue.h"
#include "a11/flow/diagnostic.h"
#include "a11/flow/syntax.h"
#include "a11/flow/vocabulary.h"
 
namespace a11::flow {
 
// Moving around a document: what is under the caret, what the file declares,
// and where a name was bound.
 
enum class SymbolClass {
  kFlow,
  kDto,
  kField,
  kPort,
  kHeader,
  kNodeMap,
  kNode,
  kCall,
  kBarrier,
  kVariable,
  kExternal,
};
 
std::string_view SymbolClassName(SymbolClass kind);
 
struct DocumentSymbol {
  std::string name;
  SymbolClass kind = SymbolClass::kFlow;
  std::string detail;
  std::string port_direction;
  std::string port_type;
  bool port_stream = false;
  bool port_required = false;
  Range range;
  Range selection;
  std::vector<DocumentSymbol> children;
};
 
std::vector<DocumentSymbol> Symbols(std::string_view source);
 
struct Description {
  bool found = false;
  std::string text;
  SymbolClass kind = SymbolClass::kExternal;
  std::string summary;
  std::string detail;
  std::string markdown;
  Range range;
  bool has_definition = false;
  Range definition;
  // Where it was declared, when it was declared in *another* file and something
  // read that file: an action or a type the catalogue carries an origin for.
  std::optional<catalogue::Origin> origin;
};
 
Description Describe(
    std::string_view source, size_t offset,
    const catalogue::Catalogue& known = catalogue::Catalogue::Builtin());
 
// An action, written out as the Markdown a reader wants to see: what it does,
// then every port it has.
std::string ActionMarkdown(const catalogue::ActionInfo& action);
 
std::string PortMarkdown(std::string_view name, std::string_view type,
                         bool required, bool unary,
                         std::string_view description);
 
std::string FlowMarkdown(const FlowPlan& flow);
 
std::string ShapeMarkdown(const DtoPlan& shape);
 
// One word or mark of the language, written out as reference: what it does,
// what it takes, how it behaves, and a line of Flow using it.
std::string WordMarkdown(std::string_view name, vocabulary::WordRole role);
 
std::string StageMarkdown(std::string_view name);
 
std::string BuiltinMarkdown(std::string_view name);
 
inline constexpr std::string_view kSymbolsFormat = "flow.symbols/v1";
inline constexpr std::string_view kHoverFormat = "flow.hover/v1";
inline constexpr std::string_view kDefinitionFormat = "flow.definition/v1";
 
}  // namespace a11::flow
 
#endif  // A11_FLOW_NAVIGATE_H_