@raviqqe/stak 0.3.23 → 0.3.25

package/README.md

@@ -19,6 +19,14 @@ For more information and usage, visit [the full documentation](https://raviqqe.g
 
 ## Install
 
+### Interpreter
+
+To install the Scheme interpreter as a command, run:
+
+```sh
+cargo install stak
+```
+
 ### Libraries
 
 To install Stak Scheme as a library in your Rust project, run:
@@ -31,27 +39,53 @@ cargo install stak-compile
 
 For full examples, see [the `examples` directory](https://github.com/raviqqe/stak/tree/main/examples).
 
-### Command line tools
-
-To install the Scheme interpreter as a command, run:
-
-```sh
-cargo install stak
-```
-
 ## Examples
 
-### Embedding Scheme scripts in Rust
+### Dynamic scripting in Rust
 
-First, prepare a Scheme script at `src/hello.scm`.
+First, prepare a Scheme script named `src/fight.scm`:
 
 ```scheme
-(import (scheme base))
-
-(write-string "Hello, world!\n")
+; Import a base library and the library named `(stak rust)` for Rust integration.
+(import (scheme base) (stak rust))
+
+; Use the `define-rust` procedure to import native functions written in Rust.
+; The order of the functions should match the ones passed into the `Engine::new()`
+; function in Rust.
+(define-rust
+  make-person
+  person-pies
+  person-wasted
+  person-throw-pie)
+
+; Make two people with a number of pies they have and their dodge rates.
+(define me (make-person 4 0.2))
+(define friend (make-person 2 0.6))
+
+; The fight begins. Let's throw pies to each other!
+(do ()
+  ((or
+      (person-wasted me)
+      (person-wasted friend)
+      (and
+        (zero? (person-pies me))
+        (zero? (person-pies friend)))))
+  (person-throw-pie me friend)
+  (person-throw-pie friend me))
+
+; Output the winner.
+(write-string
+  (cond
+    ((person-wasted friend)
+      "You won!")
+    ((person-wasted me)
+      "You lost...")
+    (else
+      "Draw...")))
 ```
 
-Then, add a build script at `build.rs` to build the Scheme source file into bytecodes.
+Then, add a build script at `build.rs` to build the Scheme source file
+into bytecodes.
 
 ```rust no_run
 use stak_build::{build_r7rs, BuildError};
@@ -61,115 +95,86 @@ fn main() -> Result<(), BuildError> {
 }
 ```
 
-Now, you can include the Scheme script into a program in Rust using [the `stak::include_module` macro](https://docs.rs/stak/latest/stak/macro.include_module.html).
+Finally, you can embed and run the Scheme script in a Rust program.
 
 ```rust
+use any_fn::{r#fn, Ref};
 use core::error::Error;
+use rand::random;
 use stak::{
-    device::StdioDevice,
-    file::VoidFileSystem,
+    engine::{Engine, EngineError},
     include_module,
-    process_context::VoidProcessContext,
-    module::{Module, UniversalModule},
-    r7rs::{SmallError, SmallPrimitiveSet},
-    time::VoidClock,
-    vm::Vm,
+    module::UniversalModule,
 };
 
 const HEAP_SIZE: usize = 1 << 16;
 
-// Include a Scheme script in the bytecode format built by the build script above.
-static MODULE: UniversalModule = include_module!("hello.scm");
-
-fn main() -> Result<(), Box<dyn Error>> {
-    run(&MODULE.bytecode())?;
-
-    Ok(())
+/// A person who holds pies to throw.
+struct Person {
+    pies: usize,
+    dodge: f64,
+    wasted: bool,
 }
 
-fn run(bytecodes: &[u8]) -> Result<(), SmallError> {
-    // Prepare a heap memory of a virtual machine.
-    let mut heap = [Default::default(); HEAP_SIZE];
-    // Create a virtual machine with its heap memory primitive procedures.
-    let mut vm = Vm::new(
-        &mut heap,
-        SmallPrimitiveSet::new(
-            // Attach standard input, output, and error of this process to a virtual machine.
-            StdioDevice::new(),
-            // Use void system interfaces for security because we don't need them for this example.
-            VoidFileSystem::new(),
-            VoidProcessContext::new(),
-            VoidClock::new(),
-        ),
-    )?;
-
-    // Initialize a virtual machine with bytecodes.
-    vm.initialize(bytecodes.iter().copied())?;
-    // Run bytecodes on a virtual machine.
-    vm.run()
-}
-```
+impl Person {
+    /// Creates a person.
+    pub fn new(pies: usize, dodge: f64) -> Self {
+        Self {
+            pies,
+            dodge,
+            wasted: false,
+        }
+    }
 
-### Communication between Scheme and Rust
+    /// Returns a number of pies the person has.
+    pub fn pies(&self) -> usize {
+        self.pies
+    }
 
-Currently, in-memory standard input (`stdin`) and output (`stdout`) to Scheme scripts are the only way to communicate information between Rust programs and Scheme scripts.
+    /// Returns `true` if a person is wasted.
+    pub fn wasted(&self) -> bool {
+        self.wasted
+    }
 
-```rust
-use core::{error::Error, str::{self, FromStr}};
-use stak::{
-    device::ReadWriteDevice,
-    file::VoidFileSystem,
-    include_module,
-    process_context::VoidProcessContext,
-    module::{Module, UniversalModule},
-    r7rs::{SmallError, SmallPrimitiveSet},
-    time::VoidClock,
-    vm::Vm,
-};
+    /// Throws a pie to another person.
+    pub fn throw_pie(&mut self, other: &mut Person) {
+        if self.pies == 0 || self.wasted {
+            return;
+        }
 
-const BUFFER_SIZE: usize = 1 << 8;
-const HEAP_SIZE: usize = 1 << 16;
+        self.pies -= 1;
 
-static MODULE: UniversalModule = include_module!("fibonacci.scm");
+        if random::<f64>() > other.dodge {
+            other.wasted = true;
+        }
+    }
+}
 
 fn main() -> Result<(), Box<dyn Error>> {
-    let input = 15;
-    let mut output = vec![];
-    let mut error = vec![];
-
-    run(&MODULE.bytecode(), input.to_string().as_bytes(), &mut output, &mut error)?;
-
-    // If stderr is not empty, we assume that some error has occurred.
-    if !error.is_empty() {
-        return Err(str::from_utf8(&error)?.into());
-    }
+    // Import a Scheme module of the script.
+    static MODULE: UniversalModule = include_module!("fight.scm");
 
-    // Decode and test the output.
-    assert_eq!(isize::from_str(&str::from_utf8(&output)?)?, 610);
+    // Run the Scheme module.
+    run_scheme(&MODULE)?;
 
     Ok(())
 }
 
-fn run(
-    bytecodes: &[u8],
-    input: &[u8],
-    output: &mut Vec<u8>,
-    error: &mut Vec<u8>,
-) -> Result<(), SmallError> {
+fn run_scheme(module: &'static UniversalModule) -> Result<(), EngineError> {
+    // Initialize a heap memory for a Scheme scripting engine.
     let mut heap = [Default::default(); HEAP_SIZE];
-    let mut vm = Vm::new(
-        &mut heap,
-        SmallPrimitiveSet::new(
-            // Create and attach an in-memory I/O device.
-            ReadWriteDevice::new(input, output, error),
-            VoidFileSystem::new(),
-            VoidProcessContext::new(),
-            VoidClock::new(),
-        ),
-    )?;
-
-    vm.initialize(bytecodes.iter().copied())?;
-    vm.run()
+    // Define Rust functions to pass to the engine.
+    let mut functions = [
+        r#fn(Person::new),
+        r#fn::<(Ref<_>,), _>(Person::pies),
+        r#fn::<(Ref<_>,), _>(Person::wasted),
+        r#fn(Person::throw_pie),
+    ];
+    // Initialize the engine.
+    let mut engine = Engine::new(&mut heap, &mut functions)?;
+
+    // Finally, run the module!
+    engine.run(module)
 }
 ```
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@raviqqe/stak",
   "type": "module",
   "description": "Stak Scheme in WebAssembly",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "license": "SEE LICENSE IN ../LICENSE",
   "repository": {
     "type": "git",