Struct Runtime 

pub struct Runtime<Ctx: OptCtx> { /* private fields */ }

Provides the types and functions that Roto can access via FFI

Roto is an embedded language, therefore, it must be hooked up to the outside world to do anything useful besides pure computation. This connection is provided by the Runtime, which exposes types, methods and functions to Roto.

Roto can run in different Runtimes, depending on the situation. Extending the default Runtime is the primary way to extend the capabilities of Roto.

Compiling a script

• Runtime::compile

Registering types, functions and constants.

• Runtime::add

Registering context type

• Runtime::with_context_type

Printing documentation

• Runtime::print_documentation

Implementations

impl<Ctx: OptCtx> Runtime<Ctx>

pub fn print_documentation(&self, path: &Path) -> Result<()>

Print documentation for all the types registered into this runtime.

The format for the documentation is markdown that can be passed to Sphinx.

impl<Ctx: OptCtx> Runtime<Ctx>

pub fn add_io_functions(&mut self)

Add functions using I/O to the runtime.

These functions are disabled by default because Roto might be used in a context where using I/O is not permitted.

For now, this just adds the print function. More functions will be added in the future.

impl<Ctx: OptCtx> Runtime<Ctx>

Compiling a script

pub fn compile( &self, path: impl AsRef<Path>, ) -> Result<Package<Ctx>, RotoReport>

Compile a script from a path and return the result.

If the path is a file, then that file will be loaded. If the path is a directory, the directory will be scanned for modules.

impl Runtime<NoCtx>

Creating a Runtime

pub fn new() -> Self

A Runtime that is as empty as possible.

This contains only type information for Roto primitives.

pub fn from_lib(items: impl Registerable) -> Result<Self, RegistrationError>

Create a new Runtime with a given library.

This is nothing more than a convenience function around Runtime::new followed by Runtime::add.

pub fn with_context_type<C: Context + 'static>( self, ) -> Result<Runtime<Ctx<C>>, String>

Add a context type to this runtime

Takes self by value to return Runtime with a new changed type parameter C.

impl<C: OptCtx> Runtime<C>

Inspecting and modifying the Runtime

pub fn add(&mut self, items: impl Registerable) -> Result<(), RegistrationError>

Add a library of items to this Runtime

Typically, one would use the library! macro to register items. This would look something like this:

use roto::{Runtime, library};

let mut rt = Runtime::new();
rt.add(library! {
    /* define items here */
}).unwrap();

See the documentation on the library! macro for more information.

However, it is – with a bit of extra boilerplate – also possible to register items without using the macro. You can directly register one of the item types:

• Module
• Type
• Function
• Constant
• Impl
• Use

Or you can register an Item which combines all the above. Additionally, you can register collections of these types, such as Vec<Item> or [Item; N].

For example:

use roto::{Runtime, Constant, Function, Impl, location, Item};

let mut rt = Runtime::new();

// Add a single constant
rt.add(
    Constant::new(
        "U32_MAX",
        "The maximum value of a `u32`.",
        u32::MAX,
        location!(),
    ).unwrap()
).unwrap();

// Add a constant and a method:

let mut impl_block = Impl::new::<i32>(location!());
impl_block.add(Function::new(
    "max",
    "The maximum value of an `i32`",
    vec![],
    || i32::MAX,
        location!(),
).unwrap());

rt.add([
    Item::Impl(impl_block),
    Item::Constant(Constant::new(
        "I32_MAX",
        "The maximum value of an `i32`",
        i32::MAX,
        location!(),
    ).unwrap())
]).unwrap();

See also Runtime::from_lib, which combines Runtime::new and Runtime::add into a single function.

pub fn context(&self) -> &Option<ContextDescription>

Get the context type, if any.

pub fn types(&self) -> &[RuntimeType]

Get the registered types.

pub fn functions(&self) -> &[RuntimeFunction]

Get the registered functions.

pub fn constants(&self) -> &HashMap<ResolvedName, RuntimeConstant>

Get the registered constants.

pub fn cli(&self)

Run a CLI based on this runtime.

pub fn try_without_ctx(self) -> Option<Runtime<NoCtx>>

Try to obtain a Runtime that does not have a context.

This is useful to turn a Runtime with a genenic C parameter into Runtime<NoCtx>.

Trait Implementations

impl<Ctx: Clone + OptCtx> Clone for Runtime<Ctx>

fn clone(&self) -> Runtime<Ctx>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Ctx: OptCtx> Debug for Runtime<Ctx>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Runtime<NoCtx>

fn default() -> Self

Returns the “default value” for a type.