v1.18.0

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!

Bug fixes

• The position of an undefined operation call now points to the operator instead of the first operand.
• The 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.
• Some tests that panic on 32-bit architecture are fixed (thanks @alexanderkjall #851).
• The optimizer no longer goes into an infinite loop when optimizing a try statement with an empty body.

Deprecated API's

• 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 existing direct API's.

New features

• Sub-strings can now be selected from full strings by indexing via ranges, e.g. s[1..4] (thanks @zitsen #845).
• Doc-comments are now automatically added to function registrations and custom types via the CustomType derive macro (thanks @Itabis #847).
• New options 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.
• A new advanced callback, Engine::on_invalid_array_index, is added (gated under the internals feature) to handle access to missing properties in object maps.
• A new advanced callback, Engine::on_missing_map_property, is added (gated under the internals feature) to handle out-of-bound index into arrays.

Enhancements

• 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.
• Array/BLOB/string iterators are defined also within the BasicIteratorPackage in addition to the regular array/BLOB/string packages.
• LexError::Runtime is added for use with Engine::on_parse_token.
• Shared values under 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.

v1.17.1

This is a bug-fix release that bumps rhai_codegen version to 2.0.0 to satisfy semver rules.

v1.17.0

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.

Potentially breaking changes

• ImmutableString now derefs to &str instead of &SmartString. Normally this should not be a breaking change.
• Traits implemented by ImmutableString are cleaned up. Normally this should not be a breaking change.
• EvalContext::new, FloatWrapper and ConditionalExpr are now gated under internals.
• Previously, Rhai follows Unicode's definition for whitespace, which allows many exotic whitespace characters in scripts. Starting from this version, whitespace follows WhatWG's definition of five ASCII characters (TAB, SPACE, CR, LF and FF), which is the same as Rust. All other Unicode whitespace characters (not inside strings) are not considered whitespace by Rhai. If a script used to contain non-ASCII whitespace characters, it now fails to parse with a syntax error.

New features

• #[derive(CustomType)] is now available, driven by procedural macros in rhai_codegen.
• A new 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.
• Functions defined in plugin modules can now be marked as volatile which prevents it from being optimized away even under OptimizationLevel::Full.
• Added 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.

Deprecated API's

• 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.
• Much of the 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.

Fixes to bugs found via fuzzing

• Fixed crash when parsing multi-segment interpolated string longer than maximum.
• Fixed crash when parsing unterminated comment.
• Fixed crash when parsing deeply-nested right-associated operators such as **.
• Fixed crash when parsing combo-chaining expressions such as (a.b).c.
• Fixed crash when calling functions that have Dynamic parameters with more than 16 parameters.
• Fixed crash when indexing into an empty array with negative index.
• Indexing into an array with a negative index that is larger than the length of the array now throws an out-of-bounds error (similar to positive indices) instead of defaulting to the first element.
• Fixed edge-case crash in timestamp functions.
• Fixed crash when indenting a block doc-comment with Unicode multi-byte space characters.
• Fixed improper parsing of numbers with too many decimal points.
• Fixed exponential running time when raising a decimal number to a very large power (> 1 million) -- it now returns an overflow error.
• Shared values that contain reference loops no longer cause a stack overflow when printing.
• sleep no longer panics on NaN.
• switch on ranges now work properly.

Other bug fixes

• Arrays in object maps now serialize to JSON correctly via 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.

Enhancements

• Avoid cloning values unless needed when performing constants propagation in optimization.
• Added 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.

v1.16.3

Public fields of VarDefInfo are marked deprecated but still accessible.

v1.16.2

Fixes compilation error when importing multiple modules.

v1.16.1

Fixes compilation error when using the serde feature with metadata.

v1.16.0

This version is a general code cleanup such that it relies less on obscure hacks unless those tricks provide genuine performance benefits. It should make the code base easier to follow for new contributors.

The minimum Rust compiler version is raised to 1.66.0.

Potentially-breaking changes

• Limit functions (e.g. 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.
• The type OptimizationLevel is no longer exported under no_optimize. Originally it was mapped to () under no_optimize.
• O/S features such as file access and time are no longer disabled when using wasm32-wasi (or any WASM target other than wasm32-unknown).

Bug fixes

• Fixes a panic when using this as the first parameter in a namespace-qualified function call.
• Comparing two different data types (e.g. a custom type and a standard type) now correctly defaults to 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.

Dependencies

• Minimal version numbers for dependencies are now specified in 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.

Deprecated API's

• 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.

New features

• New exit function that terminates script evaluation regardless of where it is called, even inside deeply-nested function calls.
• Added 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.
• Added zip function for arrays.
• Added on_print and on_debug definitions for TypeBuilder.
• Doc-comments are now included in custom type definitions within plugin modules. They can be accessed via Module::get_custom_type_raw. These doc-comments for custom types are also exported in JSON via Engine::gen_fn_metadata_to_json.

Enhancements

• once_cell is used in std environments instead of the home-brew SusLock which is removed.
• Originally, unit tests use the ? 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().
• Many inlined collections are turned back into 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.
• General code clean-up to remove optimizations tricks that are not obviously beneficial in favor of clearer code.

v1.15.1

This is a minor bug-fix release.

• Dynamic::deep_scan is fixed so now it properly scans arrays, object maps and function pointers embedded inside data.

v1.15.0

Bug fixes

• Fixes a concurrency error in static hashing keys (thanks garypen!).

Enhancements

• Expressions involving this should now run slightly faster due to a dedicated AST node ThisPtr.
• A 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).

v1.14.0

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.

Bug fixes

• is_shared is a reserved keyword and is now handled properly (e.g. it cannot be the target of a function pointer).
• Re-optimizing an AST via 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.
• Expressions such as (v[0].func()).prop now parse correctly.
• Shadowed variable exports are now handled correctly.
• Shadowed constant definitions are now optimized correctly when propagated (e.g. const X = 1; const X = 1 + 1 + 1; X now evaluates to 3 instead of 0).
• Identifiers and comma's in the middle of custom syntax now register correctly.
• Exporting an object map from a module with closures defined on properties now works correctly when those properties are called to mimic method calls in OOP-style.
• Compiling for 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.

New features

• It is now possible to require a specific type to the 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).

Enhancements

• Engine::is_symbol_disabled is added to test whether a particular keyword/symbol is disabled.
• Support is added to deserialize a Dynamic value containing custom types or shared values back into another Dynamic (essentially a straight cloned copy).