§tiro/compiler.h

Contains functions and type definitions for compiling tiro source code to modules.

§Classes

§Types

§Functions

§Types Documentation

§enum tiro_severity

Defines the possible values for the severity of diagnostic compiler messages.

§typedef tiro_severity_t

typedef enum tiro_severity tiro_severity_t;

Defines the possible values for the severity of diagnostic compiler messages.

§typedef tiro_compiler_message_t

typedef struct tiro_compiler_message tiro_compiler_message_t;

Represents a diagnostic message emitted by the compiler.

All fields are only valid for the duration of the message_callback function call.

§typedef tiro_compiler_settings_t

typedef struct tiro_compiler_settings tiro_compiler_settings_t;

An instance of this type can be passed to the compiler to configure it.

Use tiro_compiler_settings_init to initialize this struct to default values.

§Functions Documentation

§function tiro_severity_str

const char * tiro_severity_str(
    tiro_severity_t severity
)

Returns the string representation of the given severity value.

The returned string is allocated in static storage and MUST NOT be freed.

§function tiro_compiler_settings_init

void tiro_compiler_settings_init(
    tiro_compiler_settings_t * settings
)

Initializes the given compiler settings object with default values.

§function tiro_compiler_new

tiro_compiler_t tiro_compiler_new(
    tiro_string_t module_name,
    const tiro_compiler_settings_t * settings,
    tiro_error_t * err
)

Allocates a new compiler instance.

Parameters:

• module_name The name of the compiled module. Must be a valid, non-empty string. Does not have to remain valid for after the completion of this function, a copy is made internally.
• settings The compiler settings (optional). Default values will be used if this parameter is NULL. Does not have to remain valid after the completion of this function.

A compiler can be used to compile a set of source files into a module. Warnings or errors emitted during compilation can be observed through the settings->message_callback function.

§function tiro_compiler_free

void tiro_compiler_free(
    tiro_compiler_t compiler
)

Destroys and frees the given compiler instance.

Must be called exactly once for every instance created via tiro_compiler_new in order to avoid resource leaks. Does nothing if compiler is NULL.

§function tiro_compiler_add_file

void tiro_compiler_add_file(
    tiro_compiler_t compiler,
    tiro_string_t file_name,
    tiro_string_t file_content,
    tiro_error_t * err
)

Add a source file to the compiler's source set.

Can only be called before compilation started.

Filenames should be unique within a single module.

§function tiro_compiler_run

void tiro_compiler_run(
    tiro_compiler_t compiler,
    tiro_error_t * err
)

Run the compiler on the set of source files provided via tiro_compiler_add_file.

Requires at least one source file. This function can only be called once for every compiler instance.

Returns an error if the compilation fails.

§function tiro_compiler_has_module

bool tiro_compiler_has_module(
    tiro_compiler_t compiler
)

Returns true if this compiler has successfully compiled a set of source files and produced a bytecode module.

In order for this function to return true, a previous call to tiro_compiler_run must have returned TIRO_OK and the compiler must have been configured to actually produce a module.

§function tiro_compiler_take_module

void tiro_compiler_take_module(
    tiro_compiler_t compiler,
    tiro_module_t * module,
    tiro_error_t * err
)

Extracts the compiled module from the compiler and returns it.

On success, the module will be placed into the location specified by module, which must not be NULL. If a module was returned, it must be freed by calling tiro_module_free.

This function fails if tiro_compiler_has_module returns false.

§function tiro_compiler_dump_cst

void tiro_compiler_dump_cst(
    tiro_compiler_t compiler,
    char ** string,
    tiro_error_t * err
)

Returns the string representation of the concrete syntax tree (CST).

Can only be called after tiro_compiler_run has been executed. The compile process can have failed; a somewhat useful CST can often still be produced.

Returns TIRO_ERROR_BAD_STATE if the compiler cannot produce the CST.

Otherwise, this function returns TIRO_OK and returns a new string using the provided output parameter. The string must be passed to free to release memory.

§function tiro_compiler_dump_ast

void tiro_compiler_dump_ast(
    tiro_compiler_t compiler,
    char ** string,
    tiro_error_t * err
)

Returns the string representation of the abstract syntax tree (AST).

Can only be called after tiro_compiler_run has been executed. The compile process can have failed; a somewhat useful AST can often still be produced.

Returns TIRO_ERROR_BAD_STATE if the compiler cannot produce the AST.

Otherwise, this function returns TIRO_OK and returns a new string using the provided output parameter. The string must be passed to free to release memory.

§function tiro_compiler_dump_ir

void tiro_compiler_dump_ir(
    tiro_compiler_t compiler,
    char ** string,
    tiro_error_t * err
)

Returns the string representation of the internal representation immediately before code generation.

Can only be called after tiro_compiler_run has been executed successfully.

Returns TIRO_ERROR_BAD_STATE if the compiler cannot produce the internal representation.

Otherwise, this function returns TIRO_OK and returns a new string using the provided output parameter. The string must be passed to free to release memory.

§function tiro_compiler_dump_bytecode

void tiro_compiler_dump_bytecode(
    tiro_compiler_t compiler,
    char ** string,
    tiro_error_t * err
)

Returns the string representation of the compiled bytecode module.

Can only be called after tiro_compiler_run has been executed successfully.

Returns TIRO_ERROR_BAD_STATE if the compiler cannot produce the disassembled output.

Otherwise, this function returns TIRO_OK and returns a new string using the provided output parameter. The string must be passed to free to release memory.

§function tiro_module_free

void tiro_module_free(
    tiro_module_t module
)

Free a module.

Must be called exactly once for every created module.

Does nothing if module is NULL.

Updated on 2022-02-27 at 21:17:13 +0100