Metadata-Version: 2.4
Name: nl-compiler
Version: 0.1.0
Summary: NLC - an experimental natural language compiler for demonstrating compiler concepts
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# NLC — 自然语言编译器

> **N**atural **L**anguage **C**ompiler
>
> 一个实验性项目：尝试把自然语言当作编程语言，走一遍完整的编译流程，用于诠释「编译器是如何工作的」以及「自然语言与程序语言的边界在哪里」等概念。

## 这是什么

NLC 是一个**概念验证（Proof of Concept）**性质的实验项目。它并不追求生产可用，也不追求对任意自然语言的理解能力，而是希望通过一个足够小、足够直观的例子，诠释以下概念：

- **编译流水线**：词法分析 → 语法分析 → 语义分析 → 中间表示 → 代码生成/执行，如何应用于自然语言输入；
- **文法与歧义**：自然语言的歧义性在形式文法下是如何产生、又如何被消解的；
- **抽象语法树（AST）**：一句话如何被结构化为可操作的数据；
- **从「理解」到「执行」**：把一句人类语言映射为可运行程序的本质困难与可行路径。

简而言之：**这是一个用来讲解编译器思想的玩具，只不过它的源码是中文/英文句子，而不是 C 或 Python。**

## 设计思路

编译器经典结构被原样借用，仅将输入端替换为自然语言：

```mermaid
flowchart LR
    A[自然语言输入] --> B[词法分析\nLexer]
    B --> C[语法分析\nParser]
    C --> D[语义分析\nSemantic]
    D --> E[中间表示 IR]
    E --> F{后端}
    F -->|解释执行| G[Interpreter]
    F -->|代码生成| H[目标代码]
```

| 阶段 | 输入 | 输出 | 在 NLC 中的难点 |
|------|------|------|-----------------|
| 词法分析 | 原始句子 | 词元序列（tokens） | 中文分词、未登录词 |
| 语法分析 | 词元序列 | AST | 自然语言文法高度递归、歧义严重 |
| 语义分析 | AST | 带类型/含义的 AST | 指代消解、隐含前提 |
| 中间表示 | 语义 AST | IR（如结构化指令） | 如何在「模糊」与「精确」之间取舍 |
| 后端 | IR | 执行结果 / 目标代码 | 把意图映射为确定的计算 |

## 项目状态

**早期实验阶段。** 当前仓库仅包含项目骨架，编译器各阶段尚未实现——这正是实验的起点：从一个空的 `main.py` 出发，逐层构建。

### 路线图

- [ ] 最小词法分析器（针对受控的受限自然语言）
- [ ] 基于文法的语法分析器与 AST 定义
- [ ] 一个刻意保留、随后逐步消解的歧义示例（用于演示）
- [ ] 简单 IR 与树遍历解释器
- [ ] 端到端示例：一句话 → 执行结果
- [ ] 文档：每个阶段的概念诠释与设计取舍

## 约定的输入范围

为了让编译流程可被完整走通，实验会把输入限制在**受限自然语言**（Controlled Natural Language）范围内：

- 固定的小词汇表（指令类动词、名词、数量词等）；
- 明确的句式模板，允许少量合法变体；
- 超出范围的输入明确报错，而不是猜测。

这与真实的 NLP 系统（追求覆盖率与鲁棒性）目标相反——NLC 追求的是**流程的清晰可诠释**。

## 开发环境

本项目使用 [uv](https://docs.astral.sh/uv/) 管理依赖与环境。

```bash
# 安装依赖并创建虚拟环境
uv sync

# 运行入口
uv run main.py
```

要求 Python ≥ 3.12（见 `.python-version`）。

## 目录结构

```
.
├── main.py          # 程序入口
├── pyproject.toml   # 项目元数据（uv 管理）
└── README.md        # 本文档
```

> 目录结构将随编译器各阶段的实现而演进（如 `lexer/`、`parser/`、`ir/`、`backend/`）。

## 非目标

以下**不是** NLC 的目标，以免误解：

- ❌ 构建实用的自然语言理解 / 对话系统；
- ❌ 使用大模型做语义解析（本项目关注的是经典编译技术本身）；
- ❌ 支持任意句式、任意领域的开放输入；
- ❌ 生产环境下的性能与健壮性。

## 许可

待定。
