v.0.19.15

This version replaces all internal usage of HashMap with BTreeMap, which should result in some speed improvement because a BTreeMap is leaner when the number of items held is small. Most, if not all, collections in Rhai hold very few data items, so this is a typical scenario of many tiny-sized collections.

The Rhai object map type, Map, used to be an alias to HashMap and is now aliased to BTreeMap instead. This is also because, in the vast majority of usage cases, the number of properties held by an object map is small.

HashMap and BTreeMap have almost identical public API's so this change is unlikely to break existing code.

SmartString is used to store identifiers (which tend to be short, fewer than 23 characters, and ASCII-based) because they can usually be stored inline. Map keys now also use SmartString.

In addition, there is now support for line continuation in strings (put \ at the end of line) as well as multi-line literal strings (wrapped by back-ticks: `...`).

Finally, all function signature/metadata methods are now grouped under the umbrella metadata feature. This avoids spending precious resources maintaining metadata for functions for the vast majority of use cases where such information is not required.

Version 0.19.15 released to crates.io.

Bug fixes

• The feature flags no_index + no_object now compile without errors.

Breaking changes

• The traits RegisterFn and RegisterResultFn are removed. Engine::register_fn and Engine::register_result_fn are now implemented directly on Engine.
• FnPtr::call_dynamic now takes &NativeCallContext instead of consuming it.
• All Module::set_fn_XXX methods are removed, in favor of Module::set_native_fn.
• Array::reduce and Array::reduce_rev now take a Dynamic as initial value instead of a function pointer.
• protected, super are now reserved keywords.
• The Module::set_fn_XXX API now take &str as the function name instead of Into<String>.
• The reflections API such as Engine::gen_fn_signatures, Module::update_fn_metadata etc. are put under the metadata feature gate.
• The shebang #! is now a reserved symbol.
• Shebangs at the very beginning of script files are skipped when loading them.
• SmartString is used for identifiers by default. Currently, a PR branch is pulled for no-std builds. The official crate will be used once SmartString is fixed to support no-std.
• Map is now an alias to BTreeMap<SmartString, Dynamic> instead of HashMap because most object maps hold few properties.
• EvalAltResult::FnWrongDefinition is renamed WrongFnDefinition for consistency.

New features

• Line continuation (via \) and multi-line literal strings (wrapped with `) support are added.
• Rhai scripts can now start with a shebang #! which is ignored.

Enhancements

• Replaced all HashMap usage with BTreeMap for better performance because collections in Rhai are tiny.
• Engine::register_result_fn no longer requires the successful return type to be Dynamic. It can now be any clonable type.
• #[rhai_fn(return_raw)] can now return Result<T, Box<EvalAltResult>> where T is any clonable type instead of Result<Dynamic, Box<EvalAltResult>>.
• Dynamic::clone_cast is added to simplify casting from a &Dynamic.

v.0.19.14

This version runs faster due to optimizations done on AST node structures. It also fixes a number of panic bugs related to passing shared values as function call arguments.

Version 0.19.14 released to crates.io.

Bug fixes

• Panic when passing a shared string into a registered function as &str argument is fixed.
• Panic when calling switch statements on custom types is fixed.
• Potential overflow panics in range(from, to, step) is fixed.
• &mut String parameters in registered functions no longer panic when passed a string.
• Some expressions involving shared variables now work properly, for example x in shared_value, return shared_value, obj.field = shared_value etc. Previously, the resultant value is still shared which is counter-intuitive.
• Errors in native Rust functions now contain the correct function call positions.
• Fixed error types in EvalAltResult::ErrorMismatchDataType which were swapped.

Breaking changes

• Dynamic::as_str is removed because it does not properly handle shared values.
• Zero step in the range function now raises an error instead of creating an infinite stream.
• Error variable captured by catch is now an object map containing error fields.
• EvalAltResult::clear_position is renamed EvalAltResult::take_position and returns the position taken.
• private functions in an AST can now be called with call_fn etc.
• NativeCallContext::call_fn_dynamic_raw no longer has the pub_only parameter.
• Module::update_fn_metadata input parameter is changed.
• Function keywords (e.g. type_of, eval, Fn) can no longer be overloaded. It is more trouble than worth. To disable these keywords, use Engine::disable_symbol.
• is_def_var and is_def_fn are now reserved keywords.
• Engine::id field is removed because it is never used.
• num-traits is now a required dependency.
• The in operator is now implemented on top of the contains function and is no longer restricted to a few specific types.
• EvalAltResult::ErrorInExpr is removed because the in operator now calls contains.
• The methods AST::walk, Expr::walk, Stmt::walk and ASTNode::walk and the callbacks they take now return bool to optionally terminate the recursive walk.

Enhancements

• Layout of AST nodes is optimized to reduce redirections, so speed is improved.
• Function calls are more optimized and should now run faster.
• range function now supports negative step and decreasing streams (i.e. to < from).
• More information is provided to the error variable captured by the catch statement in an object map.
• Previously, private functions in an AST cannot be called with call_fn etc. This is inconvenient when trying to call a function inside a script which also serves as a loadable module exporting part (but not all) of the functions. Now, all functions (private or not) can be called in an AST. The private keyword is relegated to preventing a function from being exported.
• Dynamic::as_unit just for completeness sake.
• bytes method added for strings to get length quickly (if the string is ASCII-only).
• FileModuleResolver can now enable/disable caching.
• Recursively walking an AST can now be terminated in the middle.

v.0.19.13

This version introduces functions with Dynamic parameters acting as wildcards.

Version 0.19.13 released to crates.io.

Bug fixes

• Bug in Position::is_beginning_of_line is fixed.

Breaking changes

• For plugin functions, constants passed to methods (i.e. &mut parameter) now raise an error unless the functions are marked with #[rhai_fn(pure)].
• Visibility (i.e. pub or not) for generated plugin modules now follow the visibility of the underlying module.
• Comparison operators between the sames types or different numeric types now throw errors when they're not defined instead of returning the default. Only comparing between different types will return the default.
• Default stack-overflow and top-level expression nesting limits for release builds are lowered to 64 from 128.
• Engine::call_fn_dynamic takes an additional parameter to optionally evaluate the given AST before calling the function.

New features

• Functions are now allowed to have Dynamic arguments.
• #[rhai_fn(pure)] attribute to mark a plugin function with &mut parameter as pure so constants can be passed to it. Without it, passing a constant value into the &mut parameter will now raise an error.

Enhancements

• Built-in operators between FLOAT/Decimal and INT are now implemented for more speed under those cases.
• Error position in eval statements is now wrapped in an EvalAltResult::ErrorInFunctionCall.
• Position now implements Add and AddAssign.
• Scope now implements IntoIterator.
• Strings now have the -/-= operators and the remove method to delete a sub-string/character.
• Strings now have the split_rev method and variations of split with maximum number of segments.
• Arrays now have the split method.
• Comparisons between FLOAT/Decimal and INT are now built in.
• Comparisons between string and char are now built in.
• Engine::call_fn_dynamic can now optionally evaluate the given AST before calling the function.

v.0.19.12

This version is an incremental release with a number of enhancements and bug fixes.

Notice that there are a number of breaking changes, especially with regards to replacing the ~ exponential operator with **, and the addition of the decimal feature that turns on Decimal support.

Version 0.19.12 released to crates.io.

Bug fixes

• Empty statements (i.e. statements with only one ;) now parse correctly and no longer hang.
• continue, break and return statements no longer panic inside a try .. catch block.
• round function for f64 is now implemented correctly.

Breaking changes

• In order to be consistent with other scripting languages:
  • the power/exponentiation operator is changed from ~ to **; ~ is now a reserved symbol
  • the power/exponentiation operator now binds to the right
  • trigonometry functions now take radians and return radians instead of degrees
• Dynamic::into_shared is no longer available under no_closure. It used to panic.
• Token::is_operator is renamed to Token::is_symbol.
• AST::clone_functions_only_filtered, AST::merge_filtered, AST::combine_filtered and AST::retain_functions now take Fn instead of FnMut as the filter predicate.

New features

• Scientific notation is supported for floating-point number literals.
• A new feature, decimal, enables the Decimal data type. When both no_float and decimal features are enabled, floating-point literals parse to Decimal.

Enhancements

• Functions resolution cache is used in more cases, making repeated function calls faster.
• Added atan(x, y) and hypot(x, y) to BasicMathPackage.
• Added standard arithmetic operators between FLOAT/Decimal and INT.

v.0.19.11

This version streamlines compiling for WASM.

Rust compiler minimum version is raised to 1.49.

Version 0.19.11 released to crates.io.

Bug fixes

• Parameters passed to plugin module functions were sometimes erroneously consumed. This is now fixed.
• Fixes compilation errors in metadata feature build.
• Stacking ! operators now work properly.
• Off-by-one error in insert method for arrays is fixed.
• Invalid property access now throws the appropriate error instead of panics.

Breaking changes

• Rust compiler requirement raised to 1.49.
• NativeCallContext::new taker an additional parameter containing the name of the function called.
• Engine::set_doc_comments is renamed Engine::enable_doc_comments.

New features

• Two new features, wasm-bindgen and stdweb, to specify the JS interop layer for WASM builds. wasm-bindgen used to be required.

Enhancements

• ahash is used to hash function call parameters. This should yield speed improvements.
• Dynamic and ImmutableString now implement serde::Serialize and serde::Deserialize.
• NativeCallContext has a new field containing the name of the function called, useful when the same Rust function is registered under multiple names in Rhai.

v.0.19.10

This version improves on error source reporting and fixes a number of bugs.

Version 0.19.10 released to crates.io.

Bug fixes

• no_std feature now compiles correctly (bug introduced in 0.19.9).
• Bug in FileModuleResolver::clear_cache_for_path path mapping fixed.
• Some optimizer fringe cases are fixed - related to constants propagation when the evil eval is present.

Breaking changes

• The error variant EvalAltResult::ErrorInFunctionCall has a new parameter holding the source of the function.
• ParseErrorType::WrongFnDefinition is renamed FnWrongDefinition.
• Redefining an existing function within the same script now throws a new ParseErrorType::FnDuplicatedDefinition. This is to prevent accidental overwriting an earlier function definition.
• AST::set_source is now split into AST::set_source and AST::clear_source.

New features

• Engine::compile_into_self_contained compiles a script into an AST and eagerly resolves all import statements with string literal paths. The resolved modules are directly embedded into the AST. When the AST is later evaluated, import statements directly yield the pre-resolved modules without going through the resolution process once again.
• AST::walk, Stmt::walk and Expr::walk internal API's to recursively walk an AST.

Enhancements

• Source information is provided when there is an error within a call to a function defined in another module.
• Source information is provided to the NativeCallContext for native Rust functions.
• EvalAltResult::clear_position to clear the position information of an error - useful when only the message is needed and the position doesn't need to be printed out.
• A new optional function resolve_ast is added to the ModuleResolver trait for advanced usage.

v.0.19.9

This version fixes a bug introduced in 0.19.8 which breaks property access
within closures.

It also removes the confusing differences between packages and modules
by unifying the terminology and API under the global umbrella of modules.

Version 0.19.9 released to crates.io.

Bug fixes

• Fix bug when accessing properties in closures.
• Fix bug when accessing a deep index with a function call.
• Fix bug that sometimes allow assigning to an invalid l-value.
• Fix off-by-one error with Engine::set_max_call_levels.

Breaking changes

• Engine::load_package is renamed Engine::register_global_module and now must explicitly pass a shared [Module].
• Engine::register_module is renamed Engine::register_static_module and now must explicitly pass a shared [Module].
• Package::get is renamed Package::as_shared_module.
• Engine::set_module_resolver now takes a straight module resolver instead of an Option. To disable module resolving, use the new DummyModuleResolver.

Enhancements

• Scope is now Clone + Hash.
• Engine::register_static_module now supports sub-module paths (e.g. foo::bar::baz).
• Engine::register_custom_operator now accepts reserved symbols.
• Engine::register_custom_operator now returns an error if given a precedence of zero.
• The examples repl and rhai_runner are moved into bin and renamed rhai-repl and rhai-run respectively.

v.0.19.8

This version makes it easier to generate documentation for a Rhai code base.

Each function defined in an AST can optionally attach doc-comments (which, as in Rust,
are comments prefixed by either /// or /**). Doc-comments allow third-party tools to
automatically generate documentation for functions defined in a Rhai script.

A new API, Engine::gen_fn_metadata_to_json and Engine::gen_fn_metadata_with_ast_to_json,
paired with the new metadata feature, exports the full list of functions metadata
(including those in an AST) as a JSON document.

There are also a sizable number of bug fixes.

Version 0.19.8 released to crates.io.

Bug fixes

• Unary prefix operators -, + and ! now bind correctly when applied to an expression. Previously, -x.len is parsed as (-x).len which is obviously counter-intuitive.
• Indexing of namespace-qualified variables now work properly, such as path::to::var[x].
• Constants are no longer propagated by the optimizer if shadowed by a non-constant variable.
• A constant passed as the this parameter to Rhai functions now throws an error if assigned to.
• Generic type parameter of Engine::register_iterator is IntoIterator instead of Iterator.
• Fixes parsing of block comments ending with **/ or inner blocks starting with //*.

Breaking changes

• Engine::on_progress now takes u64 instead of &u64.
• The closure for Engine::on_debug now takes two additional parameters: source: Option<&str> and pos: Position.
• AST::iter_functions now returns ScriptFnMetadata.
• The parser function passed to Engine::register_custom_syntax_raw now takes an additional parameter containing the look-ahead symbol.

New features

• AST::iter_functions now returns ScriptFnMetadata which includes, among others, doc-comments for functions prefixed by /// or /**.
• Doc-comments can be enabled/disabled with the new Engine::set_doc_comments method.
• A new feature metadata is added that pulls in serde_json and enables Engine::gen_fn_metadata_to_json and Engine::gen_fn_metadata_with_ast_to_json which exports the full list of functions metadata (including those inside an AST) in JSON format.
• Engine::on_debug provides two additional parameters: source: Option<&str> and pos: Position, containing the current source (if any) and position of the debug statement.
• NativeCallContext and EvalContext both expose source() which returns the current source, if any.

Enhancements

• A functions lookup cache is added to make function call resolution faster.
• Capturing a constant variable in a closure is now supported, with no cloning.
• A look-ahead symbol is provided to custom syntax parsers, which can be used to parse variable-length symbol streams.

v.0.19.7

This is a minor bug-fix release with a few small enhancements.

Version 0.19.7 released to crates.io.

Bug fixes

• Fixes compilation errors with certain feature flag combinations.

Enhancements

• Property getters/setters and indexers defined in a plugin module are by default #[rhai_fn(global)].
• to_debug is a new standard function for converting a value into debug format.
• Arrays and object maps now print values using to_debug (if available).

v.0.19.6

This version adds the switch statement.

It also allows exposing selected module functions (usually methods) to the global namespace.
This is very convenient when encapsulating the API of a custom Rust type into a module while having methods
and iterators registered on the custom type work normally.

A new gen_fn_signatures API enables enumerating the registered functions of an Engine for documentation purposes.
It also prepares the way for a future reflection API.

Release 0.19.6 released to crates.io.

Bug fixes

• Custom syntax that introduces a shadowing variable now works properly.

Breaking changes

• Module::set_fn, Module::set_raw_fn and Module::set_fn_XXX_mut all take an additional parameter of FnNamespace.
• Module::set_fn takes a further parameter with a list of parameter names/types plus the function return type, if any.
• Module::get_sub_module_mut is removed.
• begin, end, unless are now reserved keywords.
• EvalPackage is removed in favor of Engine::disable_symbol.

New features

• New switch statement.
• New do ... while and do ... until statements.
• New Engine::gen_fn_signatures, Module::gen_fn_signatures and PackagesCollection::gen_fn_signatures to generate a list of signatures for functions registered.
• New Engine::register_module to register a module as a sub-module in the global namespace.
• New set_exported_global_fn! macro to register a plugin function and expose it to the global namespace.
• Module::set_fn_XXX_mut can expose a module function to the global namespace. This is convenient when registering an API for a custom type.
• Module::set_getter_fn, Module::set_setter_fn, Module::set_indexer_get_fn, Module::set_indexer_set_fn all expose the function to the global namespace by default. This is convenient when registering an API for a custom type.
• New Module::update_fn_metadata to update a module function's parameter names and types.
• New #[rhai_fn(global)] and #[rhai_fn(internal)] attributes to determine whether a function defined in a plugin module should be exposed to the global namespace. This is convenient when defining an API for a custom type.
• New get_fn_metadata_list to get the metadata of all script-defined functions in scope.

Enhancements

• New constants under Dynamic including UNIT, TRUE, FALSE, ZERO, ONE etc.
• Floating-point numbers ending with a decimal point without a trailing 0 are supported.