meaoiu 0.1.0

package/LANGUAGE_GUIDE.md

@@ -0,0 +1,511 @@
+# 喵谕语言半解
+
+> 不可以学不会喵！
+
+---
+
+## 基本规矩喵
+
+### 尾符
+句末必须有 `~`，没有尾巴是残疾的喵~ 忘了写就等着被骂吧~
+```miu
+蹭我~	(对喵)
+蹭你	(错喵，尾巴在哪里)
+```
+
+### 注释
+悄悄话用圆括号包裹，可以套很多层喵~ 多少层都无所谓，反正没人看得懂喵~
+```miu
+(这是一条悄悄话)
+(这是 (一条悄悄的悄悄话) 悄悄话)
+```
+
+### 无需空格
+字之间可以不用空格或换行喵~
+```miu
+这 就是 '有空格'~
+那就是'无空格'~
+这和 那 都好~
+```
+
+### 引用传递
+若无特别说明，传的都是引用喵~ 不会自动给你抄一份喵~ 不小心传错了会被变成奇怪的形状喵~
+
+---
+
+## 玩具的种类喵 (数据类型)
+
+你那小脑瓜能记住的也就这几种喵：
+
+| 类型 | 写法               | 何意味                               |
+| ---- | ------------------ | ------------------------------------ |
+| 摸数 | `16`, `0`, `256`   | 十进制非负数有理喵，负数自己用〇减   |
+| 闲话 | `'你好'`, `"地球"` | 一串字符喵，单引号双引号都行         |
+| 好坏 | `好喵`, `坏喵`     | 两仪喵，好就是真，坏就是假           |
+| 空碗 | `空碗`             | 你的脑袋喵，里面什么都没有           |
+| 纸箱 | 集合               | [待会](#纸箱喵-集合)讲喵，别急       |
+| 计谋 | 函数               | [后面](#计谋喵-函数)也讲喵，急了憋着 |
+
+常识喵：`好喵` 和非零摸数和非空闲话是好喵，`坏喵`、`0`、`空碗`、空闲话 `''` 是坏喵~
+
+---
+
+## 抢占地盘喵 (变量声明与赋值)
+
+### 声明变量
+用 `蹭` 声明一个变量喵~
+```miu
+蹭甲~					(声明但不赋值，甲 是空碗)
+蹭乙~ 乙 就是 16~		(声明再赋值)
+蹭丙 就是 32~			(顺便赋值)
+```
+
+### 三种赋值方式
+听好了，这比什么都重要喵~
+
+| 关键字 | 语义 | 何意味                                 |
+| ------ | ---- | -------------------------------------- |
+| `就是` | 引用 | 两个名字指向同一个碗，改一个另一个也变 |
+| `就像` | 复制 | 复制一个新碗，各吃各的互不干扰         |
+| `才是` | 移动 | 整个端走，弃掉原来的，别问有什么用     |
+
+```miu
+(--- 共有：同一碗饭 ---)
+蹭 我的碗 就是 '小鱼干'~
+蹭 你的碗 就是 我的碗~	(你我的碗是同一只)
+我的碗 就是 '空了'~		(我吃完了)
+扒[=你的碗=]喵~			(你的碗也空了！因为你我的碗是同一只)
+
+(--- 均有：各吃各的 ---)
+蹭 原版 就是 '猫粮'~
+蹭 复刻 就像 原版~		(复刻是原版的拷贝)
+原版 就是 '吃完了'~		(原版吃完了)
+扒[=复刻=]喵~			(复刻还是'猫粮'，各吃各的)
+
+(--- 专有：连锅端 ---)
+蹭 一次性 就是 '纸团'~
+蹭 搬走了 才是 一次性~	(搬走了把纸团端走了)
+(扒[=一次性=]喵~)		(坏了喵！一次性无了喵！)
+```
+里面的 `扒[=某某=]喵` 是什么喵？看[这里](#计谋喵-函数)喵~
+
+---
+
+## 高仿与抢走喵
+
+有时候不得不打断引用，除了用 `就像` 与 `才是` 重新赋值，还能用更简单的 `高仿` 和 `抢走` 喵~
+```miu
+蹭甲~ 甲 就是 32~
+蹭乙~ 乙 就是 高仿 甲~	(乙成了复制的甲，和 `乙 就像 甲` 一个效果)
+甲 就是 16~				(甲成了 16，但乙还是 32)
+高仿抢走高仿甲~			(你还可以写这种没用的废话)
+```
+> `就像` 和 `才是` 可视为 `就是高仿` 和 `就是抢走` 的简写
+
+## 算术与比较喵
+
+### 算术运算
+就这五种喵，多了你也算不明白：
+
+| 运算符 | 含义    | 示例                 |
+| ------ | ------- | -------------------- |
+| `+`    | 加/拼接 | `1 + 2`, `'a' + 'b'` |
+| `-`    | 减      | `5 - 3`              |
+| `*`    | 乘      | `3 * 4`              |
+| `/`    | 除      | `10 / 3`             |
+
+`+` 可以拼接闲话和纸箱喵~ 其他的只能用在摸数上喵~
+
+### 比较运算
+
+| 运算符 | 含义     |
+| ------ | -------- |
+| `==`   | 等于     |
+| `!=`   | 不等于   |
+| `>`    | 大于     |
+| `<`    | 小于     |
+| `>=`   | 大于等于 |
+| `<=`   | 小于等于 |
+
+`==` 和 `!=` 可以比较不同类型（结果永远是坏喵），其他比较只能同类喵~
+
+### 分节运算
+这是神奇的妙妙语法喵~ 逗号和算术运算符的组合称为 `节运算符` 喵~
+```miu
+蹭 结果 就是 10+2*3 -, 7 *, 2~
+```
+
+计算过程：先算 `10+2*3 = 16`，然后 `16 - 7 = 9`，然后 `9 * 2 = 18` 喵~ 即 `((10 + 2 * 3) - 7) * 2`~
+
+特例：`==` 和 `!=` 虽然不是算术符，但也可以参与分节运算喵~
+**铁律：一旦进入比较模式，就不能再回到算术模式喵！**
+```miu
+10 + 5 ==, 3 *, 2~   (坏了喵！比较之后不能做算术)
+10 + 5 -, 3 ==, 2~   (棒棒喵！先算术后比较)
+```
+
+---
+
+## 逻辑喵
+
+用的是自闭合语法喵~ 这里没有 `&&` `||` 那种分不清谁是谁的丑东西喵~
+
+### 开闭对
+
+| 开头 | 闭合词 | 含义 | 等价 |
+| ---- | ------ | ---- | ---- |
+| `和` | `都好` | 与   | AND  |
+| `和` | `都坏` | 或非 | NOR  |
+| `或` | `不坏` | 或   | OR   |
+| `或` | `不好` | 与非 | NAND |
+
+**开闭必须配对喵！** `和` 只能配 `都好` 或 `都坏`，`或` 只能配 `不坏` 或 `不好` 喵~ 搞混了我笑你两年半喵~
+
+```miu
+(--- 与 ---)
+a 和 b 都好~			(a && b)
+a 和 b 都坏~			(!a && !b)
+
+(--- 或 ---)
+a 或 b 不坏~			(a || b)
+a 或 b 不好~			(!a || !b)
+```
+
+### 嵌套逻辑
+```miu
+a 和 b 或 c 不坏 都好~	(等价于：a && (b || c))
+```
+套在里面的优先喵~
+
+---
+
+## 想法喵 (代码块)
+
+想法是一个用 `[# #]` 包裹的代码块，最后一个表达式的值就是整个想法的值喵~ 里面是语句喵，不要忘记尾巴~
+```miu
+蹭 结果~ 结果 就是 [# 10 + 20~ #]~	(结果是 30)
+```
+
+想法里可以写很多句喵~
+```miu
+蹭 结果 就是 [#
+	蹭 甲 就是 10~
+	蹭 乙 就是 20~
+	甲 + 乙~		(这是最后一句，叼回它的结果喵)
+#]~
+```
+
+**注意喵：不要直接拿走在里面蹭的玩具，会被打死喵~**
+```miu
+蹭 结果 就是 [#
+	蹭 丁 就是 30~
+	丁~				(完了喵)
+#]~
+```
+
+---
+
+## 纸箱喵 (集合)
+
+纸箱就是用 `[= =]` 包裹的数组/字典喵~ 会自动编号，编号从更适合人类的 1 开始喵~
+
+### 搓一个
+用逗号分隔元素喵~ 可以用声明句式命名，蹭不蹭都一样喵~
+```miu
+蹭 玩具~
+蹭 空纸箱 就是 [==]~
+蹭 混合纸箱 就是 [=
+	'第一个',			(匿名，索引 1)
+	名字 就是 '第二个',	(名为 '名字'，索引 2)
+	玩具,				(名为 '玩具'，引用 `玩具`，索引 3)
+	高仿 空纸箱,		(名为 '空纸箱'，浅复制 `空纸箱`，索引 4)
+	[= '套娃' =],		(匿名，索引 5)
+=]~
+```
+高仿一个纸箱就会得到浅复制版本喵~
+
+### 读取里面的东西
+用 `@` 从纸箱摸东西喵~
+```miu
+蹭 袋子 就是 [= '苹果', '橘子', '空气' =]~
+扒[=袋子@1=]喵~				(苹果)
+扒[=袋子@2=]喵~				(橘子)
+
+(有名字的元素可以用名字找到)
+蹭 富口袋 就是 [= 蹭 内存条 就是 '小零食' =]~
+扒[=富口袋@'内存条'=]喵~	(小零食)
+
+(嵌套访问)
+扒[=袋子@1@1=]喵~			(访问嵌套纸箱)
+```
+名字记得用引号装着，不然会把外面的同名玩具当名字或编号喵~
+
+### 改变里面的东西
+```miu
+袋子@1 就是 '烂苹果'~			(修改已有的)
+袋子@'新成员' 就是 '神秘玩具'~	(添加新成员)
+```
+
+### 纸箱拼合
+可以用 `+` 得到一个包含两个纸箱内容的纸箱喵~ 重名的讲究先来后到喵~
+```miu
+蹭 袋子一号 就是 [= 坏苹果就是好喵, 烂橘子就是'烂橘子', '空气' =]~
+蹭 袋子二号 就是 [= 坏苹果就是坏喵, '空气' =]~
+蹭 融合袋子 就是 袋子一号 + 袋子二号~	(相当于 [= 坏苹果就是好喵, 烂橘子就是'烂橘子', '空气', '空气' =])
+```
+拼出来的新纸箱依然装着原来的引用喵~
+
+---
+
+## 计谋喵 (函数)
+
+### 预谋
+`想要` 开头，想要的贡品装在纸箱 `[= =]` 里，名字在贡品后面，动作放在想法 `[# #]` 里喵~
+```miu
+(不要贡品的计谋)
+想要 [==] 打招呼 [#
+	扒[='喵~'=]喵~
+#]~
+
+(要一个贡品的计谋)
+想要 [=n=] 双倍 [#
+	叼回来 n * 2~
+#]~
+
+(要很多贡品的计谋)
+想要 [=甲, 乙=] 相加 [#
+	叼回来 甲 + 乙~
+#]~
+```
+
+### 施计
+只要 `扒` 放在纸箱 `[= =]` 里的贡品然后喊出名字就可以释放了喵~ 名在最后喵~
+```miu
+扒[=5=]双倍~			(或许得 10)
+扒[=3, 7=]相加~			(可能得 10)
+扒[==]打招呼~			(不给贡品)
+```
+
+参数传递默认是引用喵~ 想传副本就用 `高仿`，想传完就没用就用 `抢走` 喵~
+```miu
+扒[=我的碗=]计谋~		(引用传递，计谋能瞎改你的碗)
+扒[=高仿 我的碗=]计谋~	(复制传递，你的碗安然无恙)
+扒[=抢走 我的碗=]计谋~	(移动传递，你的碗没了，恭喜喵)
+```
+
+### 贡品箱
+既然写了 `[= =]`，就说明它可能真是一个纸箱喵~
+```miu
+蹭 盒子 就是 [= '电池', '空气' =]~
+扒 盒子 喵~	（可以这样传入，相当于 `扒[= '电池', '空气' =]喵~`）
+```
+预谋时不可以这样写，会摸不着头脑喵~
+
+### 返回值
+用 `叼回来` 把东西叼回来喵~
+```miu
+想要 [=x=] 绝对值 [#
+	[# 叼回来 0 - x~ #] 好不好? x < 0
+	不然 [# 叼回来 x~ #]~
+#]~
+```
+
+都到这一步了，先赐给你一些[预置计谋](#内置计谋喵-标准库)喵~
+
+---
+
+## 做决定喵 (条件表达式)
+
+### 好不好？
+先说想法 `[# #]`，然后用 `好不好?` 提问再决定做不做喵~
+```miu
+[# 扒[='大喵！'=]喵~ #] 好不好? x > 5~
+```
+
+### 不然 (else)
+```miu
+[# 扒[='大了'=]喵~ #] 好不好? x > 5
+不然 [# 扒[='小了'=]喵~ #]~
+```
+
+### 链式判断
+`不然` 后面可以接另一个 `好不好?` 喵~ 整条链算一句，中间可以不用尾巴喵~
+```miu
+[# 扒[='大了'=]喵~ #] 好不好? x > 10
+不然 [# 扒[='刚刚好'=]喵~ #] 好不好? x > 5
+不然 [# 扒[='小了'=]喵~ #]~
+```
+
+### 想法的值
+可以得到 `[# #]` 中叼回的东西喵~
+```miu
+蹭 级别 就是 [# '厉害'~ #] 好不好? 分数 > 90
+不然 [# '还行'~ #] 好不好? 分数 > 60
+不然 [# '重考'~ #]~
+```
+
+---
+
+## 玩耍喵 (循环表达式)
+
+### 普通玩耍
+`玩耍` 开头，后面跟想法，无条件喵~ `累了` 就不玩了喵~
+```miu
+蹭 i 就是 0~
+玩耍 [#
+	i 就是 i + 1~
+	扒[=i=]喵~
+	[# 累了~ #] 好不好? i >= 5~
+#]~
+```
+
+### 偷袭：下一圈或返回值
+用 `偷袭` 可以把东西带走，空扑就再来一次喵~
+```miu
+蹭 结果 就是 玩耍 [#
+	蹭 n 就是 扒[=1, 10=]添乱~
+	[# 累了~ #] 好不好? n == 1~	(不玩了，不带走东西)
+	[# 偷袭~ #] 好不好? n != 7~	(还要玩，跳到下一圈)
+	偷袭 高仿n~					(不玩了，取走目标值)
+#]~
+扒[="偷到了: ", 结果=]喵~		(结果是 7 或 空碗)
+```
+
+---
+
+## 内置计谋喵 (标准库)
+
+不用声明，直接 `扒` 就能用喵~ 伸手党狂喜喵~
+
+### 输入输出
+
+| 名称   | 用法                  | 作用            |
+| ------ | --------------------- | --------------- |
+| `喵`   | `扒[=东西=]喵~`       | 打印东西喵~     |
+| `祈求` | `扒[='提示词'=]祈求~` | 读取输入喵~     |
+| `打盹` | `扒[=秒数=]打盹~`     | 休眠指定秒数喵~ |
+
+### 类型转换
+
+| 名称     | 用法                 | 作用                   |
+| -------- | -------------------- | ---------------------- |
+| `变摸数` | `扒[='233'=]变摸数~` | 闲话变摸数，失败得空碗 |
+| `喵译`   | `扒[=256=]喵译~`     | 任何东西变闲话         |
+| `嗅嗅`   | `扒[=x=]嗅嗅~`       | 得到任何实体的类型名   |
+
+### 逻辑
+
+| 名称       | 用法                | 作用             |
+| ---------- | ------------------- | ---------------- |
+| `才怪`     | `扒[=好喵=]才怪~`   | 取反，好喵变坏喵 |
+| `理直气壮` | `扒[=-4=]理直气壮~` | 取绝对值         |
+| `差不多`   | `扒[=3.14=]差不多~` | 四舍五入         |
+
+### 数学
+
+| 名称     | 用法                   | 作用     |
+| -------- | ---------------------- | -------- |
+| `抢大的` | `扒[=3, 8, 7=]抢大的~` | 取最大值 |
+| `吃剩的` | `扒[=3, 8, 7=]吃剩的~` | 取最小值 |
+| `摸余`   | `扒[=10, 3=]摸余~`     | 取余数   |
+| `添乱`   | `扒[=1, 10=]添乱~`     | 随机整数 |
+
+### 纸箱与闲话
+
+| 名称       | 用法                     | 作用               |
+| ---------- | ------------------------ | ------------------ |
+| `找尾巴`   | `扒[='abc'=]找尾巴~`     | 取闲话或纸箱的长度 |
+| `喵语连珠` | `扒[='a','b'=]喵语连珠~` | 拼接闲话           |
+
+### 花里胡哨
+
+| 名称       | 用法                    | 作用             |
+| ---------- | ----------------------- | ---------------- |
+| `磨爪`     | `扒[==]磨爪~`           | 输出磨爪爪字符画 |
+| `猫咪艺术` | `扒[='开心'=]猫咪艺术~` | 输出猫咪表情     |
+| `呼噜`     | `扒[=3=]呼噜~`          | 咕噜咕噜         |
+| `哈气`     | `扒[='错哪了'=]哈气~`   | 哈！             |
+
+---
+
+## 特殊玩法喵
+
+### 兼容非 ASCII 字符
+可以偷懒不改输入法喵~
+```miu
+(这些都能识别喵~)
+１０~		(全宽数字)
+‘你好」~	(弯引号/直角引号 -> 直引号)
+【= 1 =】~	(方头括号 -> 方括号)
+```
+但闲话和悄悄话的内容不会被转换喵~
+
+### 花括号标识符 `{名字}`
+有花圈套住，就可以用各种字词给玩具命名喵~
+```miu
+蹭 蹭~		(坏了喵)
+蹭{蹭}~		(获得名叫 `蹭` 的玩具喵)
+```
+
+### 没有圆括号怎么办
+如果你怀念 `(a + b) * c` 这种写法，可以用 `[# #]` 装样子喵~
+```miu
+[# a + b~ #] * c~	(记得写里面的尾巴喵)
+```
+
+### 信号穿透
+`叼回来`、`累了` 和 `偷袭` 不能当成值，但可以利用 `[# #]` 让它们被叼到更外层，会被适合的想法层拦下来喵~
+```miu
+蹭 i 就是 0~
+玩耍 [#
+	i 就是 i + 1~
+	玩耍 [#
+		蹭 n 就是 扒[=1, 10=]添乱~
+		[# 偷袭[# 累了~ #]~ #] 好不好? n == i~	(带值 `偷袭` 打断内层，`累了` 抛到外层 ，外层被打断)
+	#]~
+#]~
+```
+不可以直接写 `偷袭 累了~`，一定要用 `[# #]` 装着喵~
+
+---
+
+## 简单示例喵
+
+给你看个像样的程序喵~ 虽然以你的水平可能看不懂喵~
+
+```miu
+(--- 递归求阶乘 ---)
+想要 [=n=] 阶乘 [#
+	[# 叼回来 1~ #] 好不好? n <= 1
+	不然 [# 叼回来 n * 扒[=n - 1=]阶乘~ #]~
+#]~
+
+扒[="5的阶乘是: ", 扒[=5=]阶乘=]喵~
+
+(--- 猜数字游戏 ---)
+想要 [==] 猜数字 [#
+	蹭 答案~ 答案 就是 扒[=1, 100=]添乱~
+	扒[="我心里想了个1到100的数字喵~"=]喵~
+
+	玩耍 [#
+		蹭 输入 就是 扒[='猜吧: '=]祈求~
+		蹭 猜测 就是 扒[=输入=]变摸数~
+
+		[# 扒[="请输入数字喵："=]喵~ #] 好不好? 猜测 == 空碗
+		不然 [#
+			[# 扒[="小了喵~"=]喵~ #] 好不好? 猜测 < 答案
+			不然 [# 扒[="大了喵~"=]喵~ #] 好不好? 猜测 > 答案
+			不然 [#
+				扒[="猜对了！你是天才猫咪喵~"=]喵~
+				累了~
+			#]~
+		#]~
+	#]~
+#]~
+
+扒[==]猜数字~
+```
+
+---
+
+好了喵，该教的都教了喵~ 学不会就睡觉喵~

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2026 TNPC
+
+Permission is hereby granted, free of
+charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.