Spicy
Public Types | Public Attributes | List of all members
hilti::Plugin Struct Reference

#include <plugin.h>

Public Types

template<typename Result , typename... Args>
using Hook = std::optional< std::function< Result(Args...)> >
 

Public Attributes

std::string component
 
hilti::rt::filesystem::path extension
 
std::vector< hilti::rt::filesystem::path > cxx_includes
 
int order = 0
 
Hook< std::vector< hilti::rt::filesystem::path >, std::shared_ptr< hilti::Context > > library_paths
 
Hook< Result< Node >, std::istream &, hilti::rt::filesystem::path > parse
 
Hook< std::optional< Ctor >, Ctor, const Type &, bitmask< CoercionStyle > > coerce_ctor
 
Hook< std::optional< Type >, Type, const Type &, bitmask< CoercionStyle > > coerce_type
 
Hook< void, std::shared_ptr< hilti::Context >, const std::vector< std::pair< ID, NodeRef > > &, Unit * > build_scopes
 
Hook< bool, std::shared_ptr< hilti::Context >, Node *, Unit * > resolve_ids
 
Hook< bool, std::shared_ptr< hilti::Context >, Node *, Unit * > resolve_operators
 
Hook< bool, std::shared_ptr< hilti::Context >, Node *, Unit * > apply_coercions
 
Hook< void, std::shared_ptr< hilti::Context >, Node *, Unit *, bool * > pre_validate
 
Hook< void, std::shared_ptr< hilti::Context >, Node *, Unit * > post_validate
 
Hook< void, std::shared_ptr< hilti::Context >, std::vector< Node > *, Unit * > preserved_validate
 
Hook< bool, std::shared_ptr< hilti::Context >, Node *, bool, Unit * > transform
 
Hook< bool, const Node &, hilti::printer::Stream & > print_ast
 

Detailed Description

Compiler plugin that can hook into the compilation process that's driven by Unit.

A plugin gets access to the AST at all major stages. In particular it can add support implement support for new language using HILTI as its code generation backend by providing a parse method building its AST, along with a transformation method converting any non-standard nodes HILTI equivalents.

A plugin implements a set of hook methods that get called by the compilation process at the appropriate times. All hooks should be stateless, apart from changing the AST where appropriate.

Note
HILTI compilation itself is also implemented through a default plugin that's always available. Unit cycles through all available plugins during the compilation process, including that default plugin.

Member Typedef Documentation

◆ Hook

template<typename Result , typename... Args>
using hilti::Plugin::Hook = std::optional<std::function<Result(Args...)> >

Helper template to define the type of hook methods.

Member Data Documentation

◆ apply_coercions

Hook<bool, std::shared_ptr<hilti::Context>, Node*, Unit*> hilti::Plugin::apply_coercions

Hook called perform coercions. This must carry out all the coercions that coerce_type has indicated as valid.

Parameters
arg1compiler context that's in use
arg2root node of AST; the hook may modify the AST
arg3current unit being compiled
Returns
true if the hook modified the AST in a substantial way

◆ build_scopes

Hook<void, std::shared_ptr<hilti::Context>, const std::vector<std::pair<ID, NodeRef> >&, Unit*> hilti::Plugin::build_scopes

Hook called to build the scopes in a module's AST.

Parameters
arg1compiler context that's in use
arg2root node of AST; the hook may modify the AST
arg3current unit being compiled
Returns
true if the hook modified the AST in a substantial way

◆ coerce_ctor

Hook<std::optional<Ctor>, Ctor, const Type&, bitmask<CoercionStyle> > hilti::Plugin::coerce_ctor

Hook called to perform coercion of a Ctor into another of a given target type.

If the plugin knows how to handle the coercion, the hook returns a new Ctor that's now of the target type.

Parameters
arg1compiler context that's in use
arg2ctor that needs coercion
arg3target type for ctor
arg4coercion style to use
Returns
new ctor if plugin performed coercion

◆ coerce_type

Hook<std::optional<Type>, Type, const Type&, bitmask<CoercionStyle> > hilti::Plugin::coerce_type

Hook called to approved coercion of an expression into a different type.

If the plugin knows it can handle the coercion, it returns the resulting coerced Type. If so, it must then also provide an apply_coercions hook that will later be called to perform the actual coercion during code generation.

Parameters
arg1compiler context that's in use
arg2type that needs coercion
arg3target type for coercion
arg4coercion style to use
Returns
new type if plugin can handle this coercion

◆ component

std::string hilti::Plugin::component

Name of the plugin.

◆ cxx_includes

std::vector<hilti::rt::filesystem::path> hilti::Plugin::cxx_includes

Additional C++ include files that the plugin needs to have added to generated C++ code.

◆ extension

hilti::rt::filesystem::path hilti::Plugin::extension

Extension for source files that the plugin handles. Must include the leading ..

◆ library_paths

Hook<std::vector<hilti::rt::filesystem::path>, std::shared_ptr<hilti::Context> > hilti::Plugin::library_paths

Hook called to retrieve paths to search when importing modules that this plugin handles.

Parameters
arg1compiler context that's in use
Returns
directories to search

◆ order

int hilti::Plugin::order = 0

Callbacks for plugins will be executed in numerical order, with lower order numbers executing first.

◆ parse

Hook<Result<Node>, std::istream&, hilti::rt::filesystem::path> hilti::Plugin::parse

Hook called to parse input file that this plugin handles.

Parameters
arg1compiler context that's in use #param arg2 input stream to parse
arg3file associated with the input stream
Returns
directories to search

◆ post_validate

Hook<void, std::shared_ptr<hilti::Context>, Node*, Unit*> hilti::Plugin::post_validate

Hook called to validate correctness of an AST, post-transformation. Any errors must be reported by setting the nodes' error information.

Parameters
arg1compiler context that's in use
arg2root node of AST; the hook may not modify the AST
arg3current unit being compiled

◆ pre_validate

Hook<void, std::shared_ptr<hilti::Context>, Node*, Unit*, bool*> hilti::Plugin::pre_validate

Hook called to validate correctness of an AST, pre-transformation. Any errors must be reported by setting the nodes' error information.

Parameters
arg1compiler context that's in use
arg2root node of AST; the hook may not modify the AST
arg3current unit being compiled
arg4pointer to boolean that the hook must set to true to indicate that errors were encountered.

◆ preserved_validate

Hook<void, std::shared_ptr<hilti::Context>, std::vector<Node>*, Unit*> hilti::Plugin::preserved_validate

Hook called to validate correctness of AST nodes that a module preserved before transformation. The hook runs just before the post_validate hook. Any errors must be reported by setting the nodes' error information.

Parameters
arg1compiler context that's in use
arg2preserved nodes to validate
arg3current unit being compiled

◆ print_ast

Hook<bool, const Node&, hilti::printer::Stream&> hilti::Plugin::print_ast

Hook called to print an AST back as source code. The hook gets to choose if it wants to print the node itself, or fall back to the default printer.

Parameters
arg1root of AST to print
arg2stream to print to
Returns
true if the hook printed the AST, false to fall back to default

◆ resolve_ids

Hook<bool, std::shared_ptr<hilti::Context>, Node*, Unit*> hilti::Plugin::resolve_ids

Hook called to resolved IDs in a module's AST.

Parameters
arg1compiler context that's in use
arg2root node of AST; the hook may modify the AST
arg3current unit being compiled
Returns
true if the hook modified the AST in a substantial way

◆ resolve_operators

Hook<bool, std::shared_ptr<hilti::Context>, Node*, Unit*> hilti::Plugin::resolve_operators

Hook called to resolved operators in a module's AST.

Parameters
arg1compiler context that's in use
arg2root node of AST; the hook may modify the AST
arg3current unit being compiled
Returns
true if the hook modified the AST in a substantial way

◆ transform

Hook<bool, std::shared_ptr<hilti::Context>, Node*, bool, Unit*> hilti::Plugin::transform

Hook called to replace any custom AST nodes with standard HILTI nodes. Note that this may be called multiple times while ASTs are built.

Parameters
arg1compiler context that's in use
arg2root node of AST; the hook may modify the AST
arg3boolean that's true if this hook runs for the first time on this AST.
arg4current unit being compiled
Returns
true if the hook modified the AST in a substantial way

The documentation for this struct was generated from the following file: