Spicy
Public Types | Public Member Functions | Static Public Member Functions | List of all members
hilti::Unit Class Reference

#include <unit.h>

Public Types

enum  ASTState { Modified, NotModified }
 

Public Member Functions

 ~Unit ()
 
NodeRef moduleRef () const
 
Nodemodule ()
 
const auto & cacheIndex () const
 
const auto & id () const
 
ID uniqueID () const
 
const auto & path () const
 
const auto & extension () const
 
void setExtension (const hilti::rt::filesystem::path &ext)
 
void resetAST ()
 
Result< NothingbuildASTScopes (const Plugin &plugin)
 
Result< ASTState > resolveAST (const Plugin &plugin)
 
bool validateASTPre (const Plugin &plugin)
 
bool validateASTPost (const Plugin &plugin)
 
Result< NothingtransformAST (const Plugin &plugin)
 
Result< Nothingcodegen ()
 
Result< Nothingprint (std::ostream &out) const
 
Result< NothingcreatePrototypes (std::ostream &out)
 
Result< CxxCodecxxCode () const
 
std::vector< std::weak_ptr< Unit > > dependencies (bool recursive=false) const
 
void clearDependencies ()
 
bool addDependency (const std::shared_ptr< Unit > &unit)
 
Result< linker::MetaDatalinkerMetaData () const
 
bool isCompiledHILTI () const
 
bool requiresCompilation ()
 
void setRequiresCompilation ()
 
bool isResolved ()
 
void setResolved (bool resolved)
 
std::shared_ptr< Contextcontext () const
 
const Optionsoptions () const
 

Static Public Member Functions

static Result< std::shared_ptr< Unit > > fromSource (const std::shared_ptr< Context > &context, const hilti::rt::filesystem::path &path, const std::optional< ID > &scope, std::optional< hilti::rt::filesystem::path > process_extension={})
 
static std::shared_ptr< UnitfromModule (const std::shared_ptr< Context > &context, const hilti::Module &module, hilti::rt::filesystem::path extension)
 
static Result< std::shared_ptr< Unit > > fromImport (const std::shared_ptr< Context > &context, const ID &id, const hilti::rt::filesystem::path &parse_extension, const hilti::rt::filesystem::path &process_extension, std::optional< ID > scope, std::vector< hilti::rt::filesystem::path > search_dirs)
 
static Result< std::shared_ptr< Unit > > fromCache (const std::shared_ptr< Context > &context, const hilti::rt::filesystem::path &path, const std::optional< ID > &scope)
 
static Result< std::shared_ptr< Unit > > fromCXX (const std::shared_ptr< Context > &context, detail::cxx::Unit cxx, const hilti::rt::filesystem::path &path="")
 
static Result< std::shared_ptr< Unit > > link (const std::shared_ptr< Context > &context, const std::vector< linker::MetaData > &mds)
 
static std::pair< bool, std::optional< linker::MetaData > > readLinkerMetaData (std::istream &input, const hilti::rt::filesystem::path &path="<input stream>")
 

Detailed Description

Container for a single HILTI code module. For each HILTI source file, one compiler unit gets instantiated. That unit then drives the process to compile the module AST into C++ code. While that's in progress, the unit maintains state about the process, such as a list of dependencies this unit requires.

Constructor & Destructor Documentation

◆ ~Unit()

Unit::~Unit ( )

Destructor.

Member Function Documentation

◆ addDependency()

bool Unit::addDependency ( const std::shared_ptr< Unit > &  unit)

Register a dependency on another unit for the current one.

Parameters
unitthe unit this one depends on
Returns
true if this is a new dependency that had not been previously added

◆ buildASTScopes()

Result< Nothing > Unit::buildASTScopes ( const Plugin plugin)

Runs a plugin's scope-building phase on the unit's AST.

Parameters
pluginplugin to execute
Returns
success if no error occurred, and an appropriate error otherwise

◆ cacheIndex()

const auto& hilti::Unit::cacheIndex ( ) const
inline

Returns the index to use when storing the unit inside the context's unit cache.

◆ clearDependencies()

void hilti::Unit::clearDependencies ( )
inline

Removes any dependencies registered for the unit so far.

◆ codegen()

Result< Nothing > Unit::codegen ( )

Triggers generation of C++ code from the compiled AST.

Returns
success if no error occurred, and an appropriate error otherwise

◆ context()

std::shared_ptr<Context> hilti::Unit::context ( ) const
inline

Returns the compiler context in use.

◆ createPrototypes()

Result< Nothing > Unit::createPrototypes ( std::ostream &  out)

Prints out C++ prototypes that host applications can use to interface with the generated C++ code. Must be called only after compile() was successful.

Parameters
outstream to print the code to
Returns
set if successful, or an appropriate error result

◆ cxxCode()

Result< CxxCode > Unit::cxxCode ( ) const

Returns the generated C++ code. Must be called only after compile() was successful.

Returns
code wrapped into the JIT's container class

◆ dependencies()

std::vector< std::weak_ptr< Unit > > Unit::dependencies ( bool  recursive = false) const

Returns the list of dependencies registered for the unit so far.

Parameters
recursiveif true, return the transitive closure of all dependent units, vs just direct dependencies of the current unit

◆ extension()

const auto& hilti::Unit::extension ( ) const
inline

Returns the file extension associated with the unit's code. This extension determines which plugin the unit's AST will be processed with. Note that this does not necessarily match the extension of module's source path.

◆ fromCache()

Result< std::shared_ptr< Unit > > Unit::fromCache ( const std::shared_ptr< Context > &  context,
const hilti::rt::filesystem::path &  path,
const std::optional< ID > &  scope 
)
static

Factory method that instantiates a unit from an existing HILTI module already cached by the global context.

Parameters
contextglobal compiler context
pathpath of the cached module
scopeimport-from scope associated with the existing module
Returns
instantiated unit, or an appropriate error result if operation failed

◆ fromCXX()

Result< std::shared_ptr< Unit > > Unit::fromCXX ( const std::shared_ptr< Context > &  context,
detail::cxx::Unit  cxx,
const hilti::rt::filesystem::path &  path = "" 
)
static

Factory method that instantiates a unit from existing C++ source code that's to compiled.

Parameters
contextglobal compiler context
pathpath associated with the C++ code, if any
Returns
instantiated unit, or an appropriate error result if operation failed

◆ fromImport()

Result< std::shared_ptr< Unit > > Unit::fromImport ( const std::shared_ptr< Context > &  context,
const ID id,
const hilti::rt::filesystem::path &  parse_extension,
const hilti::rt::filesystem::path &  process_extension,
std::optional< ID scope,
std::vector< hilti::rt::filesystem::path >  search_dirs 
)
static

Factory method that instantiates a unit for an import statement, performing the search for the right source file first.

This method also caches the module with the global context. Note that the module's ID or path should usually not exist with the context yet.

Parameters
contextglobal compiler context
idID of the module to be imported
parse_extensionfile extension indicating how to parse the module's source file
ast_extensionextension indicating which plugin to use for processing the AST; this will usually match parse_extension, but doesn't need to.
Returns
instantiated unit, or an appropriate error result if operation failed

◆ fromModule()

std::shared_ptr< Unit > Unit::fromModule ( const std::shared_ptr< Context > &  context,
const hilti::Module module,
hilti::rt::filesystem::path  extension 
)
static

Factory method that instantiates a unit from an existing HILTI AST.

This method also caches the module with the global context. Note that the module's ID or path should usually not exist with the context yet. If it does, this one will replace the existing version.

Parameters
contextglobal compiler context
moduleAST of the module
extensionextension indicating which plugin to use for processing the AST
Returns
instantiated unit, or an appropriate error result if operation failed

◆ fromSource()

Result< std::shared_ptr< Unit > > Unit::fromSource ( const std::shared_ptr< Context > &  context,
const hilti::rt::filesystem::path &  path,
const std::optional< ID > &  scope,
std::optional< hilti::rt::filesystem::path >  process_extension = {} 
)
static

Factory method that instantiates a unit from an existing source file that it will parse.

This method also caches the module with the global context. Note that the module's ID or path should usually not exist with the context yet.

Parameters
contextglobal compiler context
pathpath to parse the module from
scopeimport-from scope associated with the import operation, if any
ast_extensionextension indicating which plugin to use for processing the AST; if not given, this will be taken from the filename
Returns
instantiated unit, or an appropriate error result if operation failed

◆ id()

const auto& hilti::Unit::id ( ) const
inline

Returns the ID of the unit's module.

◆ isCompiledHILTI()

bool hilti::Unit::isCompiledHILTI ( ) const
inline

Returns true if this unit has been compiled from HILTI source. This is usually the case, but we also represent HILTI's linker output as a unit and there's no corresponding HILTI source code for that.

◆ isResolved()

bool hilti::Unit::isResolved ( )
inline

Returns true if the unit has been marked as fully resolved, so that no further AST processing is needed.

◆ link()

Result< std::shared_ptr< Unit > > Unit::link ( const std::shared_ptr< Context > &  context,
const std::vector< linker::MetaData > &  mds 
)
static

Entry point for the HILTI linker, The linker combines meta data from several compiled HILTI modules and creates an additional unit from it, with its C++ code representing logic the HILTI runtime library will draw upon.

Parameters
contextcompiler context to use
mdsset of meta data from modules to be linked together
Returns
a unit representing additional C++ code that the modules need to function

◆ linkerMetaData()

Result<linker::MetaData> hilti::Unit::linkerMetaData ( ) const
inline

Returns the unit's meta data for the internal HILTI linker.

Returns
meta data, or an error if no code has been compiled yet

◆ module()

Node& hilti::Unit::module ( )
inline

Returns the root node of the module AST's. Must only be called if isCompiledHilti() returns true.

◆ moduleRef()

NodeRef hilti::Unit::moduleRef ( ) const
inline

Returns a reference to the root node of the module AST's.

◆ options()

const Options& hilti::Unit::options ( ) const
inline

Returns the compiler options in use.

◆ path()

const auto& hilti::Unit::path ( ) const
inline

Returns the path associated with the unit's module.

◆ print()

Result< Nothing > Unit::print ( std::ostream &  out) const

Prints out a HILTI module by recreating its code from the internal AST. Must be called only after compile() was successful.

Parameters
outstream to print the code to
Returns
set if successful, or an appropriate error result

◆ readLinkerMetaData()

std::pair< bool, std::optional< linker::MetaData > > Unit::readLinkerMetaData ( std::istream &  input,
const hilti::rt::filesystem::path &  path = "<input stream>" 
)
static

Reads linker meta from a file. This expects the file to contain linker meta somewhere inside a appropriately marked block bracketed by C-style comments. When printing the generated C++ code for a compiled HILTI module, it will include that block. In other words, you can just save the C++ and reread the meta data with this method.

Parameters
inputstream to read from
pathfile associated with the stream, for logging and error reporting
Returns
If the input had valid meta data, the 1st element is true and the second contains it. If the input was valid but had no meta data included, the 1st element is true while the 2nd remains unset. If there was an error reading the input, the 1st element is false and the 2nd undefined.

◆ requiresCompilation()

bool Unit::requiresCompilation ( )

Returns true if the AST has been determined to contain code that needs to be compiled as its own C++ module, rather than just declaration for other units.

◆ resetAST()

void Unit::resetAST ( )

Clears any scopes and errors accumulated inside the unit's AST.

◆ resolveAST()

Result< Unit::ASTState > Unit::resolveAST ( const Plugin plugin)

Runs a plugin's resolver phase on the unit's AST.

Parameters
pluginplugin to execute
Returns
flag indicating whether the AST was modified or not; or an appropriate error if a failure occurred

◆ setExtension()

void hilti::Unit::setExtension ( const hilti::rt::filesystem::path &  ext)
inline

Set a file extension associagted with the unit's code. By default, the extension is set when a AST module is being created, for example from the file it's being parsed from. This method can explicitly override the extension to have the AST processed by a different plugin.

Parameters
extnew extension

◆ setRequiresCompilation()

void hilti::Unit::setRequiresCompilation ( )
inline

Explicily marks the unit as requiring compilation down to C++, overriding any automatic determination.

◆ setResolved()

void hilti::Unit::setResolved ( bool  resolved)
inline

Sets the resolver state for the unit.

Parameters
resolvedtrue to mark the module as fully resolved, so that no further AST processing is needed

◆ transformAST()

Result< Nothing > Unit::transformAST ( const Plugin plugin)

Runs a plugin's transformation phase on the unit's AST.

Parameters
pluginplugin to execute
Returns
success if no error occurred, and an appropriate error otherwise

◆ uniqueID()

ID hilti::Unit::uniqueID ( ) const
inline

Returns an ID for the unit's module that's globally unique across all units processed within the current context. This ID will often be the same as returned by id(), but it may include an additional string for unification, in particular if there are more than one module with the same ID.

Returns
globally unique ID for the module; the method guaranteees that the ID represents a valid C++ identifier

◆ validateASTPost()

bool Unit::validateASTPost ( const Plugin plugin)

Runs a plugin's validation phase on the unit's AST after resolving.

Parameters
pluginplugin to execute
Returns
true if the AST does not contain any errors

◆ validateASTPre()

bool Unit::validateASTPre ( const Plugin plugin)

Runs a plugin's validation phase on the unit's AST before resolving.

Parameters
pluginplugin to execute
Returns
true if the AST does not contain any errors

The documentation for this class was generated from the following files: