@raviqqe/stak 0.3.9 → 0.3.11

package/README.md

@@ -7,37 +7,38 @@
 
 The miniature, embeddable R7RS Scheme implementation in Rust
 
-The full documentation is [here](https://raviqqe.github.io/stak).
+Stak Scheme aims to be:
+
+- An embeddable Scheme interpreter for Rust with very small memory footprint and reasonable performance
+- The minimal implementation of [the R7RS-small standard][r7rs-small]
+  - A subset of [Chibi Scheme](https://github.com/ashinn/chibi-scheme), [Gauche](https://github.com/shirok/Gauche), and [Guile](https://www.gnu.org/software/guile/)
+
+For more information and usage, visit [the full documentation](https://raviqqe.github.io/stak).
 
 ## Install
 
-### Library
+### Libraries
 
 To install Stak Scheme as a library in your Rust project, run:
 
 ```sh
 cargo add stak
+cargo add --build stak-build
 ```
 
+For full examples, see [the `examples` directory](./examples).
+
 ### Command line tools
 
-To install the Scheme interpreter and alike as command line tools, run:
+To install the Scheme interpreter as a command, run:
 
 ```sh
-# Install the Scheme interpreter.
 cargo install stak
-
-# Install the minimal Scheme interpreter (6 times smaller!)
-cargo install mstak
-
-# Install the Scheme-to-bytecode compiler and bytecode interpreter.
-cargo install stak-compile
-cargo install stak-interpret
 ```
 
 ## Examples
 
-### Running a Scheme script
+### Embedding Scheme scripts in Rust
 
 First, prepare a Scheme script at `src/hello.scm`.
 
@@ -57,35 +58,107 @@ fn main() -> Result<(), BuildError> {
 }
 ```
 
-Now, you can include the Scheme script into a program in Rust using [the `stak::include_bytecode` macro](https://docs.rs/stak/latest/stak).
+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).
 
 ```rust
 use core::error::Error;
 use stak::{
     device::StdioDevice,
     file::VoidFileSystem,
-    include_bytecode,
+    include_module,
     process_context::VoidProcessContext,
+    module::{Module, UniversalModule},
     r7rs::{SmallError, SmallPrimitiveSet},
     time::VoidClock,
     vm::Vm,
 };
 
 const HEAP_SIZE: usize = 1 << 16;
-const BYTECODES: &[u8] = include_bytecode!("hello.scm");
+
+// 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(BYTECODES)?;
+    run(&MODULE.bytecode())?;
 
     Ok(())
 }
 
 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()
+}
+```
+
+### Communication between Scheme and Rust
+
+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.
+
+```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,
+};
+
+const BUFFER_SIZE: usize = 1 << 8;
+const HEAP_SIZE: usize = 1 << 16;
+
+static MODULE: UniversalModule = include_module!("fibonacci.scm");
+
+fn main() -> Result<(), Box<dyn Error>> {
+    let input = 24;
+    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());
+    }
+
+    // Decode and print the output.
+    println!("Answer: {}", isize::from_str(&str::from_utf8(&output)?)?);
+
+    Ok(())
+}
+
+fn run(
+    bytecodes: &[u8],
+    input: &[u8],
+    output: &mut Vec<u8>,
+    error: &mut Vec<u8>,
+) -> Result<(), SmallError> {
+    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(),
@@ -97,6 +170,16 @@ fn run(bytecodes: &[u8]) -> Result<(), SmallError> {
 }
 ```
 
+## References
+
+- This project is based on [Ribbit Scheme][ribbit], the small and portable R4RS implementation.
+- [Scheme][scheme]
+- [The R7RS-small standard][r7rs-small]
+
 ## License
 
 [MIT](https://github.com/raviqqe/stak/blob/main/LICENSE)
+
+[scheme]: https://www.scheme.org/
+[r7rs-small]: https://small.r7rs.org/
+[ribbit]: https://github.com/udem-dlteam/ribbit

package/package.json

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