# xihe-compiler

**Repository Path**: luobolaoda/xihe-compiler

## Basic Information

- **Project Name**: xihe-compiler
- **Description**: 羲和语言编译器（Python版）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Xihe Language Compiler

> A native programming language compiler for the Xihe CPU-64

## Project Overview

The Xihe Language Compiler is a complete toolchain that translates Xihe language source code into Xihe CPU-64 machine code.

### Core Features

- **Yin-Yang Binary Support**: Native support for BaGua (Eight Trigrams) numeral system
- **Complete Compilation Pipeline**: Full flow from source code to executable
- **Bootstrap Ready**: Foundation for rewriting the compiler in Xihe language

## Architecture

```
Source Code → Lexing → Parsing → Semantic Analysis → IR → Codegen → Link → Load → Executable
```

## Project Structure

```
xihe-compiler/
├── src/
│   ├── lexer.py              # Lexer (410 lines)
│   ├── parser.py             # Parser (556 lines)
│   ├── semantic.py           # Semantic Analyzer (752 lines)
│   ├── codegen.py            # Code Generator (513 lines)
│   ├── compiler_pipeline.py  # Complete Pipeline (771 lines)
│   ├── assembler.py          # Assembler
│   └── runtime.py            # Runtime Library
├── tests/
│   ├── test_lexer.py         # Lexer Tests (33)
│   ├── test_parser.py        # Parser Tests (40)
│   └── test_integration.py   # Integration Tests (28)
├── docs/
│   └── bootstrap_plan.md     # Bootstrap Plan
├── examples/                 # Example Programs
└── README.md
```

## Quick Start

### Install Dependencies

```bash
pip install ply
```

### Compile Xihe Program

```python
from src.compiler_pipeline import compile

source_code = '''
函数 爻 主函数() {
    爻 x = 四十二;
    返回 x;
}
'''

result = compile(source_code, "output.xh64")
print(f"Compile {'success' if result['success'] else 'failed'}")
```

### Run Tests

```bash
# Unit Tests
python tests/test_lexer.py
python tests/test_parser.py

# Integration Tests
python tests/test_integration.py
```

## Language Features

### Basic Types

> Note: BaGua symbols (乾、兑、离、震、巽、坎、艮、坤) are **BaGua constants**, not type names.

| Type | Description | Size |
|------|-------------|------|
| 爻 | 64-bit signed integer | 8 bytes |
| 浮 | 64-bit double precision float | 8 bytes |
| 符 | Single character | 1 byte |
| 串 | String (array of 符) | Variable |
| 卦 | BaGua enum type | 1 byte |
| 阴阳 | Boolean type | 1 byte |
| 虚 | Void type (no return) | - |

### BaGua Constants

Xihe language natively supports BaGua numerals, following the Yin-Yang Binary Technical Specification:

| Symbol | Value | Description |
|--------|-------|-------------|
| 乾 | 0 | Taiji/Zero |
| 兑 | 1 | Ze (Lake) |
| 离 | 2 | Huo (Fire) |
| 震 | 3 | Lei (Thunder) |
| 巽 | 4 | Feng (Wind) |
| 坎 | 5 | Shui (Water) |
| 艮 | 6 | Shan (Mountain) |
| 坤 | 7 | Di (Earth) |

### Multi-Bagua Literals

Multi-Bagua literals are parsed from **right to left**, each BaGua takes 3 bits (octal):

```
兑乾 = 1×8 + 0 = 8
离巽坎 = 2×8² + 4×8 + 5 = 165
```

**Repeated BaGua Literals**:

| Literal | Formula | Value |
|---------|---------|-------|
| 乾乾 | 0×8 + 0 = 0 | 0 |
| 兑兑 | 1×8 + 1 = 9 | 9 |
| 兑兑兑兑 | (8⁴-1)/7×1 | 585 |
| 兑兑兑兑兑兑兑兑 | (8⁸-1)/7 = 2396745 | 2396745 |
| 坤坤坤坤坤坤坤坤 | 8⁸-1 = 16777215 | 16777215 |

> **Note**: `乾` literals are all zero; other BaGua combinations produce non-zero values.

### Chinese Numeric Constants

For readability, the compiler supports Chinese numeric constants:

| Constant | Value | BaGua |
|----------|-------|-------|
| 零 | 0 | 乾 |
| 壹/一 | 1 | 兑 |
| 贰/二 | 2 | 离 |
| 叁/三 | 3 | 震 |
| 肆/四 | 4 | 巽 |
| 伍/五 | 5 | 坎 |
| 陆/六 | 6 | 艮 |
| 柒/七 | 7 | 坤 |
| 八 | 8 | - |
| 九 | 9 | - |
| 十 | 10 | - |

### Example Program

```cpp
// Factorial function
函数 爻 阶乘(爻 n) {
    如果 (n <= 壹) {
        返回 壹;
    }
    返回 n * 阶乘(n - 壹);
}

// Main function - program entry
函数 爻 主函数() {
    爻 结果 = 阶乘(伍);  // 5! = 120
    返回 结果;           // Return value in $乾 register
}
```

## Registers (Xihe CPU-64)

> Note: At assembly level, `$乾`, `$兑` etc. denote registers R0-R7, which is different from BaGua constants in Xihe language.

Xihe CPU-64 has 8 general-purpose registers:

| Register | Index | Alias | Purpose |
|----------|-------|-------|---------|
| $乾 | R0 | $RV | Accumulator/Return Value |
| $兑 | R1 | - | General Purpose |
| $离 | R2 | - | General Purpose |
| $震 | R3 | $TEMP | Temporary Register |
| $巽 | R4 | - | General Purpose |
| $坎 | R5 | - | General Purpose |
| $艮 | R6 | - | General Purpose |
| $坤 | R7 | $SP | Stack Pointer/Return Address |

### Difference Between Registers and Constants

```
// At Xihe language source level:
爻 x = 乾;      // 乾 is constant, value = 0
爻 y = 兑;      // 兑 is constant, value = 1

// At assembly level:
LOADIMM $乾, 0  // $乾 is register R0
ADD $离, $乾, $兑  // $离, $乾, $兑 are all registers
```

## Executable File Format

Generated `.xh64` files use Xihe CPU-64 executable format:

```
+------------+
| MAGIC (5)  | "XH64\0"
+------------+
| VERSION(2) | 1.0
+------------+
| CODE_LEN(8)| Code Length
+------------+
| ENTRY(8)   | Entry Point
+------------+
| SYM_CNT(4) | Symbol Count
+------------+
| SYMBOLS    | Symbol Table
+------------+
| CODE       | Code Segment
+------------+
```

## Test Results

```
Lexer Tests:        33/33 passed ✓
Parser Tests:       40/40 passed ✓
Integration Tests:   28/28 passed ✓
Total:             101/101 passed ✓
```

## Performance Benchmark

> Test Environment: Python 3.x on macOS Intel

| Test | Compile Time | Code Size |
|------|-------------|-----------|
| Empty function | 0.30 ms | 20 bytes |
| Loop 100x | 0.50 ms | 187 bytes |
| Factorial(10) | 0.49 ms | 430 bytes |
| Fibonacci(15) | 0.52 ms | 731 bytes |

## Bootstrap Roadmap

1. **Current**: Complete Python compiler implementation
2. **Next**: Develop Xihe CPU simulator + enhance compiler with string/file I/O
3. **Following**: Rewrite compiler in Xihe language (bootstrap)
4. **Final**: Compiler fully written in Xihe language

See [Bootstrap Plan](docs/bootstrap_plan.md) for details.

## Related Documents

- [Xihe Language Specification](https://gitee.com/xihe-ecosystem_1/yinyang-binary)
- [Xihe CPU-64 Architecture](https://gitee.com/xihe-ecosystem_1/yinyang-binary)
- [Bootstrap Plan]

## Version History

- v0.2.0: Complete compiler pipeline + integration tests
- v0.1.0: Basic compiler framework

## Author

**Xuān Tóng Workshop (玄同工作室)**

## License

MIT License