# Ruchy Language Features - Complete Reference

## Table of Contents
- [Language Features](#language-features)
- [CLI Commands](#cli-commands)
- [WASM Support](#wasm-support)
- [Notebook System](#notebook-system)
- [Testing Framework](#testing-framework)
- [Quality Engineering](#quality-engineering)
- [Standard Library](#standard-library)

## Language Features

### Core Syntax
```ruchy
// Variables and Constants
let x = 42
let mut y = 10
const PI = 3.14159

// Functions
fun add(a, b) {
    return a + b
}

// Fat arrow functions
let double = x => x * 2
let sum = (a, b) => a + b

// Async functions
async fun fetch_data(url) {
    let response = await http.get(url)
    return response.data
}
```

### Type System
```ruchy
// Type annotations
let x: Int = 42
let name: String = "Ruchy"
let numbers: Vec<Int> = [1, 2, 3]
let maybe: Option<String> = Some("value")

// Generic functions
fun identity<T>(x: T) -> T {
    return x
}

// Type aliases
type Point = { x: Float, y: Float }
type Result<T> = Option<T>
```

### Control Flow
```ruchy
// If expressions
let result = if x > 10 { "big" } else { "small" }

// Pattern matching
match value {
    Some(x) => println(f"Got {x}"),
    None => println("Nothing"),
    _ => println("Unknown")
}

// Pattern guards
match x {
    n if n > 0 => "positive",
    n if n < 0 => "negative",
    _ => "zero"
}

// Loops
for i in 0..10 {
    println(i)
}

while condition {
    // body
}

loop {
    if done { break }
}
```

### Error Handling
```ruchy
// Try-catch-finally
try {
    risky_operation()
} catch (e) {
    println(f"Error: {e}")
} finally {
    cleanup()
}

// Result type
fun divide(a, b) -> Result<Float> {
    if b == 0 {
        return Err("Division by zero")
    }
    return Ok(a / b)
}

// Panic for unrecoverable errors
panic!("This should never happen")
```

### Data Structures
```ruchy
// Arrays
let arr = [1, 2, 3, 4, 5]
let first = arr[0]
let slice = arr[1..3]

// Tuples
let point = (10, 20)
let (x, y) = point  // Destructuring

// Objects/Records
let person = {
    name: "Alice",
    age: 30,
    greet: fun() { println(f"Hello, I'm {this.name}") }
}

// DataFrames (with dataframe feature)
let df = df![
    "name" => ["Alice", "Bob"],
    "age" => [30, 25]
]
```

### Functional Programming
```ruchy
// Higher-order functions
let doubled = [1, 2, 3].map(x => x * 2)
let evens = [1, 2, 3, 4].filter(x => x % 2 == 0)
let sum = [1, 2, 3].reduce(0, (acc, x) => acc + x)

// Pipeline operator
let result = data
    |> filter(x => x > 0)
    |> map(x => x * 2)
    |> reduce(0, +)

// Partial application
let add5 = add(5, _)
let result = add5(10)  // 15

// Function composition
let process = compose(validate, transform, save)
```

### String Interpolation
```ruchy
let name = "World"
let greeting = f"Hello, {name}!"
let calculation = f"2 + 2 = {2 + 2}"

// Format specifiers
let pi = 3.14159
let formatted = f"Pi: {pi:.2}"  // "Pi: 3.14"
```

### Module System
```ruchy
// Importing modules
import std.io
import math.{sin, cos, PI}
from collections import HashMap

// Exporting from modules
export fun public_function() { }
export let constant = 42
export { helper1, helper2 }

// Module aliases
import very.long.module.path as short
```

### Macros and Metaprogramming
```ruchy
// DataFrame macro
let data = df![
    "column1" => [1, 2, 3],
    "column2" => ["a", "b", "c"]
]

// Custom macros (coming soon)
macro_rules! assert_eq {
    ($left, $right) => {
        if $left != $right {
            panic!(f"Assertion failed: {$left} != {$right}")
        }
    }
}
```

## CLI Commands

### Core Commands
```bash
# REPL - Interactive shell
ruchy repl
  --verbose    # Enable verbose output
  --quiet      # Suppress output

# Run - Execute scripts
ruchy run script.ruchy
  --verbose    # Show execution details

# Format - Code formatting
ruchy fmt path/
  --check      # Check without modifying
```

### WebAssembly Commands
```bash
# Compile to WASM
ruchy wasm compile input.ruchy
  -o, --output <file>    # Output file (default: input.wasm)
  --optimize             # Enable optimizations
  --validate             # Validate output (default: true)

# Validate WASM module
ruchy wasm validate module.wasm

# Run WASM module (coming soon)
ruchy wasm run module.wasm [args...]
```

### Notebook Commands
```bash
# Start notebook server
ruchy notebook serve
  -p, --port <port>      # Port number (default: 8888)
  --host <host>          # Host address (default: 127.0.0.1)

# Test notebooks
ruchy notebook test notebook.ipynb
  --coverage             # Generate coverage report
  --format <fmt>         # Output format: text, json, html

# Convert notebooks
ruchy notebook convert input.ipynb output.html
  --format <fmt>         # Output format: html, markdown, script
```

### Testing Commands
```bash
# Run tests
ruchy test run path/
  --coverage             # Generate coverage report
  --parallel             # Run tests in parallel
  --filter <pattern>     # Filter tests by name

# Generate test report
ruchy test report
  --format <fmt>         # Format: json, html, junit
  -o, --output <file>    # Output file
```

## WASM Support

### Compilation Features
- **Deterministic compilation**: Same source always produces identical bytecode
- **Validation**: Built-in wasmparser validation
- **Optimization**: Optional optimization passes
- **Security**: Sandboxed execution environment

### Supported WASM Features
- Functions with parameters and return values
- Local variables
- Basic arithmetic operations
- Control flow (if/else, loops)
- Memory operations
- Module exports

### Example WASM Compilation
```ruchy
// input.ruchy
fun fibonacci(n) {
    if n <= 1 {
        return n
    }
    return fibonacci(n - 1) + fibonacci(n - 2)
}

fun main() {
    return fibonacci(10)
}
```

```bash
# Compile to WASM
ruchy wasm compile input.ruchy -o fib.wasm --optimize

# Validate the module
ruchy wasm validate fib.wasm
# Output: ✓ WASM module is valid
```

## Notebook System

### Features
- **Jupyter-compatible**: Works with .ipynb files
- **Web interface**: Professional notebook UI
- **Cell execution**: Run cells individually or all at once
- **State management**: Persistent state between cells
- **Testing framework**: Comprehensive notebook testing

### Notebook Testing
```bash
# Test a notebook
ruchy notebook test my_notebook.ipynb --coverage

# Output:
# ✓ Cell 1: Passed
# ✓ Cell 2: Passed  
# ✓ Cell 3: Passed
# Coverage: 85%
```

### Testing Framework Features
- **Golden file testing**: Compare against expected outputs
- **Property-based testing**: Random input generation
- **Differential testing**: Compare implementations
- **Mutation testing**: Code mutation detection
- **Performance testing**: Regression detection

## Testing Framework

### Test Types
1. **Unit Tests**: Function-level testing
2. **Integration Tests**: Component interaction
3. **Property Tests**: Invariant verification
4. **Fuzz Tests**: Random input testing
5. **Acceptance Tests**: End-to-end validation

### Property Testing
```rust
// Example property test
proptest! {
    #[test]
    fn prop_compilation_deterministic(x in 0i32..100) {
        let source = format!("fun main() {{ return {} }}", x);
        let result1 = compile(&source);
        let result2 = compile(&source);
        prop_assert_eq!(result1, result2);
    }
}
```

### Fuzz Testing
```bash
# Run fuzz tests
cargo fuzz run wasm_comprehensive
cargo fuzz run wasm_security  
cargo fuzz run wasm_stress
```

## Quality Engineering

### PMAT Integration
- **TDG Score**: Technical Debt Grading (must be A- or higher)
- **Complexity Limits**: All functions <10 cyclomatic complexity
- **SATD Detection**: Zero tolerance for technical debt comments
- **Documentation Coverage**: >70% for public APIs

### Quality Gates
```bash
# Check quality before commit
pmat tdg . --min-grade A-
pmat analyze complexity --max-cyclomatic 10
pmat analyze satd --fail-on-violation
```

### Continuous Monitoring
```bash
# Start real-time dashboard
pmat tdg dashboard --port 8080 --open
```

## Standard Library

### Core Modules
- **std.io**: Input/output operations
- **std.fs**: File system operations
- **std.net**: Networking
- **std.math**: Mathematical functions
- **std.collections**: Data structures
- **std.string**: String utilities
- **std.regex**: Regular expressions
- **std.json**: JSON parsing/serialization

### Math Functions
```ruchy
import math

let x = math.sqrt(16)      // 4
let y = math.pow(2, 8)      // 256
let z = math.sin(math.PI)   // ~0
let a = math.abs(-42)       // 42
let b = math.floor(3.7)     // 3
let c = math.ceil(3.2)      // 4
let d = math.round(3.5)     // 4
let e = math.min(5, 3)      // 3
let f = math.max(5, 3)      // 5
```

### String Methods
```ruchy
let s = "Hello, World!"

s.len()                    // 13
s.to_upper()              // "HELLO, WORLD!"
s.to_lower()              // "hello, world!"
s.trim()                  // Remove whitespace
s.split(",")              // ["Hello", " World!"]
s.replace("World", "Ruchy") // "Hello, Ruchy!"
s.contains("World")       // true
s.starts_with("Hello")    // true
s.ends_with("!")          // true
s[0..5]                   // "Hello" (slicing)
```

### Collection Methods
```ruchy
let arr = [1, 2, 3, 4, 5]

arr.len()                 // 5
arr.push(6)              // [1, 2, 3, 4, 5, 6]
arr.pop()                // 5, arr = [1, 2, 3, 4]
arr.first()              // 1
arr.last()               // 5
arr.reverse()            // [5, 4, 3, 2, 1]
arr.sort()               // [1, 2, 3, 4, 5]
arr.contains(3)          // true
arr.index_of(3)          // 2
arr.slice(1, 3)          // [2, 3]
```

### Type Conversions
```ruchy
// String conversions
let s = 42.to_string()           // "42"
let n = "42".parse_int()         // 42
let f = "3.14".parse_float()     // 3.14

// Numeric conversions
let i = 3.14.to_int()            // 3
let f = 42.to_float()            // 42.0

// Boolean conversions
let b = 1.to_bool()              // true
let b = 0.to_bool()              // false
```

## Configuration

### Project Configuration (ruchy.toml)
```toml
[project]
name = "my-project"
version = "0.1.0"
authors = ["Your Name"]

[dependencies]
std = "1.0"
dataframe = { version = "0.5", optional = true }

[features]
default = ["batteries-included"]
batteries-included = ["dataframe", "notebook", "wasm-compile"]
minimal = []

[quality]
max-complexity = 10
min-coverage = 80
tdg-min-grade = "A-"
```

### Environment Variables
```bash
RUCHY_PATH=/usr/local/lib/ruchy    # Module search path
RUCHY_HOME=~/.ruchy                # Configuration directory
RUCHY_DEBUG=1                       # Enable debug output
RUCHY_COLORS=1                      # Enable colored output
```

## Platform Support

### Operating Systems
- Linux (x86_64, aarch64)
- macOS (x86_64, arm64)
- Windows (x86_64)
- FreeBSD (x86_64)

### Architectures
- x86_64
- aarch64/arm64
- armv7
- wasm32

### Minimum Requirements
- Rust 1.75+
- 2GB RAM
- 100MB disk space

## Performance

### Benchmarks
- **Parser**: ~1M lines/second
- **Type checking**: ~500K lines/second
- **Code generation**: ~300K lines/second
- **WASM compilation**: ~100K lines/second

### Optimization Levels
- **Debug**: No optimizations, full debug info
- **Release**: Standard optimizations
- **Release with LTO**: Link-time optimization
- **Release with PGO**: Profile-guided optimization

## Integration

### Editor Support
- **VS Code**: Official extension available
- **Vim/Neovim**: LSP support
- **Emacs**: LSP support
- **IntelliJ**: Plugin in development

### Build Systems
- **Cargo**: Native integration
- **Make**: Makefile templates
- **CMake**: CMake modules
- **Bazel**: Build rules

### CI/CD
- **GitHub Actions**: Workflows provided
- **GitLab CI**: Pipeline templates
- **Jenkins**: Jenkinsfile examples
- **CircleCI**: Config examples

## Resources

### Documentation
- [API Documentation](https://docs.rs/ruchy)
- [Language Specification](docs/SPECIFICATION.md)
- [Standard Library Reference](docs/STANDARD_LIBRARY_SPEC.md)
- [Tutorial](https://ruchy-lang.org/tutorial)

### Community
- [GitHub Repository](https://github.com/paiml/ruchy)
- [Discord Server](https://discord.gg/ruchy)
- [Forum](https://forum.ruchy-lang.org)
- [Stack Overflow Tag](https://stackoverflow.com/questions/tagged/ruchy)

### Learning Resources
- [Ruchy by Example](https://ruchy-by-example.org)
- [The Ruchy Book](https://book.ruchy-lang.org)
- [Video Tutorials](https://youtube.com/ruchy-lang)
- [Interactive Playground](https://play.ruchy-lang.org)

---

*Last updated: September 2025 - Version 3.0.3*