release 0.1.0
This commit is contained in:
rus07tam
commit
30d94536a9
90 changed files with 7722 additions and 0 deletions
329
README.md
Normal file
329
README.md
Normal file
|
|
@ -0,0 +1,329 @@
|
|||
# OWA-RS
|
||||
|
||||
A Lisp-inspired programming language written in Rust. This is a personal learning project, so expect rough edges and experimental design.
|
||||
|
||||
## Content
|
||||
|
||||
- [OWA-RS](#owa-rs)
|
||||
- [Content](#content)
|
||||
- [Overview](#overview)
|
||||
- [Syntax 📝](#syntax-)
|
||||
- [Literals](#literals)
|
||||
- [Collections](#collections)
|
||||
- [Special Forms](#special-forms)
|
||||
- [Comments](#comments)
|
||||
- [Annotations](#annotations)
|
||||
- [Example](#example)
|
||||
- [Quick Start 🛠️](#quick-start-️)
|
||||
- [Requirements](#requirements)
|
||||
- [Build](#build)
|
||||
- [Run a file](#run-a-file)
|
||||
- [Run directly without owu](#run-directly-without-owu)
|
||||
- [Flags](#flags)
|
||||
- [Architecture 🏗️](#architecture-️)
|
||||
- [Rust core](#rust-core)
|
||||
- [Modular standard library](#modular-standard-library)
|
||||
- [Built-in API 🔧](#built-in-api-)
|
||||
- [Core operations](#core-operations)
|
||||
- [Built-in namespaces](#built-in-namespaces)
|
||||
- [Standard Library 📚](#standard-library-)
|
||||
- [Core Library (`modules/core/`)](#core-library-modulescore)
|
||||
- [Standard Library (`modules/std/`)](#standard-library-modulesstd)
|
||||
- [owu (`modules/owu/`)](#owu-modulesowu)
|
||||
- [Performance ⚡](#performance-)
|
||||
- [Examples 🌟](#examples-)
|
||||
- [Hello World](#hello-world)
|
||||
- [Using Functions from Core](#using-functions-from-core)
|
||||
- [Working with Collections](#working-with-collections)
|
||||
- [Development 🛠️](#development-️)
|
||||
- [Running Tests](#running-tests)
|
||||
- [Building Documentation](#building-documentation)
|
||||
- [TODOs 📋](#todos-)
|
||||
- [High Priority](#high-priority)
|
||||
- [Medium Priority](#medium-priority)
|
||||
- [Lower Priority](#lower-priority)
|
||||
- [Completed](#completed)
|
||||
- [Contributing 🤝](#contributing-)
|
||||
- [License 📄](#license-)
|
||||
|
||||
## Overview
|
||||
|
||||
OWA-RS is designed as a lightweight Lisp-like interpreter with:
|
||||
|
||||
- a small Rust runtime,
|
||||
- a modular standard library,
|
||||
- a simple CLI wrapper (owu),
|
||||
- persistent immutable collections via `rpds`.
|
||||
|
||||
> ⚠️ This is a **personal project** for learning and experimentation. It's my very first Rust project, so expect some rough edges. Use at your own risk!
|
||||
|
||||
## Syntax 📝
|
||||
|
||||
OWA-RS uses a familiar Lisp-style syntax with nested expressions.
|
||||
|
||||
### Literals
|
||||
|
||||
- Integers: `42`, `-7`
|
||||
- Floats: `3.14`, `-0.5`
|
||||
- Strings: `"hello world"`
|
||||
- Keywords: `:key`, `:value`
|
||||
- Symbols: `variable-name`, `function?`
|
||||
|
||||
### Collections
|
||||
|
||||
- Lists / Calls: `(function arg1 arg2)`
|
||||
- Vectors: `[1 2 3]`
|
||||
- Maps: `{:key "value" :other 42}`
|
||||
- Sets: `#{"a" "b" "c"}`
|
||||
|
||||
### Special Forms
|
||||
|
||||
- Lambdas: `(lambda [args] body)`
|
||||
- Macros: `(macro [args] body)`
|
||||
- Quotes: `'expression`
|
||||
- Unquotes: `$expression`
|
||||
|
||||
### Comments
|
||||
|
||||
Comments start with `;;` and continue to the end of the line.
|
||||
|
||||
### Annotations
|
||||
|
||||
Annotations are placed in angle brackets (`<annotation>value`) and can contain any value that will be computedduring linting (⚠️ currently not implemented).
|
||||
|
||||
### Example
|
||||
|
||||
```owa
|
||||
(seq
|
||||
;; Define a function
|
||||
(def greet (lambda [name]
|
||||
(str.concat "Hello, " name "!")))
|
||||
|
||||
;; Call it
|
||||
(trace (greet "World")))
|
||||
```
|
||||
|
||||
## Quick Start 🛠️
|
||||
|
||||
### Requirements
|
||||
|
||||
- Rust 1.70+ (for building from source)
|
||||
- Cargo
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
git clone https://github.com/RuJect/owa-rs.git
|
||||
cd owa-rs
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
### Run a file
|
||||
|
||||
```bash
|
||||
./target/release/owa-rs run hello.owa
|
||||
```
|
||||
|
||||
### Run directly without owu
|
||||
|
||||
```bash
|
||||
./target/release/owa-rs --no-owu hello.owa
|
||||
```
|
||||
|
||||
### Flags
|
||||
|
||||
When running via owu, these flags are available:
|
||||
|
||||
- `--no-builtins`: skip Rust built-ins
|
||||
- `--no-core`: skip loading core library
|
||||
- `--no-std`: skip loading standard library
|
||||
- `--debug`: enable debug mode
|
||||
- `--test`: run in test mode
|
||||
|
||||
## Architecture 🏗️
|
||||
|
||||
OWA-RS follows a **Parse → Interpret** pipeline with modular design:
|
||||
|
||||
### Rust core
|
||||
|
||||
- `src/parser/`: source code → AST
|
||||
- `src/core/interpreter.rs`: evaluates AST nodes
|
||||
- `src/core/scope.rs`: manages variables and closures
|
||||
- `src/builtins/`: runtime primitives and host operations
|
||||
|
||||
### Modular standard library
|
||||
|
||||
- `modules/core/`: core language utilities, types, math, error handling, loops, tests
|
||||
- `modules/std/`: higher-level helpers such as `path` and `platform`
|
||||
- `modules/owu/`: command-line interface and `run` command support
|
||||
|
||||
The runtime stays intentionally small, while higher-level language features live in library code.
|
||||
|
||||
## Built-in API 🔧
|
||||
|
||||
OWA-RS follows a **minimalist principle** for Rust built-ins: the runtime only implements fundamental primitives and avoids domain/application logic. The result is a small, focused runtime with powerful libraries built on top.
|
||||
|
||||
### Core operations
|
||||
|
||||
- Language: `def`, `lambda`, `macro`, `seq`, `trace`, `apply`, `lookup`, `include`
|
||||
- Scope: `scope`, `set!`, `unset!`, `exec`
|
||||
- Type inspection: `typeof`, `cmp`
|
||||
- Flow: `return`, `break`, `continue` (via `flow` namespace)
|
||||
- Errors: `throw`, `catch` (via `errors` namespace)
|
||||
|
||||
### Built-in namespaces
|
||||
|
||||
- `math`: arithmetic and numeric helpers
|
||||
- `str`: string construction and serialization
|
||||
- `vec`: vector creation and folding
|
||||
- `map`: maps and lookup
|
||||
- `set`: set operations
|
||||
- `cond`: conditional helpers like `if-eq` and `match`
|
||||
- `platform`: environment, CLI parsing, debug flags
|
||||
|
||||
## Standard Library 📚
|
||||
|
||||
The standard library is organized in modules:
|
||||
|
||||
### Core Library (`modules/core/`)
|
||||
|
||||
Essential functionality available by default when running through owu:
|
||||
|
||||
- `assert.owa`: Assertion utilities for testing
|
||||
- `types/`: Type checking and predicates, including:
|
||||
- `main.owa`: Core type utilities and predicates
|
||||
- `bool.owa`, `str.owa`, `vec.owa`, `map.owa`, `set.owa`, `null.owa`, `option.owa`: Type-specific operations
|
||||
- `cmp.owa`: Comparison operations
|
||||
- `math.owa`: Arithmetic operations
|
||||
- `error.owa`: Error handling
|
||||
- `loop.owa`: Looping constructs
|
||||
- `test.owa`: Testing framework
|
||||
|
||||
### Standard Library (`modules/std/`)
|
||||
|
||||
Additional utilities:
|
||||
|
||||
- `platform.owa`: Platform-specific operations
|
||||
|
||||
### owu (`modules/owu/`)
|
||||
|
||||
The OWA Utility tool:
|
||||
|
||||
- `cli/`: Command-line interface framework
|
||||
- `cli/run.owa`: The `run` command handler
|
||||
|
||||
## Performance ⚡
|
||||
|
||||
OWA-RS is a tree-walking interpreter with reasonable performance for its simplicity. Rust's persistent data structures (via rpds) provide efficient immutable collections.
|
||||
|
||||
For performance-critical workloads, consider:
|
||||
|
||||
- Writing hot paths in Rust as built-ins
|
||||
- Avoiding deeply nested function calls
|
||||
- Using tail recursion where possible
|
||||
|
||||
See `benchmarks/` for sample performance characteristics.
|
||||
|
||||
## Examples 🌟
|
||||
|
||||
### Hello World
|
||||
|
||||
```owa
|
||||
(trace "Hello, OWA-RS!")
|
||||
```
|
||||
|
||||
### Using Functions from Core
|
||||
|
||||
```owa
|
||||
(def fib (lambda [n]
|
||||
(if (>= n 2)
|
||||
(+ (fib (- n 1)) (fib (- n 2)))
|
||||
n)))
|
||||
|
||||
(trace (fib 10))
|
||||
```
|
||||
|
||||
Run with: `./target/release/owa-rs run fib.owa`
|
||||
|
||||
### Working with Collections
|
||||
|
||||
```owa
|
||||
(def numbers [1 2 3 4 5])
|
||||
(trace (vec.len numbers))
|
||||
(trace (vec.first numbers))
|
||||
|
||||
(def config {:name "OWA" :version "0.1.0"})
|
||||
(trace (map.get config :name))
|
||||
```
|
||||
|
||||
## Development 🛠️
|
||||
|
||||
### Running Tests
|
||||
|
||||
The core library has a built-in testing framework:
|
||||
|
||||
```bash
|
||||
./target/release/owa-rs run --test modules/core/tests/main.owa
|
||||
```
|
||||
|
||||
### Building Documentation
|
||||
|
||||
To understand the codebase:
|
||||
|
||||
- `src/core/interpreter.rs` - Main evaluation logic
|
||||
- `src/builtins/` - Rust built-in implementations
|
||||
- `modules/core/` - OWA standard library code
|
||||
- `modules/owu/cli/` - Command-line interface implementation
|
||||
|
||||
## TODOs 📋
|
||||
|
||||
### High Priority
|
||||
|
||||
- [ ] Add proper error reporting with location information
|
||||
- [ ] Improve debugging/tracing utilities
|
||||
- [ ] Add REPL mode for interactive development
|
||||
- [ ] Implement tail call optimization
|
||||
|
||||
### Medium Priority
|
||||
|
||||
- [ ] Pattern matching enhancements
|
||||
- [x] Destructuring in set!/def
|
||||
- [ ] More comprehensive std library
|
||||
- [ ] Package manager / module repository
|
||||
- [ ] Performance profiling tools
|
||||
|
||||
### Lower Priority
|
||||
|
||||
- [ ] Concurrency support
|
||||
- [x] FFI (Foreign Function Interface)
|
||||
- [ ] File system operations (fs module)
|
||||
- [ ] Random number generation
|
||||
- [ ] Compilation to bytecode
|
||||
- [ ] Lint phase
|
||||
|
||||
### Completed
|
||||
|
||||
- [x] Annotations
|
||||
- [x] Separate core and std libraries
|
||||
- [x] CLI framework with commands
|
||||
- [x] Testing framework
|
||||
- [x] Error handling macros
|
||||
|
||||
## Contributing 🤝
|
||||
|
||||
This is a learning project exploring language design and implementation. Contributions are welcome!
|
||||
|
||||
Areas where help is appreciated:
|
||||
|
||||
- Standard library expansion
|
||||
- Bug fixes and optimizations
|
||||
- Documentation and examples
|
||||
- Testing and benchmarking
|
||||
|
||||
## License 📄
|
||||
|
||||
Unlicense License - see LICENSE file.
|
||||
|
||||
---
|
||||
|
||||
Made with ❤️ and lots of ☕ as a Rust learning project!
|
||||
Loading…
Add table
Add a link
Reference in a new issue