笔记中的一些想法

打算在清扫完实现 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 是不是应该跟输入框同步？
- 那要怎么判断是否读取自动保存的内容？是不是应该加个历史输入列表？
[x] Pages
- 应该写一个 action，但被批量结果还在显示原始数据而非 bar chart 这个问题阻挡着。
[x] 批量结果的 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、闭包、（布尔值？）、|>
[x] 通常函数一览
- 生成自代码中的声明。

通常函数

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

限制

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

步骤展现

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

解析

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

杂项

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

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

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

Playground 相关

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

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

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

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

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

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

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

再记录一波

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

关于复杂计数

计数方式可以为：

每次掷骰时：如有明确的投掷次数，投几次就算几；否则为正无穷。
每次加、减、乘、除、取余数时：每进行一次算一。
每次指数运算时：⌈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。[^1]
- 上 prettier。（目前在用 deno fmt，但只是为了格式化代码就装 deno 有些杀鸡焉用牛刀。）
- 考虑上同步 monorepo 各包依赖的工具，比如 syncpack。
- 考虑上自动化增加版本号的工具，比如 changesets。

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

[^1]: 还有和其他工具配合的 eslint-config-turbo、eslint-config-prettier。

umajho / dicexp