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 -- 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::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 = runestick::Context::with_default_modules()?;
    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 diagnostics = rune::Diagnostics::new();

    let result = rune::load_sources(&context, &options, &mut sources, &mut diagnostics);

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

    let unit = result?;
    let vm = Vm::new(Arc::new(context.runtime()), 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 self::emit_diagnostics::termcolor;

Modules

ast	AST for the Rune language.
macros	The macro system of Rune.

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.

Structs

CompileError	An error raised during compiling.
Diagnostics	Structure to collect compilation diagnostics.
Error	An error raised when using one of the load_* functions.
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.
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.
Warning	Compilation warning.

Enums

BuildError
CompileErrorKind	Compiler error.
ConfigurationError	Error when parsing configuration.
Diagnostic	A single diagnostic.
DiagnosticsError	Errors that can be raised when formatting diagnostics.
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.
DumpInstructions	Trait to dump the instructions of a unit to the given writer.
EmitDiagnostics	Helper trait for emitting diagnostics.
EmitSource	Helper trait to emit source code locations.
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.
with_context	Install the given context and call the provided function with the installed context.

Type Definitions

CompileResult

A compile result.