Crate rune

Minimum support: Rust 1.81+.

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 💻.
• Multithreaded 📖 execution.
• Hot reloading 📖.
• Memory safe through reference counting 📖.
• Awesome macros 📖 and Template literals 📖.
• Try operators 📖 and Pattern matching 📖.
• Structs and enums 📖 with associated data and functions.
• Dynamic containers like vectors 📖, objects 📖, and tuples 📖 all with out-of-the-box serde support 💻.
• First-class async support 📖 with 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 --trace

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, Source, Sources, Vm};
use rune::termcolor::{ColorChoice, StandardStream};
use std::sync::Arc;

let context = Context::with_default_modules()?;
let runtime = Arc::new(context.runtime()?);

let mut sources = Sources::new();
sources.insert(Source::memory("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 = rune::from_value(output)?;

println!("{}", output);

Modules

• alloc
  The Rune core allocation and collections library
• ast
  Abstract syntax trees for the Rune language.
• clicli
  Helper to build customized commandline interfaces using custom rune contexts.
• compile
  The Rune compiler.
• diagnostics
  Diagnostics module for Rune.
• fmt
  Helper to format Rune code.
• hash
  Utilities for working with hashes.
• item
  Types related to items.
• languageserver
  Utility for building a language server.
• macros
  The macro system of Rune.
• module
  Types used for defining native modules.
• modules
  Public packages that can be used to provide extract functionality to virtual machines.
• no_std
  Helper prelude for #[no_std] support. Public types related to using rune in #no_std environments.
• 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.
• source
  Module for dealing with sources.
• termcoloremit
  This crate provides a cross platform abstraction for writing colored text to a terminal. Colors are written using either ANSI escape sequences or by communicating with a Windows console. Much of this API was motivated by use inside command line applications, where colors or styles can be configured by the end user and/or the environment.
• 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.
• docstring
  Convenience macro for extracting a documentation string from documentation comments.
• hash
  Calculate a type hash at compile time.
• item
  Calculate an item reference at compile time.
• sources
  Helper macro to define a collection of sources populatedc with the given entries.
• static_env
  Defines a static budget and environment implementation suitable for singlethreaded no-std environments. This can be used in #[no_std] environments to implement the necessary hooks for Rune to work.
• vm_panic
  Helper to cause a panic.
• vm_try
  Helper to perform the try operation over VmResult.
• vm_write
  Helper macro to perform a write! in a context which errors with VmResult and returns VmResult<Result<_, E>> on write errors.

Structs

• Build
  A builder for 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.
• Item
  The reference to an ItemBuf.
• ItemBuf
  The name of an item in the Rune Language.
• Module
  A Module that is a collection of native functions and types.
• Mut
  A strong owned mutable reference to the given type that can be safely dereferenced.
• Options
  Options that can be provided to the compiler.
• Params
  Helper to register a parameterized function.
• Ref
  A strong owned reference to the given type that can be safely dereferenced.
• Source
  A single source file.
• SourceId
  The opaque identifier of a source file, as returned by Sources::insert.
• Sources
  A collection of source files.
• Unit
  Instructions and debug info from a single compilation.
• Value
  An entry on the stack.
• Vm
  A stack which references variables indirectly from a slab.

Enums

• ContextError
  An error raised when building the context.

Traits

• Any
  Derive for types which can be used inside of Rune.
• FromValue
  Trait for converting types from the dynamic Value container.
• ToConstValue
  Convert a value into a constant value.
• ToTypeHash
  Helper trait used to convert a type into a type hash.
• ToValue
  Trait for converting types into the dynamic Value container.
• TypeHash
  Static type hash for a given type.

Functions

• from_const_value
  Convert something into a ConstValue.
• from_value
  Convert something into the dynamic Value.
• prepare
  Entry point to building a collection Sources of Rune into a default executable Unit.
• to_const_value
  Convert something into a ConstValue.
• to_value
  Convert something into the dynamic Value.

Attribute Macros

• function
  Macro used to annotate native functions which can be loaded into rune.
• module
  Macro used to annotate a module with metadata.

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.
• ToConstValue
  Derive for the ToConstValue trait.
• ToValue
  Derive macro for the ToValue trait for converting types into the dynamic Value container.