GlimLang 🌟

GlimLang is a lightweight, educational toy programming language designed and implemented entirely from scratch in Python. It features a hand-written Lexical Analyzer (Lexer), a recursive descent Parser that structures tokens into an Abstract Syntax Tree (AST), and a stateful, tree-walking Interpreter supporting first-class environments.

GlimLang is packed with modern language constructs including first-class anonymous functions (lambdas), pattern matching (match statements), classes (OOP), and a highly capable pre-compiled built-ins library. It serves as an accessible entry point for students, educators, and curious developers seeking to understand compiler design and programming language internals.

🚀 Key Features

• ⚙️ Hand-Written Pipeline: Completely custom Lexer and Parser written in readable Python with zero external parsing dependencies.
• 📦 Rich Type System: Numbers (floats/integers), Strings (with f-string dynamic interpolation), Booleans, explicit null, dynamic Arrays, and custom Blueprint Classes.
• 🎯 Anonymous Functions & Closures: Standard function statements (def) and inline lambdas (fn) that carry outer lexical scopes.
• 🔀 Advanced Pattern Matching: A robust match construct supporting piped patterns (|), fallback wildcards (_), and multi-statement block arms.
• 🏛️ Object-Oriented Programming (OOP): Custom blueprint templates (class), constructor instantiators (init), self-referencing properties (self.x), and standard methods.
• 🛠️ Native Built-ins Library: Over 40 native helper functions covering complex arithmetic, string slicing, array filter/maps, file reader/writers, and user input prompts.

📦 Installation

Ensure you have Python 3.8 or higher installed. Clone the repository and install it in editable developer mode:

git clone https://github.com/YOUR_GITHUB_USERNAME/glimlang.git
cd glimlang
pip install -e .

Verify your installation has registered the global gl command utility:

gl version

Expected Output:

GlimLang v1.2.2

⚡ Syntax Preview & Showcase

Functions and Lexical Closures

# Let's create an anonymous function and assign it to a variable
let double = fn(x) { return x * 2 }
print double(10) # Prints 20.0

# Pass named/anonymous functions directly into array helper functions
let scores = [1, 2, 3, 4]
let doubled_scores = map(scores, double)
print doubled_scores # Prints [2.0, 4.0, 6.0, 8.0]

Pattern Matching (match)

let browser_status = 404
match browser_status {
  200 => print "Success"
  404 => print "Page Not Found"
  500 | 502 => {
    print "Server Error!"
    print "Please try again later."
  }
  _ => print "Unknown Status Code"
}

🏃 Quick Start CLI Usage

Run GlimLang Files

Save a simple print statement inside hello.glim and run it:

gl run examples/hello.glim

Run the Interactive REPL

Type GlimLang expressions directly in an active terminal loop:

gl repl

REPL Shell:

GlimLang> let msg = "Hello from REPL!"
GlimLang> print msg
Hello from REPL!
GlimLang> exit

📂 Project Structure

glimlang/
├── src/                    # Source code directory
│   └── glimlang/           # Core compiler & interpreter package
│       ├── __init__.py     # Package initialization
│       ├── __main__.py     # CLI execution entrypoint
│       ├── lexer.py        # Lexical analysis (character streams -> tokens)
│       ├── parser.py       # Syntactic analysis (token lists -> AST nodes)
│       ├── ast_nodes.py    # Abstract Syntax Tree structural dataclasses
│       ├── interpreter.py  # Stateful environment walker & native builtins
│       ├── errors.py       # Standardized diagnostics and trace compiler
│       ├── cli.py          # Positional argument CLI router (run, repl, help)
│       ├── main.py         # Programmatic API entrypoint
│       └── stdlib.glim     # Code helper utilities written in GlimLang
├── docs/                   # Documentation and Guides
│   ├── ARCHITECTURE.md     # Pipeline state flows and design patterns
│   ├── CLI.md              # Global CLI command references
│   ├── EXAMPLES.md         # Example catalog with detailed output keys
│   ├── GETTING_STARTED.md  # Installation and REPL setup instructions
│   ├── INSTALL.md          # Brief installation info
│   ├── LANGUAGE_GUIDE.md   # Core syntax, scoping, OOP, and builtins list
│   ├── README_WEB.md       # Web playground readme
│   ├── glimlang_docs.html  # Compiled docs in HTML
│   └── index.html          # Documentation index HTML
├── examples/               # Example programs in GlimLang
│   ├── arrays.glim         # Array syntax and allocations
│   ├── builtins.glim       # Demonstrates built-in function groups
│   ├── builtins_demo.glim  # Rich showcase of standard builtins
│   ├── calculator.glim     # Match-based interactive calculator
│   ├── conditions.glim     # Conditional check control flows
│   ├── countdown.glim      # Simple countdown loop
│   ├── error_handling.glim # Error catching syntax tests
│   ├── fizzbuzz.glim       # FizzBuzz implementation
│   ├── functions.glim      # Scope boundaries and functions
│   ├── grade_checker.glim  # Nested grade categorization
│   ├── greeting.glim       # Standard greetings
│   ├── hello.glim          # Hello World program
│   ├── import_demo.glim    # Demo of loading dependencies
│   ├── indexing.glim       # Array index getters and setters
│   ├── lambdas_demo.glim   # Anonymous functions and closures
│   ├── match_demo.glim     # Advanced pattern matching features
│   ├── math.glim           # Expressions and math utilities
│   ├── nested_conditions.glim # Deeply nested conditions
│   ├── simple_menu.glim    # Simple menu loops
│   ├── stdlib_demo.glim    # Demonstrates stdlib integrations
│   ├── strings.glim        # Dynamic f-string interpolation
│   ├── utils.glim          # Basic utility functions
│   ├── variables.glim      # Basic let-bindings and identifiers
│   └── while_loop.glim     # While loop control structures
├── vscode-extension/       # Visual Studio Code editor extension
│   └── glimlang-vscode/    # Syntax highlighting and snippet files for VS Code
├── web/                    # Interactive web-based playground/terminal
│   ├── server.py           # Web application server
│   ├── requirements.txt    # Web playground dependencies
│   └── templates/          # HTML templates for the playground
├── pyproject.toml          # Modern build metadata and CLI mapping
├── setup.py                # Setuptools project routing configuration
├── CONTRIBUTING.md         # Developer setup and AST feature safety checks
├── CHANGELOG.md            # Historical release logs
└── LICENSE                 # Project License File (Apache 2.0)

📚 Documentation Reference Links

For more guides and documentation, visit glimlang.org.

Deep-dive into GlimLang subsystems using these detailed local guides:

1. 🏁 Getting Started Guide — Steps for installing Python, GlimLang CLI, and launching the REPL.
2. 📝 Language Syntax Guide — Comprehensive syntax definitions, classes, built-ins, and common mistakes.
3. 💻 CLI Reference Guide — CLI flags, arguments, stdout, stderr, and exit codes.
4. ⚙️ Architecture & Implementation Design — Source code flow diagram, environment frames, and a tutorial on how to add a feature.
5. 📂 Examples Catalog — Review of pre-made sample files and expected terminal stdout.

🛠️ Development Setup

Check CONTRIBUTING.md to set up a virtual environment, run code style formats, verify parser changes, and submit structured pull requests.

📄 License

GlimLang is licensed under the Apache License 2.0. See the LICENSE file for the complete terms.

🗺️ Future Roadmap

• Standard Module Imports: File imports support (import "math.glim").
• Class Inheritance: Support standard blueprint extensions (class Dog in Animal).
• Inline Dictionary Literals: Explicit dictionary literals (let dict = { "x": 10 }).
• LSP Server: Language Server Protocol integration for autocompletions in IDEs.