Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 28 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# πŸ–₯️ TechLang
# TechLang

**TechLang** is a hacker-themed, stack-based programming language implemented in Python. It features its own custom interpreter, language parser, and playful syntax (`ping`, `crash`, `upload`, etc.). The project includes a CLI, a GUI, and a web-based playground.

---

## 🧠 What is TechLang?
## What is TechLang?

TechLang is designed for experimenting with:

Expand All @@ -15,7 +15,7 @@ TechLang is designed for experimenting with:

---

## πŸ“ Project Structure
## Project Structure

```
TechLang/
Expand Down Expand Up @@ -140,7 +140,7 @@ TechLang/

---

## πŸš€ Getting Started
## Getting Started

### 1. Clone the Repository

Expand All @@ -164,9 +164,9 @@ pip install -r requirements.txt

---

## ▢️ Running TechLang
## Running TechLang

### βœ… Option 1: Interpreter via Python
### Option 1: Interpreter via Python

```python
from techlang.interpreter import run
Expand All @@ -175,7 +175,7 @@ code = "boot ping ping print"
print(run(code)) # Output: 2
```

### βœ… Option 2: Command-Line Interface
### Option 2: Command-Line Interface

```bash
# Using the bundled script
Expand All @@ -191,7 +191,7 @@ tl -i
tl -v examples/hello.tl
```

### βœ… Option 3: Web Playground (Flask)
### Option 3: Web Playground (Flask)

```bash
cd techlang_web
Expand All @@ -201,7 +201,7 @@ python app.py
* Visit: `http://localhost:8080`
* Paste or upload `.tl` code and see output

### βœ… Option 4: GUI (Tkinter)
### Option 4: GUI (Tkinter)

```bash
python playground/gui.py
Expand All @@ -216,7 +216,7 @@ python playground/gui.py

---

## πŸ§ͺ Running Tests
## Running Tests

```bash
python run_tests.py
Expand All @@ -226,7 +226,7 @@ python run_tests.py

---

## ✨ Language Features (Highlights)
## Language Features (Highlights)

### Core & Variables
`boot`, `ping`, `crash`, `print`, `set`, `add`, `sub`, `mul`, `div`, `input`, `upload`, `download`, `debug`, `import`, `alias`, `hack`
Expand All @@ -237,14 +237,14 @@ Three styles supported: `#` single-line, `//` C-style single-line, `/* */` multi
### Control Flow
`loop ... end`, `if ... end`, `while ... end`, `switch/case/default`, `try/catch`, `def ... end`, `call`

### Macro System ✨ NEW
### Macro System (NEW)
- **Conditional Macros**: `macro name if condition param do ... end` - Expand only when condition is true
- **Nested Macros**: Macros can invoke other macros with full parameter substitution
- **Macro Libraries**: Load reusable macro collections from external files
- **REPL Integration**: `:loadmacro` command for interactive macro loading
- See [Advanced Macro Guide](docs/macros-advanced.md) for details

### Enhanced REPL ✨ NEW
### Enhanced REPL (NEW)
- **Persistent State**: Variables, functions, and macros persist across commands
- **Introspection**: `:state` shows all variables, `:macros` lists macros
- **State Management**: `:reset` clears state without restarting
Expand Down Expand Up @@ -288,7 +288,7 @@ Processes: `proc_spawn`, `proc_wait`, `proc_kill`
### Debugger
`breakpoint`, `step`, `continue`, `inspect`, `watch`, `unwatch`, `clear_breakpoints`

### Object-Oriented Programming ✨ NEW
### Object-Oriented Programming (NEW)
- **Classes**: `class Name ... end` with fields, methods, and constructors
- **Inheritance**: `class Child extends Parent` with method overriding
- **Instance Methods**: `method name params ... end` with `self` reference
Expand All @@ -297,7 +297,7 @@ Processes: `proc_spawn`, `proc_wait`, `proc_kill`
- **Type Checking**: `instanceof` for runtime type checks
- See [OOP Guide](docs/oop.md) for complete reference

### First-Class Functions & Closures ✨ NEW
### First-Class Functions & Closures (NEW)
- **Function Values**: `fn name params do ... end` creates callable values
- **Closures**: Functions capture outer scope variables
- **Function References**: `fn_ref funcName var` gets reference to existing function
Expand All @@ -307,21 +307,21 @@ Processes: `proc_spawn`, `proc_wait`, `proc_kill`
- **Lambda Expressions**: `lambda name param "expr"` for simple transforms
- See [Functions Guide](docs/functions.md) for complete reference

### Decorators ✨ NEW
### Decorators (NEW)
- **Decorator Definition**: `decorator name mode do ... end` (mode: before/after/both)
- **Apply Decorator**: `decorate func decorator` wraps function with decorator
- **Built-in Decorators**: `@log` and `@time` for common use cases
- See [Decorators Guide](docs/decorators.md) for complete reference

### Context Managers ✨ NEW
### Context Managers (NEW)
- **Built-in Contexts**: `with timer do ... end`, `with suppress do ... end`
- **File Context**: `with file "path" do ... end` for automatic file handling
- **Lock Context**: `with lock mutex do ... end` for thread safety
- **Transaction**: `with transaction do ... end` for database rollback
- **Custom Contexts**: `context name enter exit do ... end`
- See [Context Managers Guide](docs/context-managers.md) for complete reference

### Async/Await ✨ NEW
### Async/Await (NEW)
- **Async Functions**: `async def name do ... end` for coroutines
- **Await**: `await coroutine -> result` for async results
- **Task Spawning**: `spawn coroutine -> task_id` for background tasks
Expand All @@ -339,7 +339,7 @@ Processes: `proc_spawn`, `proc_wait`, `proc_kill`

---

## πŸ“‚ Example Programs
## Example Programs

All in the `examples/` folder:

Expand Down Expand Up @@ -386,7 +386,7 @@ Or try them in the web playground.

---

## πŸ“¦ Requirements
## Requirements

* Python 3.10+
* `flask` (for web)
Expand All @@ -402,13 +402,13 @@ pip install -r requirements.txt

---

## πŸ€– Future Ideas
## Future Ideas

* βœ… ~~Database transactions and schema introspection~~ (Completed)
* βœ… ~~Debugger with breakpoints and stepping~~ (Completed)
* βœ… ~~JSON support for modern data interchange~~ (Completed)
* βœ… ~~String manipulation operations~~ (Completed)
* βœ… ~~Multi-line comments~~ (Completed)
* Database transactions and schema introspection (Completed)
* Debugger with breakpoints and stepping (Completed)
* JSON support for modern data interchange (Completed)
* String manipulation operations (Completed)
* Multi-line comments (Completed)
* Error highlighting in web playground
* Bytecode version of TechLang
* Language transpiler to Python
Expand All @@ -418,13 +418,13 @@ pip install -r requirements.txt

---

## ❀️ Credits
## Credits

Crafted for hackers, students, and language lovers who want to build something weird, beautiful, and programmable.

---

## πŸ“– Quick Command Reference
## Quick Command Reference

Comprehensive command reference grouped by category. For detailed documentation, see [DOCUMENTATION.md](DOCUMENTATION.md).

Expand Down
28 changes: 14 additions & 14 deletions stl/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The TechLang STL provides reusable modules for common programming tasks. All mod
- `package use stdlib/validation` (or `stl/validation`)
- `call stdlib.validation.is_positive` (or `stl.validation.is_positive`)

## βœ… Runtime Assumptions (STL Compatibility)
## Runtime Assumptions (STL Compatibility)

Some STL modules rely on β€œstore into target” forms of core commands (so helpers can avoid printing intermediate values):

Expand All @@ -25,9 +25,9 @@ Control-flow also accepts operator synonyms used in examples:

- `eq/ne/gt/lt/ge/le` map to `==/!=/>/</>=/<=`.

## πŸ“š Available Modules
## Available Modules

### πŸ”€ strings.tl - String Utilities
### strings.tl - String Utilities
Advanced string manipulation functions.

**Functions:**
Expand Down Expand Up @@ -60,7 +60,7 @@ print padded # Output: 00042

---

### πŸ”’ math.tl - Math Utilities
### math.tl - Math Utilities
Mathematical helper functions.

**Functions:**
Expand Down Expand Up @@ -102,7 +102,7 @@ print result # Output: 120

---

### πŸ“¦ collections.tl - Collections Utilities
### collections.tl - Collections Utilities
Array and dictionary helper functions.

**Array Functions:**
Expand Down Expand Up @@ -147,7 +147,7 @@ print idx # Output: 2

---

### βœ… validation.tl - Validation Utilities
### validation.tl - Validation Utilities
Input validation and type checking functions.

**Numeric Validation:**
Expand Down Expand Up @@ -202,7 +202,7 @@ print meets_min # Output: 1

---

### 🧾 json.tl - JSON Utilities
### json.tl - JSON Utilities
Thin wrappers over core `json_*` commands.

**Functions:**
Expand All @@ -229,7 +229,7 @@ print ok # Output: 0

---

### 🌐 net.tl - Network Utilities
### net.tl - Network Utilities
Convenience wrappers over core `http_*` commands.

**Functions:**
Expand All @@ -251,7 +251,7 @@ call stl.net.get_json url obj status
print status
```

## 🎯 Usage Patterns
## Usage Patterns

### Loading Multiple Modules
```techlang
Expand Down Expand Up @@ -291,7 +291,7 @@ print user_input

---

## πŸ“– Design Philosophy
## Design Philosophy

### Private by Default
All helper functions (prefixed with `_`) are private and not exported. Only documented public API functions are accessible.
Expand All @@ -309,7 +309,7 @@ Functions return values explicitly using the `return` statement. Side effects ar

---

## πŸ› οΈ Extending the Standard Library
## Extending the Standard Library

### Adding a New Module

Expand Down Expand Up @@ -342,7 +342,7 @@ Add tests in `tests/test_stl/py` to verify functionality.

---

## πŸ§ͺ Testing
## Testing

To test stl modules, create a test file that loads and exercises each function:

Expand All @@ -367,7 +367,7 @@ python run_tests.py

---

## πŸ“ Notes
## Notes

### Placeholder Functions
Some functions (like `dict_count`, `is_numeric_string`) are placeholders waiting for core TechLang features:
Expand All @@ -384,7 +384,7 @@ These will be fully implemented when the core language supports the required pri

---

## πŸš€ Future Enhancements
## Future Enhancements

- **stl/io.tl** - Advanced file I/O helpers
- **stl/json.tl** - JSON parsing/manipulation utilities
Expand Down