# Chi Programming Language

[![PyPI version](https://badge.fury.io/py/chi-lang.svg)](https://badge.fury.io/py/chi-lang)
[![Python Support](https://img.shields.io/pypi/pyversions/chi-lang.svg)](https://pypi.org/project/chi-lang/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Chi is a modern, intuitive programming language inspired by Chichewa with seamless Python interoperability. It makes programming accessible using familiar Chichewa keywords while maintaining full programming capabilities.

## Features

🌍 **Chichewa-Inspired Syntax** - Programming keywords in Chichewa  
🐍 **Python Interoperability** - Seamless integration with Python ecosystem  
🚀 **Modern Language Features** - Functions, exception handling, data structures  
📚 **Rich Examples** - Comprehensive example library included  
🔧 **Multiple Interfaces** - CLI, REPL, Python import, and web interface  
🎯 **Educational Focus** - Perfect for learning programming concepts  

## Quick Start

### Installation

```bash
pip install chi-lang
```

### Your First Chi Program

Create a file `hello.chi`:
```chi
onetsa("Moni, dziko!")  # Hello, world!
```

Run it:
```bash
chi run hello.chi
```

## Usage

### Command Line Interface

```bash
# Run a Chi program
chi run program.chi

# Interactive REPL
chi repl

# Execute Chi code directly
chi exec 'onetsa("Hello from command line!")'

# View example code
chi run --see hello_world

# Run built-in examples
chi run --example hello_world
chi run --list-examples

# Translate between Chi and Python
chi translate hello.chi --to python
chi translate hello.py --from python --to chi
```

### Python Integration

```python
# Import and run examples
from chi.examples import hello_world
hello_world.run()

# Access example source code
print(hello_world.content)
hello_world.show()

# List all examples
from chi import examples
examples.help()

# Execute Chi code from Python
from chi import run_code
run_code('onetsa("Hello from Python!")')
```

### Interactive REPL

```bash
$ chi repl
Chi Programming Language REPL 1.0.0
Author: Duncan Masiye
Type 'exit()', 'quit()', 'help()' or press Ctrl+C to quit.
Commands: 'examples()', 'clear()', 'version()'

chi> ika name = "Chi"
chi> onetsa("Welcome to", name)
Welcome to Chi
chi> help()
```

## Language Syntax

### Variables and Data Types
```chi
# Variables (ika = "put/place")
ika name = "Jakesh"
ika age = 25
ika height = 5.8
ika is_student = zoona  # true
ika empty = palibe      # null

# Lists
ika fruits = ndandanda("apple", "banana", "orange")

# Dictionaries  
ika person = kaundula("name", "Alice", "age", 20)
```

### Control Flow
```chi
# If statements (ngati = "if", sizoona = "else")
ngati age wafananitsa 18:
    onetsa("Adult")
sizoona:
    onetsa("Minor")

# Loops (yesani = "while", bwereza = "for")
ika i = 0
yesani i wachepetsedwa 5:
    onetsa("Count:", i)
    ika i = i + 1

bwereza fruit mu fruits:
    onetsa("Fruit:", fruit)
```

### Functions
```chi
# Function definition (panga = "make/create")
panga greet(name):
    onetsa("Moni", name + "!")
    bweza "Hello " + name

# Function call
ika greeting = greet("World")
```

### Built-in Functions
```chi
# I/O Functions
onetsa("Output")           # Print
ika input = funsani("Enter text: ")  # Input

# Type Functions  
ika type = mtundu(42)      # Get type
ika length = kukula("text") # Get length

# Math Functions
ika power = mphamvu(2, 3)   # 2^3 = 8
ika root = muzu(16)         # Square root = 4
ika sum = phatikiza(1, 2, 3, 4)  # Sum = 10
```

## Examples

Chi comes with comprehensive examples covering all language features:

### Basic Examples
- `hello_world` - Simple hello world
- `simple_data_types` - Variable types and declarations  
- `simple_math` - Mathematical operations
- `operators_demo` - All operators (arithmetic, comparison, logical)

### Data Structures
- `simple_lists` - List operations
- `dictionary_operations_demo` - Dictionary methods
- `string_methods_demo` - String manipulation

### Advanced Features
- `control_structures_demo` - If/else, loops, control flow
- `functions_demo` - Function definition and usage
- `exception_handling_demo` - Try/catch error handling
- `file_operations_demo` - File I/O operations

### Real-World Applications
- `real_world_app_demo` - Student grade management system

Run any example:
```bash
chi run --example control_structures_demo
chi run --see functions_demo  # View source code
```

## Development

### Local Development

```bash
# Clone repository (will be available soon)
# git clone https://github.com/chi-lang/chi.git
# cd chi

# For now, install from source or pip
pip install chi-lang

# Install in development mode (if you have source)
pip install -e .

# Format code (optional)
black chi/
```

### Contributing

We welcome contributions! Please contact us at [duncanmasiye16@gmail.com](mailto:duncanmasiye16@gmail.com) to get involved.

1. Email your interest and ideas
2. We'll help you get started
3. GitHub repository coming soon for collaborative development
4. Documentation and contribution guidelines will be available online

## Language Reference

### Keywords
- `ika` - Variable assignment
- `onetsa()` - Print/output function
- `ngati` / `sizoona` - If/else statements
- `yesani` - While loops
- `bwereza` / `mu` - For loops
- `panga` / `bweza` - Function definition/return
- `kuyesera` / `zakanika` - Try/except

### Operators
- Arithmetic: `+`, `-`, `*`, `/`, `**`, `%`
- Comparison: `wafanana` (==), `wasiyana` (!=), `wapambana` (>), etc.
- Logical: `komanso` (AND), `kapena` (OR), `osati` (NOT)

### Data Types
- `mawu` - Strings
- `manambala` - Float numbers
- `manambala_olekeza` - Integer numbers
- `yankho` - Booleans (zoona/zabodza)
- `ndandanda` - Lists
- `kaundula` - Dictionaries
- `palibe` - Null values

## License

MIT License - see LICENSE file for details.

## Author

**Duncan Masiye** - [duncanmasiye16@gmail.com](mailto:duncanmasiye16@gmail.com)

## Support & Contact

- 📧 **Email**: [duncanmasiye16@gmail.com](mailto:duncanmasiye16@gmail.com)
- 🐛 **Bug Reports**: Please email with detailed description
- 💡 **Feature Requests**: Email your suggestions
- 📚 **Documentation**: Coming soon - check back for updates
- 🌐 **Online Resources**: GitHub repository and documentation will be available soon

---

*Chi Programming Language - Making programming accessible in Chichewa!*