Crate rune

Minimum support: Rust 1.63+.

Visit the site 🌐 — Read the book 📖

The Rune Language, an embeddable dynamic programming language for Rust.

Contributing

If you want to help out, please have a look at Open Issues.

Highlights of Rune

• Runs a compact representation of the language on top of an efficient stack-based virtual machine.
• Clean Rust integration 💻.
• Memory safe through reference counting 📖.
• Awesome macros 📖.
• Template literals 📖.
• Try operators 📖.
• Pattern matching 📖.
• Structs and enums 📖 with associated data and functions.
• Dynamic vectors 📖, objects 📖, and tuples 📖 with out-of-the-box serde support 💻.
• First-class async support 📖.
• Generators 📖.
• Dynamic instance functions 📖.
• Stack isolation 📖 between function calls.

Rune scripts

You can run Rune programs with the bundled CLI:

cargo run --bin rune -- run scripts/hello_world.rn

If you want to see detailed diagnostics of your program while it’s running, you can use:

cargo run --bin rune -- run scripts/hello_world.rn --dump-unit --trace --dump-vm

See --help for more information.

Running scripts from Rust

You can find more examples in the examples folder.

The following is a complete example, including rich diagnostics using termcolor. It can be made much simpler if this is not needed.

use rune::{Context, Diagnostics, FromValue, Source, Sources, Vm};
use rune::termcolor::{ColorChoice, StandardStream};
use std::sync::Arc;

#[tokio::main]
async fn main() -> rune::Result<()> {
    let context = Context::with_default_modules()?;
    let runtime = Arc::new(context.runtime());

    let mut sources = Sources::new();
    sources.insert(Source::new(
        "script",
        r#"
        pub fn add(a, b) {
            a + b
        }
        "#,
    ));

    let mut diagnostics = Diagnostics::new();

    let result = rune::prepare(&mut sources)
        .with_context(&context)
        .with_diagnostics(&mut diagnostics)
        .build();

    if !diagnostics.is_empty() {
        let mut writer = StandardStream::stderr(ColorChoice::Always);
        diagnostics.emit(&mut writer, &sources)?;
    }

    let unit = result?;
    let mut vm = Vm::new(runtime, Arc::new(unit));

    let output = vm.call(["add"], (10i64, 20i64))?;
    let output = i64::from_value(output)?;

    println!("{}", output);
    Ok(())
}

Re-exports

• pub use ::codespan_reporting::term::termcolor;
• pub use self::any::Any;
• pub use self::runtime::FromValue;
• pub use self::runtime::ToValue;
• pub use self::runtime::Unit;
• pub use self::runtime::Value;
• pub use self::runtime::Vm;

Modules

• ast
  Abstract syntax trees for the Rune language.
• compile
  The Rune compiler.
• diagnostics
  Diagnostics module for Rune.
• macros
  The macro system of Rune.
• modules
  Public packages that can be used to provide extract functionality to virtual machines.
• parse
  Parsing utilities for Rune.
• query
  Lazy query system, used to compile and build items on demand and keep track of what’s being used and not.
• runtime
  Runtime module for Rune.
• workspaceworkspace
  Types for dealing with workspaces of rune code.

Macros

• K
  Helper macro to reference a specific token kind, or short sequence of kinds.
• T
  Helper macro to reference a specific token.
• sources
  Helper macro to define a collection of sources populatedc with the given entries.
• span
  A macro that can be used to construct a Span that can be pattern matched over.

Structs

• Build
  High level helper for setting up a build of Rune sources into a Unit.
• BuildError
  Error raised when we failed to load sources.
• Context
  Context used for the Rune language.
• Diagnostics
  Structure to collect compilation diagnostics.
• Hash
  The primitive hash that among other things is used to reference items, types, and native functions.
• InstFnInfo
  A descriptor for an instance function.
• Module
  A Module that is a collection of native functions and types.
• Options
  Options that can be provided to the compiler.
• Params
  Helper to register a parameterized function.
• Source
  A single source file.
• SourceId
  The identifier of a source file.
• Sources
  A collection of source files, and a queue of things to compile.

Enums

• ContextError
  An error raised when building the context.
• InstFnKind
  An instance function name.

Traits

• Any
  A trait which can be stored inside of an AnyObj.
• InstFnName
  Trait used to determine what can be used as an instance function name.
• InstallWith
  Trait to handle the installation of auxilliary functions for a type installed into a module.
• IntoTypeHash
  Helper conversion into a function hash.

Functions

• prepare
  Entry point to building Sources of Rune.

Type Definitions

• Error
  Boxed error type, which is an alias of anyhow::Error.
• Result
  Exported result type for convenience using anyhow::Error as the default error type.

Derive Macros

• Any
  Macro to mark a value as external, which will implement all the appropriate traits.
• FromValue
  Derive macro for the FromValue trait for converting types from the dynamic Value container.
• ToValue
  Derive macro for the FromValue trait for converting types into the dynamic Value container.