Metadata-Version: 2.4
Name: pb-lang
Version: 0.3.1
Summary: PB 编程语言：面向中文初学者的 Python 友好中文语法解释器
Author: PengBooo / Pengbo
License: MIT
Keywords: python,chinese,interpreter,education,pb,pengbo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Natural Language :: Chinese (Simplified)
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# PB 编程语言

> **PB = PengBooo 的中文编程语言。**
> 用中文写代码，底层翻译成 Python 执行；适合编程小白入门，也适合想用中文快速表达逻辑的人。

```text
 ____                  ____
|  _ \ ___ _ __   __ _| __ )  ___   ___   ___
| |_) / _ \ '_ \ / _` |  _ \ / _ \ / _ \ / _ \
|  __/  __/ | | | (_| | |_) | (_) | (_) | (_) |
|_|   \___|_| |_|\__, |____/ \___/ \___/ \___/
                 |___/
```

| 项目 | 内容 |
|---|---|
| 语言名称 | **PB** |
| 当前版本 | **0.3.1** |
| 作者 | **PengBooo / 鹏博** |
| 适合人群 | 零基础初学者、中文编程学习者、Python 入门者 |
| 核心原理 | PB 中文语法 → Python 代码 → 执行 |
| 推荐文件后缀 | **`.pb`**（旧 `.zhpy` 文件继续兼容） |

---

## 1. 先跑起来

### 方法 A：运行一个文件

```bash
python3 zhpy.py tests/test_pb_extension.pb
```

安装后也可以用：

```bash
pb tests/test_pb_extension.pb
```

> 新项目推荐使用 `.pb` 后缀；旧的 `.zhpy` 测试和程序仍然可以继续运行。

### 方法 B：直接执行一句话

```bash
python3 zhpy.py -c '输出("你好，PB！")'
```

输出：

```text
你好，PB！
```

### 方法 C：进入交互模式

```bash
python3 zhpy.py
```

你会看到启动页：

```text
PB 编程语言 0.3.1  (中文语法 → Python 执行)
作者: PengBooo / 鹏博
输入 help 或 帮助 查看用法；输入 退出 离开。
PB >>>
```

然后输入：

```pb
输出("我开始学 PB 了！")
```

退出交互模式：

```pb
退出
```

---

## 2. 最小 PB 程序

新建文件 `hello.pb`（PB 推荐使用 `.pb` 后缀）：

```pb
输出("你好，我是 PB！")
输出("我可以用中文写程序。")
```

运行：

```bash
python3 zhpy.py hello.pb
```

---

## 3. 小白先懂这 5 件事

| 概念 | 人话解释 | PB 例子 |
|---|---|---|
| 输出 | 让电脑显示一句话 | `输出("你好")` |
| 变量 | 给一个值起名字 | `年龄 = 18` |
| 条件 | 如果……就……否则…… | `如果 年龄 大于 18 则` |
| 循环 | 重复做一件事 | `对于 i 在 范围(3) 执行` |
| 函数 | 把一段代码打包成一个名字 | `定义 问候():` |

---

## 4. 基础语法

### 4.1 输出内容

```pb
输出("你好")
输出(123)
输出("年龄是", 18)
```

### 4.2 注释：写给人看的说明

```pb
# 这一行不会被执行
输出("上面是注释")
```

### 4.3 变量：保存数据

```pb
名字 = "小明"
年龄 = 18
身高 = 1.75

输出(名字)
输出(年龄)
输出(身高)
```

也支持中文句式：

```pb
将 分数 定义为 100
输出(分数)
```

### 4.4 常见数据类型

```pb
文本 = "你好"
整数 = 100
小数 = 3.14
是否成年 = 真
空值 = 空

输出(文本, 整数, 小数, 是否成年, 空值)
```

| PB | Python 含义 |
|---|---|
| `真` | `True` |
| `假` | `False` |
| `空` | `None` |

---

## 5. 运算符

### 5.1 数学运算

```pb
输出(10 加 3)      # 13
输出(10 减 3)      # 7
输出(10 乘 3)      # 30
输出(10 除以 3)    # 3.333...
输出(10 整除 3)    # 3
输出(10 取余 3)    # 1
输出(2 的次方 3)   # 8
```

也可以混用 Python 符号：

```pb
输出(10 + 3)
输出(10 - 3)
输出(10 * 3)
输出(10 / 3)
```

### 5.2 比较运算

```pb
年龄 = 20

输出(年龄 大于 18)
输出(年龄 小于 18)
输出(年龄 等于 20)
输出(年龄 不等于 30)
输出(年龄 大于等于 20)
输出(年龄 小于等于 20)
```

### 5.3 逻辑运算

```pb
年龄 = 20
有票 = 真

如果 年龄 大于等于 18 并且 有票 则
    输出("可以入场")

如果 年龄 小于 18 或者 有票 则
    输出("满足至少一个条件")

如果 非 假 则
    输出("非假就是真")
```

| PB | Python |
|---|---|
| `并且` | `and` |
| `或者` | `or` |
| `非` | `not` |

---

## 6. 条件判断

### 6.1 如果

```pb
年龄 = 18

如果 年龄 大于等于 18 则
    输出("成年人")
```

### 6.2 如果 / 否则

```pb
分数 = 59

如果 分数 大于等于 60 则
    输出("及格")
否则:
    输出("继续努力")
```

### 6.3 多条件判断

```pb
分数 = 85

如果 分数 大于等于 90 则
    输出("优秀")
否则如果 分数 大于等于 60 则
    输出("及格")
否则:
    输出("不及格")
```

---

## 7. 循环：重复做事

### 7.1 对于循环

```pb
对于 i 在 范围(5) 执行
    输出(i)
```

输出 0 到 4。

### 7.2 遍历列表

```pb
水果列表 = ["苹果", "香蕉", "西瓜"]

对于 水果 在 水果列表 执行
    输出(水果)
```

### 7.3 当循环

```pb
数字 = 3

当 数字 大于 0:
    输出(数字)
    数字 = 数字 减 1
```

### 7.4 跳过和停止

```pb
对于 i 在 范围(5) 执行
    如果 i 等于 2 则
        继续
    如果 i 等于 4 则
        跳出
    输出(i)
```

| PB | 含义 |
|---|---|
| `继续` | 跳过本轮循环 |
| `跳出` | 结束整个循环 |

---

## 8. 常用容器

### 8.1 列表：一排数据

```pb
数字们 = [1, 2, 3]
数字们.追加(4)

输出(数字们)
输出(数字们[0])
输出(长度(数字们))
```

### 8.2 字典：键值对

```pb
学生 = {
    "名字": "小明",
    "年龄": 18
}

输出(学生["名字"])
学生["年龄"] = 19
输出(学生)
```

### 8.3 元组：不可修改的一组数据

```pb
坐标 = (10, 20)
输出(坐标[0])
```

### 8.4 集合：不重复的数据

```pb
数字集合 = {1, 2, 2, 3}
输出(数字集合)
```

---

## 9. 函数：把代码打包

### 9.1 无参数函数

```pb
定义 问候():
    输出("你好！")

问候()
```

### 9.2 有参数函数

```pb
定义 加法(a, b):
    返回 a 加 b

结果 = 加法(3, 5)
输出(结果)
```

### 9.3 简写函数

```pb
定义 打招呼:
    输出("大家好")

打招呼()
```

---

## 10. 类：创建自己的对象

如果你刚开始学，可以先跳过本节。类适合描述“一个东西”。

```pb
类 人:
    定义 __init__(自身, 名字):
        self.名字 = 名字

    定义 介绍(自身):
        输出(f"我是 {self.名字}")

小明 = 人("小明")
小明.介绍()
```

### 10.1 类内方法简写

类里面无参数方法可以省略 `自身`：

```pb
类 猫:
    定义 叫:
        输出("喵喵")

猫咪 = 猫()
猫咪.叫()
```

---

## 11. 属性、装饰器、Getter / Setter

### 11.1 中文属性分组写法

```pb
类 计数器:
    定义 __init__(自身, 初始值):
        self._值 = 初始值

    属性:
        def 获取值:
            返回 self._值

        def 设置值:
            如果 值 大于等于 0 则
                self._值 = 值
            否则:
                self._值 = 0

c = 计数器(5)
输出(c.获取值())
c.设置值(-10)
输出(c.获取值())
```

### 11.2 原生 `@property` 写法

```pb
类 温度计:
    定义 __init__(自身, 摄氏度):
        self._摄氏度 = 摄氏度

    @property
    定义 摄氏度(自身):
        返回 self._摄氏度

    @摄氏度.setter
    定义 摄氏度(自身, 值):
        如果 值 小于 -273.15 则
            抛出 值错误("温度不能低于绝对零度")
        self._摄氏度 = 值

t = 温度计(20)
输出(t.摄氏度)
t.摄氏度 = 30
输出(t.摄氏度)
```

### 11.3 静态方法和类方法

```pb
类 工具:
    @staticmethod
    定义 加(a, b):
        返回 a 加 b

    @classmethod
    定义 名称(cls):
        返回 cls.__name__

输出(工具.加(1, 2))
输出(工具.名称())
```

---

## 12. 生成器：一个一个地产生数据

```pb
定义 数数():
    产生 1
    产生 2
    产生 3

对于 x 在 数数() 执行
    输出(x)
```

在类中也支持：

```pb
类 序列:
    定义 生成:
        产生 1
        产生 2

s = 序列()
对于 x 在 s.生成 执行
    输出(x)
```

---

## 13. 枚举类

枚举适合表示固定选项，比如颜色、方向、状态。

```pb
枚举类 颜色:
    红色 = 1
    绿色 = 2
    蓝色 = 3

输出(颜色.红色)
输出(颜色.红色.名称)
输出(颜色.红色.值)

对于 item 在 颜色 执行
    输出(f"{item.名称}:{item.值}")
```

中文属性：

| 属性 | 含义 |
|---|---|
| `.名称` | 枚举名字 |
| `.名字` | 枚举名字 |
| `.值` | 枚举值 |

---

## 14. 异常处理：程序出错时怎么办

```pb
尝试
    x = 10 除以 0
捕获 零除错误 作为 e
    输出("不能除以 0")
最终
    输出("无论如何都会执行")
```

也可以抛出错误：

```pb
抛出 值错误("这里的值不对")
```

常见中文异常：

| PB | Python |
|---|---|
| `异常` | `Exception` |
| `值错误` | `ValueError` |
| `类型错误` | `TypeError` |
| `索引错误` | `IndexError` |
| `键错误` | `KeyError` |
| `零除错误` | `ZeroDivisionError` |
| `文件未找到错误` | `FileNotFoundError` |

---

## 15. 文件操作

```pb
导入 文件操作

文件操作.写入文件("/tmp/demo.txt", "你好 PB")
内容 = 文件操作.读取文件("/tmp/demo.txt")
输出(内容)

文件操作.追加文件("/tmp/demo.txt", "\n第二行")
输出(文件操作.文件存在("/tmp/demo.txt"))
输出(文件操作.获取文件大小("/tmp/demo.txt"))
文件操作.删除文件("/tmp/demo.txt")
```

---

## 16. 中文标准库

PB 内置了一批中文模块名，方便初学者直接使用。

### 16.1 数学

```pb
导入 数学

输出(数学.平方根(16))
输出(数学.正弦(数学.圆周率 / 2))
输出(数学.向上取整(3.2))
```

### 16.2 随机

```pb
导入 随机

输出(随机.随机数())
输出(随机.随机整数(1, 10))
输出(随机.随机选择(["苹果", "香蕉", "西瓜"]))
```

### 16.3 时间 / 日期时间

```pb
导入 时间
导入 日期时间

输出(时间.当前时间())
时间.睡眠(1)
输出(日期时间.现在())
```

### 16.4 正则

```pb
导入 正则

结果 = 正则.查找所有("\\d+", "年龄18，分数100")
输出(结果)
```

### 16.5 JSON

```pb
导入 json模块

文本 = json模块.转换为字符串({"名字": "小明"})
输出(文本)
输出(json模块.解析(文本))
```

### 16.6 路径

```pb
导入 路径

p = 路径.路径对象("/tmp/demo.txt")
输出(p.名称)
输出(p.后缀)
输出(p.父目录)
```

### 16.7 集合工具

```pb
导入 集合工具

计数 = 集合工具.计数器(["苹果", "香蕉", "苹果"])
输出(计数["苹果"])

队列 = 集合工具.双端队列()
队列.追加(1)
队列.追加(2)
输出(队列)
```

### 16.8 CSV

```pb
导入 CSV模块

文本 = "名字,年龄\n张三,18\n李四,20\n"
行列表 = 列表(CSV模块.字典读取器(文本.分割行()))
输出(行列表[0]["名字"])
```

### 16.9 哈希

```pb
导入 哈希

输出(哈希.SHA256文本("abc"))
输出(哈希.MD5文本("abc"))
```

### 16.10 字符串模块

```pb
导入 字符串模块

输出(字符串模块.小写字母)
输出(字符串模块.大写字母)
输出(字符串模块.数字字符)
```

### 16.11 拷贝

```pb
导入 拷贝

原始 = {"列表": [1, 2, 3]}
复制品 = 拷贝.深拷贝(原始)
复制品["列表"].追加(4)

输出(原始)
输出(复制品)
```

### 16.12 类型提示

```pb
导入 类型提示

输出(类型提示.列表)
输出(类型提示.字典)
输出(类型提示.可选)
```

### 16.13 标准库总表

| 中文模块 | 对应 Python 模块 | 常用中文功能 |
|---|---|---|
| `数学` | `math` | 平方根、正弦、余弦、圆周率 |
| `随机` | `random` | 随机数、随机整数、随机选择 |
| `时间` | `time` | 睡眠、当前时间 |
| `日期时间` | `datetime` | 日期、时间、现在 |
| `正则` | `re` | 匹配、搜索、查找所有、替换 |
| `json模块` | `json` | 解析、加载、转换为字符串 |
| `文件操作` | 文件工具 | 读写文件、追加文件、删除文件 |
| `路径` | `pathlib` | 路径对象、名称、后缀、父目录 |
| `集合工具` | `collections` | 计数器、双端队列、默认字典 |
| `CSV模块` | `csv` | 读取器、写入器、字典读取器 |
| `哈希` | `hashlib` | SHA256文本、MD5文本、摘要 |
| `字符串模块` | `string` | 小写字母、大写字母、数字字符 |
| `拷贝` | `copy` | 浅拷贝、深拷贝 |
| `类型提示` | `typing` | 任意、可选、联合、列表、字典 |
| `迭代工具` | `itertools` | 排列、组合等 |
| `函数工具` | `functools` | 缓存、部分应用等 |
| `数学统计` | `statistics` | 平均值、中位数等 |
| `系统` | `sys` | 系统相关功能 |
| `操作系统` | `os` | 操作系统相关功能 |

---

## 17. 常用中文内置函数

| PB | Python | 例子 |
|---|---|---|
| `输出` | `print` | `输出("你好")` |
| `输入` | `input` | `名字 = 输入("你叫什么？")` |
| `范围` | `range` | `范围(5)` |
| `长度` | `len` | `长度([1,2,3])` |
| `列表` | `list` | `列表("abc")` |
| `字典` | `dict` | `字典()` |
| `集合` | `set` | `集合([1,1,2])` |
| `元组` | `tuple` | `元组([1,2])` |
| `整数` | `int` | `整数("123")` |
| `浮点数` | `float` | `浮点数("3.14")` |
| `字符串` | `str` | `字符串(123)` |
| `布尔值` | `bool` | `布尔值(1)` |
| `最大值` | `max` | `最大值([1,2,3])` |
| `最小值` | `min` | `最小值([1,2,3])` |
| `求和` | `sum` | `求和([1,2,3])` |
| `排序` | `sorted` | `排序([3,1,2])` |
| `枚举` | `enumerate` | `枚举(["a", "b"])` |
| `打开` | `open` | `打开("a.txt")` |

---

## 18. 中文字符串方法

```pb
文本 = "  A,B,C  "

输出(文本.去空白())
输出(文本.替换("A", "一"))
输出("A\nB\nC".分割行())
输出("A,B,C".分割(","))
```

| PB 方法 | Python 方法 |
|---|---|
| `.分割行()` | `.splitlines()` |
| `.分割()` | `.split()` |
| `.替换(a, b)` | `.replace(a, b)` |
| `.去空白()` | `.strip()` |

---

## 19. 文件后缀：推荐 `.pb`，兼容 `.zhpy`

PB 现在正式推荐使用 `.pb` 作为程序文件后缀：

```text
hello.pb
calculator.pb
my_first_program.pb
```

历史文件后缀 `.zhpy` 仍然兼容，不需要立刻改名：

```bash
python3 zhpy.py old_program.zhpy
pb old_program.zhpy
```

如果你想迁移旧文件，只需要改文件名：

```bash
mv old_program.zhpy old_program.pb
python3 zhpy.py old_program.pb
```

项目中提供了 `.pb` 示例测试：

```bash
python3 zhpy.py tests/test_pb_extension.pb
```

---

## 20. 编译成 Python 看看

PB 可以只翻译，不执行：

```bash
python3 zhpy.py --compile tests/test_enum.zhpy
```

输出会显示翻译后的 Python 代码，适合学习“中文语法和 Python 的对应关系”。

---

## 21. 安装成命令行工具

```bash
python3 -m pip install .
```

安装后可以使用：

```bash
pb --version
pb -c '输出("命令行运行成功")'
pb tests/test_pb_extension.pb
```

> 新项目推荐使用 `.pb` 后缀；旧的 `.zhpy` 测试和程序仍然可以继续运行。

旧命令 `zhpy` 仍保留，旧 `.zhpy` 文件也仍可运行，方便兼容历史用法。

---

## 22. 运行测试

运行所有主要测试：

```bash
for f in \
  tests/test_phase1.zhpy \
  tests/test_phase2.zhpy \
  tests/test_phase3.zhpy \
  tests/test_phase4.zhpy \
  tests/test_phase5_basic.zhpy \
  tests/test_phase5_simple.zhpy \
  tests/test_phase5.zhpy \
  tests/test_enum.zhpy \
  tests/test_edge_cases.zhpy \
  tests/test_stdlib_extensions.zhpy \
  tests/test_property_setter.zhpy \
  tests/test_more_stdlib.zhpy \
  tests/test_pb_extension.pb; do
  echo "===== $f ====="
  python3 zhpy.py "$f" || exit 1
done
```

当前已验证：全部通过。

---

## 23. 项目结构

```text
zhpy.py                 # PB 解释器、翻译器、CLI 入口
stdlib/                 # 中文标准库封装模块
tests/                  # 测试程序（推荐 .pb，兼容 .zhpy）
README.md               # 使用说明
PROJECT_STATE.json      # 项目状态记录
pyproject.toml          # Python 包配置，提供 pb / zhpy 命令
setup.py                # 打包兼容入口
```

---

## 24. 已知限制

- PB 当前是“源码翻译执行器”，不是完整独立虚拟机。
- 复杂 Python 语法可以直接混用英文 Python 写法。
- 部分中文简写是约定式支持，例如 `设置xxx` 自动使用 `值` 参数。
- 静态方法参数推断只对常见简写做了兼容；复杂方法建议显式写参数。

---

## 25. 版本记录

### v0.3.1

- 正式推荐 `.pb` 作为 PB 程序文件后缀。
- 新增 `tests/test_pb_extension.pb`，验证 `.pb` 文件可直接运行。
- README 增加 `.zhpy` → `.pb` 迁移说明。
- 发布包版本更新为 `pb-lang 0.3.1`。

### v0.3.0

- 项目语言名称改为 **PB**。
- 新增启动页，展示版本、作者和 **PengBooo** ASCII 艺术字。
- 新增 `pb` 命令，保留 `zhpy` 兼容旧命令。
- README 全面重写：面向小白、列举完整语法、优化布局。
- 支持原生 `@property` / `@属性.setter`。
- 新增标准库：`字符串模块`、`拷贝`、`类型提示`。

### v0.2.0

- Phase 1–5 完成。
- 支持枚举类、生成器、异常、文件操作、中文标准库扩展。
- 支持 CLI 打包。
