@raviqqe/stak 0.3.24 → 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,14 +39,6 @@ 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
 
 ### Dynamic scripting in Rust
@@ -46,25 +46,42 @@ cargo install stak
 First, prepare a Scheme script named `src/fight.scm`:
 
 ```scheme
+; 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-throw-pie
-  person-wasted)
+  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 you (make-person 2 0.6))
-
-(person-throw-pie me you)
-(person-throw-pie you me)
-(person-throw-pie me you)
-(person-throw-pie you me)
-
-(when (person-wasted you)
-  (write-string "Congrats!"))
-(when (person-wasted me)
-  (write-string "Oh, no!"))
+(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
@@ -92,6 +109,7 @@ use stak::{
 
 const HEAP_SIZE: usize = 1 << 16;
 
+/// A person who holds pies to throw.
 struct Person {
     pies: usize,
     dodge: f64,
@@ -99,6 +117,7 @@ struct Person {
 }
 
 impl Person {
+    /// Creates a person.
     pub fn new(pies: usize, dodge: f64) -> Self {
         Self {
             pies,
@@ -107,12 +126,19 @@ impl Person {
         }
     }
 
+    /// Returns a number of pies the person has.
+    pub fn pies(&self) -> usize {
+        self.pies
+    }
+
+    /// Returns `true` if a person is wasted.
     pub fn wasted(&self) -> bool {
         self.wasted
     }
 
+    /// Throws a pie to another person.
     pub fn throw_pie(&mut self, other: &mut Person) {
-        if self.wasted {
+        if self.pies == 0 || self.wasted {
             return;
         }
 
@@ -125,22 +151,29 @@ impl Person {
 }
 
 fn main() -> Result<(), Box<dyn Error>> {
+    // Import a Scheme module of the script.
     static MODULE: UniversalModule = include_module!("fight.scm");
 
-    run(&MODULE)?;
+    // Run the Scheme module.
+    run_scheme(&MODULE)?;
 
     Ok(())
 }
 
-fn run(module: &'static UniversalModule) -> Result<(), EngineError> {
+fn run_scheme(module: &'static UniversalModule) -> Result<(), EngineError> {
+    // Initialize a heap memory for a Scheme scripting engine.
     let mut heap = [Default::default(); HEAP_SIZE];
+    // Define Rust functions to pass to the engine.
     let mut functions = [
         r#fn(Person::new),
-        r#fn(Person::throw_pie),
+        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.24",
+  "version": "0.3.25",
   "license": "SEE LICENSE IN ../LICENSE",
   "repository": {
     "type": "git",