Rhai.Engine (rhai_rustler v1.1.1)
Rhai main scripting engine.
Summary
Functions
Is anonymous function allowed? Default is true.
Is if-expression allowed? Default is true.
Are loop-expression allowed? Default is true.
Is looping allowed? Default is true.
Is shadowing allowed? Default is true.
Is statement_expression allowed? Default is true.
Is switch expression allowed? Default is true.
Call a script function defined in an AST with multiple arguments.
Compact a script to eliminate insignificant whitespaces and comments. This is useful to prepare a script for further compressing. The output script is semantically identical to the input script, except smaller in size. Unlike other uglifiers and minifiers, this method does not rename variables nor perform any optimization on the input script.
Compile a string into an AST, which can be used later for evaluation.
Compile a string containing an expression into an AST, which can be used later for evaluation.
Compile a string containing an expression into an AST using own scope, which can be used later for evaluation.
Compile a script file into an AST, which can be used later for evaluation.
Compile a script file into an AST using own scope, which can be used later for evaluation.
Compile a string into an AST using own scope, which can be used later for evaluation, embedding all imported modules. Modules referred by import statements containing literal string paths are eagerly resolved via the current module resolver and embedded into the resultant AST. When it is evaluated later, import statement directly recall pre-resolved modules and the resolution process is not performed again.
When passed a list of strings, first join the strings into one large script, and then compile them into an AST using own scope, which can be used later for evaluation.
Compile a string into an AST using own scope, which can be used later for evaluation.
Disable a particular keyword or operator in the language.
Return an error if the size of a Dynamic is out of limits (if any).
Evaluate a string as a script, returning the result value or an error.
Evaluate an AST, returning the result value or an error.
Evaluate an AST with own scope, returning the result value or an error.
Evaluate a string containing an expression, returning the result value or an error.
Evaluate a string containing an expression with own scope, returning the result value or an error.
Evaluate a script file, returning the result value or an error.
Evaluate a script file with own scope, returning the result value or an error.
Evaluate a string as a script with own scope, returning the result value or an error.
Set whether to raise error if an object map property does not exist.
Is fast operators mode enabled? Default is false.
The maximum length of arrays (0 for unlimited).
Is fast operators mode enabled? Default is false.
The depth limit for expressions (0 for unlimited).
The depth limit for expressions in functions (0 for unlimited).
The maximum size of object maps (0 for unlimited).
The maximum number of imported modules allowed for a script.
The maximum number of operations allowed for a script to run (0 for unlimited).
The maximum length, in bytes, of strings (0 for unlimited).
Create a new Engine
Create a new Engine with minimal built-in functions.
The current optimization level. It controls whether and how the Engine will optimize an AST after compilation.
Optimize the AST with constants defined in an external Scope. An optimized copy of the AST is returned while the original AST is consumed.
Register a custom operator with a precedence into the language.
Register a custom operator with a precedence into the language.
Register a shared dylib Module into the global namespace of Engine.
Register a shared dylib Module into the global namespace of Engine.
Register the package with an Engine.
Register a shared Module into the namespace of Engine.
Register a shared Module into the namespace of Engine.
Evaluate a string as script.
Evaluate an AST.
Evaluate an AST with own scope.
Evaluate a file.
Evaluate a file with own scope.
Evaluate a string as script with own scope.
Set whether anonymous function is allowed.
Set whether if-expression is allowed.
Set whether loop expressions are allowed.
Set whether looping is allowed.
Set whether shadowing is allowed.
Set whether statement_expression is allowed.
Set whether switch expression is allowed.
Set whether to raise error if an object map property does not exist.
Set whether fast operators mode is enabled.
Set the maximum length of arrays (0 for unlimited).
Set the maximum levels of function calls allowed for a script in order to avoid infinite recursion and stack overflows.
Set the depth limits for expressions (0 for unlimited).
Set the maximum size of object maps (0 for unlimited).
Set the maximum number of imported modules allowed for a script.
Set the maximum number of operations allowed for a script to run to avoid consuming too much resources (0 for unlimited).
Set the maximum length, in bytes, of strings (0 for unlimited).
Set the module resolution services used by the Engine.
Control whether and how the Engine will optimize an AST after compilation.
Set whether strict variables mode is enabled.
Is strict variables mode enabled? Default is false.
Types
Functions
allow_anonymous_fn?(engine)
Is anonymous function allowed? Default is true.
Not available under no_function.
allow_if_expression?(engine)
Is if-expression allowed? Default is true.
allow_loop_expressions?(engine)
Are loop-expression allowed? Default is true.
allow_looping?(engine)
Is looping allowed? Default is true.
allow_shadowing?(engine)
Is shadowing allowed? Default is true.
allow_statement_expression?(engine)
Is statement_expression allowed? Default is true.
allow_switch_expression?(engine)
Is switch expression allowed? Default is true.
call_fn(engine, scope, ast, name, args)
@spec call_fn(t(), Rhai.Scope.t(), Rhai.AST.t(), String.t(), list()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Call a script function defined in an AST with multiple arguments.
compact_script(engine, script)
Compact a script to eliminate insignificant whitespaces and comments. This is useful to prepare a script for further compressing. The output script is semantically identical to the input script, except smaller in size. Unlike other uglifiers and minifiers, this method does not rename variables nor perform any optimization on the input script.
compile(engine, script)
@spec compile(t(), String.t()) :: {:ok, Rhai.AST.t()} | {:error, Rhai.Error.t()}
Compile a string into an AST, which can be used later for evaluation.
compile_expression(engine, script)
@spec compile_expression(t(), String.t()) :: {:ok, Rhai.AST.t()} | {:error, Rhai.Error.t()}
Compile a string containing an expression into an AST, which can be used later for evaluation.
compile_expression_with_scope(engine, scope, script)
@spec compile_expression_with_scope(t(), Rhai.Scope.t(), String.t()) :: {:ok, Rhai.AST.t()} | {:error, Rhai.Error.t()}
Compile a string containing an expression into an AST using own scope, which can be used later for evaluation.
compile_file(engine, path)
@spec compile_file(t(), String.t()) :: {:ok, Rhai.AST.t()} | {:error, Rhai.Error.t()}
Compile a script file into an AST, which can be used later for evaluation.
compile_file_with_scope(engine, scope, script)
@spec compile_file_with_scope(t(), Rhai.Scope.t(), String.t()) :: {:ok, Rhai.AST.t()} | {:error, Rhai.Error.t()}
Compile a script file into an AST using own scope, which can be used later for evaluation.
compile_into_self_contained(engine, scope, script)
@spec compile_into_self_contained(t(), Rhai.Scope.t(), String.t()) :: {:ok, Rhai.AST.t()} | {:error, Rhai.Error.t()}
Compile a string into an AST using own scope, which can be used later for evaluation, embedding all imported modules. Modules referred by import statements containing literal string paths are eagerly resolved via the current module resolver and embedded into the resultant AST. When it is evaluated later, import statement directly recall pre-resolved modules and the resolution process is not performed again.
compile_scripts_with_scope(engine, scope, script)
@spec compile_scripts_with_scope(t(), Rhai.Scope.t(), [String.t()]) :: {:ok, Rhai.AST.t()} | {:error, Rhai.Error.t()}
When passed a list of strings, first join the strings into one large script, and then compile them into an AST using own scope, which can be used later for evaluation.
The scope is useful for passing constants into the script for optimization when using :full optimization level.
compile_with_scope(engine, scope, script)
@spec compile_with_scope(t(), Rhai.Scope.t(), String.t()) :: {:ok, Rhai.AST.t()} | {:error, Rhai.Error.t()}
Compile a string into an AST using own scope, which can be used later for evaluation.
Constants Propagation:
If not optimization_level = :none, constants defined within the scope are propagated throughout the script including functions.
This allows functions to be optimized based on dynamic global constants.
disable_symbol(engine, symbol)
Disable a particular keyword or operator in the language.
ensure_data_size_within_limits(engine, value)
@spec ensure_data_size_within_limits(t(), Rhai.Any.t()) :: :ok | Rhai.Error.t()
Return an error if the size of a Dynamic is out of limits (if any).
eval(engine, script)
@spec eval(t(), String.t()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Evaluate a string as a script, returning the result value or an error.
eval_ast(engine, ast)
@spec eval_ast(t(), Rhai.AST.t()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Evaluate an AST, returning the result value or an error.
eval_ast_with_scope(engine, scope, ast)
@spec eval_ast_with_scope(t(), Rhai.Scope.t(), Rhai.AST.t()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Evaluate an AST with own scope, returning the result value or an error.
eval_expression(engine, script)
@spec eval_expression(t(), String.t()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Evaluate a string containing an expression, returning the result value or an error.
eval_expression_with_scope(engine, scope, script)
@spec eval_expression_with_scope(t(), Rhai.Scope.t(), String.t()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Evaluate a string containing an expression with own scope, returning the result value or an error.
eval_file(engine, path)
@spec eval_file(t(), String.t()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Evaluate a script file, returning the result value or an error.
eval_file_with_scope(engine, scope, path)
@spec eval_file_with_scope(t(), Rhai.Scope.t(), String.t()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Evaluate a script file with own scope, returning the result value or an error.
eval_with_scope(engine, scope, script)
@spec eval_with_scope(t(), Rhai.Scope.t(), String.t()) :: {:ok, Rhai.Any.t()} | {:error, Rhai.Error.t()}
Evaluate a string as a script with own scope, returning the result value or an error.
fail_on_invalid_map_property?(engine)
Set whether to raise error if an object map property does not exist.
fast_operators?(engine)
Is fast operators mode enabled? Default is false.
max_array_size(engine)
The maximum length of arrays (0 for unlimited).
Zero under no_index.
max_call_levels(engine)
@spec max_call_levels(t()) :: non_neg_integer()
Is fast operators mode enabled? Default is false.
max_expr_depth(engine)
@spec max_expr_depth(t()) :: non_neg_integer()
The depth limit for expressions (0 for unlimited).
max_function_expr_depth(engine)
@spec max_function_expr_depth(t()) :: non_neg_integer()
The depth limit for expressions in functions (0 for unlimited).
Zero under no_function.
max_map_size(engine)
@spec max_map_size(t()) :: non_neg_integer()
The maximum size of object maps (0 for unlimited).
Zero under no_object.
max_modules(engine)
@spec max_modules(t()) :: non_neg_integer()
The maximum number of imported modules allowed for a script.
Zero under no_module.
max_operations(engine)
@spec max_operations(t()) :: non_neg_integer()
The maximum number of operations allowed for a script to run (0 for unlimited).
Not available under unchecked.
max_string_size(engine)
@spec max_string_size(t()) :: non_neg_integer()
The maximum length, in bytes, of strings (0 for unlimited).
new()
@spec new() :: t()
Create a new Engine
new_raw()
@spec new_raw() :: t()
Create a new Engine with minimal built-in functions.
optimization_level(engine)
@spec optimization_level(t()) :: :none | :simple | :full
The current optimization level. It controls whether and how the Engine will optimize an AST after compilation.
optimize_ast(engine, scope, ast, optimization_level)
@spec optimize_ast(t(), Rhai.Scope.t(), Rhai.AST.t(), :none | :simple | :full) :: Rhai.AST.t()
Optimize the AST with constants defined in an external Scope. An optimized copy of the AST is returned while the original AST is consumed.
Although optimization is performed by default during compilation, sometimes it is necessary to re-optimize an AST. For example, when working with constants that are passed in via an external scope, it will be more efficient to optimize the AST once again to take advantage of the new constants. With this method, it is no longer necessary to recompile a large script. The script AST can be compiled just once. Before evaluation, constants are passed into the Engine via an external scope (i.e. with Rhai.Scope.push_constant/2). Then, the AST is cloned and the copy re-optimized before running.
register_custom_operator(engine, operator, precedence)
@spec register_custom_operator(t(), String.t(), non_neg_integer()) :: {:ok, t()} | {:error, {:custom_operator, String.t()}}
Register a custom operator with a precedence into the language.
The operator can be a valid identifier, a reserved symbol, a disabled operator or a disabled keyword. The precedence cannot be zero.
register_custom_operator!(engine, operator, precedence)
@spec register_custom_operator!(t(), String.t(), non_neg_integer()) :: t()
Register a custom operator with a precedence into the language.
The operator can be a valid identifier, a reserved symbol, a disabled operator or a disabled keyword. The precedence cannot be zero.
Raises if the operator cannot be registered.
register_global_module(engine, path)
Register a shared dylib Module into the global namespace of Engine.
All functions and type iterators are automatically available to scripts without namespace qualifications. Sub-modules and variables are ignored. When searching for functions, modules loaded later are preferred. In other words, loaded modules are searched in reverse order.
Returns an error if the module cannot be loaded.
register_global_module!(engine, path)
Register a shared dylib Module into the global namespace of Engine.
All functions and type iterators are automatically available to scripts without namespace qualifications. Sub-modules and variables are ignored. When searching for functions, modules loaded later are preferred. In other words, loaded modules are searched in reverse order.
Raises an error if the module cannot be loaded.
register_package(engine, package)
@spec register_package(t(), Rhai.Package.t()) :: t()
Register the package with an Engine.
register_static_module(engine, namespace, path)
@spec register_static_module(t(), String.t(), String.t()) :: {:ok, t()} | {:error, {:runtime, String.t()}}
Register a shared Module into the namespace of Engine.
Returns an error if the module cannot be loaded.
register_static_module!(engine, namespace, path)
Register a shared Module into the namespace of Engine.
Raises an error if the module cannot be loaded.
run(engine, script)
@spec run(t(), String.t()) :: :ok | {:error, Rhai.Error.t()}
Evaluate a string as script.
run_ast(engine, ast)
@spec run_ast(t(), Rhai.AST.t()) :: :ok | {:error, Rhai.Error.t()}
Evaluate an AST.
run_ast_with_scope(engine, scope, ast)
@spec run_ast_with_scope(t(), Rhai.Scope.t(), Rhai.AST.t()) :: :ok | {:error, Rhai.Error.t()}
Evaluate an AST with own scope.
run_file(engine, path)
@spec run_file(t(), String.t()) :: :ok | {:error, Rhai.Error.t()}
Evaluate a file.
run_file_with_scope(engine, scope, path)
@spec run_file_with_scope(t(), Rhai.Scope.t(), String.t()) :: :ok | {:error, Rhai.Error.t()}
Evaluate a file with own scope.
Constants Propagation
If the optimization_level is not :none constants defined within the scope are propagated throughout the script including functions.
This allows functions to be optimized based on dynamic global constants.
run_with_scope(engine, scope, script)
@spec run_with_scope(t(), Rhai.Scope.t(), String.t()) :: :ok | {:error, Rhai.Error.t()}
Evaluate a string as script with own scope.
Constants Propagation
If the optimization_level is not :none constants defined within the scope are propagated throughout the script including functions.
This allows functions to be optimized based on dynamic global constants.
set_allow_anonymous_fn(engine, enable)
Set whether anonymous function is allowed.
Not available under no_function.
set_allow_if_expression(engine, enable)
Set whether if-expression is allowed.
set_allow_loop_expressions(engine, enable)
Set whether loop expressions are allowed.
set_allow_looping(engine, enable)
Set whether looping is allowed.
set_allow_shadowing(engine, enable)
Set whether shadowing is allowed.
set_allow_statement_expression(engine, enable)
Set whether statement_expression is allowed.
set_allow_switch_expression(engine, enable)
Set whether switch expression is allowed.
set_fail_on_invalid_map_property(engine, enable)
Set whether to raise error if an object map property does not exist.
set_fast_operators(engine, enable)
Set whether fast operators mode is enabled.
set_max_array_size(engine, max_size)
Set the maximum length of arrays (0 for unlimited).
Not available under unchecked or no_index.
set_max_call_levels(engine, levels)
@spec set_max_call_levels(t(), non_neg_integer()) :: t()
Set the maximum levels of function calls allowed for a script in order to avoid infinite recursion and stack overflows.
Not available under unchecked or no_function.
set_max_expr_depths(engine, max_expr_depth, max_function_expr_depth)
@spec set_max_expr_depths(t(), non_neg_integer(), non_neg_integer()) :: t()
Set the depth limits for expressions (0 for unlimited).
Not available under unchecked.
set_max_map_size(engine, size)
@spec set_max_map_size(t(), non_neg_integer()) :: t()
Set the maximum size of object maps (0 for unlimited).
Not available under unchecked or no_object.
set_max_modules(engine, modules)
@spec set_max_modules(t(), non_neg_integer()) :: t()
Set the maximum number of imported modules allowed for a script.
Not available under unchecked or no_module.
set_max_operations(engine, operations)
@spec set_max_operations(t(), non_neg_integer()) :: t()
Set the maximum number of operations allowed for a script to run to avoid consuming too much resources (0 for unlimited).
Not available under unchecked.
set_max_string_size(engine, string_size)
@spec set_max_string_size(t(), non_neg_integer()) :: t()
Set the maximum length, in bytes, of strings (0 for unlimited).
Not available under unchecked.
set_module_resolvers(engine, module_resolvers)
Set the module resolution services used by the Engine.
This library supports :file and :dylib module resolvers.
set_optimization_level(engine, optimization_level)
Control whether and how the Engine will optimize an AST after compilation.
set_strict_variables(engine, enable)
Set whether strict variables mode is enabled.
strict_variables?(engine)
Is strict variables mode enabled? Default is false.