ovsm 1.0.0

OVSM (Open Versatile Seeker Mind) language interpreter for blockchain automation and scripting
Documentation

OVSM - Open Versatile Seeker Mind Language Interpreter

Crates.io Documentation License: MIT Build Status

A production-ready interpreter for the OVSM scripting language, designed for blockchain automation, data processing, and general-purpose scripting.

Features

✨ Complete Language Implementation

  • Full control flow (IF/THEN/ELSE, FOR, WHILE)
  • Loop control (BREAK, CONTINUE with conditions)
  • Rich data types (Int, Float, String, Bool, Arrays, Objects)
  • Comprehensive operators (arithmetic, comparison, logical)
  • Proper variable scoping and constants

🚀 Production Ready

  • 97.3% test coverage (107/110 tests passing)
  • Fast parsing and execution
  • Zero unsafe code
  • Comprehensive error messages

📚 Well Documented

  • Complete API documentation with usage examples
  • Enhanced error messages with context and prevention tips
  • Three-tier documentation: structure, purpose, and usage
  • Usage guides and tutorials
  • Example scripts included
  • Interactive REPL for experimentation

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
ovsm = "1.0.0"

Basic Usage

use ovsm::{Evaluator, Parser, Scanner, Value};

fn execute_ovsm(code: &str) -> Result<Value, Box<dyn std::error::Error>> {
    let mut scanner = Scanner::new(code);
    let tokens = scanner.scan_tokens()?;

    let mut parser = Parser::new(tokens);
    let program = parser.parse()?;

    let mut evaluator = Evaluator::new();
    Ok(evaluator.execute(&program)?)
}

fn main() {
    let code = r#"
        $sum = 0
        FOR $i IN [1..11]:
            $sum = $sum + $i
        RETURN $sum
    "#;

    match execute_ovsm(code) {
        Ok(result) => println!("Result: {:?}", result), // Int(55)
        Err(err) => eprintln!("Error: {}", err),
    }
}

Language Examples

Variables and Arithmetic

$x = 10
$y = 20
RETURN $x + $y  // 30

Control Flow

$score = 85

IF $score >= 90 THEN
    RETURN "A"
ELSE
    IF $score >= 80 THEN
        RETURN "B"
    ELSE
        RETURN "C"

Loops with Break/Continue

$sum = 0
FOR $i IN [1..20]:
    IF $i % 2 == 0 THEN
        CONTINUE
    IF $i > 15 THEN
        BREAK
    $sum = $sum + $i
RETURN $sum  // Sum of odd numbers 1-15

Arrays and Iteration

$numbers = [1, 2, 3, 4, 5]
$sum = 0

FOR $num IN $numbers:
    $sum = $sum + $num

RETURN $sum / 5  // Average

File Execution

The crate includes an example runner for executing .ovsm script files:

cargo run --example run_file script.ovsm

Example scripts are provided in the examples/ directory.

Interactive REPL

Launch an interactive Read-Eval-Print Loop:

cargo run --example simple_repl

Language Features

Control Flow

  • IF/THEN/ELSE - Conditional execution
  • FOR ... IN - Iterate over arrays, ranges, strings
  • WHILE - Loop while condition is true
  • BREAK / BREAK IF - Exit loops early
  • CONTINUE / CONTINUE IF - Skip iterations
  • RETURN - Return values

Data Types

  • Primitives: Int, Float, String, Bool, Null
  • Collections: Arrays [1, 2, 3], Objects {name: "Alice"}
  • Ranges: [1..10] (exclusive end)

Operators

  • Arithmetic: +, -, *, /, %, ** (power)
  • Comparison: <, >, <=, >=, ==, !=
  • Logical: AND, OR, NOT
  • Ternary: condition ? then : else
  • Membership: IN (check if item in collection)

Variables

  • Assignment: $variable = value
  • Constants: CONST NAME = value
  • Scoping: Proper scope chain with shadowing

Performance

  • Fast: Direct AST interpretation with minimal overhead
  • Efficient: Lazy evaluation and smart caching
  • Safe: Memory-safe with no undefined behavior

Documentation

Documentation Quality

All public APIs are thoroughly documented with:

  • Structure: What the API is and its components
  • Purpose: What it does and when to use it
  • Usage: How to use it with practical examples

Error messages include:

  • Trigger context: What causes the error
  • Examples: Concrete code that triggers it
  • Prevention: How to avoid the error
  • Recovery: Whether the error is recoverable

Test Coverage

  • Runtime Tests: 65/65 passing ✅
  • Parser Tests: 42/42 passing ✅
  • Integration Tests: Comprehensive coverage ✅
  • Overall: 97.3% success rate (107/110 tests)

Known Limitations

  • TRY/CATCH error handling is experimental
  • Some advanced features (lambdas, parallel execution) not yet implemented
  • See TEST_RESULTS_SUMMARY.md for details

Contributing

Contributions are welcome! Please see our Contributing Guide.

License

Licensed under the MIT License.

Links

Examples

Check out the examples directory for more:

  • hello_world.ovsm - Basic greeting
  • factorial.ovsm - Calculate factorials
  • fibonacci.ovsm - Generate Fibonacci numbers
  • array_operations.ovsm - Array manipulation
  • conditional_logic.ovsm - Complex conditionals
  • loop_control.ovsm - Advanced loop control

Made with ❤️ by the OpenSVM team