Metadata-Version: 2.4
Name: ptyhno
Version: 0.1.0
Summary: 🦄 Ptyhno 编程语言 — 当 Python 喝多了之后的样子
Author: Ptyhno 语言设计委员会
Author-email: noreply@ptyhno.lang
License: WTFPL
Project-URL: Homepage, https://github.com/ptyhno/ptyhno
Project-URL: Source, https://github.com/ptyhno/ptyhno
Classifier: Development Status :: 3 - Alpha
Classifier: License :: Freely Distributable
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Interpreters
Classifier: Topic :: Software Development :: Compilers
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author-email
Dynamic: requires-python

# 🦄 Ptyhno 语言参考

> **版本 0.1.0** — 当 Python 喝多了之后的样子。
>
> Ptyhno 是一种基于 Python 的转译语言。它把你的"中文关键字 + 表情符号 + 行尾噪音"代码转成标准 Python 再执行。本质上就是在 Python 外面包了一层很骚的皮。

---

## 目录

1. [快速开始](#快速开始)
2. [语言规范](#语言规范)
3. [关键字表](#关键字表)
4. [操作符表](#操作符表)
5. [内置函数映射](#内置函数映射)
6. [语法特性](#语法特性)
7. [Import Hook](#import-hook)
8. [扩展名](#扩展名)
9. [完整示例](#完整示例)
10. [工作原理](#工作原理)

---

## 快速开始

### 安装

```bash
pip install ptyhno
```

### 写你的第一个 Ptyhno 程序

创建 `hello.🦄`：

```python
定义 函数 你好(名字):
    打印 "Hello, " + 名字  ～～～
    返回 名字 + "さん"

你好("Ptyhno")
```

在 Python 里使用它：

```python
import ptyhno   # ← 自动安装 import hook
import hello    # ← 自动找 hello.🦄

hello.你好("世界")  # → Hello, 世界
```

### 一行测试

```python
import ptyhno; exec(ptyhno.transpile('打印 "牛逼"  哈哈哈🔥'))
```

### 命令行

```bash
# 直接运行文件
python -m ptyhno 文件.🦄

# 交互式 REPL
python -m ptyhno
🦄> 打印 "你好"  嘿嘿！
```

---

## 语言规范

### 字符集

Ptyhno 源码使用 **UTF-8** 编码。支持的字符范围：

- 全部 Unicode（中文、日文、韩文、表情符号等）
- 标准 ASCII（英文、数字、符号）
- **文件扩展名也支持 Unicode**（`.🦄`、`.疯`）

### 注释

```python
# 这是注释
// 这也是注释
注：这也是注释
```

### 字符串

```python
"双引号字符串"
'单引号字符串'
「中文引号字符串」
【方括号字符串】
```

字符串内的所有内容保持原样，不会被关键字替换或噪音去除影响。

### 标识符

标识符（变量名、函数名）支持 Unicode：

```python
名字 👉 "Ptyhno"
费波那契(10)          # 中文函数名
🚀 👉 100             # 表情变量名
_特殊_名称 👉 42      # 混合命名
```

### 行尾噪音

Ptyhno 最骚的特性。行末可以随意添加语气词和表情，转译器自动忽略：

```python
打印 "你好"  哈哈哈！！！🤪🔥  ～～～  对吧对吧！
返回 结果  搞定搞定！  冲冲冲🚀
```

噪音规则：
- **语气词**: `啊` `哦` `呀` `哈` `嘿` `啦` `吗` `吼` 等
- **标点**: `！` `？` `～` `。` `、` `…` `·` 等
- **所有 emoji**: `🤪` `🔥` `🎉` `🚀` 等
- **网络用语**: `牛逼` `厉害` `搞定` `可以` `冲鸭` `不是吧` 等
- **重复双字词**: `递归递归` `搞定搞定` `对吧对吧对吧`
- **尾随数字**: 噪音后可以跟数字（如`答案就是42`）

### 缩进

Ptyhno 使用缩进表示代码块（和 Python 一致），支持：

- 空格缩进（推荐 4 空格）
- `·` `•` `👉` `*` `-` 等符号也自动转为缩进

```python
定义 函数 嗨():
· 打印 "你好"  哈哈！
👉 打印 "也是缩进"
```

---

## 关键字表

### 函数和类定义

| 你写 | 相当于 |
|------|--------|
| `定义 函数 名字():` | `def 名字():` |
| `函数 名字():` | `def 名字():` |
| `搞一个 名字():` | `def 名字():` |
| `弄一个 名字():` | `def 名字():` |
| `定义 类 名字():` | `class 名字():` |
| `类型 名字():` | `class 名字():` |

### 条件判断

| 你写 | 相当于 |
|------|--------|
| `如果 条件:` | `if 条件:` |
| `要是 条件:` | `if 条件:` |
| `假如 条件:` | `if 条件:` |
| `否则如果 条件:` | `elif 条件:` |
| `再如果 条件:` | `elif 条件:` |
| `否则:` | `else:` |
| `不然:` | `else:` |
| `要不:` | `else:` |

### 循环

| 你写 | 相当于 |
|------|--------|
| `循环 i 在 范围(10):` | `for i in range(10):` |
| `遍历 列表:` | `for 元素 in 列表:` |
| `对于 元素 在 列表:` | `for 元素 in 列表:` |
| `当 条件:` | `while 条件:` |
| `只要 条件:` | `while 条件:` |
| `每当 条件:` | `while 条件:` |

### 返回值

| 你写 | 相当于 |
|------|--------|
| `返回 值` | `return 值` |
| `吐出来 值` | `return 值` |
| `交出 值` | `return 值` |
| `给 值` | `return 值` |

### 输入输出

| 你写 | 相当于 |
|------|--------|
| `打印 内容` | `print(内容)` |
| `说 内容` | `print(内容)` |
| `输出 内容` | `print(内容)` |
| `吼 内容` | `print(内容)` |
| `输入()` | `input()` |
| `问()` | `input()` |

### 布尔值和空值

| 你写 | 相当于 |
|------|--------|
| `真` | `True` |
| `对` | `True` |
| `没错` | `True` |
| `是的` | `True` |
| `假` | `False` |
| `错` | `False` |
| `不对` | `False` |
| `才怪` | `False` |
| `没有` | `None` |
| `空` | `None` |
| `无` | `None` |

### 逻辑运算符

| 你写 | 相当于 |
|------|--------|
| `A 并且 B` | `A and B` |
| `A 跟 B` | `A and B` |
| `A 且 B` | `A and B` |
| `A 或者 B` | `A or B` |
| `A 或 B` | `A or B` |
| `不是 条件` | `not 条件` |
| `并非 条件` | `not 条件` |

### 异常处理

| 你写 | 相当于 |
|------|--------|
| `尝试:` | `try:` |
| `试试:` | `try:` |
| `捕捉 异常:` | `except 异常:` |
| `抓到 异常:` | `except 异常:` |
| `管他呢:` | `finally:` |
| `最终:` | `finally:` |
| `抛 异常` | `raise 异常` |
| `扔 异常` | `raise 异常` |

### 流程控制

| 你写 | 相当于 |
|------|--------|
| `继续` | `continue` |
| `下一个` | `continue` |
| `跳出` | `break` |
| `不玩了` | `break` |
| `懂的都懂` | `pass` |
| `就这样吧` | `pass` |

### 模块

| 你写 | 相当于 |
|------|--------|
| `引入 模块` | `import 模块` |
| `导入 模块` | `import 模块` |
| `从 模块 引入 东西` | `from 模块 import 东西` |
| `东西 以 别名` | `东西 as 别名` |

### 其他

| 你写 | 相当于 |
|------|--------|
| `自己` | `self` |
| `我` | `self` |
| `本尊` | `self` |
| `全局 变量` | `global 变量` |
| `全都要 变量` | `global 变量` |
| `生成 值` | `yield 值` |
| `断言 条件` | `assert 条件` |
| `我赌 条件` | `assert 条件` |
| `删除 变量` | `del 变量` |
| `丢掉 变量` | `del 变量` |
| `省略` | `...` |

---

## 操作符表

### 赋值

| 你写 | 相当于 |
|------|--------|
| `x 👉 值` | `x = 值` |
| `x ← 值` | `x = 值` |
| `x ➡️ 值` | `x = 值` |
| `x 赋值加 1` | `x += 1` |
| `x 赋值减 1` | `x -= 1` |
| `x 赋值乘 2` | `x *= 2` |
| `x 赋值除 2` | `x /= 2` |

### 比较

| 你写 | 相当于 |
|------|--------|
| `a 等于 b` | `a == b` |
| `a 不等于 b` | `a != b` |
| `a 大于 b` | `a > b` |
| `a 小于 b` | `a < b` |
| `a 大于等于 b` | `a >= b` |
| `a 小于等于 b` | `a <= b` |

### 算术

| 你写 | 相当于 |
|------|--------|
| `a ➕ b` | `a + b` |
| `a ➖ b` | `a - b` |
| `a ✖️ b` | `a * b` |
| `a ➗ b` | `a / b` |
| `a 取整 b` | `a // b` |
| `a 取余 b` | `a % b` |
| `a 次方 b` | `a ** b` |
| `a 幂 b` | `a ** b` |

### 中文单字操作符

当两边有空格时，中文字也被识别为操作符：

| 你写 | 相当于 |
|------|--------|
| `a 加 b` | `a + b` |
| `a 减 b` | `a - b` |
| `a 乘 b` | `a * b` |
| `a 除 b` | `a / b` |

> 注意：单字操作符只在两边有空格时替换，这样不会把函数名中的字（如 `加法`）误替换。

### 比较中文词

| 你写 | 相当于 |
|------|--------|
| `A 是 B` | `A is B` |
| `A 在 列表` | `A in 列表` |
| `A 不在 列表` | `A not in 列表` |

---

## 内置函数映射

| 你写 | 相当于 | 说明 |
|------|--------|------|
| `范围(n)` | `range(n)` | 生成范围 |
| `长度(x)` | `len(x)` | 取长度 |
| `类型(x)` | `type(x)` | 取类型 |
| `整数(x)` | `int(x)` | 转整数 |
| `浮点(x)` | `float(x)` | 转浮点 |
| `字符串(x)` | `str(x)` | 转字符串 |
| `列表(x)` | `list(x)` | 转列表 |
| `字典(x)` | `dict(x)` | 转字典 |
| `集合(x)` | `set(x)` | 转集合 |
| `绝对值(x)` | `abs(x)` | 绝对值 |
| `最大值(x, y)` | `max(x, y)` | 最大值 |
| `最小值(x, y)` | `min(x, y)` | 最小值 |
| `求和(列表)` | `sum(列表)` | 求和 |
| `排序(列表)` | `sorted(列表)` | 排序（返回新列表） |
| `所有(x)` | `all(x)` | 所有为真？ |
| `任意(x)` | `any(x)` | 任意为真？ |
| `过滤(函数, 列表)` | `filter(函数, 列表)` | 过滤 |
| `映射(函数, 列表)` | `map(函数, 列表)` | 映射 |
| `压缩(列表1, 列表2)` | `zip(列表1, 列表2)` | 拉链合并 |
| `枚举(列表)` | `enumerate(列表)` | 枚举 |

### 方法映射

| 你写 | 相当于 |
|------|--------|
| `列表.追加(x)` | `list.append(x)` |
| `列表.添加(x)` | `list.append(x)` |
| `列表.弹出()` | `list.pop()` |
| `列表.取出(0)` | `list.pop(0)` |

---

## 语法特性

### 列表推导式

```python
# 中文关键字 + 列表推导式
平方 👉 [x**2 对于 x 在 范围(10) 如果 x % 2 等于 0]
# → [0, 4, 16, 36, 64]
```

### 多变量赋值

```python
a, b, c 👉 1, 2, 3
a, b 👉 b, a       # 交换变量

# 配合中文名
名字, 年龄 👉 "Ptyhno", 1
```

### 比较链

```python
如果 0 小于 x 并且 x 小于 10:
    打印 "x 在 0 和 10 之间"
```

### Lambda 表达式

```python
平方 👉 lambda x: x ** 2
打印 平方(5)  # → 25
```

### With 语句

（即将支持）

### 装饰器

（即将支持）

---

## Import Hook

Ptyhno 的核心机制是 Python 的 **import hook**。当你 `import ptyhno` 时，它会把自己注册到 `sys.meta_path` 中。

之后任何 `import 语句` 都会触发查找过程：

1. Python 先在标准路径找 `.py` 文件
2. 没找到 → PtyhnoFinder 开始工作
3. 找 `.🦄` → `.pty` → `.ptyno` → `.疯` → `.pyt`
4. 找到后 → PtyhnoLoader 读取文件 → 转译 → 编译 → 执行
5. 返回一个正常的 Python 模块对象

这意味着你可以：

```python
# 在你的 Python 项目里混用两种语言
import ptyhno
import fib            # fib.🦄 — 中文代码
import json           # 标准库 — Python
from math import sqrt # 还是正常 Python

print(fib.费波那契(10))  # → 55
```

### 搜索优先级

对于 `import foo`，按顺序找：
1. `foo.py`（标准 Python）
2. `foo.🦄`
3. `foo.pty`
4. `foo.ptyno`
5. `foo.疯`
6. `foo.pyt`

---

## 扩展名

| 扩展名 | 含义 | 推荐度 |
|--------|------|--------|
| `.🦄` | 独角兽！ | ⭐⭐⭐⭐⭐ |
| `.pty` | Ptyhno 缩写 | ⭐⭐⭐⭐ |
| `.ptyno` | 全名 | ⭐⭐⭐ |
| `.疯` | 中文狂野 | ⭐⭐⭐ |
| `.pyt` | 兼容模式 | ⭐⭐ |

---

## 完整示例

### 斐波那契数列

```python
# fib.🦄
定义 函数 费波那契(n):
    如果 n <= 1:
        返回 n
    不然:
        返回 费波那契(n - 1) + 费波那契(n - 2)

循环 i 在 范围(10):
    打印 费波那契(i)
```

```python
>>> import ptyhno, fib
>>> fib.费波那契(10)
55
```

### 排序算法

```python
# sorting.🦄
定义 函数 冒泡排序(arr):
    n 👉 长度(arr)
    循环 i 在 范围(n):
        循环 j 在 范围(0, n - i - 1):
            如果 arr[j] > arr[j + 1]:
                arr[j], arr[j + 1] 👉 arr[j + 1], arr[j]
    返回 arr

定义 函数 快速排序(arr):
    如果 长度(arr) <= 1:
        返回 arr
    基准 👉 arr[0]
    左边 👉 [x 对于 x 在 arr[1:] 如果 x <= 基准]
    右边 👉 [x 对于 x 在 arr[1:] 如果 x > 基准]
    返回 快速排序(左边) + [基准] + 快速排序(右边)
```

### 数学工具

```python
# math.🦄
定义 函数 判断素数(n):
    如果 n < 2:
        返回 假
    循环 i 在 范围(2, int(n ** 0.5) + 1):
        如果 n % i 等于 0:
            返回 假
    返回 真

定义 函数 最大公约数(a, b):
    当 b:
        a, b 👉 b, a % b
    返回 a

定义 函数 统计(数据):
    打印 "总数: " + 字符串(求和(数据))
    打印 "平均: " + 字符串(求和(数据) / 长度(数据))
    打印 "最大: " + 字符串(最大值(数据))
    打印 "最小: " + 字符串(最小值(数据))
```

### 猜数字游戏

```python
# guess.🦄
定义 函数 猜数字游戏():
    秘密 👉 42
    打印 "猜一个数字（1-100）："

    当 真:
        尝试:
            猜 👉 int(输入("> "))
        捕捉:
            打印 "输数字啊笨蛋！！"
            继续

        如果 猜 == 秘密:
            打印 "猜对了！🎉"
            跳出
        否则如果 猜 < 秘密:
            打印 "太小了"
        不然:
            打印 "太大了"
```

### 异常处理

```python
尝试:
    打印 1 / 0
捕捉 ZeroDivisionError:
    打印 "不能除零啊兄弟"  哈哈哈
管他呢:
    打印 "finally 必执行"
```

### 猜数字（完整网络用语版）

```python
定义 函数 猜数字():
    目标 👉 42

    打印 "来猜数字！"  冲冲冲！
    当 真:
        试一下:
            猜 👉 int(问("> "))
        抓到:
            打印 "输数字！"  真是的～
            继续  下一个！

        如果 猜 等于 目标:
            打印 "牛逼！猜对了🔥"  完美！
            不玩了  收工！
        否则如果 猜 小于 目标:
            打印 "小了"  再想想～
        不然:
            打印 "大了"  可惜可惜

猜数字()  启动！
```

---

## 工作原理

### 转译流程

```
Ptyhno 源码
    │
    ▼
Step 1: 提取字符串（保护字符串内容不被后续步骤影响）
    │
    ▼
Step 2: 统一引号（「」【】→ ""）
    │
    ▼
Step 3: 去除注释（# // 注：）
    │
    ▼
Step 4: 标准化缩进（符号缩进 → 空格缩进）
    │
    ▼
Step 5: 替换操作符（👉 ➕ ➖ ✖️ ➗ → = + - * /）
    │
    ▼
Step 6: 去除行尾噪音（循环直到稳定）
    │   ├── 匹配网络用语（SLANG_NOISE）
    │   ├── 匹配重复双字词（REPEATED_BIGRAM）
    │   ├── 匹配重复单字（REPEATED_NOISE）
    │   └── 匹配字符噪音（TRAILING_NOISE）
    │
    ▼
Step 7: 替换关键字（中文 → Python）
    │
    ▼
Step 8: 恢复提取的字符串
    │
    ▼
Step 9: 后处理
    │   ├── print 加括号
    │   ├── 去重 break/continue
    │   └── 压缩空行
    │
    ▼
标准 Python 代码 → compile() → exec()
```

### 技术要点

- **Import Hook**: 通过 `sys.meta_path` 机制实现自定义导入器
- **关键字映射**: 正则 `\b...\b` 词边界匹配，避免中文词内误替
- **复合关键字**: `定义 函数` 优先于 `定义` + `函数` 分别替换
- **噪音循环**: 使用 while 循环反复净化直到行尾不再变化
- **内置函数**: `打印` `范围` `长度` 等在 KEYWORD_MAP 中映射为 Python 内置函数

### 性能

Ptyhno 在转译后生成的是纯 Python 字节码，所以**运行时性能与原生 Python 完全相同**。转译本身的开销只在首次 import 时发生，之后模块被缓存。

---

## 项目结构

```
ptyhno/
├── ptyhno/
│   ├── __init__.py       # 包入口
│   ├── transpiler.py     # 转译引擎（Ptyhno → Python）
│   └── loader.py         # Import Hook 实现
├── examples/
│   ├── fib.🦄            # 斐波那契数列
│   ├── sorting.🦄        # 排序算法
│   ├── math.🦄           # 数学工具
│   └── guess.🦄          # 猜数字游戏
├── README.md             # 本文件
├── CHEATSHEET.md         # 快速参考小抄
├── setup.py              # 安装脚本
├── pyproject.toml        # 项目配置
├── test.py               # 测试套件（10项测试）
└── final_test.py         # 最终验收测试
```

---

## 许可

WTFPL — Do What The Fuck You Want To Public License

## 贡献

这是我们的语言，想加什么关键字就加什么关键字！
PR 永远欢迎，issue 永远开放，创意永远不嫌多 🦄
