slang::syntax::SyntaxTree class

The SyntaxTree is the easiest way to interface with the lexer / preprocessor / parser stack.

Give it some source text and it produces a parse tree.

The SyntaxTree object owns all of the memory for the parse tree, so it must live for as long as you need to access its syntax nodes.

Public static functions

static auto fromFile(std::string_view path) -> TreeOrError
Creates a syntax tree from a full compilation unit.
static auto fromFile(std::string_view path, SourceManager& sourceManager, const Bag& options = {}) -> TreeOrError
Creates a syntax tree from a full compilation unit.
static auto fromFiles(std::span<const std::string_view> paths) -> TreeOrError
Creates a syntax tree by concatenating several files loaded from disk.
static auto fromFiles(std::span<const std::string_view> paths, SourceManager& sourceManager, const Bag& options = {}) -> TreeOrError
Creates a syntax tree by concatenating several files loaded from disk.
static auto fromText(std::string_view text, std::string_view name = "source", std::string_view path = "") -> std::shared_ptr<SyntaxTree>
Creates a syntax tree by guessing at what might be in the given source snippet.
static auto fromText(std::string_view text, const Bag& options, std::string_view name = "source"sv, std::string_view path = "") -> std::shared_ptr<SyntaxTree>
Creates a syntax tree by guessing at what might be in the given source snippet.
static auto fromText(std::string_view text, SourceManager& sourceManager, std::string_view name = "source"sv, std::string_view path = "", const Bag& options = {}, const SourceLibrary* library = nullptr) -> std::shared_ptr<SyntaxTree>
Creates a syntax tree by guessing at what might be in the given source snippet.
static auto fromFileInMemory(std::string_view text, SourceManager& sourceManager, std::string_view name = "source"sv, std::string_view path = "", const Bag& options = {}) -> std::shared_ptr<SyntaxTree>
Creates a syntax tree from a full compilation unit already in memory.
static auto fromBuffer(const SourceBuffer& buffer, SourceManager& sourceManager, const Bag& options = {}, MacroList inheritedMacros = {}) -> std::shared_ptr<SyntaxTree>
Creates a syntax tree from an already loaded source buffer.
static auto fromBuffers(std::span<const SourceBuffer> buffers, SourceManager& sourceManager, const Bag& options = {}, MacroList inheritedMacros = {}) -> std::shared_ptr<SyntaxTree>
Creates a syntax tree by concatenating several loaded source buffers.
static auto fromLibraryMapFile(std::string_view path, SourceManager& sourceManager, const Bag& options = {}) -> std::shared_ptr<SyntaxTree>
Creates a syntax tree from a library map file.
static auto fromLibraryMapText(std::string_view text, SourceManager& sourceManager, std::string_view name = "source"sv, std::string_view path = "", const Bag& options = {}) -> std::shared_ptr<SyntaxTree>
Creates a syntax tree from a library map located in memory.
static auto fromLibraryMapBuffer(const SourceBuffer& buffer, SourceManager& sourceManager, const Bag& options = {}) -> std::shared_ptr<SyntaxTree>
Creates a syntax tree from a library map already loaded into a source buffer.
static auto getDefaultSourceManager() -> SourceManager&
This is a shared default source manager for cases where the user doesn't care about managing the lifetime of loaded source.

Public functions

auto diagnostics() -> Diagnostics&
Gets any diagnostics generated while parsing.
auto allocator() -> BumpAllocator&
Gets the allocator containing the memory for the parse tree.
auto sourceManager() -> SourceManager&
Gets the source manager used to build the syntax tree.
auto sourceManager() const -> const SourceManager&
Gets the source manager used to build the syntax tree.
auto getSourceLibrary() const -> const SourceLibrary*
Gets the source library with which the syntax tree is associated.
auto root() -> SyntaxNode&
Gets the root of the syntax tree.
auto root() const -> const SyntaxNode&
Gets the root of the syntax tree.
auto options() const -> const Bag&
The options used to construct the syntax tree.
auto getParentTree() const -> const SyntaxTree*
Gets the parent syntax tree, if there is one.
auto getMetadata() const -> const parsing::ParserMetadata&
Gets various bits of metadata collected during parsing.
auto getDefinedMacros() const -> MacroList
Gets the list of macros that were defined at the end of the loaded source file.

Public variables

bool isLibraryUnit
Indicates whether this syntax tree represents a "library" compilation unit, which means that modules declared within it are not automatically instantiated.

Function documentation

static TreeOrError slang::syntax::SyntaxTree::fromFile(std::string_view path)

Creates a syntax tree from a full compilation unit.

Returns the created and parsed syntax tree.

path is the path to the source file on disk.

static TreeOrError slang::syntax::SyntaxTree::fromFile(std::string_view path, SourceManager& sourceManager, const Bag& options = {})

Creates a syntax tree from a full compilation unit.

Returns the created and parsed syntax tree on success, or an OS error code if the file fails to load.

path is the path to the source file on disk. sourceManager is the manager that owns all of the loaded source code. options is an optional bag of lexer, preprocessor, and parser options.

static TreeOrError slang::syntax::SyntaxTree::fromFiles(std::span<const std::string_view> paths)

Creates a syntax tree by concatenating several files loaded from disk.

Returns the created and parsed syntax tree on success, or an OS error code if the file fails to load.

paths is the list of paths to the source files on disk.

static TreeOrError slang::syntax::SyntaxTree::fromFiles(std::span<const std::string_view> paths, SourceManager& sourceManager, const Bag& options = {})

Creates a syntax tree by concatenating several files loaded from disk.

Returns the created and parsed syntax tree on success, or an OS error code if the file fails to load.

paths is the list of paths to the source files on disk. sourceManager is the manager that owns all of the loaded source code. options is an optional bag of lexer, preprocessor, and parser options.

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromText(std::string_view text, std::string_view name = "source", std::string_view path = "")

Creates a syntax tree by guessing at what might be in the given source snippet.

Returns the created and parsed syntax tree.

text is the actual source code text. name is an optional name to give to the loaded source buffer. path is an optional path to give to the loaded source buffer.

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromText(std::string_view text, const Bag& options, std::string_view name = "source"sv, std::string_view path = "")

Creates a syntax tree by guessing at what might be in the given source snippet.

Returns the created and parsed syntax tree.

text is the actual source code text. options is a bag of lexer, preprocessor, and parser options. name is an optional name to give to the loaded source buffer. path is an optional path to give to the loaded source buffer.

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromText(std::string_view text, SourceManager& sourceManager, std::string_view name = "source"sv, std::string_view path = "", const Bag& options = {}, const SourceLibrary* library = nullptr)

Creates a syntax tree by guessing at what might be in the given source snippet.

Returns the created and parsed syntax tree.

text is the actual source code text. sourceManager is the manager that owns all of the loaded source code. name is an optional name to give to the loaded source buffer. path is an optional path to give to the loaded source buffer. options is an optional bag of lexer, preprocessor, and parser options. library the source library to associated with the parsed tree

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromFileInMemory(std::string_view text, SourceManager& sourceManager, std::string_view name = "source"sv, std::string_view path = "", const Bag& options = {})

Creates a syntax tree from a full compilation unit already in memory.

Returns the created and parsed syntax tree.

text is the actual source code text. sourceManager is the manager that owns all of the loaded source code. name is an optional name to give to the loaded source buffer. path is an optional path to give to the loaded source buffer. options is an optional bag of lexer, preprocessor, and parser options.

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromBuffer(const SourceBuffer& buffer, SourceManager& sourceManager, const Bag& options = {}, MacroList inheritedMacros = {})

Creates a syntax tree from an already loaded source buffer.

Returns the created and parsed syntax tree.

buffer is the loaded source buffer. sourceManager is the manager that owns the buffer. options is an optional bag of lexer, preprocessor, and parser options. inheritedMacros is a list of macros to predefine in the new syntax tree.

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromBuffers(std::span<const SourceBuffer> buffers, SourceManager& sourceManager, const Bag& options = {}, MacroList inheritedMacros = {})

Creates a syntax tree by concatenating several loaded source buffers.

Returns the created and parsed syntax tree.

buffers is the list of buffers that should be concatenated to form the compilation unit to parse. sourceManager is the manager that owns the buffers. options is an optional bag of lexer, preprocessor, and parser options. inheritedMacros is a list of macros to predefine in the new syntax tree.

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromLibraryMapFile(std::string_view path, SourceManager& sourceManager, const Bag& options = {})

Creates a syntax tree from a library map file.

Returns the created and parsed syntax tree.

path is the path to the source file on disk. sourceManager is the manager that owns all of the loaded source code. options is an optional bag of lexer, preprocessor, and parser options.

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromLibraryMapText(std::string_view text, SourceManager& sourceManager, std::string_view name = "source"sv, std::string_view path = "", const Bag& options = {})

Creates a syntax tree from a library map located in memory.

Returns the created and parsed syntax tree.

text is the actual source code text. sourceManager is the manager that owns all of the loaded source code. name is an optional name to give to the loaded source buffer. path is an optional path to give to the loaded source buffer. options is an optional bag of lexer, preprocessor, and parser options.

static std::shared_ptr<SyntaxTree> slang::syntax::SyntaxTree::fromLibraryMapBuffer(const SourceBuffer& buffer, SourceManager& sourceManager, const Bag& options = {})

Creates a syntax tree from a library map already loaded into a source buffer.

Returns the created and parsed syntax tree.

buffer is the loaded source buffer. sourceManager is the manager that owns the buffer. options is an optional bag of lexer, preprocessor, and parser options.

static SourceManager& slang::syntax::SyntaxTree::getDefaultSourceManager()

This is a shared default source manager for cases where the user doesn't care about managing the lifetime of loaded source.

Note that all of the source loaded by this thing will live in memory for the lifetime of the process.

const SyntaxTree* slang::syntax::SyntaxTree::getParentTree() const

Gets the parent syntax tree, if there is one.

Otherwise returns nullptr. Most syntax trees don't have a parent; this is for cases where a given tree is derived from another and relies on the parent tree's memory remaining valid for the lifetime of the child tree.