omg_runtime 0.1.4

The OMG language runtime and virtual machine, providing bytecode execution, REPL, and built-in functions.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# OMG Runtime


The **OMG Runtime** is the execution engine for the OMG programming language — a personal, educational language project designed to explore the full stack of compiler and interpreter implementation.  

This crate provides:
- A **stack-based virtual machine** for executing OMG bytecode
- A **tree-walk REPL** for interactive exploration
- A **bytecode loader and function table** format
- A set of **built-in functions** for data, math, and filesystem operations
- A well-defined **error system** for reporting runtime failures

## Features


### 🎛️ Virtual Machine

- Operand stack evaluation model
- Global and local variable environments
- Function call frames (with tail call optimization)
- Exception-style error handling (`setup_except`, `raise`, `pop_block`)

### ⚙️ Instruction Set

Supports all major categories of instructions:
- **Literals**: integers, strings, booleans, `None`
- **Arithmetic & Bitwise**: `+ - * / % & | ^ << >> ~`
- **Logical & Comparison**: `== != < <= > >= and or`
- **Structures**: list/dict building, indexing, slicing, attributes
- **Control Flow**: jumps, conditional jumps, function calls, returns
- **Exceptions**: `assert`, `raise`, `setup_except`
- **I/O**: `emit` to stdout

### 🛠 Built-in Functions

Out-of-the-box helpers for everyday use:
- Conversion: `chr`, `ascii`, `hex`, `binary`
- Introspection: `length`
- Data: `freeze` (immutable dicts)
- Errors: `panic`, `raise`
- Filesystem: `read_file`, `file_exists`
- File I/O (descriptor-based): `file_open`, `file_read`, `file_write`, `file_close`
- Meta: `call_builtin`

### ⚡ REPL

Interactive interpreter for OMG source code:
- Prompts with `>>>` and supports multiline input (`...`)
- Tracks brace depth for entering whole blocks
- Preserves state across commands
- Exits cleanly with `exit` / `quit`

### 🧩 Error System

Two-layer error handling:
- **`ErrorKind`** – compact categories (for bytecode raise ops)
- **`RuntimeError`** – detailed structured errors (with `Display` messages)

Examples:
- `AssertionError`
- `TypeError("expected integer")`
- `IndexError("out of bounds")`
- `VmInvariant("stack underflow")`

## Example


```omg
;;;omg

proc greeting(name) {
    return "Hello " + name
}

emit greeting("World")

alloc xs := [1, 2, 3]
emit "length(xs) = " + length(xs)

# Assertions and loops

facts 2 + 2 == 4

alloc i := 0
loop i < 3 {
    emit "i = " + i
    i := i + 1
}
````

Compile to bytecode (`.omgb`) or run directly through the embedded interpreter.

## Using the REPL


```bash
$ cargo run
OMG Language Interpreter - REPL
Type `exit` or `quit` to leave.
>>> alloc x := 5
>>> emit x * 2
10
```

## Installation

Add to your project:

```toml
[dependencies]
omg_runtime = "0.1.2"
```

Or install the runtime directly:

```bash
cargo install omg_runtime
```

## License


Licensed under the [MIT License](../LICENSE).

## Project Status


OMG is an educational project. The runtime is stable enough to run example scripts and bytecode, but the language is not serious. Expect breaking changes as new features are added.

## Links


* [OMG Language Specification](../spec/OMG_SPEC.md)
* [Lexer Documentation](../spec/OMG_LEXER.md)
* [Parser Documentation](../spec/OMG_PARSER.md)
* [Development Guide](../spec/DEVELOPMENT.md)