Metadata-Version: 2.4
Name: duan
Version: 1.7.0
Summary: 段言（Duan）— 中文自然语言编程语言
Author: Duan Contributors
License: MIT
Project-URL: Homepage, https://github.com/skywalk163/duan
Project-URL: Source, https://github.com/skywalk163/duan
Project-URL: BugTracker, https://github.com/skywalk163/duan/issues
Project-URL: Documentation, https://github.com/skywalk163/duan/tree/main/docs
Keywords: programming-language,chinese,nlp,compiler,hm-inference,null-safety,module-system
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: antlr4-python3-runtime>=4.13
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: autopep8>=2.0.0; extra == "dev"
Provides-Extra: llvm
Provides-Extra: repl
Requires-Dist: prompt-toolkit>=3.0.0; extra == "repl"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Dynamic: license-file

# 段言（DuanLang）编程语言

**段言**是一门基于中文的现代化编程语言，采用中文关键字，让编程更加直观易懂。

## 特性

- **中文关键字**：使用中文关键字如`遍历`、`如果`、`那么`等
- **纯缩进语法**：v3.x 中文关键字，类似 Python 的缩进风格，无"结束"关键字
- **统一编译器**：手写递归下降解析器 + Python 代码生成
- **LLVM 后端**：支持原生编译为 EXE，typed 模式性能优异，跨平台支持 Windows/Linux
- **标准库**：23 个中文命名模块（日志、表格、CSV、JSON 等）
- **泛型系统**：泛型函数、泛型类、泛型方法
- **模块系统**：导入/导出、包管理、跨模块继承
- **类与对象**：完整面向对象编程，支持继承、构造函数、运算符重载、类方法/静态方法
- **异常处理**：完整 try-catch-finally，自定义异常类、多重捕获、栈追踪、异常链
- **字典类型**：内置字典/映射类型，支持键值对操作
- **列表优化**：动态数组实现，O(1) 随机访问和均摊 O(1) 追加性能
- **可空类型**：null 安全检查、空合并、安全获取
- **开发工具链**：REPL、调试器、LSP 语言服务器、VS Code 插件
- **性能优化**：常量折叠、死代码消除、循环不变量外提

## 安装

> **注意**：PyPI 包 `pip install duan` 暂未上线，请使用源码安装方式。

```bash
# 从源码安装（当前推荐方式）
git clone https://github.com/skywalk163/duan.git
cd duan
pip install -e .
```

安装后即可使用 `duan` 命令：
```bash
duan --version
duan --help
```

## 快速开始

### 3 步跑起来

**第1步：安装**
```bash
git clone https://github.com/skywalk163/duan.git
cd duan
pip install -e .
```

**第2步：创建程序**
```段言
# hello.duan
打印 "你好，段言！"
```

**第3步：运行**
```bash
duan run hello.duan
```

### Hello World

```段言
打印 "你好，世界！"
```

### 变量和函数

```段言
段落 加一 接收 数：
    返回 数 加 1
```

### 条件语句

```段言
如果 年龄 大于 18 那么：
    打印 "成年人"
否则：
    打印 "未成年人"
```

### 循环

```段言
遍历 项 在 列表：
    打印 项
```

## 编译运行

```bash
# 解释执行（推荐）
duan run hello.duan

# 编译为 Python 文件
duan compile hello.duan -o hello.py

# 编译为 Windows EXE（需安装 pyinstaller）
pip install pyinstaller
duan compile hello.duan -o hello.exe

# LLVM 原生编译（需安装 clang/LLVM）
duan compile hello.duan --backend llvm-typed -o hello.exe
```

后端选择：
```bash
# SRC 后端（3.x 纯缩进语法，推荐，Python 解释执行）
duan run hello.duan --backend src

# ANTLR 后端（兼容模式，支持 v3 纯缩进语法）
duan run hello.duan --backend antlr

# LLVM string 模式（原生编译，字符串类型系统）
duan compile hello.duan --backend llvm -o hello.exe

# LLVM typed 模式（原生编译，DuanValue 类型系统，推荐）
duan compile hello.duan --backend llvm-typed -o hello.exe
```

## 项目结构

```
duan/
├── src/                 # 核心编译器
│   ├── lexer.py        # 词法分析器
│   ├── parser_stmt.py  # 语法分析器
│   ├── ast_nodes.py    # AST 节点定义
│   ├── compiler.py     # 编译器主体
│   ├── llvm/           # LLVM 后端
│   │   ├── codegen.py       # LLVM 代码生成（string 模式）
│   │   ├── codegen_typed.py # LLVM 代码生成（typed 模式）
│   │   ├── runtime_typed.c  # typed 模式运行时库
│   │   ├── compiler.py      # LLVM 编译入口
│   │   └── core.py          # 代码生成核心
│   ├── optimizer/      # 代码优化器（常量折叠、死代码消除等）
│   └── ...
├── cli/                 # 命令行工具
│   └── duan.py         # CLI 入口
├── stdlib/              # 标准库（23 个模块）
│   ├── 日志.duan/py
│   ├── 表格.duan/py
│   ├── JSON.duan/py
│   └── ...
├── antlrparser/         # ANTLR 后端
│   ├── indent_preprocessor.py  # v3 缩进语法预处理
│   └── ...
├── lsp/                 # LSP 语言服务器
├── benchmarks/          # 性能基准测试
├── examples/            # 示例程序
├── tests/               # 测试（unit / integration / e2e）
└── docs/                # 文档
```

## 编译器架构

| 组件 | 说明 |
|------|------|
| 词法分析 | 手写词法分析器，支持 Unicode 中文关键字 |
| 语法分析 | 递归下降解析器，v3.x 纯缩进语法 |
| 类型检查 | Hindley-Milner 全局类型推断 |
| 代码生成（Python） | Python 代码生成（类型擦除策略） |
| 代码生成（LLVM） | LLVM IR 生成，DuanValue 类型化后端 |
| 运行时（C） | typed 模式运行时库，提供基础操作实现 |
| 优化器 | 常量折叠、死代码消除、循环不变量外提 |

## 语法参考（v3.1）

> 当前版本语法：纯缩进式 + 句号可选

| 段言 | 说明 |
|------|------|
| `设 X 为 Y`（推荐） / `X 等于 Y` / `定义 X 等于 Y` | 变量声明 |
| `段落 名 接收 参数：`（`段落`可简写为`段`） | 函数定义 |
| `如果 条件 那么：` | 条件语句 |
| `遍历 X 在 列表：` | 遍历循环 |
| `当 条件：` | 当循环 |
| `返回 X` | 返回值 |
| `打印 X` | 打印输出 |
| `类 名称：` | 类定义 |
| `类 子类 继承 父类：` | 类继承 |
| `属性 名称` | 类属性声明 |
| `构造 接收 参数：` | 构造函数 |
| `己属性名` | 访问自身属性（对应 self.属性名） |
| `父构造(参数)` | 调用父类构造函数（对应 super().__init__()） |
| `新建 类名(参数)` | 实例化对象 |
| `从 模块 导入 符号` | 从模块导入 |
| `导入 模块` | 导入整个模块 |
| `导出 符号列表` | 导出符号 |
| `尝试：... 捕获 错误 为 e：... 最终：...` | 异常处理 |
| `抛出 异常类型(消息)` | 抛出异常 |

### 类示例

```段言
类 动物：
  属性 名字
  构造 接收 名字：
    己名字 为 名字
  段落 介绍：
    打印 "我叫" 加 己名字

类 狗 继承 动物：
  段落 叫声：
    打印 "汪汪汪"

设 小狗 为 新建 狗("旺财")
小狗.介绍()
小狗.叫声()
```

### 模块示例

```段言
// math_utils.duan
段落 加法 接收 a, b：
  返回 a 加 b
导出 加法

// main.duan
从 math_utils 导入 加法
打印 加法(3, 5)
```

## 文档导航

> **新手从哪开始读？** 推荐顺序：[快速开始](docs/getting-started.md) → [用户手册](docs/USER_MANUAL.md) → [语法参考](docs/syntax.md) → [统一语法规范](docs/统一语法规范_v3.1.md)

| 文档 | 适用人群 | 内容简介 |
|------|---------|---------|
| [快速开始](docs/getting-started.md) | 新手 | 安装、第一个程序、常用命令 |
| [用户手册](docs/USER_MANUAL.md) | 所有用户 | 完整语法教程 + 示例 + FAQ，系统学习段言 |
| [语法参考](docs/syntax.md) | 所有用户 | 简洁的语法速查表，快速查阅 |
| [统一语法规范 v3.1](docs/统一语法规范_v3.1.md) | 高级用户/贡献者 | 最权威、最完整的语法规范，含迁移对比表 |
| [标准库](docs/stdlib.md) | 所有用户 | 23 个标准库模块说明 |
| [API 参考](docs/API_REFERENCE.md) | 高级用户 | Python API 接口文档 |
| [工具链](docs/tools.md) | 开发者 | CLI、调试器、LSP 等工具说明 |
| [架构设计](docs/architecture.md) | 贡献者 | 编译器架构说明 |
| [开发指南](docs/DEVELOPMENT_GUIDE.md) | 贡献者 | 开发规范和流程 |

更多文档请查看 [docs/ 目录](docs/index.md)

## 开发

### 运行测试

```bash
python -m pytest tests/
```

### 代码格式

项目使用中文注释和 UTF-8 编码。

## 许可证

本项目采用 MIT 许可证。
