ranger-compiler 2.1.70 → 3.0.4

package/README.md

@@ -1,24 +1,709 @@
-
 # Ranger cross language compiler
 
-Status: `experimental`
+**Version 3.0.4** | Status: `experimental`
+
+Ranger is a self-hosting cross-language compiler for writing portable algorithms, parsers, generators, and small tools once and compiling them to multiple target languages.
+
+It includes a compact typed language with classes, inheritance, traits, lambdas, type inference, extension methods, custom operators, and host integration through system classes.
+
+Ranger is best approached today as a compiler and language lab with practical multi-target output, not as a polished general-purpose language ecosystem.
+
+## What Ranger Is Good At
+
+- Writing one algorithm or tool and emitting several target languages from the same source
+- Building parsers, analyzers, generators, and DSL-like tooling with a small runtime surface
+- Experimenting with language design, operator templates, and code generation strategies
+- Studying a self-hosting compiler that is actively used to compile itself
+
+## Word of Warning
+
+- Ranger is still `experimental`, which means: be ready to fix bugs or add new capabilities when needed
+- Target quality varies by language and by feature area
+- The compiler is self-hosting, but the official and best-supported host is Node.js
+- Not every example in this repository works fully out of the box on every machine
+- Several examples in `gallery/` are research or showcase projects and may require extra toolchains, platform-specific commands, or manual setup
+
+If you want one sentence of positioning: Ranger is currently more convincing as a portable algorithm compiler / DSL toolchain than as a drop-in replacement for mainstream application languages.
+
+## Where To Start
+
+- `README.md` - language overview, installation, and syntax notes
+- `ai/QUICKREF.md` - fast reference for syntax and core concepts
+- `ai/INSTRUCTIONS.md` - fuller language guide for operators, templates, and compiler concepts
+- `ai/EXAMPLES.md` - short focused language examples
+- `gallery/` - larger examples and experiments such as parsers, EVG/TSX tooling, and games
+- `gallery/js_parser` - substantial parser example with benchmarks and README
+- `gallery/pdf_writer` - EVG / TSX document tooling and preview server
+- `gallery/invaders` - cross-target demo game
+
+## Compatibility Snapshot
+
+The project can target `JavaScript`, `Java`, `Go`, `Swift`, `PHP`, `C++`, `C#`, `Scala`, `Python`, `Kotlin`, and `Rust`, but support is uneven.
+
+| Area | Current expectation |
+| --- | --- |
+| Host/runtime | Node.js is the primary supported host for the compiler |
+| Self-hosting | Actively used, but full compiler generation quality is strongest in JavaScript |
+| JavaScript / ES6 | Best baseline target and most reliable place to start |
+| Go / Swift / Rust / Kotlin / C++ | Useful and increasingly capable, but expect edge cases and target-specific gaps |
+| Gallery examples | Good for understanding direction and capability, but some require manual setup or platform-specific tooling |
+
+## What's New in Version 3.0
+
+- **New File Extension** - Transitioning from `.clj` to `.rgr` for Ranger identity
+- **Simplified CLI** - Use `rgrc` command for shorter invocations
+- **VSCode Extension** - Language server with syntax highlighting (in development)
+- **CI/CD Pipeline** - Automated testing and NPM publishing
+- **Unit Test Suite** - Comprehensive test coverage with Vitest
+
+### Quick Start
+
+```bash
+# Install globally
+npm install -g ranger-compiler
+
+# Compile to JavaScript
+rgrc -l=es6 myfile.rgr -o=output.js
+
+# Compile to TypeScript
+rgrc -l=es6 -typescript myfile.rgr -o=output.ts
+
+# Compile to Python
+rgrc -l=python myfile.rgr -o=output.py
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for full version history and [PLAN_3.md](PLAN_3.md) for the roadmap.
 
-Ranger is a small self-hosting cross -language, cross -platform compiler to enable writing portable algorithms and applications.
-The language has type safety, classes, inheritance, operator overloading, lambda functions, generic traits, 
-class extensions, type inference and can integrate with host system API's using system classes. 
+---
 
 ## Host platforms and target languages
 
-The compiler is *self hosting*  which means that it has been written using the compiler itself and thus it can be hosted
+The compiler is _self hosting_ which means that it has been written using the compiler itself and thus it can be hosted
 on several platforms. At the moment the official platform is node.js, because external plugins are only available as npm packages.
 
-The target languages supported are `JavaScript`, `Java`, `Go`, `Swift`, `PHP`, `C++`, `C#` and `Scala`. The quality
-of the target translation still varies and at the moment of this writing the compiler can only be compiled fully to JavaSript
-target. However, most targets already can compile reasonably good code. 
+The target languages supported are `JavaScript`, `Java`, `Go`, `Swift`, `PHP`, `C++`, `C#`, `Scala`, `Python`, and `Rust`. The quality
+of the target translation still varies and at the moment of this writing the compiler can only be compiled fully to JavaScript
+target. However, most targets already can compile reasonably good code.
+
+## Recent Updates (December 2025)
+
+### TypeScript Parser (TSParser) Enhancements
+
+The TSParser (`gallery/ts_parser`) now supports additional JavaScript/TypeScript syntax features:
+
+**New Operators:**
+- **UpdateExpression**: `i++`, `++i`, `i--`, `--i` with proper prefix/postfix semantics
+- **Compound Assignment**: `+=`, `-=`, `*=`, `/=`, `%=` operators
+- **Computed Member Access**: Array indexing `arr[i]` now correctly sets the `computed` flag
+
+These enhancements enable the EVG ComponentEngine to evaluate for loops and dynamic array operations in TSX files.
+
+### Swift 6 Target Support
+
+The Swift 6 target (`-l=swift6`) has been significantly enhanced with the following features:
+
+- Modern Swift 6 compatible code generation
+- Simple `main()` function entry point (avoids @main conflicts with operator overloads)
+- Proper integer-to-string conversion using `String()`
+- Array operations using `.append()` instead of `.push()`
+- File I/O with `Foundation` framework integration
+- String operations: `substring`, `indexOf`, `startsWith`, `endsWith`, `contains`, `split`, `trim`
+- Optional handling with `unwrap` and `!!` operators
+- Command-line argument access
+- CRLF grapheme cluster handling for cross-platform string compatibility
+
+**Successfully compiled projects:**
+
+- ✅ JavaScript ES6+ Parser (`gallery/js_parser`) - 4500+ lines, parses and pretty-prints ES6+ code
+- ✅ Space Invaders game (`gallery/invaders`)
+
+Example compilation:
+
+```bash
+node bin/output.js myfile.rgr -l=swift6 -o=myfile.swift
+sed -i '' $'s/\r$//' myfile.swift  # Fix line endings on macOS
+swiftc myfile.swift -o myfile
+```
+
+### Rust Target Support (Preliminary)
+
+The Rust target (`-l=rust`) now has preliminary support with the following features:
+
+- Classes compiled to structs with `impl` blocks
+- Constructors as `pub fn new()` returning owned structs
+- Static factory methods
+- Instance methods with `&mut self`
+- Proper String handling with `.to_string()` for literals
+- Array operations (`push`, `itemAt`, `set`) with `Vec<T>`
+- String concatenation using `format!` macro
+- Ternary expressions as `if/else` expressions
+- Automatic `#[derive(Clone)]` for structs
+- Smart mutability detection (`let` vs `let mut`)
+
+Example compilation:
+
+```bash
+node bin/output.js myfile.rgr -l=rust -o=myfile.rs
+rustc myfile.rs -o myfile
+```
+
+### C++ Static Analysis Optimizer (New)
+
+The C++ target (`-l=cpp`) now includes a static analysis pass that automatically detects mutation patterns and generates proper C++ references. This solves a common issue where local variables assigned from member fields were incorrectly copied instead of referenced.
+
+**The Problem:**
+
+```ranger
+fn writeByte:void (b:int) {
+    def buf:buffer currentChunk.data   ; Assigned from member field
+    buffer_set buf 0 b                  ; Mutates the buffer
+}
+```
+
+Without static analysis, this would generate:
+
+```cpp
+void writeByte(int b) {
+    std::vector<uint8_t> buf = currentChunk->data;  // COPY!
+    buf[0] = static_cast<uint8_t>(b);               // Modifies copy, not original!
+}
+```
+
+**The Solution:**
+
+The static analyzer detects when:
+
+1. A local variable is assigned from a member field (e.g., `obj.field`)
+2. That variable is later mutated with in-place operations (`buffer_set`, `push`, `set`, etc.)
+
+When both conditions are met, it generates a C++ reference:
+
+```cpp
+void writeByte(int b) {
+    std::vector<uint8_t>& buf = currentChunk->data;  // REFERENCE!
+    buf[0] = static_cast<uint8_t>(b);                // Modifies original
+}
+```
+
+**Mutating Operations Detected:**
+
+| Category   | Operators                                                     |
+| ---------- | ------------------------------------------------------------- |
+| Buffer     | `buffer_set`, `int_buffer_set`, `double_buffer_set`, `*_fill` |
+| Array      | `push`, `set`, `clear`, `remove`, `removeIndex`               |
+| Dictionary | `put`                                                         |
+
+This optimization is automatically applied when compiling to C++ - no source code changes required.
+
+### HTTP Server Support (New - December 2025)
+
+Ranger now supports defining HTTP servers using **annotation-based type aliasing**. Classes marked with `@(HttpServer)` can use HTTP operators and route annotations.
+
+**Example HTTP Server:**
+
+```ranger
+Import "stdlib.rgr"
+
+class MyServer@(HttpServer) {
+    fn handleIndex@(GET "/"):void (req:HttpRequest res:HttpResponse) {
+        http_set_header res "Content-Type" "text/html"
+        http_set_status res 200
+        http_send res "<h1>Hello from Ranger!</h1>"
+    }
+    
+    fn handleEvents@(SSE "/events"):void (client:SSEClient) {
+        sse_send client "message" "Welcome!"
+    }
+}
+
+sfn main@(main):void () {
+    def server:MyServer (new MyServer())
+    start server 3000
+}
+```
+
+**Key Features:**
+
+- **Systemclass types**: `HttpRequest`, `HttpResponse`, `SSEClient`, `HttpServer`
+- **HTTP operators**: `http_get_method`, `http_get_path`, `http_set_status`, `http_set_header`, `http_send`
+- **SSE operators**: `sse_send`, `sse_is_connected`
+- **Route annotations**: `@(GET "/path")`, `@(POST "/path")`, `@(SSE "/path")`
+- **Server lifecycle**: `start server port`, `stop server`
+
+**Compilation:**
+
+```bash
+# Compile to Go
+RANGER_LIB=./compiler/Lang.rgr node bin/output.js -l=go ./myserver.rgr -d=./bin -o=myserver.go -nodecli
+
+# Run the server
+cd bin && go run myserver.go
+```
+
+Currently supports **Go** target. See `tests/fixtures/http_server.rgr` for a complete example.
+
+### EVG Document Preview Tools (New - December 2025)
+
+Ranger includes tools for creating and previewing documents using a React-like TSX syntax. The EVG (Extensible Vector Graphics) system supports multi-page documents with flexbox layout.
+
+**Live Preview Server:**
+
+```bash
+# Build the preview server (one-time)
+npm run evgpreview:build
+
+# Start live preview with auto-reload
+cd gallery/pdf_writer
+./bin/evg_preview_server examples/test_gallery.tsx 3006
+
+# Open http://localhost:3006 - auto-refreshes on file save!
+```
+
+**HTML Generation:**
+
+```bash
+# Build the HTML tool (one-time)
+npm run evg:tool:build:go
+
+# Convert TSX to HTML
+cd gallery/pdf_writer
+./bin/evg_tool examples/test_gallery.tsx output.html
+
+# With component imports
+./bin/evg_tool document.tsx --assets=../components;../assets
+```
+
+**Features:**
+
+- **Live reload** - Browser auto-refreshes when you save
+- **Component imports** - Reusable TSX components
+- **Multi-page documents** - Print, Section, Page elements
+- **Flexbox layout** - CSS-like positioning
+- **Images & fonts** - Asset serving from configurable paths
+
+See `gallery/pdf_writer/README.md` for full documentation and TSX syntax reference.
+
+### EVG ComponentEngine TypeScript Evaluation (New - December 2025)
+
+The EVG ComponentEngine now supports **full TypeScript control flow evaluation**, enabling dynamic document generation with loops and conditionals. Functions defined in TSX files can use for loops, array operations, and return arrays of elements.
+
+**Supported Features:**
+
+| Feature | Syntax | Description |
+|---------|--------|-------------|
+| For loops | `for (let i = 0; i < n; i++)` | Standard for loop with init/test/update |
+| Decrement loops | `for (let i = 5; i > 0; i--)` | Countdown loops |
+| Step loops | `for (let i = 0; i < n; i += 2)` | Custom step increments |
+| Array.push | `arr.push(<Element />)` | Build arrays of JSX elements |
+| Array indexing | `colors[i]` | Access array elements by index |
+| Compound assignment | `total += value` | `+=`, `-=`, `*=`, `/=`, `%=` operators |
+| Update expressions | `i++`, `++i`, `i--`, `--i` | Pre/post increment/decrement |
+| Function calls in JSX | `{buildItems()}` | Call functions that return element arrays |
+
+**Example - Dynamic List Generation:**
+
+```tsx
+const colors = ["#ef4444", "#f97316", "#eab308", "#22c55e", "#3b82f6"];
+
+function buildColorBoxes() {
+  const boxes: any[] = [];
+  
+  for (let i = 0; i < colors.length; i++) {
+    const color = colors[i];
+    boxes.push(
+      <View backgroundColor={color} padding={8}>
+        <Label color="#ffffff">Box {i + 1}: {color}</Label>
+      </View>
+    );
+  }
+  
+  return boxes;
+}
+
+function render() {
+  return (
+    <Print>
+      <Section>
+        <Page>
+          <View padding={16}>
+            <Label fontSize={20} fontWeight="bold">Color Boxes</Label>
+            {buildColorBoxes()}
+          </View>
+        </Page>
+      </Section>
+    </Print>
+  );
+}
+```
+
+**Example - Progressive Widths with Accumulator:**
+
+```tsx
+function buildProgressBars() {
+  const bars: any[] = [];
+  let totalWidth = 0;
+  
+  for (let i = 1; i <= 5; i++) {
+    totalWidth += i * 20;  // 20, 60, 120, 200, 300
+    bars.push(
+      <View width={totalWidth} backgroundColor="#0ea5e9" padding={4}>
+        <Label color="#ffffff">Width: {totalWidth}px</Label>
+      </View>
+    );
+  }
+  
+  return bars;
+}
+```
+
+See `gallery/pdf_writer/examples/test_for_loop.tsx` for a complete demonstration.
+
+### Space Invaders Demo Game
+
+A complete terminal-based Space Invaders game demonstrating Ranger's cross-language capabilities. The same source code compiles to **4 different targets**:
+
+| Target         | Executable          | Build Command               |
+| -------------- | ------------------- | --------------------------- |
+| ES6/JavaScript | `invaders.js`       | `npm run game:compile`      |
+| Rust           | `invaders_rust.exe` | `npm run game:build:rust`   |
+| Go             | `invaders_go.exe`   | `npm run game:build:go`     |
+| Kotlin         | `invaders.jar`      | `npm run game:build:kotlin` |
+| C++            | `invaders_cpp.exe`  | Cross-compile via WSL       |
+| Swift          | `invaders_swift`    | macOS/Linux only            |
+
+> **Note:** Kotlin target renders correctly but keyboard input has issues on Windows (uses PowerShell subprocess for key reading which is slow).
+
+```bash
+# Build all targets at once
+npm run game:build:all
+
+# Run the game
+npm run game:run        # JavaScript
+npm run game:run:rust   # Rust
+npm run game:run:go     # Go
+```
+
+#### Cross-Compiling the Game
+
+The Space Invaders game demonstrates cross-platform compilation from a single source file.
+
+**JavaScript (ES6)**
+
+```bash
+npm run game:compile        # Generates invaders.js
+node gallery/invaders/invaders.js
+```
+
+**Rust**
+
+```bash
+npm run game:compile:rust   # Generates invaders.rs
+cd gallery/invaders && rustc invaders.rs -o invaders_rust.exe
+# Or use the combined command:
+npm run game:build:rust
+```
+
+**Go**
+
+```bash
+npm run game:compile:go     # Generates invaders.go
+cd gallery/invaders && go build -o invaders_go.exe invaders.go
+# Or use the combined command:
+npm run game:build:go
+```
+
+**C++ (Windows via WSL)**
+
+C++ compilation requires POSIX-threaded MinGW for `std::thread` and `std::mutex` support:
+
+```bash
+npm run game:compile:cpp    # Generates invaders.cpp
+
+# Cross-compile from WSL to Windows:
+wsl -d Ubuntu -- bash -c "
+  cd /mnt/c/path/to/Ranger/gallery/invaders && \
+  sed -i 's/\r$//' invaders.cpp && \
+  x86_64-w64-mingw32-g++-posix -std=c++17 -static -pthread invaders.cpp -o invaders_cpp.exe
+"
+```
+
+> **Note:** The standard MinGW compiler (`x86_64-w64-mingw32-g++`) uses win32 threads which don't support `<mutex>` and `<thread>`. You must use the POSIX variant (`g++-posix`).
+
+**Swift (macOS/Linux only)**
+
+```bash
+npm run game:compile:swift  # Generates invaders.swift
+swiftc invaders.swift -o invaders_swift
+```
+
+#### Platform-Specific Keyboard Input
+
+The game uses `on_keypress` and `poll_keypress` operators with platform-specific implementations:
+
+| Platform | Windows                           | Unix/Linux/macOS           |
+| -------- | --------------------------------- | -------------------------- |
+| Rust     | `windows-sys` crate               | `termios` + `libc`         |
+| Go       | `msvcrt.dll` (`_kbhit`, `_getch`) | `stty` + `os.Stdin`        |
+| C++      | `<conio.h>` (`_kbhit`, `_getch`)  | `<termios.h>` + `read()`   |
+| Swift    | `_kbhit` / `_getch` via C interop | `Darwin` / `Glibc` termios |
+
+The game uses terminal control operators (`clear_screen`, `move_cursor`, `hide_cursor`, etc.) and keyboard input (`on_keypress`, `poll_keypress`) that have platform-specific implementations for Windows and Unix.
+
+#### Target Comparison: Code Size and Executable Size
+
+The Space Invaders game provides an interesting comparison of how the same Ranger source code translates to different targets.
+
+**Source Code Sizes:**
+
+| Target     | Generated File   | Size (bytes) | Lines | Notes                           |
+| ---------- | ---------------- | ------------ | ----- | ------------------------------- |
+| **Ranger** | `invaders.rgr`   | 11,289       | ~400  | Original source                 |
+| Python     | `invaders.py`    | 9,271        | ~330  | Most compact generated code     |
+| JavaScript | `invaders.js`    | 10,301       | ~350  | Clean, readable output          |
+| Swift      | `invaders.swift` | 12,554       | ~470  | Verbose type annotations        |
+| Go         | `invaders.go`    | 13,701       | ~480  | Explicit error handling         |
+| C++        | `invaders.cpp`   | 14,148       | ~500  | Headers and type declarations   |
+| Rust       | `invaders.rs`    | 17,918       | ~600  | Most verbose (ownership, types) |
+
+**Executable Sizes (Windows):**
+
+| Target | Executable           | Size   | Notes                             |
+| ------ | -------------------- | ------ | --------------------------------- |
+| Swift  | `invaders_swift.exe` | 76 KB  | Smallest native binary            |
+| Rust   | `invaders_rust.exe`  | 291 KB | Optimized, statically linked      |
+| Go     | `invaders_go.exe`    | 2.3 MB | Includes Go runtime               |
+| C++    | `invaders_cpp.exe`   | 3.0 MB | Static linking with MinGW/pthread |
+
+**Analysis:**
+
+- **Python** generates the most compact code due to its concise syntax (no type annotations, no braces)
+- **Rust** generates the most verbose code because of explicit ownership (`clone()`, `&mut`), type annotations, and safety features
+- **Swift** produces the smallest native executable because it links dynamically to system libraries
+- **Go** and **C++** have large executables due to static linking of their runtimes
+- **JavaScript** runs on Node.js, so there's no standalone executable (interpreter required)
+
+The ~11KB Ranger source compiles to native executables ranging from 76KB to 3MB, demonstrating the trade-offs between different target languages' runtime requirements and linking strategies.
+
+**Known Issues:**
+
+- Console rendering may have timing artifacts on some terminals
+- Swift target requires macOS or Linux (not available on Windows)
+
+### JavaScript ES6+ Parser
+
+A comprehensive JavaScript ES6+ parser written entirely in Ranger, demonstrating the language's capability to build complex tools. The parser includes a full lexer, recursive descent parser, and pretty-printer.
+
+**Features:**
+
+- **Full ES6+ support** - Classes, arrow functions, async/await, generators, destructuring, spread operators, template literals
+- **Pretty-printer** - Parses JavaScript and outputs formatted code
+- **Comment preservation** - Line comments, block comments, and JSDoc are attached to AST nodes
+- **Multi-target** - Parser compiles to JavaScript, Swift, Go, Python, etc.
+
+**Quick Start (JavaScript):**
+
+```bash
+# Compile the parser
+node bin/output.js gallery/js_parser/js_parser_main.rgr -o=js_parser.js -d=gallery/js_parser
+
+# Parse and pretty-print a JavaScript file
+node gallery/js_parser/js_parser.js -i input.js -o output.js
+
+# Show AST structure
+node gallery/js_parser/js_parser.js -i input.js --ast
+```
+
+**Quick Start (Swift):**
+
+```bash
+# Compile to Swift (from gallery/js_parser directory)
+cd gallery/js_parser
+node ../../bin/output.js js_parser_main.rgr -l=swift6 -o js_parser.swift
+
+# Fix line endings and compile
+sed -i '' $'s/\r$//' bin/js_parser_main.swift
+swiftc -o js_parser_swift bin/js_parser_main.swift
+
+# Run the native Swift binary
+./js_parser_swift -i input.js --ast
+./js_parser_swift -d
+```
+
+**Quick Start (C++ on Windows via WSL):**
+
+```bash
+# Compile to C++ (from Ranger root)
+node bin/output.js gallery/js_parser/js_parser_main.rgr -l=cpp -d=gallery/js_parser -o=js_parser.cpp
+
+# Cross-compile from WSL to Windows
+wsl -d Ubuntu -- bash -c "
+  cd /mnt/c/path/to/Ranger/gallery/js_parser && \
+  sed -i 's/\r$//' js_parser.cpp && \
+  x86_64-w64-mingw32-g++-posix -std=c++17 -static -o js_parser_cpp.exe js_parser.cpp
+"
+
+# Run the native Windows binary
+./js_parser_cpp.exe -i input.js --ast
+./js_parser_cpp.exe -d
+```
+
+**Supported ES6+ Features:**
+
+| Category     | Features                                                               |
+| ------------ | ---------------------------------------------------------------------- |
+| Declarations | `let`, `const`, `var`, function declarations/expressions               |
+| Classes      | `class`, `extends`, `constructor`, `static`, getters, `super`          |
+| Functions    | Arrow functions (`=>`), async/await, generators (`function*`, `yield`) |
+| Operators    | Spread (`...`), rest parameters, destructuring (array/object)          |
+| Literals     | Template literals with interpolation, computed property names          |
+| Control Flow | `for-of`, `for-in`, `while`, `if/else`, `switch`, `try/catch`          |
+
+**Performance Benchmark (vs popular parsers):**
+
+The Ranger js_parser was benchmarked against popular JavaScript parsers. All parsers run in-process with warm-up:
+
+| Rank   | Parser               | Large (17KB) | XL (35KB)   |
+| ------ | -------------------- | ------------ | ----------- |
+| #1     | meriyah              | 0.51 ms      | 0.84 ms     |
+| **#2** | **Ranger js_parser** | **0.88 ms**  | **1.39 ms** |
+| #3     | acorn                | 1.41 ms      | 2.70 ms     |
+| #4     | esprima              | 1.41 ms      | 2.33 ms     |
+| #5     | espree (ESLint)      | 1.58 ms      | 3.47 ms     |
+| #6     | @babel/parser        | 2.63 ms      | 3.06 ms     |
+
+🥈 **Ranger ranks #2**, outperforming espree, acorn, esprima, and @babel/parser by **2-4x**.
+
+```bash
+# Run the benchmark yourself
+cd gallery/js_parser/benchmark
+npm install
+npm run benchmark:large
+```
+
+See [gallery/js_parser/benchmark](gallery/js_parser/benchmark) for the full benchmark suite.
+
+**Example transformation:**
+
+```javascript
+// Input
+const greet = async (name) => {
+  const msg = `Hello, ${name}!`;
+  return msg;
+};
+
+// Output (pretty-printed)
+const greet = async (name) => {
+  const msg = `Hello, ${name}!`;
+  return msg;
+};
+```
+
+See [gallery/js_parser/README.md](gallery/js_parser/README.md) for complete documentation.
+
+### Polyfill System
+
+Ranger supports automatic polyfill generation for operators that require helper functions in the target language. Polyfills are utility functions, types, or constants that are automatically added to the generated output when an operator needs them.
+
+Key features:
+
+- **Automatic deduplication** - Polyfills are only generated once even if the operator is used multiple times
+- **Per-target definitions** - Each target language can have its own polyfill implementation
+- **Platform-specific code** - Polyfills can contain platform conditionals (e.g., `#[cfg(windows)]` in Rust)
+
+Example: The `on_keypress` operator in Rust generates polyfill functions for raw terminal input handling that work on both Windows and Unix platforms.
+
+See the `ai/INSTRUCTIONS.md` file for details on creating operators with polyfills.
+
+### Unit Test Suite
+
+A comprehensive test suite has been added using Vitest:
+
+```bash
+npm test              # Run all tests
+npm run test:es6      # JavaScript/ES6 tests only
+npm run test:python   # Python target tests
+npm run test:go       # Go target tests
+npm run test:rust     # Rust target tests
+```
+
+Test coverage includes:
+
+- **ES6/JavaScript**: Full runtime tests (array operations, classes, inheritance, string operations, math, etc.)
+- **Python**: Compilation and runtime tests with pytest
+- **Go**: Compilation and runtime tests
+- **Rust**: Compilation tests (runtime tests in progress)
+
+### Known Issues
+
+See `ISSUES.md` for a comprehensive list of known issues and their status. Key issues include:
+
+- `toString` method name causes compiler crash (use `getSymbol` or similar instead)
+- Go target has integer division type conversion issues
+- Python target has inheritance constructor argument issues
+
+### AI Documentation
+
+The `ai/` folder contains documentation optimized for AI assistants:
+
+- `INSTRUCTIONS.md` - Complete language guide
+- `EXAMPLES.md` - Code examples for common patterns
+- `GRAMMAR.md` - Formal grammar reference
+- `QUICKREF.md` - Quick reference card
+- `INTROSPECTION.md` - Compiler introspection API for IDE/AI integration
+
+These files are also useful for human readers who want the shortest path to understanding Ranger without reading the whole README front to back.
+
+### Compiler Introspection API (New)
+
+The compiler now exposes powerful introspection capabilities for IDE integration and AI-assisted development:
+
+**Position-Based Type Querying**
+
+- Query what type is at any line/column position in source code
+- Convert between line/column and byte offsets
+- Find all typed nodes in a source file
+
+**Class Structure Introspection**
+
+- Check if classes have specific properties with optional type verification
+- Check if classes have specific methods with optional return type verification
+- Get all properties and methods with full signatures
+- Track inheritance relationships
+
+**Use Cases**
+
+- IDE autocomplete and hover information
+- AI code generation with type-safe suggestions
+- Incremental compilation planning
+- Codebase analysis and documentation
+
+Example usage:
+
+```typescript
+import {
+  compileForIntrospection,
+  classHasProperty,
+  getTypeAtPosition,
+} from "./tests/helpers/introspection";
+
+// Compile source code
+const result = await compileForIntrospection(sourceCode);
+
+// Check class structure
+if (classHasProperty(result, "Person", "name", "string")) {
+  // Safe to reference person.name
+}
+
+// Query type at cursor position (1-based line/column)
+const typeInfo = getTypeAtPosition(result.rootNode, sourceCode, 5, 12);
+console.log(typeInfo.evalTypeName); // e.g., "int"
+```
+
+See `ai/INTROSPECTION.md` for complete API documentation.
 
 ## Installing the compiler
 
-To install the latest test version of the compiler using npm run
+Install the compiler from npm:
 
 ```
  npm install -g ranger-compiler
@@ -27,11 +712,11 @@ To install the latest test version of the compiler using npm run
 Running `ranger-compiler` without arguments shows available command-line options:
 
 ```
-Ranger compiler, version 2.1.33
-Installed at: C:\dev\static\tools\ranger-compiler
-Usage: <file> <options> <flags>
+Ranger Compiler v3.0.1
+
+Usage: rgrc <file> [options] [flags]
 Options: -<option>=<value>
-  -l=<value>             Selected language, one of es6, go, scala, java7, swift3, cpp, php, csharp
+    -l=<value>             Selected language, one of es6, go, scala, java7, swift3, swift6, kotlin, cpp, php, csharp, python, rust
   -d=<value>             output directory, default directory is "bin/"
   -o=<value>             output file, default is "output.<language>"
   -classdoc=<value>      write class documentation .md file
@@ -45,7 +730,8 @@ Flags: -<flag>
   -typescript    Writes JavaScript code with TypeScript annotations
   -npm           Write the package.json to the output directory
   -nodecli       Insert node.js command line header #!/usr/bin/env node to the beginning of the JavaScript file
-  -nodemodule    Export the classes as node.js modules (this option will disable the static main function)
+  -nodemodule    Export classes as CommonJS modules using module.exports (disables static main function)
+  -esm           Export classes as ES6/ESM modules using export keyword (disables static main function)
   -client        the code is ment to be run in the client environment
   -scalafiddle   scalafiddle.io compatible output
   -compiler      recompile the compiler
@@ -54,95 +740,127 @@ Pragmas: (inside the source code files)
    @noinfix(true)   disable operator infix parsing and automatic type definition checking
 ```
 
+### JavaScript Module Formats
+
+The compiler supports three JavaScript module output formats:
+
+| Flag          | Format   | Output                    | Use Case                         |
+| ------------- | -------- | ------------------------- | -------------------------------- |
+| (none)        | Plain JS | No exports, runs `main()` | Standalone scripts               |
+| `-nodemodule` | CommonJS | `module.exports.X = X;`   | Node.js require()                |
+| `-esm`        | ES6/ESM  | `export class X`          | Modern ES modules, import/export |
+
+**Examples:**
+
+```bash
+# Standalone JavaScript (runs main function)
+node bin/output.js -es6 myfile.rgr -o=myfile.js
+
+# CommonJS module (.cjs)
+node bin/output.js -es6 -nodemodule myfile.rgr -o=myfile.cjs
+
+# ES6/ESM module (.mjs)
+node bin/output.js -es6 -esm myfile.rgr -o=myfile.mjs
+```
+
+**File Extensions:**
+The compiler automatically detects JavaScript-related extensions (`.js`, `.ts`, `.mjs`, `.cjs`) and won't double-add them. You can safely specify the full filename with extension.
+
 ## Getting started with Hello World
 
-Create file `hello.clj`
-```   
+Create file `hello.rgr`
+
+```
 class Hello {
-    static fn main () {
+    sfn m@(main):void () {
         print "Hello World"
     }
 }
 
 ```
-Then compile it using `ranger-compiler` using command line
+
+Then compile it using `ranger-compiler` from the command line:
 
 ```
-ranger-compiler hello.clj
+ranger-compiler hello.rgr
 ```
 
-The result will be outputtted into directory `bin/hello.js`
+The result will be written to `bin/output.js` by default, or you can choose the output name explicitly:
+
+```
+ranger-compiler hello.rgr -o=hello.js
+```
 
 ## Compiling using TypeScript
 
 The compiler can be used from TypeScript, which makes possible to create new versions of the
 compiler just using TypeScript.
 
-Note: the example requires content of Lang, stdlib, stdops and JSON to be loaded for the compiler, in this example they are loaded from the filesystem using `readFileSync`.
+Note: the example requires `Lang`, `stdlib`, `stdops`, and `JSON` to be loaded for the compiler. In this example they are loaded from the filesystem using `readFileSync`.
 
 ```typescript
 // Notice this part of example is required:
-addFile('Lang.clj', fs.readFileSync('./libs/Lang.clj', 'utf8') )
-addFile('stdlib.clj', fs.readFileSync('./libs/stdlib.clj', 'utf8') )
-addFile('stdops.clj', fs.readFileSync('./libs/stdops.clj', 'utf8') )
-addFile('JSON.clj', fs.readFileSync('./libs/JSON.clj', 'utf8') )
+addFile("Lang.rgr", fs.readFileSync("./libs/Lang.rgr", "utf8"));
+addFile("stdlib.rgr", fs.readFileSync("./libs/stdlib.rgr", "utf8"));
+addFile("stdops.clj", fs.readFileSync("./libs/stdops.clj", "utf8"));
+addFile("JSON.clj", fs.readFileSync("./libs/JSON.clj", "utf8"));
 ```
 
 The full compiler code:
 
 ```typescript
+import * as R from "ranger-compiler";
+import { CodeNode } from "ranger-compiler";
 
-import * as R from 'ranger-compiler'
-import { CodeNode } from 'ranger-compiler';
-
-const compilerInput = new R.InputEnv()
-compilerInput.use_real = false
+const compilerInput = new R.InputEnv();
+compilerInput.use_real = false;
 
 // manually create a filesystem
-const folder = new R.InputFSFolder()
-const addFile = (name:string, contents:string) => {
-const newFile = new R.InputFSFile()
-newFile.name = name
-newFile.data = contents
-folder.files.push( newFile )
-}
-addFile('hello.clj',
-` 
+const folder = new R.InputFSFolder();
+const addFile = (name: string, contents: string) => {
+  const newFile = new R.InputFSFile();
+  newFile.name = name;
+  newFile.data = contents;
+  folder.files.push(newFile);
+};
+addFile(
+  "hello.clj",
+  ` 
 class hello {
     static fn main() {
         print "Hello World"
     }
 }  
-`);
+`
+);
 
 // compiler requires language definition and libraries to work
-const fs = require('fs')
-addFile('Lang.clj', fs.readFileSync('./libs/Lang.clj', 'utf8') )
-addFile('stdlib.clj', fs.readFileSync('./libs/stdlib.clj', 'utf8') )
-addFile('stdops.clj', fs.readFileSync('./libs/stdops.clj', 'utf8') )
-addFile('JSON.clj', fs.readFileSync('./libs/JSON.clj', 'utf8') )
+const fs = require("fs");
+addFile("Lang.clj", fs.readFileSync("./libs/Lang.clj", "utf8"));
+addFile("stdlib.clj", fs.readFileSync("./libs/stdlib.clj", "utf8"));
+addFile("stdops.clj", fs.readFileSync("./libs/stdops.clj", "utf8"));
+addFile("JSON.clj", fs.readFileSync("./libs/JSON.clj", "utf8"));
 
-compilerInput.filesystem = folder
+compilerInput.filesystem = folder;
 
 // set compiler options -l=es6 -typescript
-const params = new R.CmdParams()
+const params = new R.CmdParams();
 // target language is Go
-params.params['l'] = 'go'
-params.params['o'] = 'hello.go'
-params.values.push('hello.clj')
-compilerInput.commandLine = params
+params.params["l"] = "go";
+params.params["o"] = "hello.go";
+params.values.push("hello.clj");
+compilerInput.commandLine = params;
 
 // Run compiler
-const vComp = new R.VirtualCompiler()
+const vComp = new R.VirtualCompiler();
 
 // Check results...
-const res = await vComp.run(compilerInput)
+const res = await vComp.run(compilerInput);
 
 // browse through the target compiler file system
-res.fileSystem.files.forEach( file=>{
-    console.log(file.getCode())
-})
-
+res.fileSystem.files.forEach((file) => {
+  console.log(file.getCode());
+});
 ```
 
 ## Switching to different target language
@@ -157,48 +875,49 @@ Currently the compiler supports at least following language versions:
 - JavaScript ES2015
 - PHP versions 5.4 and above
 - C++ version C++14
-- Java version 7 
+- Java version 7
 - Swift version 3
 - Golang version 1.8
-- Scala 2.xx 
-- CSharp 7.0 
+- Scala 2.xx
+- CSharp 7.0
+- Python 3.x
+- Rust (preliminary support)
 
 However, it is possible to add support for older versions by implementing custom operators, which target to certain compiler flags.
 
 Additionally, JavaScript has '-typescript' flag, which will add typescript annotations to the source file.
 
-
 # Operators
 
 Operators enable creating short, funtional commands like 'get' or 'push' that operate on certain, typed parameters. Whenever there is
-need for some functionality it is woth considering whether it is best implemented using operator or a function or a class method. A 
+need for some functionality it is woth considering whether it is best implemented using operator or a function or a class method. A
 simple operator definition would be `M_PI` which is defined in the Compilers internal Lang.clj file as
 
 ```
     M_PI mathPi:double () {
         templates {
             es6 ("Math.PI")
-            go ( "math.Pi" (imp "math"))                                
-            swift3 ( "Double.pi" (imp "Foundation"))   
-            java7 ( "Math.PI" (imp "java.lang.Math"))         
-            php ("pi()")        
-            cpp ("M_PI" (imp "<math.h>"))               
+            go ( "math.Pi" (imp "math"))
+            swift3 ( "Double.pi" (imp "Foundation"))
+            java7 ( "Math.PI" (imp "java.lang.Math"))
+            php ("pi()")
+            cpp ("M_PI" (imp "<math.h>"))
         }
     }
 ```
 
-Oops! Looks like C# defintion is missing! It should be `Math.PI` and it requires `System`. We can add that easily to Lang.clj 
+Oops! Looks like C# defintion is missing! It should be `Math.PI` and it requires `System`. We can add that easily to Lang.clj
 
 ```
     M_PI mathPi:double () {
         templates {
             es6 ("Math.PI")
-            go ( "math.Pi" (imp "math"))                                
-            swift3 ( "Double.pi" (imp "Foundation"))   
-            java7 ( "Math.PI" (imp "java.lang.Math"))         
-            php ("pi()")        
-            cpp ("M_PI" (imp "<math.h>"))               
-            csharp ("Math.PI" (imp "System"))               
+            go ( "math.Pi" (imp "math"))
+            swift3 ( "Double.pi" (imp "Foundation"))
+            java7 ( "Math.PI" (imp "java.lang.Math"))
+            php ("pi()")
+            cpp ("M_PI" (imp "<math.h>"))
+            csharp ("Math.PI" (imp "System"))
         }
     }
 ```
@@ -211,9 +930,16 @@ For a quick reference of available basic operators see [Operators doc](operators
 
 # Plugins
 
-Compiling
+Compiling as CommonJS module:
+
 ```
-ranger-compiler hello.clj -npm  -nodemodule
+ranger-compiler hello.clj -npm -nodemodule
+```
+
+Compiling as ES6/ESM module:
+
+```
+ranger-compiler hello.clj -npm -esm
 ```
 
 Example
@@ -233,13 +959,12 @@ class Plugin {
   fn features:[string] () {
       return ([]  "postprocess")
   }
-  fn postprocess (root:CodeNode ctx:RangerAppWriterContext wr:CodeWriter) {  
+  fn postprocess (root:CodeNode ctx:RangerAppWriterContext wr:CodeWriter) {
     print "*** plugin postprocess was called ***"
   }
 }
 ```
 
-
 # Notes about the syntax
 
 Ranger syntax is originally based on Lisp -language syntax and most operators will use prefix notation. However, the Ranger modifies
@@ -254,14 +979,15 @@ class Hello {
             print "x < 10"
         } {
             print "x >= 10"
-        }   
+        }
     }
 }
 ```
 
 However, when you go deeper in the expression you may have to include the parenthesis, for example when invoking object you have to write
+
 ```
-def obj (new Hello) 
+def obj (new Hello)
 ```
 
 For most common mathematical symbols and boolean operators infix notation can be used and they are automatically converted to lisp expressions.
@@ -270,41 +996,45 @@ Thus you can write expressions such as `(x + y * z)` instead of `(+ x (* y z))`
 ```
 def x 100
 def y 200
-def z ( x + y * 10)    
+def z ( x + y * 10)
 if ( x < 20 || y == 0 ) {
 
 }
 ```
+
 The assigment operator is also automatically prefixed from infix notation so you can say
+
 ```
 x = y
 ```
+
 Instead of common lisp syntax `(= x y)`
 
 ## Main function
 
 Each file can have a static main function, which is executed as the main program.
 
-```   
+```
 class Hello {
     static fn main() {
-    }   
+    }
 }
 
 ```
+
 This is a static function which marks the start of execution for the program.
 
 ## Functions and Static functions
 
-```   
+```
 class Hello {
     fn SomeNonStaticFn () {
-    }      
+    }
     sfn SomeStaticFn () {
         ; static function which instantiates Hello and calls non-static
         def o (new Hello)
         o.SomeNonStaticFn()
-    }   
+    }
 }
 
 ```
@@ -319,8 +1049,8 @@ Hello.SomeStaticFn()
 
 Function not inferred or declared as `void` should always return value with `return` statement.
 
-
 ## Comments
+
 ```
 ; here is a comment
 class Hello {
@@ -346,18 +1076,21 @@ Basic primitive types are
 - boolean
 - string
 - double
-- char  
+- char
 - charbuffer
 
 Type of function returning nothing is
+
 - void
 
 Type which can be used as variable types, but require signature are
+
 - Arrays
 - Hashes
 - Anonymous functions
 
 Types which require type declaration are
+
 - Enum
 - class
 - systemclass
@@ -375,9 +1108,39 @@ def long_string "
 "
 ```
 
+## String Operations
+
+Ranger provides a comprehensive set of string manipulation operators. Here are some commonly used ones:
+
+```
+def text "Hello World"
+
+; Length and substring operations
+def len (strlen text)                    ; returns 11
+def sub (substring text 0 5)             ; returns "Hello"
+
+; Case conversion
+def lower (to_lowercase text)            ; returns "hello world"
+def upper (to_uppercase text)            ; returns "HELLO WORLD"
+
+; Search operations
+def idx (indexOf text "World")           ; returns 6
+def hasWorld (contains text "World")     ; returns true
+def starts (startsWith text "Hello")     ; returns true
+def ends (endsWith text "World")         ; returns true
+
+; String manipulation
+def replaced (replace text "World" "Ranger")  ; returns "Hello Ranger"
+def parts (strsplit text " ")            ; returns ["Hello", "World"]
+def trimmed (trim "  hello  ")           ; returns "hello"
+```
+
+For the complete list of string operators, see [Operators doc](operators.md).
+
 ## Enums
 
 Enums will be compiled to type `int` but are type checked by the Ranger preprosessor
+
 ```
 Enum LineJoin (
     Undefined
@@ -393,6 +1156,7 @@ class foo {
 ## Arrays and Hashes
 
 Arrays and hashes are automatically initialized and are ready to be used after their declaration
+
 ```
 def list:[string]
 def usedKeywords:[string:string]
@@ -402,20 +1166,27 @@ def classMap:[string:myClass]
 ### Operators for hashes
 
 if we have a hashmap
+
 ```
   def someMap:[string:string]
 ```
+
 Operator `set` can be used to set key/value pair
+
 ```
   set someMap "foo" "bar"
 ```
+
 Operator `has` can be used to check if a key exists in the hash
+
 ```
     if (has someMap "a key") {
-        
+
     }
 ```
+
 Get is used to read the value associated with a key. The result is `@(optional)`
+
 ```
   (get someMap "foo")
 ```
@@ -423,6 +1194,7 @@ Get is used to read the value associated with a key. The result is `@(optional)`
 ## Anonymous functions / lambdas
 
 Anonymous function type declaration is automatically inferred
+
 ```
 def name "foo"
 def myFilter (fn:boolean (param:string) {
@@ -451,9 +1223,7 @@ this.foo({
 })
 ```
 
-
-
-# Automatically infixed math support 
+# Automatically infixed math support
 
 It is easy to define new mathematical operations in the Lang.clj file or in modules. However, some mathematical operations are automatically infixed
 for easier usage. Thus, instead of using common lips notation `(* 4 10)` you can use easier to read infixed `4 * 10` -syntax
@@ -484,7 +1254,6 @@ a >= b
 a != b
 ```
 
-
 # Common set of Operators and the Grammar file
 
 The file `Lang.clj` is used by the compiler for the common set of operators and compilation rules. The
@@ -501,13 +1270,57 @@ modifications, rather it describes common set of rules used and thus should be e
 The file has couple of sections, but the `reserved_words` and `commands`. The Reserved words section declares (surprise!)
 the reserved words and their transformation. This is required because for example in Go the word `map` is a keyword and can
 not be used unless it is conveted to some other name, for example to `FnMap`.
+
 ```
     reserved_words {
-        map FnMap
-        forEach forEachItem
+        * {
+            map FnMap
+            forEach forEachItem
+            self _self
+            func _func
+        }
+        cpp {
+            operator _operator
+            static _static
+            union _union
+            bool _bool
+            ref _ref
+            class _class
+            new _new
+            delete _delete
+            template _template
+            namespace _namespace
+            virtual _virtual
+            public _public
+            private _private
+            protected _protected
+        }
+        go {
+            type _type
+        }
+        rust {
+            type r#type
+            static r#static
+            ref r#ref
+            union r#union
+            bool r#bool
+        }
+        swift3 {
+            operator _operator
+            static _static
+            init _init
+        }
+        swift6 {
+            operator _operator
+            static _static
+            init _init
+        }
     }
 ```
-What the result should be is of course highly opinionated. In this example, the line `map FnMap` means that if possible the 
+
+The `*` section defines global mappings that apply to all target languages. Language-specific sections (like `cpp`, `rust`, `go`, `swift3`, `swift6`) define additional reserved word mappings for that particular target. For Rust, the `r#` prefix is used to escape keywords (raw identifiers).
+
+What the result should be is of course highly opinionated. In this example, the line `map FnMap` means that if possible the
 compiler will transform anything named `map` to `fnMap` if possible. If transformation is not possible, compiler error is
 generated.
 
@@ -516,16 +1329,17 @@ and return values and rules on how they should be compiled into the target langu
 and possible macros or helper function which should be created if the operator is used.
 
 Example of simple operator is `(M_PI)` which will return double value of mathematical symbol "pi".
+
 ```
     commands {
         M_PI mathPi:double () {
             templates {
                 es6 ("Math.PI")
-                go ( "math.Pi" (imp "math"))                                
-                swift3 ( "Double.pi" (imp "Foundation"))   
-                java7 ( "Math.PI" (imp "java.lang.Math"))         
-                php ("pi()")        
-                cpp ("M_PI" (imp "<math.h>"))               
+                go ( "math.Pi" (imp "math"))
+                swift3 ( "Double.pi" (imp "Foundation"))
+                java7 ( "Math.PI" (imp "java.lang.Math"))
+                php ("pi()")
+                cpp ("M_PI" (imp "<math.h>"))
             }
         }
         ...
@@ -534,15 +1348,15 @@ Example of simple operator is `(M_PI)` which will return double value of mathema
 Most operators are simple, but some require creating custom macros, helpoer functions and some of them are so complex
 that they may be implemented in the compiler core.
 
-
 # Modules, classes and operators
 
 The basic unit of the program is class. The functions of classes can not be overloaded at the moment, which means that you can not
-have two functions with different parameters or different return values. 
+have two functions with different parameters or different return values.
+
+Each source file can import other files using `Import` command.
 
-Each source file can import other files using `Import` command. 
-``` 
-Import "Vec2.clj"  
+```
+Import "Vec2.clj"
 
 class vectorTest {
     fn testVectors () {
@@ -553,7 +1367,7 @@ class vectorTest {
 
 ## Class declaration
 
-``` 
+```
 class fatherClass {
     def msg "Hello "
     fn foo:string ( txt:string ) {
@@ -575,7 +1389,7 @@ class mainProgram {
 
 ## Class constructor
 
-``` 
+```
 class myClass {
     def name:string ""
     Constructor (n:string) {
@@ -585,13 +1399,16 @@ class myClass {
 ```
 
 Notes:
-1. currently only a single variant of the constructor is possible. 
+
+1. currently only a single variant of the constructor is possible.
 2. as of this writing calling the parent class constructor does not work properly
 
 ## Class invocation
+
 ```
 def obj (new myClass ("name"))
 ```
+
 classes without constructor can be invocated without arguments
 
 ```
@@ -608,7 +1425,7 @@ Extension can
 - add new functions to the class
 - add new member variables to the class
 
-``` 
+```
 extension childClass {
     def name:string ""
     fn bar:string ( txt:string ) {
@@ -625,26 +1442,28 @@ non-nullable value should cause compiler error. In Ranger any variable which is
 This corresponds to Swift `?` optional type.
 
 You can also declare variables optional using @optional annotation
+
 ```
     def item@(optional):myClass
 ```
 
 Some operators also return optional values, for example `(get <hash> <key>)` operator is returning always optional value. To use
 the value you must use `(unwrap <value>)` operator
+
 ```
     def strMap:[string:string]
     def str (get strMap "myKey")
     if(!null? str) {
         print (unwrap str)
     }
-``` 
+```
 
-**Warning***  currently optinal variables in Ranger are not "safe" in the sense the language makes sure that you can not make 
+**Warning\*** currently optinal variables in Ranger are not "safe" in the sense the language makes sure that you can not make
 programming errors - it is possible to create programming mistake by using a variable which automatically unwrapped. The plan
-is to try to make them safer in the future, and options are considered how to enable them 
+is to try to make them safer in the future, and options are considered how to enable them
 
 Another warning: Ranger does not protect you from mistakes when automatically unwrapping long reference chains like
-`obj.property.subProperty.foo` where `property` and `subProperty ` are optional variables. 
+`obj.property.subProperty.foo` where `property` and `subProperty ` are optional variables.
 
 ## Control flow
 
@@ -661,7 +1480,7 @@ if ( x < 10 ) {
 }
 ```
 
-### switch - case 
+### switch - case
 
 Note: currently case statement does not support multiple matching values, it is planned to add support for that later.
 
@@ -683,15 +1502,18 @@ switch name {
 ## Loops
 
 ### for -loop
+
 ```
 def list:[string]
 for list s:string i {
     print s
 }
 ```
+
 You can use `break` and `continue` to control the for -loop.
 
 ### while -loop
+
 ```
 def cnt 10
 while (cnt > 0 ) {
@@ -708,6 +1530,7 @@ using macros. Together with `systemclass` they allow the system to integrate to
 native API's.
 
 Operators allow type matching against
+
 - defined primitive types
 - defined classes
 - Enums
@@ -749,17 +1572,17 @@ operators {
     *  base:Mat2 ( a:Mat2 b:Mat2) {
         templates {
             * @macro(true) ( (e 1 ) ".multiply(" (e 2) " )" )
-        }        
+        }
     }
 }
 
 ```
-The `* @macro(true)` means that we target all languages and this is a macro, not actual target language construct.
 
+The `* @macro(true)` means that we target all languages and this is a macro, not actual target language construct.
 
 ## Custom operators and System classes
 
-To integrate with the target languages running environment,  Ranger modules can declare `systemclass` which can be used
+To integrate with the target languages running environment, Ranger modules can declare `systemclass` which can be used
 together with the code.
 
 ```
@@ -771,12 +1594,12 @@ operators {
     find  base:DOMElement ( id:string) {
         templates {
             es6 ("document.getElementById( " (e 1) " )")
-        }        
+        }
     }
     setAttribute  _:void ( elem:DOMElement name:string value:string) {
         templates {
             es6 ( (e 1) ".setAttribute(" (e 2) ", " (e 3) ")" )
-        }        
+        }
     }
 }
 
@@ -788,25 +1611,25 @@ class tester {
 }
 ```
 
-
 Note: Definition of system classes will be revisited in near future and there will be potentially small changes to it.
 
 ## Unions of system classes
 
-Sometimes the system class can be of union type. This means that the traget language can accept multiple types in place of 
+Sometimes the system class can be of union type. This means that the traget language can accept multiple types in place of
 a single type.
 
 ```
 systemunion DOMElementUnion ( DOMElement string )
 ```
-The you can create operator which accepts either `DOMElement` or `string` and reduces that to a single type. 
 
+The you can create operator which accepts either `DOMElement` or `string` and reduces that to a single type.
 
 ## Traits
 
 Traits are like extensions, which can be plugged into several classes using `does` keyword.
 
-Traits 
+Traits
+
 ```
 trait bar {
     fn hello() {
@@ -814,7 +1637,7 @@ trait bar {
     }
 }
 
-; foo implements "bar" trait 
+; foo implements "bar" trait
 class foo {
     does bar
 }
@@ -855,14 +1678,14 @@ class Main {
         def n (coll.map({
             return ("item = " + item)
         }))
-        print (join n.items " ")     
+        print (join n.items " ")
     }
     sfn hello@(main):void () {
         def hello (new Main ())
         hello.testCollection()
-    }   
+    }
 }
-``` 
+```
 
 ## Variable definitions
 
@@ -879,15 +1702,15 @@ def strObjMap:[string:someClass]    ; map of string -> object of type someClass
 
 # Advanced topics
 
-
 ## Compiling a new version of the compiler
 
 Then run command
+
 ```
 ranger-compiler -compiler -copysrc
 ```
-The result will be written to directory `bin/ng_Compiler.js`.
 
+The result will be written to directory `bin/ng_Compiler.js`.
 
 # Annotations
 
@@ -917,7 +1740,7 @@ trait GenericCollection @paras(T V) {
 class StringCollection {
     does GenericCollection @params(string StringCollection)
 }
-``` 
+```
 
 ## def variableName@(optional)
 
@@ -943,4 +1766,4 @@ the lifetime calculations.
 ## def variableName@(temp)
 
 @(temp) annotation can be used to note the compiler that it should not worry about freeing the variable, in case the
-target language has option to release the variable. 
+target language has option to release the variable.