NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
crates.io · #3006 most downloaded on crates.io
Embedded scripting for Rust
Last release 28 days ago
10 Sep 2026
Ships fairly regularly
a new release about every 3 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
9 versions withdrawn
withdrawn after publishing
11 years old
105 releases · first in 2016
This is a maintenance release to fix a bug in the tokenizer that disallows valid variable names like _i (thanks `@dtolnay` `#1167`).
The major change in this version is the addition of the experimental Rhai Grain bytecodes VM for faster evaluation of scripts under resource constrain
This is a significant release.
The major change in this version is the addition of the experimental Rhai Grain bytecodes VM for faster evaluation of scripts under resource constraints.
This is experimental and gated under the grain feature flag.
grain feature) for fast evaluation of scripts (thanks @ImTheSquid #1109).Since the Rhai Grain VM must run a script exactly the same as the standard AST interpreter, a number of bugs have been uncovered that are now fixed.
#1126).#1139).switch statement that fails to try ranges when all conditions of exact matches fail (#1117).switch statement that fails to match shared values (#1123).#1114).Engine::compact_script that generates invalid compacted scripts due to missing spaces between ambiguous operators (thanks @yuvalrakavy #1106).One column per quarter.
This is a patch release that reverses the change in 1.25.0 that removed certain exports from the rhai::plugin module, which is a breaking change.
This is a patch release that reverses the change in 1.25.0 that removed certain exports from the
rhai::plugin module, which is a breaking change.
The exports are now re-added will only be removed in the next major version.
Thanks to @Abendrill #1099.
Engine::compact_script now properly compacts scripts with custom syntax that uses $raw$ (thanks @yuvalrakavy #1079 ).
Engine::compact_script now properly compacts scripts with custom syntax that uses $raw$ (thanks @yuvalrakavy #1079).split, split_rev and their variants are now marked pure so they can be called on const strings (thanks @theJC #1082).index_of now falls back to value comparison for string argument when no script function of that name is registered (thanks @yinho999 #1086).walk API now correctly visits the arguments to MethodCall and switch statements (thanks @isSerge #1092 #1093)Engine::on_missing_function, is added (gated under the internals feature) to override default handling when a called function or method is not found (thanks @yuvalrakavy #1067).EvalContext::new_frame, is added to created an isolated frame guard that automatically restores field values upon Drop (thanks @yuvalrakavy for the idea #1085).\${...} is supported in multi-line literal strings to escape interpolation, yielding literally ${...} for the string (thanks @yinho999 #1089).#[export_module] and #[derive(CustomType)] no longer require importing standard Rhai types (thanks @timokoesters #1071).FnPtr::call_fn_as_method and FnPtr::call_as_method_within_context are added (when not under no_object) to accept a this pointer for calling the function pointer as a method call (thanks @yunfengzh for the request #1080).NativeCallContext::call_method and NativeCallContext::call_native_method are added (when not under no_object) to accept a this pointer for method calls (thanks @yunfengzh for the idea #1080).This new release has a breaking change because of the upgrade to the getrandom crate to version 0.3.
This new release has a breaking change because of the upgrade to the getrandom crate to version 0.3.
As a result, stdweb support has been dropped. It is anticipated that this change would not have significant impact on normal usage.
stdweb support is removed. The feature flag stdweb is also removed. Use wasm-bindgen instead.web-time is used for WASM targets instead of instant, which is no longer maintained #1063.sort on an array with a comparer function that does not implement a total order #1058.@phsym #1050).if cond1 { if cond2 { ... } } into if cond1 && cond2 { ... }.sort for arrays is also aliased to sort_by.sort_desc, order, order_by and order_desc are added to arrays.sort on an array containing unsupported element types.AST::new_from_module is added to create an AST from a shared Module.The binary bit-wise operators &, | and ^ now work correctly with INT operands (#1037).
&, | and ^ now work correctly with INT operands (#1037).contains, get, filter and to_json for object maps are now marked pure (#1037).contains, get, parse_le_int, parse_be_int, parse_le_float and parse_be_float for BLOB's are now marked pure (#1037).E can now be used in scientific notation for floating-point and decimal literals (thanks @BrynCooke #1039).drain and retain methods for object maps no longer empty the target map upon errors (#1043).VariableExpected parser error (thanks @TheAwiteb #1047).map is added to object maps.starts_with and ends_with now work with character argument (#1042).This version is the same as version 1.23.6 but maintains compatibility by restricting the `ahash` dependency to <=0.8.11 because higher versions break
This version is the same as version 1.23.6 but maintains compatibility by restricting the
ahash dependency to <=0.8.11 because higher versions break
no-std builds.
(Fuzzing) Fixed crash when using ..= in arrays, BLOB's, bit-fields and iterators (#1004).
..= in arrays, BLOB's, bit-fields and iterators (#1004).ModuleResolversCollection now properly enable access to the scope etc.@mkeeter #1003).NativeCallContext::fn_source now correctly returns the source of the function (usually None). The missing NativeCallContext::call_source is added to return the source of caller (thanks @FlashSystems #1013).Engine::collect_fn_metadata now properly includes functions registered into the global namespace (thanks @therealprof and @matthiasbeyer #1017).build.rs no longer writes to the source tree but OUT_DIR instead (thanks @matthiasbeyer #1018)CustomType derive macro now supports generic types (thanks @ProphetOSpam #999). The rhai_codegen crate dependency is bumped to 3.0.0 or later.CustomType derive macro now handles Option fields (thanks @agersant #1011).Engine::eval_fn_call is added to make a generic function call.Engine::eval_binary_op is added to quickly compare two Dynamic values.try_from (thanks @therealprof #1009).$token$, $inner$, and $raw$ can now be used in custom syntax definitions (#1023).Engine::register_custom_syntax_without_look_ahead_raw is added to allow the use of $raw$ in custom syntax, which returns the script text character-by-character without processing, by-passing the tokenizer. This in turn allows for parsing arbitrary syntax. (#1022)CallFnOptions::in_all_namespaces is added to allow calling functions in all namespaces, instead of only scripted Rhai functions in the AST.The ahash crate that Rhai depends on has a breaking change since version 0.8.12 which bumps getrandom to version 0.3 , braking certain no-std and wasm…
The ahash crate that Rhai depends on has a breaking change since version 0.8.12 which bumps getrandom to version 0.3, braking certain no-std and wasm builds.
Version 1.23.3: Use this version when building for no-std
Version 1.23.4: This is the main version for std builds.
..= in arrays, BLOB's, bit-fields and iterators (#1004).ModuleResolversCollection now properly enable access to the scope etc.@mkeeter #1003).NativeCallContext::fn_source now correctly returns the source of the function (usually None). The missing NativeCallContext::call_source is added to return the source of caller (thanks @FlashSystems #1013).Engine::collect_fn_metadata now properly includes functions registered into the global namespace (thanks @therealprof and @matthiasbeyer #1017).build.rs no longer writes to the source tree but OUT_DIR instead (thanks @matthiasbeyer #1018)CustomType derive macro now supports generic types (thanks @ProphetOSpam #999). The rhai_codegen crate dependency is bumped to 3.0.0 or later.CustomType derive macro now handles Option fields (thanks @agersant #1011).Engine::eval_fn_call is added to make a generic function call.Engine::eval_binary_op is added to quickly compare two Dynamic values.try_from (thanks @therealprof #1009).$token$, $inner$, and $raw$ can now be used in custom syntax definitions (#1023).Engine::register_custom_syntax_without_look_ahead_raw is added to allow the use of $raw$ in custom syntax, which returns the script text character-by-character without processing, by-passing the tokenizer. This in turn allows for parsing arbitrary syntax. (#1022)CallFnOptions::in_all_namespaces is added to allow calling functions in all namespaces, instead of only scripted Rhai functions in the AST.This version is the same as version 1.23.4 but maintains compatibility by restricting the
ahash dependency to <=0.8.11 because higher versions break
no-std builds.
Nothing published for this version
Nothing published for this version
Nothing published for this version
This version removes the version restriction on ahash which may break code for no-std builds.
This version removes the version restriction on ahash which may break code for no-std builds.
Do not mask out version 0.8.11 for ahash.
ahash.(Fuzzing) An integer-overflow bug from an inclusive range in get_bits is fixed ( #963 ).
get_bits is fixed (#963).private now properly cause compilation errors (#993).@dcihlar #976). The same for passing a closure (thanks again, @dcihlar #979).@HactarCE #981).@HactarCE #987).Engine::collect_fn_metadata now properly includes the namespaces of functions in static modules (thanks @therealprof and @elkowar #992).@rhizoome and @HactarCE #988).source and position in NativeCallContext are now fn_source and call_position. A new method call_source is added to return the source (if any) of the caller function (thanks @rhizoome and @HactarCE #989).&&, || and ?? operators are optimized to allow efficient chaining (#994).Nothing published for this version
Fixed bug in raw strings (thanks @benatkin 944 ).
@benatkin 944).get_fn_metadata_list function is marked volatile.no-std plus sync should now build correctly (thanks stargazing-dino 947).FnPtr) which binds to a native Rust function or closure via FnPtr::from_dn and FnPtr::from_dyn_fn. When called in script, the embedded function will be called (thanks @makspll 952).call_fn, call_native_fn, call_fn_raw and call_native_fn_raw are added to EvalContext (thanks @rawhuul 954).internals function, Engine::collect_fn_metadata, is added to collect all functions metadata. This is to facilitate better error reporting for missing functions (thanks therealprof 945).Fixed bug in raw strings with newlines (thanks @benatkin 940 ).
(Fuzzing) An integer-overflow bug from an inclusive range in the bits iterator is fixed.
@irevoire 917).Scope now works correctly (thanks @AngelicosPhosphoros 918).thumbv6m target is fixed (thanks chxry 919)##..#" ... "#..## (thanks @cellomath 908 910).Variable resolver now correctly resolves variables that are captured in a closure.
NativeCallContext<'_> (with a lifetime parameter) now parses correctly in the #[export_module] macro. This is to allow for rust_2018_idioms lints (thanks @ltabis 864).sync feature now works properly in no-std builds (thanks @misssonder 874).min and max functions where both operands are floats or Decimal are added.@MageWeiG 880).Engine::call_fn and Engine::call_fn_with_options now correctly use the AST's source field...= in strings.Dynamic::is_hashable is fixed.break, continue, return and throw statements can now follow the ?? operator to short-circuit operations where the value is ().$func$, is added to custom syntax to allow parsing of anonymous functions.filter, drain and retain methods are added to object maps.The plugin macros export_fn , register_exported_fn! , set_exported_fn! and set_exported_global_fn! are deprecated because they do not add value over e…
Starting from this version, we try to put contributors' names on features/enhancements/fixes that they contributed.
We apologize for neglecting to adopt this practice earlier, but late is better than never!
optimize command in rhai-repl now works properly and cycles through None->Simple->Full.Engine::call_fn_XXX no longer return errors unnecessarily wrapped in EvalAltResult::ErrorInFunctionCall.@alexanderkjall #851).try statement with an empty body.export_fn, register_exported_fn!, set_exported_fn! and set_exported_global_fn! are deprecated because they do not add value over existing direct API's.s[1..4] (thanks @zitsen #845).CustomType derive macro (thanks @Itabis #847).Engine::set_max_strings_interned and Engine::max_strings_interned are added to limit the maximum number of strings interned in the Engine's string interner.Engine::on_invalid_array_index, is added (gated under the internals feature) to handle access to missing properties in object maps.Engine::on_missing_map_property, is added (gated under the internals feature) to handle out-of-bound index into arrays.parse_json is also available without the metadata or serde feature -- it uses Engine::parse_json to parse the JSON text (thanks @Mathieu-Lala #840).FuncRegistration::in_global_namespace and FuncRegistration::in_internal_namespace are added to avoid pulling in FnNamespace.BasicIteratorPackage in addition to the regular array/BLOB/string packages.LexError::Runtime is added for use with Engine::on_parse_token.sync are now handled more elegantly -- instead of deadlocking and hanging indefinitely, it spins for a number of tries (waiting one second between each), then errors out.This is a bug-fix release that bumps rhai_codegen version to 2.0.0 to satisfy semver rules.
This is a bug-fix release that bumps rhai_codegen version to 2.0.0 to satisfy semver rules.
ImmutableString now derefs to &str instead of &SmartString. Normally this should not be a breaking change.
Starting from this version, the official preferred method of registering an API for a custom type is via the #[derive(CustomType)] macro. The old API is still available for types that reside in external crates (and thus cannot implement CustomType).
Starting from this version, the new FuncRegistration API is preferred for registering native Rust functions into a Module. The old API is still available but deprecated.
Starting from this version, fuzzing via Google OSS-Fuzz is used to flush out hidden bugs and edge cases. This should result in higher code quality, better stability and improved security. And indeed, a large number of bugs have been discovered from this and fixed.
ImmutableString now derefs to &str instead of &SmartString. Normally this should not be a breaking change.ImmutableString are cleaned up. Normally this should not be a breaking change.EvalContext::new, FloatWrapper and ConditionalExpr are now gated under internals.@silvergasp for setting up fuzzing.#[derive(CustomType)] is now available, driven by procedural macros in rhai_codegen (thanks @MavethGH #817).FuncRegistration API is added to assist in registering native Rust functions into modules with various settings. Some of the original Module::set_fn... API is now deprecated.volatile which prevents it from being optimized away even under OptimizationLevel::Full.Engine::max_functions and Engine::set_max_functions to limit the maximum number of functions allowed in a script. This is to guard against DOS attacks -- e.g. a simple closure || (two characters) is a function. When max_function is exceeded during script compilation, a new parse error, ParseErrorType::TooManyFunctions, is returned.Engine::get_interned_string is made public instead of gated under internals.rhai::config::hashing::set_ahash_seed, rhai::config::hashing::get_ahash_seed and the RHAI_AHASH_SEED environment variable are deprecated in favor of rhai::config::hashing::set_hashing_seed, rhai::config::hashing::get_hashing_seed and RHAI_HASHING_SEED.AST::clear_doc is deprecated.Module::update_XXX API is deprecated in favor of using the FuncRegistration API.Module::gen_fn_signatures is deprecated in favor of Module::gen_fn_signatures_with_mapper.**.(a.b).c.Dynamic parameters with more than 16 parameters.sleep no longer panics on NaN.switch on ranges now work properly.to_json() when the serde feature is not enabled.Engine::format_map_as_json now serializes arrays correctly.Engine::gen_fn_signatures(false) now properly skips functions in the standard library.TypeBuilder::with_name now properly sets the display-name of the type for use in generating metadata.to_int method for characters.Token::FloatConstant and Token::DecimalConstant now carry the original text representation for use in, say, a token mapper.Dynamic::is_fnptr is made a public API.Scope::get_value_ref and Scope::get_value_mut are added.TypeBuilder::with_name now takes any &str instead of just &'static str.Engine::gen_fn_signatures now formats the function signatures using pretty-print names of custom types.Public fields of VarDefInfo are marked deprecated but still accessible.
Public fields of VarDefInfo are marked deprecated but still accessible.
Fixes compilation error when importing multiple modules.
Fixes compilation error when importing multiple modules.
Fixes compilation error when using the serde feature with metadata.
Fixes compilation error when using the serde feature with metadata.
Minimal version numbers for dependencies are now specified in Cargo.toml to avoid breaking changes in future versions.
The minimum Rust compiler version is raised to 1.66.0.
max_operations, max_array_size etc.) as well as Engine::ensure_data_size_within_limits are no longer exported under unchecked. This should be the correct behavior instead of returning None or zero.OptimizationLevel is no longer exported under no_optimize. Originally it was mapped to () under no_optimize.wasm32-wasi (or any WASM target other than wasm32-unknown).this as the first parameter in a namespace-qualified function call.false (except for != which defaults to true).max and min for integers, strings and characters were missing from the standard library. They are now added.Cargo.toml to avoid breaking changes in future versions.bitflags is bumped to version 2.syn in rhai_codegen is bumped to version 2.hashbrown (used in no-std builds) is bumped to version 0.14.ParseErrorType::MalformedCallExpr and ParseErrorType::MalformedInExpr are deprecated and will be removed in the next major version.Module::get_custom_type is deprecated in favor of Module::get_custom_type_display_by_name and other new methods.exit function that terminates script evaluation regardless of where it is called, even inside deeply-nested function calls.Engine::max_variables and Engine::set_max_variables to limit the maximum number of variables allowed within a scope at any time. This is to guard against defining a huge number of variables containing large data just beyond individual data size limits. When max_variables is exceeded a new error, ErrorTooManyVariables, is returned.zip function for arrays.on_print and on_debug definitions for TypeBuilder.Module::get_custom_type_raw. These doc-comments for custom types are also exported in JSON via Engine::gen_fn_metadata_to_json.once_cell is used in std environments instead of the home-brew SusLock which is removed.? operator liberally to simplify code. However, this causes the loss of proper line numbers when a test fails, making it difficult to identify the exact location of the failure. This is now fixed by changing to unwrap().Vec because they are not transient and do not appear to improve performance. Using Vec seems to be yield better performance as it probably enables more compiler optimizations.Dynamic::deep_scan is fixed so now it properly scans arrays, object maps and function pointers embedded inside data.
Dynamic::deep_scan is fixed so now it properly scans arrays, object maps and function pointers embedded inside data.Fixes a concurrency error in static hashing keys (thanks `garypen`!).
garypen!).this should now run slightly faster due to a dedicated AST node ThisPtr.take function is added to the standard library to take ownership of any data (replacing with ()) in order to avoid cloning.Dynamic::take is added to take ownership of the data (replacing with ()) in order to avoid cloning.EvalAltResult::ErrorMismatchOutputType now gives a better name for the requested generic type (e.g. &str is now &str and not string).This new version contains a substantial number of bug fixes for edge cases.
This new version contains a substantial number of bug fixes for edge cases.
A new syntax is supported to facilitate writing object methods in script.
The code hacks that attempt to optimize branch prediction performance are removed because benchmarks do not show any material speed improvements.
is_shared is a reserved keyword and is now handled properly (e.g. it cannot be the target of a function pointer).optimize_ast with constants now works correctly for closures. Previously the hidden Share nodes are not removed and causes variable-not-found errors during runtime if the constants are not available in the scope.(v[0].func()).prop now parse correctly.const X = 1; const X = 1 + 1 + 1; X now evaluates to 3 instead of 0).thumbv6m-none-eabi target (e.g. Raspberry Pi Pico) now completes successfully. Dependency to no-std-compat is now pointed to the latest repo instead of crates.io.this pointer for a particular script-defined function so that it is called only when the this pointer contains the specified type.is_def_fn is extended to support checking for typed methods, with syntax is_def_fn(this_type, fn_name, arity)Dynamic::take is added as a short-cut for std::mem::take(&mut value).Engine::is_symbol_disabled is added to test whether a particular keyword/symbol is disabled.Dynamic value containing custom types or shared values back into another Dynamic (essentially a straight cloned copy).The trait method ModuleResolver::resolve_raw (which is a low-level API) now takes a &mut Scope parameter. This is a breaking change because the signat…
This version attempts a number of optimizations that may yield small speed improvements:
gperf) for keyword recognition.Engine::black_box) is used to prevent LLVM from optimizing hand-tuned AST node matches back into a lookup table, which messes up branch prediction on modern CPU's.a[b][c[d]].emap and filter for arrays are marked pure. Warnings are added to the documentation of pure array methods that take this closures.foo.bar::baz no longer panics, but returns a proper parse error.!inside now parses correctly instead of as !in followed by side.x += y where x and y are char, now work correctly instead of failing silently.ModuleResolver::resolve_raw (which is a low-level API) now takes a &mut Scope parameter. This is a breaking change because the signature is modified, but this trait method has a default and is rarely called/implemented in practice.Module::eval_ast_as_new_raw (a low-level API) now takes a &mut Scope instead of the Scope parameter. This is a breaking change because the &mut is now required.Engine::allow_loop_expressions now correctly defaults to true (was erroneously false by default).Engine::new_raw is now const and runs very fast, delaying all other initialization until first use.min and max are added for numbers.switch statements now also match floating-point and decimal values. In order to support this, however, small numeric ranges cases are no longer unrolled.import now gives the module access to the current scope, including variables and constants defined inside.gperf. At least theoretically it should be faster...isAnonymous is added to JSON functions metadata.Module::with_capacity is deprecated.
INT now fall back to Decimal or FLOAT instead of silently truncating.||{||{||{||{||{||{||{...}}}}}}}) no longer panics but will be confined to the nesting limit.Engine::eval_expression etc.Engine::new_raw without any standard package.Fn now throws an error if the name is a reserved keyword as it cannot possibly map to such a function. This also disallows creating function pointers to custom operators which are defined as disabled keywords (a mouthful), but such custom operators are designed primarily to be used as operators.Fn(&Engine, Debugger) -> Debugger. This allows more control over the initial setup of the debugger.reify! is no longer available publicly.Module::with_capacity is deprecated.Engine::eval_statements_raw is deprecated.Fn("...") call.exported from modules!!in!in is added which maps to !(... in ...).Engine::call_fn_with_optionsEngine::call_fn_raw is deprecated in favor of Engine::call_fn_with_options which allows setting options for the function call.NativeCallContext::tag) for a function evaluation, overriding Engine::set_default_tag.Engine::compact_script is added which takes a valid script (it still returns parsing errors) and returns a compacted version of the script with all insignificant whitespaces and all comments removed.Engine::compact_script does not optimize the script in any way, nor does it rename variables.map, filter, index_of, reduce etc.), can now bind the array element to this when calling a closure.find and find_map are added for arrays.for_each is also added for arrays, allowing a closure to mutate array elements (bound to this) in turn.Option<Box<T>>. This resulted in some speed improvements.CallableFunction is exported under internals.TypeBuilder type and CustomType trait are no longer marked as volatile.FuncArgs is also implemented for arrays.Engine::set_XXX API can now be chained.EvalContext::scope_mut now returns &mut Scope instead of &mut &mut Scope.doc field.Index and IndexMut are added to FnPtr.FnPtr::iter_curry and FnPtr::iter_curry_mut are added.Dynamic::deep_scan is added to recursively scan for Dynamic values.>> and << operators on integers no longer throw errors when the number of bits to shift is out of bounds. Shifting by a negative number of bits simply reverses the shift direction.NativeCallContext::new is completely deprecated and unimplemented (always panics) in favor of new API's.
Engine::parse_json now returns an error on unquoted keys to be consistent with JSON specifications.import statements inside eval no longer cause errors in subsequent code.global in imported modules with no alias names now work properly.do { ... } until true with a break statement inside) and cause crashes are removed.Dynamic::is now works properly for shared values.NativeCallContext::new is completely deprecated and unimplemented (always panics) in favor of new API's.Dynamic detection APIDynamic in the form of is_XXX() where XXX is a type (e.g. is_int, is_unit, is_bool, is_array).is::<XXX>().loop, do, while and for) can now act as expressions, with the break statement returning an optional value.() as the value.Engine::set_allow_loop_expressionsahash hasher, via a static function rhai::config::hashing::set_ahash_seed or an environment variable (RHAI_AHASH_SEED), in order to force static (i.e. deterministic) hashes for function signatures.RHAI_AHASH_SEED, if any) and splice it into the source code before compilation.no_time for no timestampsno_time, is added to disable support for timestamps.ScopeScope is now serializable and deserializable via serde.NativeCallContextNativeCallContext into a new NativeCallContextStore type.NativeCallContext to be stored and recreated later on.NativeCallContextNativeCallContext::call_native_fn is added to call registered native Rust functions only.NativeCallContext::call_native_fn_raw is added as the advanced version.string).Engine::max_string_len) are now available even under unchecked.parse_json function is added to parse a JSON string into an object map.Error::ErrorNonPureMethodCallOnConstant is added which is raised when a non-pure method is called on a constant value.[Engine::register_custom_syntax_raw] is deprecated.
decimal feature.Engine::register_custom_syntax_with_state_raw] is added. The custom syntax parser and implementation functions take on an additional parameter that holds a user-defined custom state which should substantially simplify writing some custom parsers.Engine::register_custom_syntax_raw] is deprecated.All versions of the Engine::register_XXX_result API that register a function returning Result > are now deprecated. The regular, non-result versions h…
This version introduces Fast Operators mode, which is turned on by default but can be disabled via
a new options API: Engine::set_fast_operators.
Fast Operators mode assumes that none of Rhai's built-in operators for standard data types are
overloaded by user-registered functions. In the vast majority of cases this should be so (really,
who overloads the + operator for integers anyway?).
This assumption allows the Engine to avoid checking for overloads for every single operator call.
This usually results in substantial speed improvements, especially for expressions.
The minimum Rust version is now 1.61.0 in order to use some const generics.
Engine now works with functions that take a first parameter of NativeCallContext.Module::set_getter_setter_fn is added.rhai-run; previous it was full optimization.Engine::register_XXX_result API that register a function returning Result<T, Box<EvalAltResult>> are now deprecated. The regular, non-result versions handle all functions correctly.Engine::fast_operators is introduced (default to true) to enable/disable Fast Operators mode.if-expressions are allowed in Engine::eval_expression and Engine::compile_expression provided that both statement blocks each contain at most a single expression.switch-expressions are allowed in Engine::eval_expression and Engine::compile_expression provided that match actions are expressions only.is_empty method is added to arrays, BLOB's, object maps, strings and ranges.StaticModuleResolver now stores the path in the module's id field.Engine::module_resolver is added to grant access to the Engine's module resolver.This is a bug-fix version that fixes a bug.
This is a bug-fix version that fixes a bug.
Accessing properties in Strict Variables Mode no longer generates a variable not found error.
The error ParseErrorType::DuplicatedSwitchCase is deprecated.
The minimum Rust version is now 1.60.0 in order to use the dep: syntax for dependencies.
switch cases with conditions that evaluate to constant () no longer optimize to false (should raise a type error during runtime).call_fn_raw on a function without evaluating the AST no longer panics on namespace-qualified function calls due to import statements not run.Engine::register_debugger now takes a single parameter which is a reference to the current Engine.std, which is enabled by default, is added due to requirements from dependency crates.no_custom_syntax, is added to remove custom syntax support from Rhai for applications that do not require it (which should be most).//! (requires the metadata feature) are now collected as the script file's module documentation.AST and Module have methods to access and manipulate documentation.Engine, for use with the Rhai Language Server.rhai::eval, rhai::run, rhai::eval_file, rhai::run_file are added as convenient wrappers.Engine::build_type, enables registration of the entire API of a custom type in one go, provided that the custom type implements the CustomType trait (which uses TypeBuilder to register the API functions).Package::register_into_engine and Package::register_into_engine_as API.switch statementswitch cases can now include multiple values separated by |.switch cases are now allowed.ParseErrorType::DuplicatedSwitchCase is deprecated.switch statements that are small (currently no more than 16 items) are unrolled if possible.EvalContext::eval_expression_tree_raw and Expression::eval_with_context_raw are added to allow for not rewinding the Scope at the end of a statements block.range function variant that takes an exclusive range with a step.as_string is added to BLOB's to convert it into a string by interpreting it as a UTF-8 byte stream.FnAccess::is_private, FnAccess::is_public, FnNamespace::is_module_namespace and FnNameSpace::is_global_namespace are added for convenience.Iterator<Item=T> type for functions metadata is simplified to Iterator<T>.Scope::remove is added to remove a variable from a Scope, returning its value.ParseError::err_type and ParseError::position are added for convenience.AST compiled from a script file is set to the file's path.|> and <| are now reserved symbols.FnPtr::num_curried is deprecated in favor of FnPtr::curry().len().
AST now works properly with Engine::call_fn.to_int from Decimal is added.AST into another AST now works properly.#![deny(missing_docs)].Engine::register_static_module are now checked in Strict Variables Mode.?, ??, ?., ?[ and !. are now reserved symbols.FnPtr::num_curried is deprecated in favor of FnPtr::curry().len().?. and ?[) are now supported for property access, method calls and indexing.??) is now supported to short-circuit () values.EvalAltResult::IndexNotFound is added to aid in raising errors for indexers.Engine::def_tag, Engine::def_tag_mut and Engine::set_tag are added to manage a default value for the custom evaluation state, accessible via EvalState::tag() (which is the same as NativeCallContext::tag()).EvalState::tag() (which is the same as NativeCallContext::tag()). It is now split into its own variable accessible under Debugger::state().serde.Scope::get is added to get a reference to a variable's value.Compound assignments now work properly with indexers.
Scope no longer turns all constants to mutable.Scope.Engine::on_var and Engine::on_parse_token API's are now marked unstable/volatile.Engine::on_var, Engine::on_def_var and Engine::register_debugger take EvalContext instead of &EvalContext or &mut EvalContext.non_exhaustive: AccessMode, FnAccess, FnNamespace, FnMetadata, OptimizationLevelModule::eval_ast_as_new_raw is made public as a low-level API.format_map_as_json is provided globally, which is the same as to_json for object maps.Engine::call_fn_raw_raw is added to add speed to repeated function calls.Engine::eval_statements_raw is added to evaluate a sequence of statements.Dynamic, which can hold any data, and can be accessed by the host via EvalContext::tag, EvalContext::tag_mut, NativeCallContext::tag and GlobalRuntimeState.tag.switch case condition syntax is now caught at parse time.Engine::parse_json now natively handles nested JSON inputs (using a token remap filter) without needing to replace { with #{.to_json is added to object maps to cheaply convert it to JSON format (() is mapped to null, all other data types must be supported by JSON)FileModuleResolver now accepts a custom Scope to provide constants for optimization.Start and End, are added to DebuggerEvent triggered at the start/end of script evaluation.Functions with Dynamic parameters now work in qualified calls from imported modules.
Dynamic parameters now work in qualified calls from imported modules.rhai-repl now compiles with the new patch version of rustyline.rhai_codegen dependency is now explicitly 1.4 or higher.split now splits a string by whitespaces instead of splitting it into individual characters. This is more in line with common practices.to_chars for strings is added to split the string into individual characters.for .. in) yielding individual characters.This version, in particular, fixes a plugin macro hygiene error for the nightly compiler:
This version, in particular, fixes a plugin macro hygiene error for the nightly compiler:
error[E0425]: cannot find value `args` in this scope
1.57 due to smartstring dependency.a.b::c.d or a.b::func() no longer panics but properly returns a syntax error.Scope::is_constant now returns the correct value.FnAccess and FnNamespace now implement Ord and PartialOrd.event_handler_map example is enhanced to prevent shadowing of the state object map.sleep is added to block the current thread by a specified number of seconds.Scope::set_alias is added to export a variable under a particular alias name.starts_with and ends_with are added for strings.register_global_module can now be accessed in the global namespace.Dynamic::into_read_only is added to convert a Dynamic value into constant.Module now holds a collection of custom types with an API.This version adds a debugging interface, which can be used to integrate a debugger.
This version adds a debugging interface, which can be used to integrate a debugger.
Based on popular demand, an option is added to throw exceptions when invalid properties are accessed on object maps (default is to return ()).
Also based on popular demand, the REPL tool now uses a slightly-enhanced version of rustyline for line editing and history.
Scope::clone_visible, constants are now properly cloned as constants.try blocks are now properly cleaned up upon an exception.catch-ed.import statement, the export statement no longer exports multiple variables.+, +=, append or string interpolation) now treats the BLOB as a UTF-8 encoded string.+= or append) now adds the string/character as a UTF-8 encoded byte stream.rhai-dbg (aka The Rhai Debugger), is added to showcase the debugging interface.DebuggingPackage, is added which contains the back_trace function to get the current call stack anywhere in a script.Engine::set_fail_on_invalid_map_property is added to control whether to raise an error (new EvalAltResult::ErrorPropertyNotFound) when invalid properties are accessed on object maps.Engine::set_allow_shadowing is added to allow/disallow variables shadowing, with new errors EvalAltResult::ErrorVariableExists and ParseErrorType::VariableExists.Engine::on_def_var allows registering a closure which can decide whether a variable definition is allow to continue, during compilation or runtime, or should fail with an error (ParseErrorType::ForbiddenVariable or EvalAltResult::ErrorForbiddenVariable).$crate meta variable).ahash/std and num-traits/std) are no longer required.no_module feature now eliminates large sections of code via feature gates.AST is improved.NativeCallContext::call_level() is added to give the current nesting level of function calls.bin-features, pulls in all the required features for bin tools.AST position display is improved:
Expr::start_position is added to give the beginning of the expression (not the operator's position).StmtBlock and Stmt::Block now keep the position of the closing } as well.EvalAltResult::unwrap_inner is added to access the base error inside multiple layers of wrappings (e.g. EvalAltResult::ErrorInFunction).def_package! that further simplifies the old syntax.to_blob is added to convert a string into a BLOB as UTF-8 encoded bytes.to_array is added to convert a BLOB into array of integers.The REPL bin tool, rhai-rpl, has been enhanced.
rustyline feature is now required in order to build rhai-repl.rhai-repl is no longer automatically built when using a simple cargo build with default features.rhai-repl now uses a modified version of rustyline as a line editor with history.\ continuation character the end of each line.rhai-repl is made much more convenient.strict to turn on/off Strict Variables Mode.optimize to turn on/off script optimization.history to print lines history.!!, !num, !text and !?text to recall a history line.keys to print all key bindings.This is primarily a bug-fix version which fixes a large number of bugs.
This is primarily a bug-fix version which fixes a large number of bugs.
x = x + 1 no longer panics.pad no longer loops indefinitely.chop for arrays and BLOB's now works properly.set_bit for bit-flags with negative index now works correctly.params field name in the JSON output of Engine::gen_fn_metadata_to_json is fixed (was incorrectly named type).unsafe violation in for loop.to_hex, to_octal and to_binary for i128 and u128 are added.remove for arrays and BLOB's now treat negative index correctly.parse_int now works properly for negative numbers.Engine::gen_fn_signatures now generates signatures for external packages registered via Engine::register_global_module.\r\n pairs are now recognized correctly for doc-comments.SmartString for Scope variable names and remove unsafe lifetime casting.Engine::gen_fn_metadata_to_json).get and set methods are added to arrays, BLOB's, object maps and strings.Expression::get_variable_name is deprecated in favor of the new Expression::get_string_value.
This version adds support for integer ranges via the .. and ..= operators.
Many standard API's are extended with range parameters where appropriate.
is is (pun intended) now a reserved keyword to prepare for possible future type checking expressions (e.g. x is "string").LogicPackage is removed from CorePackage.BitFieldPackage (used to be in LogicPackage) which makes more sense.INT integer types are now treated exactly as custom types under only_i64 and only_i32.pad on an array now checks for total size over limit after each item added... and ..= operators.EvalAltResult::ErrorCustomSyntax to catch errors in custom syntax, which should not happen unless an AST is compiled on one Engine but evaluated on another unrelated Engine.BLOB's are refined to display in a more compact hex format.def_package! that will replace the old syntax in future versions.NativeCallContext::call_fn to easily call a function.Expression::get_variable_name is deprecated in favor of the new Expression::get_string_value.def_package! is deprecated in favor of the new syntax.NativeCallContext::new is deprecated because it is simpler to call a function pointer via FnPtr::call.
This version adds native support for BLOB's (byte arrays), as well as a number of configuration
settings to fine-tun language features.
from_dynamic now supports deserializing Option.BLOB (essentially a byte array) is added as a supported primitive value type parallel to arrays.Engine which allows disabling if-expressions, switch-expressions, statement expressions, anonymous functions and/or looping (i.e. while, loop, do and for statements):
Engine::set_allow_if_expressionEngine::set_allow_switch_expressionEngine::set_allow_statement_expressionEngine::set_allow_anonymous_fnEngine::set_allow_loopingEngine (enabled via Engine::set_strict_variables) to throw parse errors on undefined variable usage. Two new parse error variants, ParseErrorType::VariableNotFound and ParseErrorType::ModuleNotFound, are added."") in a string literal now maps to "; two back-ticks (``) in a literal string now maps to `.Engine::register_type_with_name_raw to register a custom type based on a fully-qualified type path.into_array and into_typed_array for Dynamic.FnPtr::call and FnPtr::call_within_context to simplify calling a function pointer.baseHash field in the JSON object should map directly to the pre-calculated hash in the function call.Expression now derefs to Expr.NativeCallContext::new is deprecated because it is simpler to call a function pointer via FnPtr::call.AST::merge_filtered and AST::combine_filtered are no longer exported under no_function.AST::new and AST::new_with_source are moved under internals.FnPtr::call_dynamic is deprecated in favor of FnPtr::call_raw.Array methods (such as map) taking a closure with captures as argument now works properly.
map) taking a closure with captures as argument now works properly.Engine::call_fn_dynamic is deprecated and Engine::call_fn_raw is added which allows keeping new variables in the custom scope.
!) now operates directly on the caller's scope, allowing variables inside the scope to be mutated.Engine::XXX_with_scope API's now properly propagate constants within the provided scope also to functions in the script.0.0).func!() calls now work properly under no_closure.if foo { ... } -x parses correctly.#[cfg(...)] attributes can now be put directly on plugin functions or function defined in a plugin module.$$ to inform the implementation function which syntax variant was actually parsed.AST::iter_literal_variables is added to extract all top-level literal constant/variable definitions from a script without running it.Engine::call_fn_dynamic is deprecated and Engine::call_fn_raw is added which allows keeping new variables in the custom scope.dedup method.sort method with no parameters which sorts homogeneous arrays of built-in comparable types (e.g. INT).optimize module is completely eliminated under no_optimize, which should yield smaller code size.NativeCallContext::position is added to return the position of the function call.Scope::clone_visible is added that copies only the last instance of each variable, omitting all shadowed variables.NativeCallContext::call_fn_dynamic_raw is deprecated and NativeCallContext::call_fn_raw is added.From<EvalAltResult> for Result<T, Box<EvalAltResult> > is deprecated so it will no longer be possible to do EvalAltResult::ErrorXXXXX.into() to convert to a Result; instead, Err(EvalAltResult:ErrorXXXXX.into()) must be used. Code is clearer if errors are explicitly wrapped in Err.0.0 now prints correctly (used to print 0e0).
0.0 now prints correctly (used to print 0e0).+ operations.Assignment to indexing expression with dot expressions inside no longer cause a compilation error.
no_module and internals features now work together without a compilation error."hello" + ", world") now optimizes correctly.Engine::consume_XXX methods are renamed to Engine::run_XXX to make meanings clearer. The consume_XXX API is deprecated.
Engine::call_fn, new variables defined during evaluation of the body script are removed and no longer spill into the function call.NamespaceRef::new is fixed.Engine APIEngine::consume_XXX methods are renamed to Engine::run_XXX to make meanings clearer. The consume_XXX API is deprecated.Engine::register_type_XXX are now available even under no_object.Engine::on_parse_token to allow remapping certain tokens during parsing.Engine::const_empty_string to merge empty strings into a single instance.$symbol$ is supported in custom syntax to match any symbol.$block$, } or ; as the last symbol are now self-terminating (i.e. no need to attach a terminating ;).Dynamic ValuesDynamic::as_string and Dynamic::as_immutable_string are deprecated and replaced by into_string and into_immutable_string respectively.Dynamic.fromXXX constant methods to Dynamic.sin, cos and tan for Decimal values.Decimal Valuesparse_float(), PI() and E() now defer to Decimal under no_float if decimal is turned on.log10() for Decimal.ln for Decimal is now checked and won't panic.SmartString now uses LazyCompact instead of Compact to minimize allocations.pop for strings.ImmutableString::ptr_eq to test if two strings point to the same allocation.serde feature of SmartString is turned on under metadata to make Map serializable.Scope APIScope::set_value now takes anything that implements Into<Cow<str> >.Scope::is_constant to check if a variable is constant.Scope::set_or_push to add a new variable only if one doesn't already exist.AST APIASTNode::position.ReturnType is removed in favor of option flags for Stmt::Return.Stmt::Break and Stmt::Continue are merged into Stmt::BreakLoop via an option flag.StaticVec is changed to keep three items inline instead of four.Eliminate unnecessary property write-back when accessed via a getter since property getters are assumed to be _pure_.
MultiInputsStream, ParseState, TokenIterator, IdentifierBuilder and AccessMode are exported under the internals feature.FloatWrapper is no longer erroneously exported under no_float+internals.
FloatWrapper is no longer erroneously exported under no_float+internals.sign function now works properly for float values that are NaN.Fixed bug with catch variable used in catch block.
catch variable used in catch block.Nothing published for this version
Fixed bug in method call followed by an array indexing.
Fixed bug in using indexing/dotting inside index bracket.
while and loop statements are no longer considered pure (since a loop can go on forever and this is a side effect).Almost the same version as 0.20.3 but with deprecated API's removed.
The official version 1.0.
Almost the same version as 0.20.3 but with deprecated API's removed.
no-std no longer requires patching smartstring.return or throw without a semicolon at the end of a block no longer raises an error.RegisterFn and RegisterResultFn traits) are removed.Module::set_id is split into Module::set_id and Module::clear_id pair.begin, end, each, then, unless are no longer reserved keywords.is_odd, is_even for integers, and is_zero for all numbers.From<BTreeSet> and From<HashSet> are added for Dynamic, which create object maps with () values.This version adds support to index into an integer number, treating it as a bit-field.
This version adds support to index into an integer number, treating it as a bit-field.
chars method to iterate through the characters in a string.Dynamic::take_string and Dynamic::take_immutable_string are renamed to Dynamic::as_string and Dynamic::as_immutable_string respectively.for statement to include counter variable.bits method of an integer can be used to iterate through its bits.$bool$, $int$, $float$ and $string$ expression types for custom syntax.to_hex, to_octal and to_binary for integer numbers.to_upper, to_lower, make_upper, make_lower for strings/characters.This version adds a number of convenience features:
This version adds a number of convenience features:
Ability for a Dynamic to hold an i32 tag of arbitrary data
Simplifies dynamic properties access by falling back to an indexer (passing the name of the property as a string) when a property is not found.
().Engine::disable_doc_comments is removed because doc-comments are now placed under the metadata feature flag.Scope is adjusted (i.e. whether variables are added or removed). There is no need to specify the number of variables added/removed.EvalAltResult::ErrorAssignmentToConstant error. This is to facilitate the Singleton pattern. Registered setter functions are automatically guarded against setters calling on constants and will continue to raise errors unless the pure attribute is present (for plugins).Engine::register_indexer_XXX and Module::set_indexer_XXX) are now also exposed under no_index.Dynamic value can now contain arbitrary data (type i32) in the form of a tag. This is to use up otherwise wasted space in the Dynamic type.no_smartstring to turn off SmartString for those rare cases that it is needed.DynamicReadLock and DynamicWriteLoc are exposed under internals.From< Shared< Locked<Dynamic> > > is added for Dynamic mapping directly to a shared value, together with support for Dynamic::from.Scope is adjusted (i.e. whether variables are added or removed). This allows more flexibility for cases where the number of new variables declared depends on internal logic.pure attribute on a plugin property/index setter now enables it to be used on constants.This version enables functions to access constants declared at global level via the special global module.
This version enables functions to access constants declared at global level via the special global module.
insert and split_at methods for arrays.Dynamic::is_shared and Dynamic::is_locked are removed under the no_closure feature. They used to always return false.Engine::call_fn now evaluates the AST before calling the function.Engine::on_progress is disabled with unchecked.no-std-compat is used to compile for no-std. This removes the need to use a special crate::stdlib namespace for std imports.global is automatically created to hold global-level constants, which can then be accessed from functions.no_position is added to turn off position tracking during parsing to squeeze out the last drop of performance.Your coding agent can read these notes before it upgrades. Set up the MCP server →