笔记中的一些想法

[umajho]

打算在清扫完实现 reroll、explode 的阻碍后将重心移到 rotext
或其他地方，待到能将 rotext 与 dicexp 整合时再继续完成剩下的工作。

以下是一些记在笔记中，但没有单独开 issues 的想法：

一般

• 扩展 .
  • 访问列表：[1, 2, 3].(0) => 1
  • 获得关键词列表对应原子的值：[foo: 42].foo
    => 42
    • 可以嵌套：[foo: [bar: 42]].foo.bar => 42
    • 要如何与外部变量中的 .
      相区分？隐式转换？
• 在解析时提前求值
  • 比如像是 2 * 3 这样的常量。
  • 如果明确只是单次执行，还可以将确保不会反复（不在 #
    右侧、不在闭包内）的随机取值操作提前求出。
• 到底要不要加回来 d%？
  • 目前的倾向是不，除了之前容易看混的理由外，其本身含义也不直观。

Playground

• URL 是不是应该跟输入框同步？
  • 那要怎么判断是否读取自动保存的内容？是不是应该加个历史输入列表？
• Pages
  • 应该写一个 action，但被批量结果还在显示原始数据而非 bar chart
    这个问题阻挡着。
• 批量结果的 Bar chart

  • 随便找个库加上 bar chart 不难。（私下已经做过了。）

    但考虑到需要定制一些功能（分布、至少、至多光标悬浮同时高亮，同时显示数量和百分比，可能性过多时合并结果…），打算未来用
    d3.js 手动实现。

• “快速上手” 指南

  • 一行例子、一行说明。例子只举出相关的部分运算符，说明中举出全部。众所周知的运算符在说明中只列举，不阐述。

    分以下几对：

    • 1~10 -- ~
    • 3d(4+5*6) --
      +、-、*、//（整除）、%（正数求余）、^（幂）、d、(、)
    • 3#d10 -- #
    • reroll(3d10, \(x -> x <= 2)) == 3d10 |> reroll \(x -> x <= 2) --
      reroll、explode、闭包、（布尔值？）、|>
• 通常函数一览
  • 生成自代码中的声明。

通常函数

• identity/1 或 id/1。（还没确定好用哪个。）
• shuffle/1。
• 还有一些在关于数据结构的 issue
  里提到。

限制

• 字数限制、结果的数据大小限制（结果的数目、结果步骤的数目与字数等等）。

步骤展现

• 通常函数应该可以自定中间步骤的展现。
• 可能带括号的步骤展现信息附带元数据（如优先级，或者 null
  代表不能去掉括号），以让同优先级的运算内外去掉括号。

解析

• 解析 /，给一个解析错误，像是 “dicexp 仅支持整除，是否想用 “//”
  整除运算符？”。
• 应该在 Lezer 层面处理全角符号。

杂项

• callValue 里对左侧值的 concretize 是不是该放在 _yield 里？
• 之前在限制步骤时（已删，应该是这里），那时用的方式得出
  +1 总计 5 步，为什么？
• 'a'~'z'，但目前不打算引入字符串。还可以拓展到范围运算符。

[umajho]

在转移重心前还是应该先完成：

• 批量模式结果的图表。（done）
• Playground Pages Action。（done）
• 全部记录于此的通常函数，外加 shuffle/1。
• 允许非 ASCII 标识符。
• 支持原子。
• 外部变量。

[umajho]

Playground 相关

• 未来引入带显式标签的函数调用（如 if($cond, do: d10, else: d20)）后，函数文档需要区分基于位置的参数的名称与显式参数的名称：前者用小括号括起来，后者不用。此外，代码中原先用 label 来表示名称，为防止歧义应作修改。
• 函数文档中应包含范例一栏，并允许试执行。（将 rotext 那边的组件提取到单独的包里，再引入到本项目中。）
• 快速上手也应该挪到 playground 里。（引入 rotext，以及上述的组件来试执行其中出现的代码。）
• 应该再加一个欢迎页面。
  • 示例也许可以移到这里。
• 应该记录页面所在位置。
• 未来引入复杂计数后，应显示相关信息。（计数是多少，怎么算出来的等。）
• 步骤以四种颜色划分：根据深度的奇偶分为两组（每组两色），然后在同深度时根据位次交替使用该组当中的两色。

[umajho]

再更新一波，越往下记录得越早。

---

完成这些后就暂时不碰本库了：

• 现在在实现/马上要实现：
  • 用 alias 代替在解析层面将 ^/2 视为 **/2。
  • playground 中将 “内置通常函数文档” 的 “运算符” 和 ”函数“ 两部分合并，并添加标签筛选和名称筛选功能。
  • 实现一众 默认作用域中的通常函数的实现进展记录 #18 提到的通常函数（包括可能要修改内部机制的 reroll/2、explode/2，以及后加的 shuffle/1 等）。
• 然后要实现：
  • 让步骤展现与 rotext 中的 dicexp 相关挂件联动。
• 如果有精力，还要实现：
  • 将 playground 的结果面板改为：
    • 记录复数结果，最新的结果在最上方。
    • 单次与批量的结果混合。
    • 没有结果时显示相应提示。
    • 关闭按钮改为清空结果按钮，每个单独的结果也有单独的清空按钮。
    • 添加折叠按钮，折叠时只显示最新结果，并在下方显示已折叠多少结果（点按钮或下方显示皆可展开）。
• 大概没有实现的精力，但未来需要实现：
  • 复杂计数。（上面提到过）
• 大概没有实现的精力，但想要实现：
  • playground 的快速上手等页面。（上面提到过）
  • 通常函数等的文档悬浮：
    • 不只在编辑器中，（上面提到过）
    • 而且在步骤展现中。
• 大概没有实现的精力，在考虑要不要实现：
  • 将连起来的管道步骤合在一起，并在展现时使用多行：
    • 第一行是第一次调用的第一个参数，其后每行一步调用。
    • 可以有多层。

目前发现且要修复的 bug（没有长期记录价值，修好后直接把这里删掉。）：

• a.() 错误信息显示了两遍。（低优先级）

---

• 将 @dicexp/solid-components 改名为 @dicexp/web-components。
• 步骤展现中区分了通常函数标识符和变量标识符的颜色，但编辑器那边还没有同步修改。
• closure 也许应该有自己的步骤，而不是直接用 “raw” 步骤。
• 在步骤展示中将 >= 之类显示成 ≥ 这种？（解析时也应该支持这些。）
• 把 rotext 中的挂件组件和 dicexp 中的步骤展现组件抽到单独的项目中去？
• dicexp 和 @dicexp/builtins 相互依赖的问题如何解决？
  • 前者依赖后者只是取了小部分函数用于测试调用功能，也许应该把被取出来的那些函数复制一份放到 dicexp 中，以去掉前者对后者的依赖？
• 投掷结果包含执行时间、选用 seed 等信息。（集成到 widget 中。）
• 对内建函数的测试，目前还没有覆盖非正常使用的情况。
• 批量执行时不需要 appendix，所以步骤之类的也统统不需要记录。
• dicexp 库对应的 README.md 信息过时了，还没更新。
• 注：当时打算把流的显示类型名起为类似 “有限流【含基准长度，隐式求和】” 这样，翻笔记才发现。
• 函数文档中，应该把参数的标签从 “类似 foo: 这样” 改为 “类似 0 (foo): 这样”，以为未来的 “关键词列表类” 参数铺路。
• 代码文件的文件名中存在 “_” 和 “-” 的混用，应该统一一下。

[umajho]

再记录一波

由于准备将目前 “基于树遍历的解释器” 重写为 “基于字节码的虚拟机”，针对前者实现层面的改进将无限期推迟。
不过由于重写也不会是近期就要完成的事情，实质上本项目一段时间内大概不会有任何能立刻看到成效的改进了。

关于复杂计数

计数方式可以为：

• 每次掷骰时：如有明确的投掷次数，投几次就算几；否则为正无穷。
• 每次加、减、乘、除、取余数时：每进行一次算一。
• 每次指数运算时：⌈log2(幂)⌉。
• 只要存在其他操作：正无穷。

rojo 对此的处理：
在后端进行的 dicexp 求值会记录最终结果以及可以用于重建运算的信息（包括各类版本及种子等）。
当计数超过设定好的阈值时，后端不会记录运算步骤，用户在前端只会收到最终结果及用于重建运算的信息。如果这时用户需要获知运算步骤，会在浏览器中根据上述信息重建它。

Playground

• 实现记录的投掷结果的上限，超过上限时将最早的结果删除？
• 用 LocalStorage 持久化记录投掷结果？
• 步骤展现
  • 步骤展现中的 Items 组件应该切开必定显示的前几项元素与剩余的元素，用 ShowKeepAlive 调整后者是否显示，以保持后者中元素的状态。

---

• 似乎是由于浏览器的特性，页面放置一段时间后 worker 的心跳包可能会中断，导致宿主判断 worker 失去联络，从而重新创建 worker。也许改成宿主主动 ping 更好？
• 每次创建 worker 都会触发新的请求（虽然大部分时候请求都被缓存了），应该找个缓存 worker 构造器的方式。
• 没有处理获取 worker 时网络异常的情况，导致掷骰按钮可能会无限处于读取的状态。应该要么自动重试，要么让用户通过按钮手动重试。
• 也许页面内所有掷骰都用同一个求值器比较好？加一个等待队列，在等待中的组件显示相应的排队提示，并且可以取消。

问题

• 渲染 StepsRepresentation 期间的异常没有处理。
• 内建函数配套的声明/定义/文档不齐时 playground 会空屏，开发途中不是很方便。

杂项

• 废弃掉解释器里的 reporter，感觉没什么实质作用。
• 给通常函数的声明加一项 parseLevel: true，以便让不存在对应定义的 “函数”（比如 #）也能有文档。
• 类似上一项，允许给通常函数的声明加一项 canCapture: false，文档中会提示该函数不能被捕获。

2023/11/01 更新

本来预计的阶段性收尾工作是：

• 规范出 Dicexp 准·标准的接口。
• 把执行（求值）与内建函数的测试抽离出来，形成对应两项的 test suites。
• 移除 @dicexp/builtins 对 dicexp 的依赖，两者的测试统一在 dicexp 库下通过调用上述 test suites 进行。
• 改进项目结构：
  • 以下工具安装到 workspace 的根部包中，但在单独的包中配置使用。
  • 配置可以参考 turbobuild 的 monorepo 手册。
  • 上 turbobuild。（由于 @dicexp/builtins 和 dicexp 测试造成的循环依赖而卡住。）
    • 不至于每次构建 playground 要重复几遍从语法文件生成解析器代码。
    • 严格控制环境变量。
  • 上 eslint/tsline。¹
  • 上 prettier。（目前在用 deno fmt，但只是为了格式化代码就装 deno 有些杀鸡焉用牛刀。）
  • 考虑上同步 monorepo 各包依赖的工具，比如 syncpack。
  • 考虑上自动化增加版本号的工具，比如 changesets。

目前只是完成了第一项中的一部分（尚未并入 main 分枝）。
感觉有些燃尽了，想要做些其他事情换换气，所以即使是阶段性的收尾工作，也打算先搁置了。

Footnotes

1. 还有和其他工具配合的 eslint-config-turbo、eslint-config-prettier。 ↩