### scm_program_arguments_init example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/c-api.md

Example demonstrating how to initialize program arguments using scm_program_arguments_init.

```c
int my_enter(ContextRef ctx, void *arg) {
    char *argv[] = {"program", "arg1", "arg2"};
    scm_program_arguments_init(ctx, 3, argv);
    return 0;
}
```

--------------------------------

### Primitive Expansion Examples

Source: https://github.com/playx18/capyscheme/blob/main/docs/IMPLEMENTATION.md

Examples of optimizations performed during primitive expansion.

```scheme
(memq x '(a b c)) => (if (eq? x 'a) #t (if (eq? x 'b) #t (if (eq? x 'c) #t) #f))
```

```scheme
(+ 1 2 3 4) => (+ (1 2) (+ 3 4))
```

--------------------------------

### Standard Rust Installation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Command to install the CapyScheme library and headers.

```bash
cargo install --path capy
```

--------------------------------

### current_module Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example of getting the current module.

```rust
let current = current_module(ctx);
```

--------------------------------

### C Header Generation Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Example command for generating C headers using cbindgen.

```bash
cbindgen -c crate-type.toml --output capy.h --lang c
```

--------------------------------

### Module::name Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example of getting a module's name.

```rust
let name = module.name();
println!("Module: {}", name);
```

--------------------------------

### Codegen Options Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Example of controlling code generation at compile time using RUSTFLAGS.

```bash
RUSTFLAGS="-C target-cpu=native -C lto" cargo build --release
```

--------------------------------

### Module::new Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example usage of Module::new.

```rust
let uses = list!(ctx, imported_module);
let mod_name = ctx.intern("my-module");
let module = Module::new(ctx, 100, uses, Value::new(false));
```

--------------------------------

### System-wide Installation

Source: https://github.com/playx18/capyscheme/blob/main/INSTALLATION.md

Command to install CapyScheme system-wide with a specified prefix.

```sh
$ make PREFIX=/usr/local install
```

--------------------------------

### scm_fork example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/c-api.md

Example demonstrating how to fork a new Scheme thread.

```c
void *thread_init(ScmRef scm, void *arg) {
    // Code executed in the new thread
    return NULL;
}

Value thread = scm_fork(ctx, thread_init, NULL);
```

--------------------------------

### Portable Installation

Source: https://github.com/playx18/capyscheme/blob/main/INSTALLATION.md

Command to install CapyScheme in a portable manner.

```sh
$ make install-portable
```

--------------------------------

### Basic Value Creation Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example demonstrating how to create Value instances from raw bits and Rust values.

```rust
let num = Value::from_raw_i64(42);
let bool_val = Value::new(true);
```

--------------------------------

### Gc Creation Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of creating a new Gc-managed object.

```rust
let obj = Gc::new(*ctx, MyHeapType { /* ... */ });
```

--------------------------------

### Scheme::new Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Demonstrates how to create a new Scheme instance.

```rust
let scm = Scheme::new();
```

--------------------------------

### Context::intern Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example of using Context::intern to create a symbol.

```rust
let sym = ctx.intern("my-symbol");
```

--------------------------------

### Library Export Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Shows how to define exported bindings from a library.

```scheme
(library (my-module utilities)
  (export factorial map-list filter-list)
  (import (scheme base))
  
  (define (factorial n)
    (if (<= n 1) 1 (* n (factorial (- n 1)))))
  
  (define (map-list proc lst)
    ; ...
    ))
```

--------------------------------

### Str Length

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of getting the length of a Scheme string.

```rust
let len = string.len();  // Number of characters
```

--------------------------------

### Quickstart Build Command

Source: https://github.com/playx18/capyscheme/blob/main/docs/BOOTSTRAP.md

Builds the entire CapyScheme project, including the runtime and all bootstrap stages (0, 1, and 2).

```sh
make build
```

--------------------------------

### Example 1: Simple Pattern Matching

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Demonstrates simple pattern matching with scm_match!.

```rust
let result = scm_match!(ctx, form, {
    ('quote datum) => datum,
    ('define (name . args) body) => {
        // Handle function definition
    },
    ('lambda args body) => {
        // Handle lambda expression
    },
    _ => form,
});
```

--------------------------------

### Re-export Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Illustrates how to re-export bindings from another library.

```scheme
(library (my-module reexport)
  (export (import-from (scheme base) list? map ...))
  (import (scheme base)))
```

--------------------------------

### CAPY_BOOTSTRAP Usage Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Controls whether bootstrap code is loaded on startup.

```bash
CAPY_BOOTSTRAP=0 ./minimal_program
```

--------------------------------

### Tuple Access

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of getting the length and accessing fields of a Scheme Tuple.

```rust
let len = t.len();
let field = t.get(0);
```

--------------------------------

### scm_string Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/c-api.md

Example usage of scm_string.

```c
Value str = scm_string(ctx, "hello");
```

--------------------------------

### type_mismatch Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/errors.md

Example usage of the type_mismatch constructor.

```rust
return Err(ConversionError::type_mismatch(0, "Symbol", value));
```

--------------------------------

### Install cross-compilation tool

Source: https://github.com/playx18/capyscheme/blob/main/docs/BOOTSTRAP.md

Command to install the 'cross' tool if it's not found when cross-compiling.

```shell
make install-cross
```

--------------------------------

### Applying to Modules - Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Example usage of the #[scheme] macro on Rust modules.

```rust
#[scheme]
pub mod math_ops {
    #[scheme]
    pub fn sqrt(ctx: Context<'gc>, x: f64) -> f64 {
        x.sqrt()
    }
    
    #[scheme]
    pub fn pow(ctx: Context<'gc>, base: f64, exp: f64) -> f64 {
        base.powf(exp)
    }
}
```

--------------------------------

### Value::new Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example showing Value creation from various Rust types implementing IntoValue.

```rust
let num = Value::new(42i64);
let bool_v = Value::new(true);
```

--------------------------------

### arity_mismatch Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/errors.md

Example usage of the arity_mismatch constructor.

```rust
return Err(ConversionError::arity_mismatch(0, Arity { min: 2, max: Some(2) }, args.len()));
```

--------------------------------

### CompilationOptions usage example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

Example of creating CompilationOptions and using compile_cps_to_object.

```rust
let options = CompilationOptions {
    optimize_level: OptimizationLevel::O3,
    emit_debug_info: false,
    ..Default::default()
};

compile_cps_to_object(ctx, cps, &options)?;
```

--------------------------------

### Performance: Lazy Loading Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Illustrates pre-loading frequently used modules for performance.

```scheme
(import (scheme base)
        (scheme file)
        (my-project utils))
```

--------------------------------

### macOS Code Signing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Example command for code signing a library on macOS.

```bash
codesign -s - target/release/libcapy.dylib
```

--------------------------------

### Module::search Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example of searching for a binding using Module::search.

```rust
let binding = module.search(|m| {
    let obarray = m.obarray.get();
    obarray.get(symbol)
});
```

--------------------------------

### Applying to Functions - Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Example usage of the #[scheme] macro on Rust functions.

```rust
use capy::prelude::*;

#[scheme]
pub fn add(ctx: Context<'gc>, a: i64, b: i64) -> i64 {
    a + b
}

#[scheme]
pub fn greet(ctx: Context<'gc>, name: String) -> String {
    format!("Hello, {}", name)
}
```

--------------------------------

### Scheme::enter Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Shows how to enter the runtime and execute a closure within a GC context.

```rust
let result = scm.enter(|ctx| {
    let num = Value::new(42i64);
    let sym = ctx.intern("hello");
    // Use num and sym
    42
});
```

--------------------------------

### Str Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of creating a Scheme string.

```rust
let s = ctx.str("hello");
```

--------------------------------

### Strip Symbols Example (Command Line)

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Command to strip symbols from release binaries.

```bash
cargo build --release
strip target/release/capy.so
```

--------------------------------

### Ypsilon Individual Library Test Example

Source: https://github.com/playx18/capyscheme/blob/main/tests/r6rs/README.txt

How to run an individual library's tests using Ypsilon.

```shell
cd <somewhere>
ypsilon --sitelib=. --clean-acc tests/r6rs/run/program.sps
```

--------------------------------

### PLT Scheme Collection Path Example

Source: https://github.com/playx18/capyscheme/blob/main/tests/r6rs/README.txt

Example of how to find the collection path for PLT Scheme.

```scheme
(build-path (find-system-path 'addon-dir)
              (version) "collects"
              "tests" "r6rs")
```

--------------------------------

### FromValue Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example usage of the FromValue trait for type conversions.

```rust
let num: i64 = i64::try_from_value(ctx, val)?;
let b: bool = bool::try_from_value(ctx, val)?;
```

--------------------------------

### Trace Macro Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

An example demonstrating the use of the #[derive(Trace)] macro with a struct.

```rust
use capy::prelude::*;

#[derive(Trace)]
pub struct Environment<'gc> {
    parent: Option<Gc<'gc, Environment<'gc>>>,
    vars: Gc<'gc, Vector<'gc>>,
    data: i64,
}
```

--------------------------------

### Ypsilon Example

Source: https://github.com/playx18/capyscheme/blob/main/tests/r6rs/README.txt

How to run the R6RS test suite using Ypsilon.

```shell
cd <somewhere>
ypsilon --sitelib=. --clean-acc tests/r6rs/run.sps
```

--------------------------------

### Applying to Structs and Enums - Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Example usage of the #[scheme] macro on a Rust struct.

```rust
#[scheme]
pub struct Person {
    pub name: String,
    pub age: i64,
}
```

--------------------------------

### Example 2: Pattern with Guard

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Illustrates pattern matching combined with guards using scm_match!.

```rust
let kind = scm_match!(ctx, form, {
    ('if test conseq alt) => IfForm { test, conseq, alt },
    ((head . rest) if head.is::<Symbol>()) => {
        // head is a symbol, rest is the argument list
        CallForm { head, args: rest }
    },
    (x . rest) => {
        // Generic list pattern
        GenericForm { car: x, cdr: rest }
    },
    _ => OtherForm(form),
});
```

--------------------------------

### Example Usage of Prelude

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Demonstrates how to use the CapyScheme prelude in a Rust main function.

```rust
use capy::prelude::*;

fn main() {
    let scm = Scheme::new();
    scm.enter(|ctx| {
        let x = Value::new(42);
        let list = list!(ctx, x, Value::new(10));
    });
}
```

--------------------------------

### Ikarus Example

Source: https://github.com/playx18/capyscheme/blob/main/tests/r6rs/README.txt

How to run the R6RS test suite using Ikarus.

```shell
cd <somewhere>
ikarus --r6rs-script tests/r6rs/run.sps
```

--------------------------------

### Ikarus Individual Library Test Example

Source: https://github.com/playx18/capyscheme/blob/main/tests/r6rs/README.txt

How to run an individual library's tests using Ikarus.

```shell
cd <somewhere>
ikarus --r6rs-script tests/r6rs/run/program.sps
```

--------------------------------

### Value::is Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example of checking if a Value is of a specific heap type.

```rust
if val.is::<Symbol>() {
    // Treat as symbol
}
```

--------------------------------

### Macro Expansion Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

Demonstrates the expansion of a `when` macro in Scheme, showing the transformation from a macro-based input to its expanded form.

```scheme
; Input with macro
(define-syntax when
  (syntax-rules ()
    ((when test body ...)
     (if test (begin body ...)))))

(when (> x 0)
  (display "positive")
  (newline))

; After expansion:
(if (> x 0)
  (begin
    (display "positive")
    (newline)))
```

--------------------------------

### Importing (scheme base)

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example of importing the core (scheme base) module.

```scheme
(import (scheme base))
```

--------------------------------

### Value::cons Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example of creating a cons cell (pair) from two values.

```rust
let pair = Value::cons(ctx, Value::new(1), Value::new(2));
```

--------------------------------

### Tuple Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of creating a Scheme Tuple.

```rust
let t = Tuple::from_slice(ctx, &[field1, field2, field3]);
```

--------------------------------

### Usage of (scheme file)

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example of using file I/O operations from the (scheme file) module.

```scheme
(import (scheme file))
(call-with-input-file "data.txt"
  (lambda (port)
    (read port)))
```

--------------------------------

### Expansion Error Reporting Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example of a macro expansion error message, indicating an undefined syntax and its location.

```text
Error: Undefined syntax 'my-macro' at line 10
  (my-macro 1 2 3)
  ^^^^^^^^^
Module: (my-module)
```

--------------------------------

### Pattern Matching Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/README.md

Example of using the scm_match! macro for pattern matching in Rust.

```rust
let result = scm_match!(ctx, form, {
    ('lambda args body) => compile_lambda(args, body),
    ('if test cons alt) => compile_if(test, cons, alt),
    _ => fallback(form),
});
```

--------------------------------

### Vector Length

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of getting the length of a Scheme Vector.

```rust
let len = v.len();
```

--------------------------------

### Symbol Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Examples of creating and comparing symbols.

```rust
let sym = ctx.intern("my-symbol");
let sym2 = ctx.intern("my-symbol");  // sym == sym2 (identity)
```

--------------------------------

### Applying to Static Variables - Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Example usage of the #[scheme] macro on Rust static variables.

```rust
#[scheme]
pub static MAX_VALUE: i64 = 1000;

#[scheme]
pub static PI: f64 = 3.14159;
```

--------------------------------

### Tail Call Optimization Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example demonstrating Tail Call Optimization, which eliminates stack frames for tail-recursive calls.

```scheme
; Input
(define (factorial n acc))
  (if (<= n 1)
    acc
    (factorial (- n 1) (* n acc))))

; Optimized: No recursive stack growth
```

--------------------------------

### Importing (scheme r5rs)

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example of importing the R5RS compatibility layer.

```scheme
(import (scheme r5rs))
```

--------------------------------

### Good Example of scm_match!

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Demonstrates efficient and readable control flow using `scm_match!` with pattern matching and guards.

```rust
scm_match!(ctx, expr, {
    ('if test conseq alt) => handle_if(ctx, test, conseq, alt),
    ('let bindings body) if validate_bindings(bindings) => handle_let(ctx, bindings, body),
    ('quote datum) => datum,
    _ => expand_generic(ctx, expr),
})
```

--------------------------------

### List Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of creating a Scheme list using a macro.

```rust
let list = list!(ctx, a, b, c);
// Equivalent to: (cons a (cons b (cons c VALUE_NULL)))
```

--------------------------------

### MMTk_PLAN Usage Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Sets the garbage collection algorithm using the MMTk_PLAN environment variable.

```bash
MMTk_PLAN=GenImmix ./program
```

--------------------------------

### Macro Attributes - Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Example usage of macro attributes for module specification and name overriding.

```rust
#[scheme(module = "my_lib::utils")]
pub fn utility_function(ctx: Context<'gc>) -> i64 {
    42
}

#[scheme(name = "custom-name")]
pub fn renamed_function(ctx: Context<'gc>) -> String {
    "hello".to_string()
}
```

--------------------------------

### Circular Dependency Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

An example illustrating a circular dependency error in the module system.

```scheme
; module-a.sls imports module-b
; module-b.sls imports module-a
; => Error: Circular dependency
```

--------------------------------

### Larceny Individual Library Test Example

Source: https://github.com/playx18/capyscheme/blob/main/tests/r6rs/README.txt

How to run an individual library's tests using Larceny.

```shell
larceny -path <somewhere> -r6rs -program run/program.sps
```

--------------------------------

### Accessing and Modifying Variable Value

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of getting and setting a variable's value in Rust.

```rust
let var_value = variable.value.get();
variable.value.set(new_value);
```

--------------------------------

### Larceny Example

Source: https://github.com/playx18/capyscheme/blob/main/tests/r6rs/README.txt

How to run the R6RS test suite using Larceny.

```shell
larceny -path <somewhere> -r6rs -program run.sps
```

--------------------------------

### Syntax Error Reporting Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example of a syntax error message, including the location and expected token.

```text
Error: Unexpected token ')' at line 5, column 42
  (define (foo x))
     (+ x y))
             ^
Expected ')'
```

--------------------------------

### Contification Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example of Contification, converting tail-recursive continuations to loops, showing the transformation from CPS form to a machine-level loop.

```scheme
; Input (CPS form)
(define (loop n cont))
  (if (<= n 0)
    (cont 'done)
    (loop (- n 1) cont)))

; After contification
(define (loop n cont))
  (begin
    (set! n (- n 1))
    ...
    (if (<= n 0) (cont 'done) (loop n cont))))

; Optimized to machine-level loop
```

--------------------------------

### CAPY_LOAD_PATH Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Sets the Scheme library search path, separated by path separators.

```bash
CAPY_LOAD_PATH=/usr/local/lib/scheme:/home/user/.scheme ./program
```

--------------------------------

### Accessing a Module

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of accessing a module from the context in Rust.

```rust
let module = ctx.public_ref("module-name", "_module_").unwrap().downcast::<Module>();
```

--------------------------------

### Example 4: Binding and Type Checking

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Demonstrates binding and type checking within scm_match! patterns.

```rust
let operation = scm_match!(ctx, form, {
    (op x y) if op == ctx.intern("+") => {
        Binary { op, left: x, right: y }
    },
    (op x y) if op == ctx.intern("*") => {
        Binary { op, left: x, right: y }
    },
    _ => Unknown(form),
});
```

--------------------------------

### Immediate Integers Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Examples of creating immediate integer values.

```rust
let num = Value::new(42i64);
let num = Value::new(10u32);
```

--------------------------------

### Vector Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Examples of creating a Scheme Vector.

```rust
let vec = vector!(ctx, val1, val2, val3);
let vec = Vector::from_slice(ctx, &[val1, val2, val3]);
```

--------------------------------

### PLT Scheme Example

Source: https://github.com/playx18/capyscheme/blob/main/tests/r6rs/README.txt

How to run the R6RS test suite using PLT Scheme.

```shell
mzscheme -l tests/r6rs/run.sps
```

--------------------------------

### scm_intern_symbol Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/c-api.md

Example usage of scm_intern_symbol.

```c
Value sym = scm_intern_symbol(ctx, "my-symbol");
```

--------------------------------

### Common Subexpression Elimination Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example illustrating Common Subexpression Elimination, reusing computation results.

```scheme
; Input
(+ (+ x y) (+ x y))

; Optimized to
(let ((temp (+ x y))))
  (+ temp temp))
```

--------------------------------

### Gc Mutation Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of mutating a Gc-managed object.

```rust
let mut_ref = Gc::write(ctx, obj);
mut_ref.some_field.set(new_value);
```

--------------------------------

### Character Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of creating a character value.

```rust
let ch = Value::new('A');
```

--------------------------------

### Dead Code Elimination Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example demonstrating Dead Code Elimination, where unused definitions are removed.

```scheme
; Input
(define x 42)
(define y 100)
(define z (+ y 1))
y  ; Only y is used

; Output
(define y 100)
y
```

--------------------------------

### Link-Time Optimization (LTO) Configuration

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Example TOML configuration to enable LTO for smaller binaries.

```toml
[profile.release]
lto = "thin"  # or "fat" for maximum optimization
```

--------------------------------

### Undefined Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of creating the undefined value.

```rust
let undef = Value::undefined();
```

--------------------------------

### Closure Calling

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of calling a Scheme closure.

```rust
let result = call_scheme(ctx, clos, args)?;
```

--------------------------------

### Error Object Example with `with-exception-handler`

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/errors.md

A Scheme example showing how to use `with-exception-handler` to catch an out-of-bounds string index error and extract the message and irritants.

```scheme
(with-exception-handler
  (lambda (e)
    (if (error-object? e)
      (list
        (error-object-message e)
        (error-object-irritants e))
      #f))
  (lambda () 
    (string-ref "short" 100)))  ; Index out of bounds
```

--------------------------------

### Inlining Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example of Inlining, where function calls are replaced with function bodies for small functions, followed by Common Subexpression Elimination.

```scheme
; Input
(define (square x) (* x x))
(square (+ a b))

; Inlined
(* (+ a b) (+ a b))

; With CSE
(let ((temp (+ a b)))
  (* temp temp))
```

--------------------------------

### Null Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of creating the null value.

```rust
let empty = Value::null();
```

--------------------------------

### Scheme::call Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Demonstrates calling a named procedure in a specific module.

```rust
scm.call("my module", "my-function",
    |ctx, args| {
        args.push(Value::new(42i64));
    },
    |ctx, result| {
        match result {
            Ok(v) => println!("Success: {}", v),
            Err(e) => println!("Error: {}", e),
        }
        0
    }
);
```

--------------------------------

### Reflection Procedures for Module Information

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Provides examples of procedures to access module information at runtime.

```scheme
(module? obj)                    ; Test if module
(module-name module)             ; Get module name
(module-exports module)          ; List exported names
(module-imports module)          ; List imported modules
```

```scheme
(module-defined? module symbol)  ; Check if binding exists
(module-ref module symbol)       ; Get binding value
(module-set! module symbol val)  ; Set binding value
```

```scheme
(make-module size)               ; Create empty module
(module-use! module imported)    ; Add imports
```

--------------------------------

### Flonum Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Examples of creating floating-point values.

```rust
let pi = Value::new(3.14159);
let f: f64 = 2.71828;
let val = Value::new(f);
```

--------------------------------

### Best Practice: Separate Interfaces and Implementations

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example of separating module interfaces from their implementations.

```scheme
; interface.sls
(library (my-project interface)
  (export public-function)
  (import (scheme base))
  (define (public-function x) ...))

; implementation.sls
(library (my-project)
  (export public-function)
  (import (my-project interface)))
```

--------------------------------

### Using the C API

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/README.md

Example demonstrating how to use the C API for initializing the runtime, entering a context, and calling a Scheme function.

```c
#include "capy.h"

ScmRef scm = scm_new();

scm_enter(scm, my_callback, NULL);

int finish(ContextRef ctx, bool success, Value result, void *data) {
    if (success) {
        printf("Result: %s\n", ...);
    }
    return 0;
}

scm_call(scm, "module", "func", prepare, NULL, finish, NULL);
scm_free(scm);

```

--------------------------------

### scm_public_ref Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/c-api.md

Example usage of scm_public_ref to retrieve a variable.

```c
int my_enter(ContextRef ctx, void *arg) {
    Value var = scm_public_ref(ctx, "boot cli", "enter", VALUE_NULL);
    if (!VALUE_IS_NULL(var)) {
        // Use var
    }
    return 0;
}
```

--------------------------------

### Module Exports using `provide`

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Example of declaring module exports using the `provide` statement.

```scheme
(module my-module scheme
  (provide my-function other-function)
  
  (define (my-function x) ...)
  (define (other-function y) ...))
```

--------------------------------

### Booleans Creation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of creating boolean values.

```rust
let t = Value::new(true);
let f = Value::new(false);
```

--------------------------------

### Scheme::call_value Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Illustrates calling a Scheme closure with prepared arguments.

```rust
let result = scm.call_value(
    |ctx, args| {
        args.push(Value::new(10i64));
        args.push(Value::new(20i64));
        ctx.public_ref("my module", "add").unwrap()
    },
    |ctx, result| {
        match result {
            Ok(val) => println!("Result: {:?}", val),
            Err(e) => println!("Error: {:?}", e),
        }
        0
    }
);
```

--------------------------------

### Gc Dereferencing Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of dereferencing a Gc reference to access a field.

```rust
let field = obj.some_field;
```

--------------------------------

### IntoValue Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example usage of the IntoValue trait for type conversions.

```rust
let val = 42i64.into_value(ctx);
let bool_val = true.into_value(ctx);
```

--------------------------------

### Importing a Library

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Demonstrates various ways to import libraries into the current context.

```scheme
(import (scheme base))
(import (my-module utils))
(import (lib name) (prefix lib-))
```

--------------------------------

### Dynamic Module Loading with `require`

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Demonstrates dynamic module loading using the `require` form.

```scheme
(require (math utils))
(math-utils:some-function)
```

--------------------------------

### Running Tests

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Command to run all tests in release mode.

```bash
cargo test --release
```

--------------------------------

### Example 3: Nested Patterns

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/macros.md

Shows nested pattern matching capabilities of scm_match!.

```rust
let result = scm_match!(ctx, expr, {
    ('let ((var val) ...) . body) => {
        // let binding with multiple variables
    },
    ('cond (test . consequent) ...) => {
        // Cond with multiple clauses
    },
    ((lambda (arg) body) . rest) => {
        // Immediately invoked lambda
    },
    _ => fallback(ctx, expr),
});
```

--------------------------------

### Immediate Integers Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Examples of testing and accessing immediate integer values.

```rust
if val.is_int32() { /* ... */ }
let i = val.as_int32();
```

--------------------------------

### Unix/Linux Standard Build

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Command to perform a standard release build on Unix/Linux.

```bash
cargo build --release
```

--------------------------------

### Str Conversion

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of converting a Scheme string to a Rust String.

```rust
let rust_string: String = string.to_string();
```

--------------------------------

### Str Access

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of accessing a character in a Scheme string by index.

```rust
if let Some(ch) = string.get(0) {
    println!("First char: {}", ch);
}
```

--------------------------------

### TypeMismatch Error Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/errors.md

Example of handling a TypeMismatch error during value conversion.

```rust
match i64::try_from_value(ctx, val) {
    Ok(num) => { /* use num */ } 
    Err(ConversionError::TypeMismatch { pos, expected, found }) => {
        eprintln!("Arg {}: expected {}, got {}", pos, expected, found);
    }
    _ => {} 
}
```

--------------------------------

### Getting Rust Stack Traces

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/errors.md

Bash command to enable Rust backtraces when running a program, useful for debugging.

```bash
RUST_BACKTRACE=1 ./program
```

--------------------------------

### Value::downcast Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example of downcasting a Value to a typed reference for a heap object.

```rust
let sym = val.downcast::<Symbol>();
let s = val.downcast::<Str>();
```

--------------------------------

### Best Practice: Use Prefixes for Imports

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Shows how to use prefixed imports to avoid name conflicts.

```scheme
(import (prefix str- (scheme string))
        (prefix vec- (scheme vector)))

(str-append "a" "b")    ; Clear origin
(vec-ref v 0)           ; Clear origin
```

--------------------------------

### with_appended_pos Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/errors.md

Example of using with_appended_pos to adjust error position in nested calls.

```rust
match process_sublist(ctx, rest) {
    Err(e) => return Err(e.with_appended_pos(1)),  // Arguments start at index 1
    Ok(v) => v,
}
```

--------------------------------

### ArityMismatch Error Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/errors.md

Example of handling an ArityMismatch error when checking function arguments.

```rust
match check_arity(args) {
    Err(ConversionError::ArityMismatch { pos, expected, found }) => {
        if let Some(max) = expected.max {
            eprintln!("Expected {}-{} args, got {}", expected.min, max, found);
        } else {
            eprintln!("Expected at least {} args, got {}", expected.min, found);
        }
    }
    _ => {} 
}
```

--------------------------------

### Troubleshooting Out of Memory

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Command to reduce build parallelism to mitigate out-of-memory errors.

```bash
cargo build --release -j 1
```

--------------------------------

### Debug Information Usage with GDB/LLDB

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

Example commands for using GDB/LLDB with compiled programs that emit DWARF debug information.

```bash
gdb ./program
(gdb) break my_function
(gdb) run
(gdb) step     # Step through compiled code
(gdb) print x  # Print variable value
```

--------------------------------

### Value::try_as Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Example of safely attempting to downcast a Value to an optional typed reference.

```rust
if let Some(sym) = val.try_as::<Symbol>() {
    // Use sym
}
```

--------------------------------

### Compilation Error Reporting Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example of a compilation error message, highlighting a type mismatch.

```text
Error: Type mismatch at (+ x "hello")
Cannot add number and string
  File: myprogram.scm:15
```

--------------------------------

### Full-Featured Build Configuration

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Configuration to enable all optional features.

```toml
[dependencies]
capy = { version = "1.3.0", features = ["portable", "expeditor", "bootstrap", "aslr"] }
```

--------------------------------

### Constant Folding Example

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/compilation-pipeline.md

An example showing Constant Folding, where constant expressions are evaluated at compile time.

```scheme
; Input
(+ 1 2 3)

; Compiled as
42  ; Constant
```

--------------------------------

### Module::new Constructor

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Creates a new module instance.

```rust
pub fn new(
    ctx: Context<'gc>,
    size: usize,
    uses: Value<'gc>,
    binder: impl IntoValue<'gc>,
) -> Gc<'gc, Self>
```

--------------------------------

### WebAssembly Build

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Commands to add the wasm32 target and build for WebAssembly.

```bash
rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --release
```

--------------------------------

### Bootstrap Feature

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Enables macro expansion and module compilation at runtime.

```toml
[dependencies]
capy = { version = "1.3.0", features = ["bootstrap"] }
```

--------------------------------

### Minimal Build Configuration

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Configuration for minimal embedded systems, disabling unnecessary features.

```toml
[dependencies]
capy = { version = "1.3.0", default-features = false, features = ["portable"] }
```

--------------------------------

### Symbol Access

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of accessing the name of a Symbol.

```rust
let name: Gc<'gc, Str<'gc>> = sym.name();
```

--------------------------------

### Web/WASM Build Configuration

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Configuration for WebAssembly targets.

```toml
[dependencies]
capy = { version = "1.3.0", default-features = false, features = ["portable", "bootstrap"] }

[target.'cfg(target_arch = "wasm32")'.dependencies]
getrandom = { version = "0.2", features = ["js"] }
```

--------------------------------

### Null Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of testing for the null value.

```rust
if val.is_null() { /* ... */ }
```

--------------------------------

### Booleans Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of testing boolean values.

```rust
if val == Value::new(true) { /* ... */ }
```

--------------------------------

### Run tests

Source: https://github.com/playx18/capyscheme/blob/main/tests/lib/README.md

To run tests, execute 'make test' in the root directory. To use a custom Capy binary, set the CAPY environment variable.

```bash
make test
export CAPY=/path/to/custom/capy
make test
```

--------------------------------

### Module Initialization Procedure

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Signature for the `init_modules` procedure used to initialize the module system.

```rust
pub fn init_modules(ctx: Context<'gc>)
```

--------------------------------

### Closure Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of checking if a value is a Closure and downcasting.

```rust
if val.is::<Closure>() {
    let clos = val.downcast::<Closure>();
}
```

--------------------------------

### Vector Mutation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of mutating an element in a Scheme Vector.

```rust
let wv = Gc::write(ctx, v);
wv[0].unlock().set(new_value);
```

--------------------------------

### CAPY_GC_HEAP_SIZE Examples

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Sets the initial garbage collector heap size in bytes. Supports numeric values with optional suffixes (K, M, G).

```bash
CAPY_GC_HEAP_SIZE=1G ./program        # 1 gigabyte
CAPY_GC_HEAP_SIZE=512M ./program      # 512 megabytes
CAPY_GC_HEAP_SIZE=10485760 ./program  # 10 megabytes (raw bytes)
```

--------------------------------

### Vector Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of checking if a value is a Vector and downcasting.

```rust
if val.is::<Vector>() {
    let v = val.downcast::<Vector>();
}
```

--------------------------------

### Str Mutation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of mutating a character in a Scheme string.

```rust
Str::set(string, ctx, 0, 'x');  // Set character at index 0 to 'x'
```

--------------------------------

### Setting Load Path (Rust)

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

How to programmatically set the load path using Rust.

```rust
scm.enter(|ctx| {
    ctx.set_load_path(&["/path/to/libs", "."])
});
```

--------------------------------

### Str Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of checking if a value is a Str and downcasting.

```rust
if val.is::<Str>() {
    let string = val.downcast::<Str>();
}
```

--------------------------------

### Symbol Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of testing if a Value is a Symbol and downcasting.

```rust
if val.is::<Symbol>() {
    let sym = val.downcast::<Symbol>();
}
```

--------------------------------

### Custom Module Registration with #[scheme]

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/module-system.md

Illustrates how to specify a custom module name for #[scheme] macro registration.

```rust
#[scheme(module = "my_lib")]
pub fn my_function(ctx: Context<'gc>) -> i64 {
    42
}
```

--------------------------------

### Character Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of testing and accessing character values.

```rust
if val.is_char() {
    let c: char = val.char();
}
```

--------------------------------

### Context::str

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Create a new Scheme string.

```rust
pub fn str(self, data: &str) -> Value<'gc>
```

--------------------------------

### Flonum Testing

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of testing and accessing floating-point values.

```rust
if let Some(num) = val.number() {
    let f = num.real_to_f64(ctx);
}
```

--------------------------------

### Vector::len Method

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Get the vector length.

```rust
pub fn len(self) -> usize
```

--------------------------------

### Running R6RS Test Suite

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Command to run the R6RS test suite using the capy interpreter.

```bash
capy -L . -s tests/r6rs/run-via-eval.sps
```

--------------------------------

### Context::mutation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/api-reference/rust-api.md

Get the underlying Mutation handle.

```rust
pub fn mutation(self) -> Mutation<'gc>
```

--------------------------------

### Checking Linked Libraries

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/configuration.md

Command to inspect the dynamic libraries linked by a shared object on Linux.

```bash
ldd target/release/libcapy.so
```

--------------------------------

### Trace Derive Usage

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of deriving the Trace trait for a struct.

```rust
#[derive(Trace)]
pub struct MyStruct<'gc> {
    field1: Gc<'gc, SomeType>,
    field2: Value<'gc>,
    non_gc_field: i64,
}
```

--------------------------------

### CPS Conversion Example: 'car' operation

Source: https://github.com/playx18/capyscheme/blob/main/docs/IMPLEMENTATION.md

Illustrates the rough expansion of a 'car' operation during CPS conversion, showing the handling of type checking and potential errors.

```scheme
        letk cold (h) not_pair () = assertion_violation(cps, src, op, "not a pair", &[x], h) in
        letk (h) k () = {
            let x = #%car (x) in
            continue ret(x)
        } in
        letk (h) check_pair_typecode () =  {
            let tc8 = #% %typecode8 (h, x) in
            let pair_typecode = #% u8= (h, tc8, Value::new(TypeCode8::PAIR.bits())) in
            if pair_typetypecode => k | not_pair
        } in

        let is_immediate = #% immediate? (h, x) @ src;
        if is_immediate => not_pair | check_pair_typecode

```

--------------------------------

### Custom IntoValue Implementation

Source: https://github.com/playx18/capyscheme/blob/main/_autodocs/types.md

Example of a custom implementation for the `IntoValue` trait.

```rust
impl<'gc> IntoValue<'gc> for MyType {
    fn into_value(self, ctx: Context<'gc>) -> Value<'gc> {
        // Conversion logic
    }
}
```