Crate rune

Visit the site 🌐 - Read the book 📖

An embeddable dynamic programming language for Rust.

Contributing

If you want to help out, there should be a number of optimization tasks available in Future Optimizations. Or have a look at Open Issues.

Create an issue about the optimization you want to work on and communicate that you are working on it.

Highlights of Rune

• Clean Rust integration 💻.
• Memory safe through reference counting 📖.
• Template strings 📖.
• Try operators 📖.
• Pattern matching 📖.
• Structs and enums 📖 with associated data and functions.
• Dynamic vectors 📖, objects 📖, and tuples 📖 with built-in serde support 💻.
• First-class async support 📖.
• Generators 📖.
• Dynamic instance functions 📖.
• Stack isolation 📖 between function calls.
• Stack-based C FFI, like Lua's (TBD).

Rune scripts

You can run Rune programs with the bundled CLI:

cargo run --bin rune -- 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 -- 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::termcolor::{ColorChoice, StandardStream};
use rune::EmitDiagnostics as _;
use runestick::{Vm, FromValue as _, Item, Source};

use std::error::Error;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let context = Arc::new(rune_modules::default_context()?);
    let options = rune::Options::default();

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

    let mut errors = rune::Errors::new();
    let mut warnings = rune::Warnings::new();

    let unit = match rune::load_sources(&*context, &options, &mut sources, &mut errors, &mut warnings) {
        Ok(unit) => unit,
        Err(rune::LoadSourcesError) => {
            let mut writer = StandardStream::stderr(ColorChoice::Always);
            errors.emit_diagnostics(&mut writer, &sources)?;
            return Ok(());
        }
    };

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

    let vm = Vm::new(context.clone(), Arc::new(unit));

    let mut execution = vm.execute(&["calculate"], (10i64, 20i64))?;
    let value = execution.async_complete().await?;

    let value = i64::from_value(value)?;

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

Re-exports

pub use diagnostics::termcolor;

pub use diagnostics::DiagnosticsError;

pub use diagnostics::DumpInstructions;

pub use diagnostics::EmitDiagnostics;

pub use diagnostics::EmitSource;

Modules

ast	AST for the Rune language.
diagnostics	Runtime helpers for loading code and emitting diagnostics.
macros	The macro system of Rune.
testing	Utilities used for testing small Rune programs.

Macros

K	Helper macro to reference a specific token kind, or short sequence of kinds.
T	Helper macro to reference a specific token.
quote	Macro helper function for quoting the token stream as macro output.
rune	Same as rune_s! macro, except it takes a Rust token tree. This works fairly well because Rust and Rune has very similar token trees.
rune_s	Run the given program and return the expected type from it.

Structs

CompileError	An error raised during compiling.
Error	An error raised when using one of the load_* functions.
Errors	A collection of errors.
FileSourceLoader	A filesystem-based source loader.
Id	An opaque identifier that is associated with AST items.
ImportEntryStep	A single stap as an import entry.
IrError	An error raised during compiling.
Lexer	Lexer for the rune language.
LoadSourcesError	Error raised when we failed to load sources.
Location	A source location.
MacroContext	Context for a running macro.
NoopCompileVisitor	A compile visitor that does nothing.
Options	Compiler options.
ParseError	An error raised during parsing.
Parser	Parser for the rune language.
Peeker	Construct used to peek a parser.
QueryError	An error raised during querying.
Quote	ToTokens implementation generated by quote_fn.
ResolveError	An error during resolving.
ScopeError	An error cause by issues with scoping.
Sources	A collection of source files, and a queue of things to compile.
Storage	Storage for synthetic language items.
TokenStream	A token stream.
TokenStreamIter	A token stream iterator.
UnitBuilder	Instructions from a single source file.
Var	A locally declared variable, its calculated stack offset and where it was declared in its source file.
Warning	Compilation warning.
Warnings	Compilation warnings.

Enums

BuildError
CompileErrorKind	Compiler error.
ErrorKind
IrErrorKind	Error when encoding AST.
IrValue	A constant value.
LinkerError	An error raised during linking.
ParseErrorKind	Error when parsing.
QueryErrorKind	Error raised during queries.
ResolveErrorKind	The kind of a resolve error.
ScopeErrorKind
Used	Indication whether a value is being evaluated because it's being used or not.
WarningKind	Compilation warning kind.

Traits

CompileVisitor	A visitor that will be called for every language item compiled.
OptionSpanned	Types for which we can optionally get a span.
Parse	The parse trait, implemented by items that can be parsed.
Peek	Implemented by tokens that can be peeked for.
Resolve	A type that can be resolved to an internal value based on a source.
ResolveOwned	Trait for resolving a token into an owned value.
SourceLoader	A source loader.
Spanned	Types for which we can get a span.
ToTokens	Trait for things that can be turned into tokens.

Functions

compile	Compile the given source with default options.
load_sources	Load and compile the given sources.
load_sources_with_visitor	Load the specified sources with a visitor.
parse_all	Parse the given input as the given type that implements [Parse][crate::traits::Parse].

Type Definitions

CompileResult

A compile result.