# Ruby

能写，但这个前端支持的特性最少 —— «bold»完全平铺着写«/»。

## 在手机上怎么跑

```
vml run examples/ruby/test/sysinfo.rb
```

编译要等一会儿（C 那种要一两分钟，脚本类语言几秒）。程序跑起来后**屏幕底部就是手柄**，
方向键 + 四个动作键都在；点右上角返回可以回到命令行。

## 写法要点

- 全部逻辑写在顶层，不要包函数、不要嵌套
- 直接调用 `ui_*`

## 示例

| 文件 | 演示什么 |
|---|---|
| `test/catch.rb` | 接方块（完全平铺的一份，这一路写不了函数） |
| `test/file_io.rb` | 读写文件 |
| `test/sysinfo.rb` | 设备信息 |

同目录还有：`3d/box.glb`、`3d/demo_3d.rb`、`app/invaders.rb`、`app/minesweeper.rb`、`bgi/demo_bgi.rb`、`demo/demo_std.rb`、`school/100-doors.rb`、`school/99-bottles.rb`、`school/MANIFEST.md`、`school/NOTICE.md`、`school/bubble-sort.rb`、`school/caesar-cipher.rb`、`school/fibonacci.rb`、`school/guess-the-number.rb`、`school/n-queens.rb`、`school/primality-trial-division.rb`、`school/sieve-of-eratosthenes.rb`、`school/towers-of-hanoi.rb`、`stringutil/main.rb`、`test/libs.rb`、`tty/demo_tty.rb`、`ui/demo_ui.rb`

## 实测踩过的坑

- ⚠ «bold»不认 `&&`«/»（用 `and`，或者分开写 `if`）。
- ⚠ «bold»`def` 会报 `Unexpected token: End`«/» —— 也就是说这一路«bold»一个函数都写不了«/»，
  只能平铺（`examples/ruby/test/catch.rb` 就是这么写的）。

---

下面的内容是**从 VML 源码里直接带的**（`third_party/vml/VMLPrepares/RubyCompiler/`）：
`README` 讲这个前端支持什么、怎么编；`语言规范` 讲语法本身。
上游一改，这里重新生成就是最新的。

## 语言规范

### Ruby 语言编译器规范说明

> «bold»版本«/»：v1.0 | «bold»日期«/»：2026-07-06 | «bold»修订者«/»：深圳市探索智能科技有限公司

#### 规范标准

| 字段 | 值 |
|:-----|:----|
| «bold»目标标准«/» | Ruby 1.9+ 子集 |
| «bold»发布年份«/» | 1995 (Ruby 1.9: 2007) |
| «bold»完成度«/» | ~96% |
| «bold»文件扩展名«/» | `.rb` |

#### 概述

本编译器支持 Ruby 语言的核心子集，将 Ruby 源代码编译为 VML (Virtual Machine Language) 汇编代码。编译器流程：预处理 → 词法分析 → 语法分析 → 代码生成。

#### 支持的语言特性

##### 1. 数据类型

- «bold»整数«/»: `Integer` — 整数类型 (4 字节有符号)
- «bold»浮点数«/»: `Float` — 单精度浮点数
- «bold»字符串«/»: `String` — 字符串字面量，双引号 `"..."` 或单引号 `'...'`
- «bold»符号«/»: `Symbol` — 以 `:` 开头，如 `:name`
- «bold»数组«/»: `Array` — 方括号字面量 `[1, 2, 3]`
- «bold»nil«/»: `nil` — 空值
- «bold»布尔值«/»: `true` / `false`

##### 2. 变量

```ruby
x = 10           # 局部变量
@x = 20          # 实例变量 (已识别但功能受限)
name = "hello"   # 字符串变量
```

##### 3. 运算符

###### 算术运算符
```ruby
+    # 加法
-    # 减法
*    # 乘法
/    # 除法
%    # 取模
**   # 幂运算
```

###### 复合赋值
```ruby
+=   # 加后赋值
-=   # 减后赋值
*=   # 乘后赋值
/=   # 除后赋值
```

###### 比较运算符
```ruby
==   # 等于
!=   # 不等于
<    # 小于
>    # 大于
<=   # 小于等于
>=   # 大于等于
<=>  # 飞船运算符 (比较结果 -1/0/1)
```

###### 逻辑运算符
```ruby
!    # 逻辑非 (not)
```

##### 4. 控制流

###### 条件语句
```ruby
if condition
  # then body
elsif other_condition
  # elsif body
else
  # else body
end

unless condition
  # then body (条件为假时执行)
end
```

###### 循环语句
```ruby
while condition
  # loop body
end

until condition
  # loop body (条件为假时重复)
end
```

###### for 循环
```ruby
for var in start..end
  # loop body
end
```

##### 5. 方法定义

```ruby
def method_name(param1, param2)
  # method body
  return value
end

def method_name  # 无参数方法
  # body
end
```

##### 6. 类定义

```ruby
class ClassName
  def method_name
    # method body
  end
end
```

类在内部被编译为带 `self.` 前缀的方法，`self` 存储为第一个局部变量。

##### 7. 返回值

```ruby
return value     # 带返回值
return           # 返回 nil
```

##### 8. 方法调用

```ruby
method_name(arg1, arg2)
object.method_name(arg1)
method_name       # 无参数调用
```

##### 9. 注释

```ruby
# 单行注释
```

#### 表达式优先级

| 优先级 | 类型 | 运算符 |
|:------:|:-----|:-------|
| 1 (最低) | 赋值 | `=`（含多重赋值 `a, b = 1, 2`）`+=` `-=` `*=` `/=` `%=` `&=` `\|=` `^=` |
| 2 | 三元 | `?:` |
| 3 | 区间 | `..` `...` |
| 4 | 逻辑或 | `\|\|` `or` |
| 5 | 逻辑与 | `&&` `and` |
| 6 | 比较 | `==` `!=` `<` `>` `<=` `>=` `<=>` |
| 7 | 按位或 / 异或 | `\|` `^` |
| 8 | 按位与 | `&` |
| 9 | 加法 | `+` `-` `<<` |
| 10 | 乘法 | `*` `/` `%` `**` |
| 11 | 一元 | `-` `!` |
| 12 (最高) | 主表达式 | 字面量、变量、函数调用、括号 |

⚠ 与 CRuby 的差异：`and`/`or` 与 `&&`/`||` «bold»同档«/»（真 Ruby 里 `and`/`or` 比赋值还松）；
`«bold»` 与 `*` `/` 同档（真 Ruby 里 `«/»` 更紧、且右结合）。

#### 预定义宏

| 宏名 | 值 |
|:-----|:---|
| `__VML__` | `1` |
| `__VML_VERSION__` | `"1.65.32"` |
| `__RUBY__` | `1` |
| `__DATE__` | 编译日期 |
| `__TIME__` | 编译时间 |

#### 已知限制

- 不支持 `module`、`yield`、`mixin`（`include` 只是文档级引用）
- «bold»Hash«/»：支持字面量 `{k => v}`、`h[k]` 读、`h[k] = v` 写、`h.length` / `size`、
  `h.each do |k, v| … end`（单形参按 Ruby 口径收成 `[k, v]`）。底层复用数组的带头布局
  `[k0, v0, k1, v1, …]`。⚠ 键只支持«bold»字符串 / 整数«/»；哈希«bold»传参/返回«/»后不再认得
  （没有运行期类型标记）；重复键按"首次出现"读（真 Ruby 是最后一次赋值覆盖）
- «bold»File«/»：`File.read(path)` / `File.write(path, text)`（相对路径按«bold»源文件目录«/»解析）。
  打不开时 `read` 返回空串、`write` 返回 0（本子集没有异常对象）
- «bold»Time«/»：`Time.now.to_i` 返回当前 Unix 秒
- «bold»splat `*args`«/»：不支持（`&x` 传 Proc 对象编译期报错，不静默）。
  «bold»`&:sym`«/» 支持 —— 在语法层摊成 `{ |e| e.sym }`（不构造 Proc）
- «bold»区间当值«/»：`.to_a` 支持（整数区间 / `.step(k)` / «bold»两端都是单字符字面量的字符串区间«/»，
  如 `("A".."Z").to_a`）；运行期端点的字符串区间、浮点端点仍«bold»编译期报错«/»
- 块方法：数组上支持 `each` / `each_index` / `times` / `upto` / `downto` / `map`(=`collect`) /
  `select` / `reject` / `flat_map` / `each_slice`；区间上支持 `each` / `step` / `map` / `select` /
  `reject` / `none?` / `any?` / `all?`。«bold»其余«/»（`sort_by` / `group_by` …）明确报错，不静默丢掉块
- «bold»`Array#rotate`«/» 支持（非破坏性，返回新数组）；`rotate!` 未实现
- «bold»`String#tr(from, to)`«/» 在前端摊开实现。⚠ 差异：`to` 比 `from` 短时按 Ruby 口径用末字符补齐；
  `to` «bold»为空«/»时真 Ruby 是"删掉匹配字符"，本子集«bold»跳过«/»（不做删除）
- «bold»`puts` / `print` 的数组实参«/»：按«bold»元素«/»逐个输出（`puts` 每个元素一行）。
  ⚠ `print` 在真 Ruby 里打的是 `inspect`（`["a", "b"]`），本子集打元素本身
- «bold»类体语句在定义处执行一次«/»（`class X; CONST = …; end` 里的常量在方法里读得到）。
  常量（首字母大写）按«bold»全局«/»落地 —— 本子集没有词法作用域模型
- «bold»返回类型"两种都有"的函数«/»（一处 `return "串"`、另一处返回数组）：按数组落地，
  字符串那一支«bold»包成单元素数组«/»（`puts` 的输出与 CRuby 逐字相同）。
  ⚠ 已知边界：字符串 + «bold»整数«/»数组的混合分不清元素类型
- «bold»零实参的库函数«/»只能写 `newline()`（带括号）；裸写 `newline` 会被当成读一个变量
- 类继承和多态方法分发尚未实现

##### 区间 `a..b` / `a...b` 的四种用法（其余位置报错）

| 用法 | 例 | 实现 |
|:---|:---|:---|
| `for` 循环 | `for i in 1..n` / `for i in 1...n` | `a...b` 脱糖成 `a..(b-1)` |
| 块迭代 | `(1..100).each { \|i\| }` / `.step(k) { \|i\| }` | 脱糖成计数循环（`.step()` 无实参 = 步长 1） |
| 随机数 | `rand(1..10)` | 脱糖成 `a + rb_rand(b - a + 1)`（两端都含） |
| 当值 | `(1..n).to_a` / `[*1..n]` / `(1..n).step(2).to_a` | 摊成"建数组 + 逐个 push"（整数区间）；字符串区间只支持单字符字面量端点 |

---

#### 🆕 字符串编码 (v1.65.19)

该语言编译器通过共享库 (Lib/shared/) 间接使用 VML 字符串体系。

| 伪指令 | 宽度 | 编码 | C 类型 |
|:------|:----:|:-----|:--------|
| `.string` | 8-bit | UTF-8 | `char*` |
| `.wstring` | 16-bit | UTF-16LE | `wchar_t*` |
| `.ustring` | 32-bit | UTF-32LE | `char32_t*` |

«bold»MCU 模式«/» (默认): 字符串输出为 UTF-8 (`.string`)
«bold»OS 模式«/»: 可通过 `VML_WSTRING` 宏判断编码

共享库已提供宽字符串转换函数 (wchar.h/uchar.h)，各语言编译器可按需使用。

## 编译器 README

### Ruby 编译器

«bold»路径«/»: `VMLPrepares/RubyCompiler/`
«bold»完成度«/»: ~96% | 🟢 生产可用
«bold»标准库«/»: `Lib/ruby/`

#### 功能
- ✅ 词法分析 + 语法分析 + 代码生成 (Lexer/Parser/CodeGenerator)
- ✅ 控制流 (if/elsif/else/unless/while/until/for/in)
- ✅ 函数: def/return/参数传递
- ⚠️ Class: «bold»只做语法接受，没有对象模型«/» —— `X.new` / `@ivar` / 方法分发都未接，
  读到一个源码里定义过的类名会报「类实例化尚未实现」（清单 RUBY-12，v0.96.829 实测）
- ✅ 运算符: 赋值/比较/算术/一元/<=>/and/or/not
- ✅ 字面量: 整数/浮点/字符串/布尔/数组/Symbol/** 幂/.. 范围
- ✅ 复合赋值 (+= -= *= /= %=)
- ✅ case/when/else 分支
- ✅ 34 测试 0 失败
- ✅ module/mixin — include 内联
- ⚠️ yield/Proc — 未实现（`arr.each do |x| … end` 这类«bold»块«/»已支持：each / times / upto / downto，脱糖成普通循环）
- ✅ require 库导入
- ✅ C 风格预处理 (#ifdef/#ifndef/#define/#include)

#### 编译模式

##### MCU 模式（默认 `--mode mcu`）
MCU 模式针对单片机/裸机环境优化，自动跳过不兼容操作系统的特性。

«bold»跳过«/»（MCU 不支持）:
- require 动态加载、yield/block

«bold»保留«/»（BIOS 实现底层）:
- 基本类型运算、控制流、函数调用
- print/puts 映射到 UART

##### OS 模式（`--mode os`）
OS 模式支持全部语言特性（文件系统、多线程等）。

##### RAM 级别
- `--ram k`：KB级别（2KB~64KB）
- `--ram m`：MB级别（64KB~1MB，默认）
- `--ram g`：GB级别

#### 使用
```bash
dotnet run --project VMLTool -- input.rb -o output.vml
```

#### 测试
- `VMLTests/NewCompilerTests.cs` — 34 测试 (0 失败)
- `VMLTests/FullPipelineTests.cs` — 全管线测试
- `Examples/ruby/` — 示例程序 (start/factorial/file_io/info)
