@ruby/wasm-wasi
v2.6.0
Published
WebAssembly port of CRuby with WASI
Downloads
7,887
Readme
@ruby/wasm-wasi
This package provides core APIs for Ruby on WebAssembly targeting WASI-compatible environments. WebAssembly binaries are distributed in version-specific packages.
See Cheat Sheet for how to use this package.
Ruby Version Support
| Version | Package |
| ------- | --------------------------------------------------------------------------------------------------------------- |
| head | @ruby/head-wasm-wasi |
| 3.3 | @ruby/3.3-wasm-wasi |
| 3.2 | @ruby/3.2-wasm-wasi |
API
consolePrinter
Create a console printer that can be used as an overlay of WASI imports. See the example below for how to use it.
const imports = {
wasi_snapshot_preview1: wasi.wasiImport,
};
const printer = consolePrinter();
printer.addToImports(imports);
const instance = await WebAssembly.instantiate(module, imports);
printer.setMemory(instance.exports.memory);Note that the stdout and stderr functions are called with text, not
bytes. This means that bytes written to stdout/stderr will be decoded as
UTF-8 and then passed to the stdout/stderr functions every time a write
occurs without buffering.
Parameters
$0Object (optional, default{stdout:console.log,stderr:console.warn})$0.stdout$0.stderr
stdoutA function that will be called when stdout is written to. Defaults toconsole.log.stderrA function that will be called when stderr is written to. Defaults toconsole.warn.
Returns any An object that can be used as an overlay of WASI imports.
RubyVM
A Ruby VM instance
Examples
const wasi = new WASI();
const vm = new RubyVM();
const imports = {
wasi_snapshot_preview1: wasi.wasiImport,
};
vm.addToImports(imports);
const instance = await WebAssembly.instantiate(rubyModule, imports);
await vm.setInstance(instance);
wasi.initialize(instance);
vm.initialize();initialize
Initialize the Ruby VM with the given command line arguments
Parameters
argsThe command line arguments to pass to Ruby. Must be an array of strings starting with the Ruby program name. (optional, default["ruby.wasm","-EUTF-8","-e_=0"])
setInstance
Set a given instance to interact JavaScript and Ruby's WebAssembly instance. This method must be called before calling Ruby API.
Parameters
instanceThe WebAssembly instance to interact with. Must be instantiated from a Ruby built with JS extension, and built with Reactor ABI instead of command line.
addToImports
Add intrinsic import entries, which is necessary to interact JavaScript and Ruby's WebAssembly instance.
Parameters
importsThe import object to add to the WebAssembly instance
printVersion
Print the Ruby version to stdout
eval
Runs a string of Ruby code from JavaScript
Parameters
codeThe Ruby code to run
Examples
vm.eval("puts 'hello world'");
const result = vm.eval("1 + 2");
console.log(result.toString()); // 3Returns any the result of the last expression
evalAsync
Runs a string of Ruby code with top-level JS::Object#await
Returns a promise that resolves when execution completes.
Parameters
codeThe Ruby code to run
Examples
const text = await vm.evalAsync(`
require 'js'
response = JS.global.fetch('https://example.com').await
response.text.await
`);
console.log(text.toString()); // <html>...</html>Returns any a promise that resolves to the result of the last expression
wrap
Wrap a JavaScript value into a Ruby JS::Object
Parameters
valueThe value to convert to RbValue
Examples
const hash = vm.eval(`Hash.new`);
hash.call("store", vm.eval(`"key1"`), vm.wrap(new Object()));Returns any the RbValue object representing the given JS value
RbValue
A RbValue is an object that represents a value in Ruby
call
Call a given method with given arguments
Parameters
calleename of the Ruby method to callargs...any arguments to pass to the method. Must be an array of RbValue
Examples
const ary = vm.eval("[1, 2, 3]");
ary.call("push", vm.wrap(4));
console.log(ary.call("sample").toString());Returns any The result of the method call as a new RbValue.
callAsync
Call a given method that may call JS::Object#await with given arguments
Parameters
calleename of the Ruby method to callargs...any arguments to pass to the method. Must be an array of RbValue
Examples
const client = vm.eval(`
require 'js'
class HttpClient
def get(url)
JS.global.fetch(url).await
end
end
HttpClient.new
`);
const response = await client.callAsync(
"get",
vm.eval(`"https://example.com"`),
);Returns any A Promise that resolves to the result of the method call as a new RbValue.
toPrimitive
- See: https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive
Parameters
hintPreferred type of the result primitive value."number","string", or"default".
toString
Returns a string representation of the value by calling to_s
toJS
Returns a JavaScript object representation of the value
by calling to_js.
Returns null if the value is not convertible to a JavaScript object.
RbError
Extends Error
Error class thrown by Ruby execution
RbFatalError
Extends RbError
Error class thrown by Ruby execution when it is not possible to recover. This is usually caused when Ruby VM is in an inconsistent state.