{"id":18113367,"url":"https://github.com/rhaiscript/rhai_rustler","last_synced_at":"2025-04-14T07:11:09.654Z","repository":{"id":62823832,"uuid":"551945795","full_name":"rhaiscript/rhai_rustler","owner":"rhaiscript","description":"Elixir NIF bindings for Rhai, an embedded scripting language and engine for Rust","archived":false,"fork":false,"pushed_at":"2024-04-12T13:48:38.000Z","size":324,"stargazers_count":10,"open_issues_count":8,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-14T09:55:20.726Z","etag":null,"topics":["elixir","nif","rhai","rust","rustler","scripting-language"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhaiscript.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-15T13:04:45.000Z","updated_at":"2024-05-14T17:30:15.225Z","dependencies_parsed_at":"2022-11-07T11:03:23.277Z","dependency_job_id":"c7e3c5f2-c7f7-479e-8c57-8cfe49d6ce9f","html_url":"https://github.com/rhaiscript/rhai_rustler","commit_stats":{"total_commits":48,"total_committers":3,"mean_commits":16.0,"dds":0.3125,"last_synced_commit":"f9941fe9ea6e17bf145ba846d4b8ac398f8817ce"},"previous_names":["rhaiscript/rhai_rustler","fabriziosestito/rhai_rustler"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai_rustler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai_rustler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai_rustler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhaiscript%2Frhai_rustler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhaiscript","download_url":"https://codeload.github.com/rhaiscript/rhai_rustler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837287,"owners_count":21169374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","nif","rhai","rust","rustler","scripting-language"],"created_at":"2024-11-01T02:08:05.649Z","updated_at":"2025-04-14T07:11:09.623Z","avatar_url":"https://github.com/rhaiscript.png","language":"Elixir","readme":"# rhai_rustler\n\n[![CI](https://github.com/rhaiscript/rhai_rustler/actions/workflows/main.yaml/badge.svg)](https://github.com/rhaiscript/rhai_rustler/actions/workflows/main.yaml)\n[![Rust CI](https://github.com/rhaiscript/rhai_rustler/actions/workflows/rust-ci.yaml/badge.svg)](https://github.com/rhaiscript/rhai_rustler/actions/workflows/rust-ci.yaml)\n[![NIFs precompilation](https://github.com/rhaiscript/rhai_rustler/actions/workflows/release.yaml/badge.svg)](https://github.com/rhaiscript/rhai_rustler/actions/workflows/release.yaml)\n[![Hex.pm](https://img.shields.io/hexpm/v/rhai_rustler.svg)](https://hex.pm/packages/rhai_rustler)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-purple.svg)](https://hexdocs.pm/rhai_rustler/)\n\nElixir NIF bindings for Rhai, a tiny, simple and fast embedded scripting language for Rust that gives you a safe and easy way to add scripting to your applications.\n\nPlease refer to [The Rhai Book](https://rhai.rs/book/index.html) for extended information about the language.\n\n## Installation\n\nAdd `:rhai_rustler` to the list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:rhai_rustler, \"~\u003e 1.0.0\"}\n  ]\nend\n```\n\n## Features\n\n`rhai_rustler` exposes a subset of the Rhai API to Elixir:\n\n- [Engine]() - [Rhai Book](https://rhai.rs/book/engine/index.html) - [docs.rs](https://docs.rs/rhai/latest/rhai/struct.Engine.html)\n- [Scope]() - [Rhai book](https://rhai.rs/book/engine/scope.html) - [docs.rs](https://docs.rs/rhai/latest/rhai/struct.Scope.html)\n- [AST]() - [Rhai book](https://rhai.rs/book/engine/ast.html) - [docs.rs](https://docs.rs/rhai/latest/rhai/struct.Ast.html)\n\nNote that not all the Rhai API features are supported. For instance, advanced and low-level APIs are not exposed.\n\nIf any usage patterns become apparent, they will be included in the future.\n\nPlease refer to [NIF bindings](guides/nif-bindings.md) to see the methods supported by the Elixir NIF.\n\nThe Elixir NIF provides a way to extend Rhai with external native Rust modules, see: [Extending Rhai with external native Rust modules](#extending-rhai-with-external-native-rust-modules) and [rhai_dylib](https://github.com/rhaiscript/rhai-dylib) for more information.\n\nTo check the supported types conversion, see [Type conversion table](#type-conversion-table).\n\n## Usage patterns\n\n### \"Hello Rhai\"\n\n```elixir\nengine = Rhai.Engine.new()\n\n{:ok, \"Hello Rhai!\"} = Rhai.Engine.eval(engine, \"\\\"Hello Rhai!\\\"\")\n```\n\n### Eval\n\n```elixir\nengine = Rhai.Engine.new()\n\n# Simple evaluation\n{:ok, 2} = Rhai.Engine.eval(engine, \"1 + 1\")\n\n# Evaluation with scope\nscope = Rhai.Scope.new() |\u003e Rhai.Scope.push(\"a\", 10) |\u003e Rhai.Scope.push(\"b\", 3)\n{:ok, 30} = Rhai.Engine.eval_with_scope(engine, scope, \"a * b\")\n```\n\n### AST\n\n```elixir\nengine = Rhai.Engine.new()\nscope = Rhai.Scope.new() |\u003e Rhai.Scope.push_constant(\"a\", 10) |\u003e Rhai.Scope.push_constant(\"b\", 3)\n\n{:ok, %Rhai.AST{} = ast} = Rhai.Engine.compile_with_scope(engine, scope, \"a * b\")\n{:ok, 30} = Rhai.Engine.eval_ast(engine, ast)\n\n# AST can be shared between engines\ntask = Task.async(fn -\u003e Rhai.Engine.eval_ast(Rhai.Engine.new(), ast) end)\n{:ok, 30} = Task.await(task)\n```\n\n### Raw Engine\n\n```elixir\nengine = Rhai.Engine.new_raw()\n\n# Returns an error since BasicArrayPackage is not registered\n{:error, {:function_not_found, _}} = Rhai.Engine.eval(engine, \"[1, 2, 3].find(|x| x \u003e 2)\")\n\n# Please refer to https://rhai.rs/book/rust/packages/builtin.html for more information about packages\nengine = Rhai.Engine.register_package(engine, :basic_array)\n{:ok, 3} = Rhai.Engine.eval(engine, \"[1, 2, 3].find(|x| x \u003e 2)\")\n```\n\n### Extending rhai_rustler with external native Rust modules\n\n`rhai_rustler` utilizes the `[rhai_dylib](https://github.com/rhaiscript/rhai-dylib)` library to expand the capabilities of Rhai by loading external native Rust modules. This allows users to introduce new functions, custom types, and operators.\n\n[test_dylib_module](https://github.com/rhaiscript/rhai_rustler/tree/main/native/test_dylib_module) serves as an example of how to create a dylib module. A [dummy rustler module](https://github.com/rhaiscript/rhai_rustler/blob/main/test/support/test_dylib_module.ex) is employed to trigger the compilation process. This same approach can be adopted in real-world projects, such as when distributing the dylib module as a Hex package.\n\n## Type conversion table\n\nElixir Types are converted to Rhai types (and back) as follows:\n\n| Elixir                          | Rhai                  |\n| ------------------------------- | --------------------- |\n| integer()                       | Integer               |\n| float()                         | Float                 |\n| float()                         | Decimal               |\n| bool()                          | Boolean               |\n| String.t()                      | String                |\n| String.t()                      | Char                  |\n| list()                          | Array                 |\n| tuple()                         | Array                 |\n| %{ String.t() =\u003e Rhai.Any.t() } | Object map            |\n| nil()                           | Empty                 |\n| pid()                           | Empty (not supported) |\n| ref()                           | Empty (not supported) |\n| fun()                           | Empty (not supported) |\n| map()                           | Empty (not supported) |\n\n## Rustler precompiled\n\nBy default, **you don't need the Rust toolchain installed** because the lib will try to download\na precompiled NIF file.\nIn case you want to force compilation set the\n`RHAI_RUSTLER_FORCE_BUILD` environment variable to `true` or `1`.\n\nPrecompiled NIFs are available for the following platforms:\n\n- aarch64-apple-darwin\n- x86_64-apple-darwin\n- x86_64-unknown-linux-gnu\n- x86_64-unknown-linux-musl\n- arm-unknown-linux-gnueabihf\n- aarch64-unknown-linux-gnu\n- aarch64-unknown-linux-musl\n- x86_64-pc-windows-msvc\n- x86_64-pc-windows-gnu\n\n### Release flow\n\nPlease follow [this guide](https://hexdocs.pm/rustler_precompiled/precompilation_guide.html#the-release-flow) when releasing a new version of the library.\n\n## License\n\nThis library is licensed under Apache 2.0 License. See [LICENSE](LICENSE) for details.\n\n## Links\n\n- [rhai](https://github.com/rhaiscript/rhai) The Rust crate doing most of the dirty work.\n- [RustlerPrecompiled](https://github.com/philss/rustler_precompiled) Use precompiled NIFs from trusted sources in your Elixir code.\n- [NimbleLZ4](https://github.com/whatyouhide/nimble_lz4) Major inspiration for the RustlerPrecompiled GitHub actions workflow and general setup.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhaiscript%2Frhai_rustler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhaiscript%2Frhai_rustler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhaiscript%2Frhai_rustler/lists"}