Metadata-Version: 2.4
Name: caap
Version: 0.0.5
Summary: CPU AS A PROGRAM
Author-email: tamimdevlopment <tamimdevlopment@hotmail.com>
License: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ⚙️ CAAP (CPU As A Program)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/caap?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/caap)
> 🧠 A simple virtual CPU that executes custom assembly-like instructions inside Python.

CAAP is a lightweight interpreter that simulates a basic CPU.  
It lets you run simple text-based instructions like `SET` and `MOV` to manipulate variables, just like a minimal processor.

---

# 🚀 Features

- 🧠 Simple CPU-like instruction system  
- ⚡ Fast and lightweight (pure Python)  
- 📦 No external dependencies  
- 🧪 Easy to extend with new commands  
- 🎮 Great for learning interpreters and CPU concepts  
- 👀 CAAP provides a low-level memory system to read and write external process memory using powerful pointer-based access.
- 🔥 It supports multi-backend control (ctypes & pymem), dynamic pointer chains, and future tools like scanners and value freezing.

---

# 📥 Installation

```bash
pip install caap
```

---

# 🧑‍💻 Basic Usage

```python
from caap import cpu

cpu = cpu()
@cpu.scommand("SET")
def function(a,b):
    cpu.varb[a] = b
@cpu.scommand("MOV")
def func(a,b):
    cpu.varb[a] = cpu.varb[b]

code = """
SET A, 10
SET B, 20
MOV C, A
"""

result = cpu.run(code)

print(cpu.varb)
```

---

# 📊 Output

```python
{'A': 10, 'B': 20, 'C': 10}
```
---

## 👨‍💻 pointers usage

```python
from caap import cpu

cpu = cpu()

f = cpu.pointers("pymem")

game = f.Pointer("minecraft.exe")

game.set_value("health123",value=999999,type="int")

print(game.get_value("health123"))
```
---

# 📊 Output

```python
999999
```

---
# 📦 Changelog

All notable changes to this project will be documented in this section.

---
## 🚀 Version 0.0.5 ( latest )

### ✨ Added

* Added external process memory modification support (read/write to other applications)
* Added ctypes backend address auto-normalization (string → hex int)
* backends for external process memory modification ( pymem , ctypes )
* Improved memory write stability with pointer handling
* Better error handling for invalid memory addresses
* Added support for stable pointer-chain resolution, allowing memory values to stay accurate even after restarting the target program.
### 🛠️ Fixed

* Fixed crash when passing hex string addresses (e.g. "00D6FCDC")
* Fixed ctypes pointer conversion errors in write operations

### ⚡ Improved

* More stable memory backend behavior
* Cleaner internal address processing pipeline
* Reduced user-side input restrictions for addresses

## 🚀 Version 0.0.4

### ✨ Added

* Nothing

### 🛠️ Fixed

* package cannot find in package manager

### ⚡ Improved

* Nothing

---
## 🚀 Version 0.0.3

### ✨ Added

* Improved command parsing system
* Support for handling empty lines safely
* Better error messages for invalid syntax
* Adds Decorator Pattern
* Adds Debug Mode

### 🛠️ Fixed

* Fixed crash when command arguments are missing
* Fixed parsing issue causing incorrect split results
* Fixed IndexError when processing malformed input

### ⚡ Improved

* Cleaner execution flow inside `run()`
* More stable command execution system

---

## 🚀 Version 0.0.2

### ✨ Added

* Basic CPU system implementation
* `SET` and `MOV` commands
* Custom command registration system (`scommand`)

### 🛠️ Fixed

* Minor bugs in variable handling

---

## 🚀 Version 0.0.1

### 🎉 Initial Release

* Core structure of CAAP
* Basic execution engine
* Variable storage system

---

# 🧠 Notes

* This project is under active development
* Expect frequent updates and improvements
* Feedback and contributions are welcome 🚀


# ⚙️ Supported Instructions

| Instruction | Description |
|------------|------------|
| SET A, value | Assign a value to a variable |
| MOV A, B | Copy value from variable B into A |

---

# 🧠 How It Works

CAAP reads each line of text, splits it into commands, and executes it using an internal memory system (like CPU registers).

Each variable acts like a register inside a virtual CPU.

---

# 🔥 More Examples

## 📌 Example 1: Simple Math Storage

```text
SET X, 5
SET Y, 15
MOV Z, X
```

### Output:
```python
{'X': 5, 'Y': 15, 'Z': 5}
```

---

## 📌 Example 2: Overwriting Values

```text
SET A, 100
SET B, 50
MOV A, B
```

### Output:
```python
{'A': 50, 'B': 50}
```

---

# 🎮 Projects You Can Build With CAAP

## 🧮 1. Mini Calculator Engine
Use CAAP to simulate calculations step by step.

## 🧠 2. Simple AI Decision System
Use variables like memory states for decisions.

## 🎮 3. Text-Based Game Engine
Build HP systems, inventory, and battle logic.

## ⚙️ 4. CPU Simulation Learning Tool
Teach how CPUs work (registers, memory, execution).

## 🧪 5. Custom Language Experiments
Use CAAP as base for your own scripting language.

---

# 🧩 Roadmap

- [✔️] ADD support (A + B)
- [✔️] PRINT instruction
- [✔️] IF conditions
- [✔️] LOOP / JMP support
- [✔️] Error handling improvements
- [✔️] Debug mode (step-by-step execution)

---

# 🤝 Contributing

Feel free to:
- Add new instructions
- Improve execution engine
- Suggest optimizations

---

# 📄 License

This project is licensed under Apache License 2.0

---

# 🧠 Author

Built with ⚙️ and creativity by tamimdevlopment

---

# 🔥 Final Note

CAAP is not just a tool —  
it’s a virtual CPU inside Python 🧠⚡
