glimlang 1.2.1

A simple toy programming language built in Python

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.1

---

⚡ 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/                    # Compiler & Interpreter Core Engine
│   ├── 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             # Basic programmatic entrypoint
│   └── stdlib.glim         # Code helper utilities written in GlimLang
├── docs/                   # Beginner-Friendly Educational Guides
│   ├── GETTING_STARTED.md  # Installation, first hello-world, and REPL setup
│   ├── LANGUAGE_GUIDE.md   # Core syntax, scoping, OOP, and builtins list
│   ├── CLI.md              # Global CLI command references and output keys
│   ├── ARCHITECTURE.md     # Pipeline state flows and how to add a feature
│   └── EXAMPLES.md         # Example catalog with detailed output keys
├── examples/               # Progressively structured test programs
│   ├── hello.glim          # Hello World
│   ├── variables.glim      # Declarations and dynamic scoping
│   ├── math.glim           # Exponentiation, division, and modulo
│   ├── strings.glim        # Dynamic f-string interpolation
│   ├── conditions.glim     # Basic if-else branches
│   ├── nested_conditions.glim # Nested condition evaluations
│   ├── while_loop.glim     # Iterative loops with break/continue
│   ├── functions.glim      # Named functions and recursive stacks
│   ├── arrays.glim         # Array syntax and allocations
│   ├── indexing.glim       # Element retrieval and modification
│   ├── builtins.glim       # Demonstrates all built-in function groups
│   ├── countdown.glim      # Countdown iterations
│   ├── fizzbuzz.glim       # Classic FizzBuzz algorithm
│   ├── calculator.glim     # Matching calculator script
│   ├── grade_checker.glim  # Conditional grade calculator
│   └── simple_menu.glim    # Menu state machine
├── 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

Deep-dive into GlimLang subsystems using these detailed 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.