diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 239 |
1 files changed, 205 insertions, 34 deletions
diff --git a/README.md b/README.md index 3e5ef9a..fbdffbc 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,222 @@ # Pry Programming Language -Pry is a simple, elegant, statically typed and compiled programming language implemented in Zig, with support for variables, control flow, functions, and code generation using LLVM. +Pry is a simple, statically-typed programming language that compiles to native code via LLVM. It features a minimal C-like syntax with basic functional programming elements. -## Building and Running +## Features -1. Ensure you have Zig and LLVM installed on your system. -2. Run the compiler on an example file: - ``` - zig build run -- examples/8.pry - ``` -3. Link the generated object file to create an executable: - ``` - cc output.o +- **Static typing** with explicit type annotations +- **Basic functions** with parameters and return types +- **Structs** with field access +- **Manual memory management** via C library functions +- **C interoperability** through extern declarations +- **Simple import system** for code organization +- **LLVM backend** for native code generation + +## Quick Start + +### Prerequisites + +- Zig (latest stable version) +- LLVM development libraries +- A C compiler (gcc/clang) for linking + +### Using with Nix + +If you have Nix with flakes enabled: + +```bash +# Enter development shell with all dependencies +nix develop + +# Or run directly +nix develop -c zig build run -- examples/1.pry +``` + +The flake provides Zig, ZLS (Zig Language Server), LLVM, and debugging tools. + +### Building and Running + +1. **Compile a Pry program:** + ```bash + zig build run -- examples/1.pry ``` -4. Run the executable: + +2. **Link and create executable:** + ```bash + cc output.o -o program ``` - ./a.out + +3. **Run the program:** + ```bash + ./program ``` -## Language Features +## Language Overview -- **Variables and Declarations**: Uses `let` for variable declaration. -- **Control Flow**: Supports `if` and `while` statements. -- **Functions**: Supports function declarations with parameters and return types. -- **Expressions**: Includes additive, multiplicative, equality, and unary expressions. -- **Code Generation with LLVM**: Translates AST to LLVM IR and generates object files for native execution. -- **Import System**: Allows importing libraries and other Pry files. +### Basic Syntax -## Example Program +```pry +// Hello World +import "!stdlib.pry"; -```js let main = () => i64 { - let fib = (n: i64) => i64 { - if n == 0 { - return 0; - }; - if n == 1 { - return 1; - }; - return fib(n-2) + fib(n-1); - }; + printf("Hello, World!\n"); + return 0; +}; +``` + +### Variables and Types + +```pry +let x = 42; // i64 integer +let name = "Alice"; // String literal (*i8) +let flag = true; // Boolean +``` + +**Built-in types:** +- `i64`, `i32`, `i8` - Signed integers +- `bool` - Boolean values +- `*T` - Pointers to type T +- `void` - Unit type - let result = fib(30); - print(result); - return result; +### Functions + +```pry +// Function with explicit parameter types +let add = (a: i64, b: i64) => i64 { + return a + b; +}; + +// Recursive function +let fib = (n: i64) => i64 { + if n == 0 { + return 0; + }; + if n == 1 { + return 1; + }; + return fib(n-2) + fib(n-1); }; ``` + +### Control Flow + +```pry +// If statements (no else yet) +if condition { + // statements +}; + +// While loops +let i = 0; +while i < 10 { + printf("%d\n", i); + i = i + 1; +}; ``` -Output: 832040 + +### Structs + +```pry +// Define a struct type +let Point = struct { + x: i64, + y: i64 +}; + +let main = () => i64 { + let p = Point{}; // Empty initialization + p.x = 10; // Field assignment + p.y = 20; + return 0; +}; ``` + +### Memory Management + +```pry +// Use C library functions for memory management +extern malloc = (i64) => *void; +extern free = (*void) => void; + +let main = () => i64 { + let ptr = cast(*i64, malloc(8)); + *ptr = 42; + free(cast(*void, ptr)); + return 0; +}; +``` + +### C Interoperability + +```pry +// Declare external C functions +extern printf = (*i8, varargs) => void; +extern putchar = (i64) => i64; + +let main = () => i64 { + putchar(72); // 'H' + putchar(105); // 'i' + putchar(10); // '\n' + return 0; +}; +``` + +## Current Limitations + +Pry is a work-in-progress language with several limitations: + +- No `else` clauses for if statements +- No `for` loops (only `while`) +- No arrays (use pointers and manual indexing) +- No string manipulation beyond C functions +- No generics or templates +- No pattern matching +- Limited error handling +- Basic type system + +## Examples + +The `examples/` directory contains test programs showing: + +- Basic I/O (`examples/1.pry`) +- Recursive functions (`examples/8.pry`) +- Memory management (`examples/20.pry`) +- Struct usage (`examples/22.pry`, `examples/24.pry`) +- C library integration (`examples/15.pry`) + +Try running: +```bash +zig build run -- examples/8.pry # Fibonacci sequence +zig build run -- examples/1.pry # Hello world +zig build run -- examples/20.pry # Array manipulation +``` + +## Standard Library + +The minimal standard library (`std/stdlib.pry`) provides: + +- `printf` - C printf wrapper +- `strcmp` - String comparison +- `isdigit`, `isalpha` - Character classification helpers +- `assert` - Simple assertion function + +## Implementation + +Pry is currently implemented in Zig with plans for self-hosting: + +- `src/main.zig` - Compiler entry point +- `src/tokenizer.zig` - Lexical analysis +- `src/parser.zig` - Syntax analysis and AST generation +- `src/codegen.zig` - LLVM IR generation +- `src/bootstrap/` - Future self-hosted compiler (work in progress) + +The grammar is formally defined in `grammar.ebnf`. + +## Development Status + +Pry is an experimental language currently in active development. While functional for basic programs, it's not yet feature-complete. + +--- + +*Pry is a minimal systems programming language focused on simplicity and clean design.* |