Metadata-Version: 2.4
Name: samlang
Version: 0.1.1
Summary: SamLang — A modern, high-performance programming language blending Python simplicity with C# elegance.
Author: Samrane Ahmed
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/samrane-ahmed/samlang
Project-URL: Repository, https://github.com/samrane-ahmed/samlang
Project-URL: Issues, https://github.com/samrane-ahmed/samlang/issues
Keywords: programming-language,interpreter,samlang,compiler,oop
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/badge/SamLang-v0.1.0-blue?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHRleHQgeD0iNCIgeT0iMTgiIGZvbnQtc2l6ZT0iMTYiPvCfmoA8L3RleHQ+PC9zdmc+" alt="SamLang Badge">
  <img src="https://img.shields.io/pypi/v/samlang?style=for-the-badge&color=brightgreen" alt="PyPI Version">
  <img src="https://img.shields.io/badge/python-%3E%3D3.8-yellow?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/license-Proprietary-red?style=for-the-badge" alt="License">
</p>

<h1 align="center">🚀 SamLang</h1>

<p align="center">
  <strong>A modern, high-performance programming language blending Python simplicity with C# elegance.</strong><br>
  <em>Created by <a href="https://github.com/samrane-ahmed">Samrane Ahmed</a></em>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-why-samlang">Why SamLang?</a> •
  <a href="#-language-features">Features</a> •
  <a href="#-code-examples">Examples</a> •
  <a href="#-ide-support">IDE Support</a> •
  <a href="#-oop-system">OOP</a> •
  <a href="#-built-in-functions">Built-ins</a> •
  <a href="#-roadmap">Roadmap</a>
</p>

---

## 💡 Why SamLang?

SamLang was designed to take the best ideas from multiple languages and unify them into one clean, beginner-friendly, yet powerful syntax:

| Feature | Python | JavaScript | C# | **SamLang** |
|:---|:---:|:---:|:---:|:---:|
| Clean readable syntax | ✅ | ❌ | ❌ | ✅ |
| Curly brace blocks `{ }` | ❌ | ✅ | ✅ | ✅ |
| Colon `:` indentation blocks | ✅ | ❌ | ❌ | ✅ |
| String interpolation `${}` | ❌ (f-strings) | ✅ (template) | ✅ | ✅ |
| Arrow functions `=>` | ❌ (lambda) | ✅ | ✅ | ✅ |
| Auto-properties `{ get; set; }` | ❌ | ❌ | ✅ | ✅ |
| SQL-style array ops | ❌ | ❌ | ✅ (LINQ) | ✅ |
| `for-in` loops | ✅ | ✅ | ✅ | ✅ |
| C-style `for(;;)` loops | ❌ | ✅ | ✅ | ✅ |
| `repeat N` loops | ❌ | ❌ | ❌ | ✅ |
| Built-in LSP server | ❌ | ❌ | ❌ | ✅ |
| Zero dependencies | ❌ | ❌ | ❌ | ✅ |

> **SamLang = Python's readability + JavaScript's flexibility + C#'s OOP elegance — with zero dependencies.**

---

## ⚡ Quick Start

```bash
pip install samlang
```

### Run a script
```bash
samlang hello.sl
```

### Launch the interactive REPL
```bash
samlang
```
```
==================================================
  SamLang 0.1.0 Interactive REPL
  Created by Samrane Ahmed
  Type 'exit' or 'quit' to exit.
==================================================
samlang> let name = "World";
samlang> println "Hello ${name}!";
Hello World!
```

---

## 🎯 Language Features

| Category | Highlights |
|:---|:---|
| **Variables** | `let x = 10;` · `const PI = 3.14;` · `x = 42;` (dynamic) |
| **Types** | Integers, Floats, Strings, Booleans, `null`, Arrays, Dictionaries |
| **Operators** | `+` `-` `*` `/` `%` `^` · `==` `!=` `<` `>` · `and` `or` `not` · `&&` `\|\|` `!` |
| **Control Flow** | `if/elif/else` · `while` · `for-in` · `for(;;)` · `do-while` · `repeat N` · `switch/case` |
| **Functions** | `func name(args)` · Arrow `x => x * 2` · Closures · Recursion |
| **OOP** | Classes · Inheritance · Virtual/Override · Auto-properties · Static methods |
| **Modules** | `import math;` · `import "file.sl"` · `from "file" import func;` |
| **Error Handling** | `try/catch/finally` with rich error objects |
| **Functional** | `.map()` `.filter()` `.reduce()` `.for_each()` |
| **Dual Syntax** | C-style `{ }` blocks and Python-style `: indentation` — your choice! |

---

## 💻 Code Examples

### Hello World & Variables
```javascript
println "Salam, SamLang!";

let name = "Ahmed";
const AGE = 22;
println "Name: ${name}, Age: ${AGE}";
```

### Arrays & SQL-Style Operations
```javascript
let numbers = [42, 10, 85, 3, 99, 7];

println numbers.order();         // [3, 7, 10, 42, 85, 99]
println numbers.distinct();      // removes duplicates
println numbers.filter(n => n > 20);  // [42, 85, 99]
println numbers.map(n => n * 2);      // [84, 20, 170, 6, 198, 14]
println numbers.sum();           // 246
println numbers.avg();           // 41.0
```

### Dictionaries
```javascript
let dev = {
    name: "Samrane Ahmed",
    role: "Language Creator",
    skills: ["Compilers", "Python", "SamLang"]
};

println "Name: ${dev.name}";
println "Skills: ${dev.skills}";

for key, val in dev {
    println "  ${key}: ${val}";
}
```

### Functions & Arrow Syntax
```javascript
func factorial(n) {
    if n <= 1 { return 1; }
    return n * factorial(n - 1);
}
println "5! = ${factorial(5)}";  // 120

// Arrow functions
let square = x => x * x;
let add = (a, b) => a + b;
println square(7);    // 49
println add(15, 27);  // 42
```

### Object-Oriented Programming
```javascript
class Person {
    let Name { get; set; }
    let Age { get; set; } = 18

    Person(name, age) {
        this.Name = name;
        this.Age = age;
    }

    func virtuel greet() {
        return "Salam, ana " + this.Name;
    }
}

class Student : Person {
    let Filiere { get; set; }

    Student(name, age, filiere) {
        base(name, age);
        this.Filiere = filiere;
    }

    func override greet() {
        return base.greet() + " | " + this.Filiere;
    }
}

let s = new Student("Ahmed", 22, "Genie Informatique");
println s.greet();
// -> Salam, ana Ahmed | Genie Informatique
```

### Error Handling
```javascript
try {
    let result = 10 / 0;
} catch (err) {
    println "Error: ${err.message}";
} finally {
    println "Cleanup done.";
}
```

### Modules & Imports
```javascript
import math;
println math.sqrt(144);    // 12
println math.pi;           // 3.14159...

import json;
let data = { name: "SamLang", version: 1 };
println json.stringify(data);

import "utils.sl";
utils.helper_func();
```

---

## 🏗️ OOP System

SamLang's OOP combines the best of Python and C#:

| Feature | Syntax |
|:---|:---|
| **Class Declaration** | `class MyClass { ... }` |
| **Auto-Properties** | `let Name { get; set; }` · `let Id { get; } = "readonly"` |
| **Constructors** | `ClassName(args) { ... }` or `func init(args) { ... }` |
| **Inheritance** | `class Child : Parent { ... }` |
| **Virtual Methods** | `func virtuel method()` (parent) |
| **Override Methods** | `func override method()` (child) |
| **Parent Delegation** | `base(args)` · `base.method()` |
| **Self-Reference** | Both `this` (C#) and `self` (Python) work |
| **Static Methods** | `static func add(a, b) { ... }` |
| **Instantiation** | `new Class()` · `let x = new Class()` · `Parent x = new Child()` |

---

## 🔧 Built-in Functions

### String Methods
| Method | Description | Example |
|:---|:---|:---|
| `clean()` | Strip whitespace | `"  hi  ".clean()` → `"hi"` |
| `upper()` / `lower()` | Case conversion | `"hello".upper()` → `"HELLO"` |
| `mirror()` | Reverse string | `"abc".mirror()` → `"cba"` |
| `begin(prefix)` | Starts with | `"hello".begin("he")` → `true` |
| `end(suffix)` | Ends with | `"hello".end("lo")` → `true` |
| `find(sub)` | Find index | `"hello".find("ll")` → `2` |
| `clip(start, end)` | Substring | `"hello".clip(0, 3)` → `"hel"` |
| `divide(sep)` | Split | `"a-b-c".divide("-")` → `["a","b","c"]` |
| `merge(sep)` | Join array | `["a","b"].merge("-")` → `"a-b"` |
| `swap(old, new)` | Replace | `"hi".swap("hi","hello")` → `"hello"` |

### SQL-Style Array Methods
| Method | SQL Equivalent | Example |
|:---|:---|:---|
| `order()` | `ORDER BY ASC` | `[3,1,2].order()` → `[1,2,3]` |
| `order_desc()` | `ORDER BY DESC` | `[1,3,2].order_desc()` → `[3,2,1]` |
| `distinct()` | `SELECT DISTINCT` | `[1,1,2].distinct()` → `[1,2]` |
| `limit(n)` | `LIMIT n` | `[1,2,3,4].limit(2)` → `[1,2]` |
| `offset(n)` | `OFFSET n` | `[1,2,3,4].offset(2)` → `[3,4]` |
| `sum()` | `SUM()` | `[1,2,3].sum()` → `6` |
| `avg()` | `AVG()` | `[2,4,6].avg()` → `4.0` |
| `count()` | `COUNT(*)` | `[1,2,3].count()` → `3` |
| `exists(val)` | `EXISTS` | `[1,2,3].exists(2)` → `true` |
| `insert(item)` | `INSERT` | `arr.insert("new")` |
| `delete(val)` | `DELETE` | `arr.delete("old")` |
| `union(arr2)` | `UNION` | `union([1,2], [2,3])` → `[1,2,3]` |

### Functional Methods
| Method | Description |
|:---|:---|
| `arr.map(fn)` | Transform each element |
| `arr.filter(fn)` | Keep elements matching predicate |
| `arr.reduce(fn, init)` | Fold to single value |
| `arr.for_each(fn)` | Execute action per element |

---

## 🌐 IDE Support

SamLang includes built-in IDE support with **syntax highlighting**, **code snippets**, and a full **Language Server (LSP)**.

### Automatic Setup

IDE extensions are **automatically installed** when you first use `samlang` after `pip install`:

```bash
pip install samlang
samlang --version    # Extensions auto-install on first run!
```

To manually install or reinstall:
```bash
samlang ide            # Install IDE extension
samlang ide remove     # Remove IDE extension
```

**Supported IDEs:** VS Code · Antigravity IDE · Cursor · Windsurf

### LSP Features

| Feature | Description |
|:---|:---|
| **Live Diagnostics** | Instant syntax error reporting with precise markers |
| **Smart Autocomplete** | Keywords, built-ins, stdlib modules, user symbols |
| **Hover Tooltips** | Signatures, docs, and parameter details |
| **Go to Definition** | Jump to declarations with `F12` |
| **Document Outline** | Breadcrumbs and symbol hierarchy |

### Neovim Setup
```lua
local configs = require('lspconfig.configs')
configs.samlang = {
  default_config = {
    cmd = { "samlang", "--lsp" },
    filetypes = { "samlang" },
    root_dir = require('lspconfig').util.root_pattern(".git", "."),
  },
}
require('lspconfig').samlang.setup{}
```

### Sublime Text Setup
```json
{
  "clients": {
    "samlang": {
      "enabled": true,
      "command": ["samlang", "--lsp"],
      "selector": "source.samlang"
    }
  }
}
```

### Helix / Zed Setup
```toml
[[language]]
name = "samlang"
scope = "source.samlang"
file-types = ["sl"]
language-servers = ["samlang-lsp"]

[language-server.samlang-lsp]
command = "samlang"
args = ["--lsp"]
```

---

## 📁 Module System

```
my-project/
├── main.sl
├── utils.sl
└── spm_modules/         # Future: SamLang Package Manager
    └── some-package/
```

### Import Styles
```javascript
import "utils.sl";                        // Namespace: utils.func()
import "utils.sl" as u;                   // Alias: u.func()
import { add, sub } from "math.sl";      // Named imports
import { add as plus } from "math.sl";   // Renamed imports
import * from "utils.sl";                // Wildcard import
from "utils.sl" import add, sub;         // Python-style

// Standard library
import math;    // pi, sqrt, floor, ceil, sin, cos, random...
import json;    // stringify, parse
import time;    // now, date, sleep, clock
import os;      // cwd, exists, read_file, write_file, env
```

---

## 🔬 Architecture

```
Source Code (.sl)
       │
       ▼
   ┌────────┐     ┌────────┐     ┌─────────────┐     ┌─────────────┐
   │ Lexer  │ ──▶ │ Parser │ ──▶ │  AST Nodes  │ ──▶ │ Interpreter │
   │        │     │        │     │             │     │  (Tree-Walk) │
   └────────┘     └────────┘     └─────────────┘     └─────────────┘
   Tokenizer     Recursive       Expression &         Environment &
   (tokens.py)   Descent         Statement Trees      Scoped Eval
                 (parser.py)     (ast_nodes.py)       (interpreter.py)
```

---

## 📄 CLI Reference

```
Usage: samlang [file.sl | ide | --lsp | --help | --version]

Commands:
  <file.sl>      Run a SamLang source file
  ide            Install IDE extension (syntax highlighting)
  ide remove     Remove IDE extension
  lsp / --lsp    Start the Language Server
  -v, --version  Show version
  -h, --help     Show help
```

---

## 🗺️ Roadmap

SamLang is actively evolving. Here's what's planned:

| Phase | Feature | Status |
|:---|:---|:---:|
| ✅ Phase 1 | Arithmetic, Variables, Output | Done |
| ✅ Phase 2 | Booleans, Logic, Scoping | Done |
| ✅ Phase 3 | Functions, Control Flow, Dual Syntax | Done |
| ✅ Phase 4 | Advanced Loops, Constants, Operators | Done |
| ✅ Phase 5 | Arrays, Dicts, String Interpolation, Built-ins | Done |
| ✅ Phase 6 | Module System, Standard Library, Imports | Done |
| ✅ Phase 7 | Arrow Functions, try/catch, Functional Methods | Done |
| ✅ Phase 8 | OOP — Classes, Inheritance, Polymorphism | Done |
| ✅ IDE | LSP Server, VS Code Extension, Syntax Highlighting | Done |
| 🔜 Phase 9 | Type Annotations & Optional Static Typing | Planned |
| 🔜 Phase 10 | `spm` — SamLang Package Manager | Planned |
| 🔜 Phase 11 | Async/Await & Concurrency | Planned |
| 🔜 Phase 12 | Bytecode Compiler & VM | Planned |

---

## 🤝 Contributing

SamLang is a passion project by [Samrane Ahmed](https://github.com/samrane-ahmed). Contributions, ideas, and feedback are welcome!

- **Report bugs:** [Open an issue](https://github.com/samrane-ahmed/samlang/issues)
- **Suggest features:** [Start a discussion](https://github.com/samrane-ahmed/samlang/issues)
- **Share your `.sl` programs:** Tag `#SamLang` on social media

---

## 📜 License

Proprietary — Created by **Samrane Ahmed**.

See [LICENSE](LICENSE) for details.
