Rhai - An embedded scripting language for Rust.
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]].e
map
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.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.export
ed from modules!!in
!in
is added which maps to !(... in ...)
.Engine::call_fn_with_options
Engine::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.This is a large release containing numerous new features, bug fixes and speed improvements.
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 import
ed 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_expressions
ahash
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.Scope
Scope
is now serializable and deserializable via serde
.NativeCallContext
NativeCallContext
into a new NativeCallContextStore
type.NativeCallContext
to be stored and recreated later on.NativeCallContext
NativeCallContext::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.This is a bug-fix release that fixes an error when compiling for 32-bit architectures.
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.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.
Accessing properties in Strict Variables Mode no longer generates a variable not found error.
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.This version includes a number of usability improvements, especially the Elvis operator ?.
and null-coalescing operator ??
.
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::default_tag
, Engine::default_tag_mut
and Engine::set_default_tag
are added to manage a default value for the custom evaluation state, accessible via EvalState::tag()
(which is the same as NativeCallContext::tag()
). Closes #563EvalState::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.This release is primarily minor functionality and API enhancements.
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
, OptimizationLevel
Module::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.Dynamic
parameters now work in qualified calls from import
ed 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.