高级数据结构的文本写法

作品装了「高级数据结构」扩展时，文本语法里多出一套对象和列表的写法，读起来像 JavaScript 原生对象。 没装这个扩展时下面的写法都不启用，原有语法一字不变。写法只是积木的另一种样子：积木打印成文本、文本编回积木，结构完全一致； 写不成这些写法的积木（输入框里直接填了名字的、形状不标准的）读回时保持块式 moreDataTypes.xxx(...)。

命令行和 AI 助手用 gandi guide data-structures 离线读到这套写法的速查、陷阱和可编译的示例。

这个扩展有两个版本，扩展 id 不同，积木集合也不同（写法按作品里装的那个 id 自动对应，同一份文字在两个作品里编出的积木前缀不同）：

集市版才有的写法在线上版里报错（new Set() 报 E_JS_EXPR，for...of 报 E_UNSUPPORTED，o.map(...)、o.add(x)、isSet(x)、merge(...) 报 E_MDT_MISSING，提示要装集市版 test.moreDataTypes）；线上版有的写法两边都能用。 一个作品里同时装两个版本时，文本只对上先识别到的那一个。

作品里一个版本都没装时，这些写法都不启用：写入 / 贴入前的预检和编译都报 E_MDT_MISSING（「需要先装高级数据结构」，fix 里写明用 add_extension 装 moreDataTypes）， 不会说成「扩展库里找不到 store」。装了之后，store.set、o.push(1)、JSON.stringify(o) 这些是糖，不是名叫 store / o / JSON 的扩展的积木， 预检只把真正不认识的带点 id（FurryR.NotJS.run()）当成缺扩展去库里装。

const o = stage.variable("o", 0);
const hits = stage.variable("hits", 0);

when.flagclicked(() => {
    o = { name: "bob", hp: 100, tags: ["a", "b"] };
    o.pos = { x: 1, y: hits };
    o.hp += 5;
    o.items = [];
    o.items.push(3);
    o.items.sort();
    if (o.has("hp") && size(o.items) > 0) {
        hits = o.pos.x + o.items.pop();
    }
    delete o.pos.y;
    looks.say(JSON.stringify(o));
});

速查#

对象和列表#

读写属性#

列表方法#

Scratch 自己的列表（const L = sprite.list(...)）只支持原来的写法：L.push(v)、L.insert(i, v)、L.remove(i)、L.clear()、L.includes(v)、L.indexOf(v)、L.length、L[i]。 上面表里别的写法用在 Scratch 列表上（L.sort()、L.join(",")、L.pop()、L.range(1, 2)、size(L)、delete L[1]、Object.keys(L)、typeof L、"k" in L、for (const v of L)……） 一律报 E_MDT_RECEIVER：扩展把列表积木读出来的文字当成「临时数据名」，找不到就静默什么都不做，所以编译期直接拦下。 要对 Scratch 列表的内容用这些方法，先读成对象列表：块式 o = moreDataTypes.getScratchList("L")（集市版 test.moreDataTypes.getScratchList("L")）返回的就是那个列表本身， o.sort()、o.push(x) 直接改 Scratch 列表；元素在编译模式下是数字，解释模式下是文字。或者一开始就把数据放进对象列表（o = []）。

临时数据和设置#

临时数据只在内存里，不存档。

设置命令改的是整个作品的设置，对每段脚本都生效；新写进一条设置命令时，编译结果会带一条说明。 编译执行（默认）里 for...of 的键从几开始是脚本编译时就定死的：同一段脚本里先 ads.indexStart(0) 再 for...of，键仍然是 1、2（解释执行是 0、1）； map、reduce 这类 lambda 积木读运行时的设置，不受影响。

文本里的名字规则：变量（文件里声明的，或作品里本来就有的）叫 store、ads、JSON、Object、Array、Set 时，变量压过同名的糖： store.set("k", 1) 读成「变量 store 的方法」，而变量上没有 set，报 E_MDT_SHADOWED，fix 里给块式写法 moreDataTypes.setTempData(...)，也可以给变量改名； store.has(...)、store.clear() 这类对象本来就有的方法名照常读成变量的方法。

集市版的写法#

下面几节的写法只在装了集市版（test.moreDataTypes）时启用。

集合（集市版）#

「设为空集合」（createOrClearSet）没有糖，写块式 test.moreDataTypes.createOrClearSet("s")。

遍历（集市版）#

for...of 是「遍历」积木（forEachWithObj）：积木上有两个参数槽（键、值），循环体是它的 C 形口。

for (const [key, value] of Object.entries(o)) {   // 键和值都用
    total += value;
}
for (const item of L) { ... }                     // 只用值：列表、对象、集合都行
for (const k of Object.keys(o)) { ... }           // 遍历 Object.keys(o) 这个列表本身

• 键：列表和集合是项目的序号（从 1 起，ads.indexStart(0) 之后从 0 起），对象是属性名；值：项目本身。
• 循环变量只在循环体里有效，不能赋值；名字只是文字里的写法，不存进积木：打印时取 key / value，和变量、别的形参重名就加数字（value2）。
• for (const [key] of Object.entries(o)) 只绑定键；for (const x of ...) 绑定的是值，键槽照常在积木上。
• 循环体里写 break; / continue; 只在解释执行有效；编译执行里被忽略（扩展 1.6.18 的循环没接这两个积木），文字里写了会给 W_FOREACH_BREAK 警告。要提前结束就把后面的语句放进 if。
• 块式等价写法是带形参的回调：test.moreDataTypes.forEachWithObj(o, (key, value) => { ... })，见回调形参。

回调方法（集市版）#

回调是 (形参...) => 表达式 的箭头函数，形参依次绑定积木上的参数槽，回调体是一个表达式（不是 { ... } 语句）。

• 回调体产出的值放进列表时，数字字面量是数字、true / false 是布尔：L.map((item) => 5) 得到数字 5，和 L.push(5) 同一条规则。
• 形参只在回调体里有效，名字是文字里的写法：打印时取积木上槽的名字（item、index、acc、a、b），重名加数字；少写形参也行，没写的槽照样在积木上。
• index 从 1 起（受 ads.indexStart 控制）；some / every / find* 作用在对象上时 index 是属性名。reduce 对对象也能累加（把属性值加起来），map 对对象得到空列表 []，sort(回调) 只用于列表。
• 里层回调会盖住外层的同名积木：item、index 在各个回调积木里是同一块积木，运行时读最近一层的值。在里层回调体里写外层的 item 报 E_PARAM_SHADOWED（连里层没写形参的槽也算：reduce 有 index 槽，写 (acc, cur) 它也在运行时定义 index）。要用外层的值，先放进变量。
• 回调积木在编译模式下靠扩展自己的编译支持（扩展设置里的「开启编译优化」，默认开）；关掉后编译模式里这些积木在日志里报错、什么都不做。解释执行不受影响。

其他函数（集市版）#

数字、文字和值#

• 值放进对象、列表时，数字字面量是数字：o.hp = 100 之后 typeof o.hp 是 "number"，JSON.stringify(o) 里是 100，两种运行模式都一样。 编出来的积木是一个 0 + 100 的运算（运算的结果才是数字），true / false 编成解析 JSON。0 + n 同理：两种模式都存真数字。
• 别的情况解释模式和编译模式（项目默认）不一样，两个版本实测相同（下表）。原因是编译器认得常量：数字样的常量按数字传给扩展，变量被赋成常量后它的类型也被编译器推出来。

需要数字样的文字在两种模式下都保持文字：写在 {...} / [...] 字面量里（{k: "5"}，全字面量按 JSON 解析，文字原样保留），或者拼一下（o.k = "5" + ""）。 编译模式下 o.k = "5" 存不成文字，o.k = `${"5"}` 也一样（单段模板就是那个字符串字面量）。JSON.parse 要读数字样的文字时，别让编译器把它看成常量（来自 store.get、拼接的结果等），或直接写成数字。

• 字符串字面量在解释模式里是文字：o.id = "5" 存文字；积木里输入框敲的 5 是文字，读回时写成 "5"。
• 缺失的属性读出空文字 ""，null 存不进去也比不了：用 o.k == "" 或 o.has("k")。o.k = null、x == null 报 E_MDT_NULL；{a: null}、[null] 这样字面量里的 null 同样报 E_MDT_NULL（和动态路径一致）。 积木里 JSON 文本含 null 是合法的（手拖的 getObjFromJson("{\"a\":null}")）：存进去，读出来是 ""，size 会把它计数；这样的积木打印成 JSON.parse("{\"a\":null}")，读回无损。
• 字面量里不是有限数的数字（1e400、-1e400）报 E_MDT_NUMBER：JSON 里没有 Infinity，静态字面量会悄悄变成 null。先建对象，再 o.k = 1e400（运行时存真的 Infinity），或写文字 "Infinity"。
• 键始终是文字：o[1] 和 o["1"] 是同一个键。整数样的键（"1"、"12"）运行时被引擎提到对象最前面：o = {"2": "b", "1": "a"} 用起来是 {"1":"a","2":"b"}， 只有积木里保住了书写顺序，运行时顺序不归 DSL 管。

下标#

列表下标从 1 数起，负数从末尾倒数（L[-1] 最后一项），0 取不到东西：Scratch 列表上的字面量 0 和 L.insert(0, v) 给 W_INDEX_FROM_ONE 警告。 对象 / 列表变量上的 o[0]、delete o[0]、o.items[0] = 1 不给警告：接收者的类型这里看不出，0 也可能是对象的键 "0"。 ads.indexStart(0) 把整个作品的列表改成从 0 数，之后写法不变，字面量下标自己对应调整；文本里 ads.indexStart(0) 之后的 0 下标不再给 W_INDEX_FROM_ONE（再写 ads.indexStart(1) 恢复提示）。 自动创建默认关：o.a.b = 1 在 o.a 不存在时什么都不做；ads.autoCreate(true) 之后会沿路径建出对象。 ads.allowJSON(false) 之后，内容像 JSON 的文字不再被悄悄当成对象读。

陷阱#

对象和列表是引用：p = o; p.x = 2 之后 o.x 也是 2，要复制用 clone / structuredClone。

积木式写法#

所有积木照常可以写成块式 moreDataTypes.getPropOfObject("k", o, ["b", "c"])（扩展 id 前缀随作品里装的 id）。扩展 id 带点时（集市版）， 前缀是成员链：test.moreDataTypes.getPropOfObject("k", o, ["b", "c"])；id 或积木名写不成标识符（连字符、空格、中文）时写成 ext["my-ext"]["积木名"](...)，规则见 dsl-syntax.md。

动态参数写在固定参数后面， 一个槽的组写数组 ["b", "c"]，键值成对的组（getNewObject）写 [["a", 1], ["b", x]]，具名写法用 DYNAMIC_ARGS1、DYNAMIC_ARGS2… 动态参数存档时是积木 mutation 的 dynamicargids / dynamicargtypes，输入名从 DYNAMIC_ARGS1 起连续编号，编辑器里的积木和文本编出来的完全一致。 集市版的 getNewSet、merge 也是动态参数（merge 的组插在 B 后面）。

带参数槽的积木（遍历、mapList、reduceList、someAll、findInList、listFrom、sortListByRule）块式写成回调： test.moreDataTypes.mapList(o, (item, index) => 表达式)、test.moreDataTypes.forEachWithObj(o, (key, value) => { ... })， 回调永远是最后一个参数，形参依次绑定积木上的参数槽（forEachWithObj 是键、值，reduceList 是 acc、item、index，sortListByRule 是 a、b）。 具名写法把回调放在回调体输入的键里：{NAME_OR_OBJ: o, EXP: (item) => item}，或者作为第二个参数。 参数槽里的影子是积木自己的可再生参数（test.moreDataTypes.item()、forEachKey()……）；回调体里引用形参就是引用这块积木。 没有写成回调的形状（槽里被别的积木盖住、缺输入的）读回时保持位置参数写法，参数槽里的标准影子写成它自己的调用，同样无损。

回调形参名写不成标识符的槽（带空格、连字符、数字开头、保留字、空名……）不打印成回调，保持位置参数写法 cb.loopWith(3, "my item", () => { ... })，读回无损。 扩展 id 是 JavaScript 保留字或 DSL 自己占用的名字（if、null、class、when、call、Math、JSON、Object、store、ads、ext、stage……）时， 一律写成 ext["id"].积木名(...)，不会打印出读不回的 null.go("p")。 带点 id 的链没对上已装扩展、根名又不是任何变量时（FurryR.NotJS.run()）是还没装的扩展：编译报 E_UNKNOWN_BLOCK，fix 里写出这个 id 的 add_extension； 写入 / 贴入前的预检按文字里写的 id 装它（id 带下划线时也按写的 id，不是第一段）。

缺扩展的页读出来是只读预览，预览里高级数据结构的积木也统一写成块式，不会混出一半糖（size(o)、store.set）一半块式；装上缺的扩展之后读到的才是糖。

编译配置#

编译执行时，自制积木里只用同步积木才能内联，所以每块积木在 编译配置 里声明 sync：线上版共 57 块（原有的 10 块 + 47 块）， 集市版 72 块 sync（再加 15 块），其余 7 块是 lambda / 循环积木（会让出，不声明）、8 块是参数 reporter。 线上版里取 / 设属性两块另有「快路径」替身，对着扩展源码写，所以只在扩展还是写它时那个版本时装上：fastGuard 把扩展里相关几个方法的源码（getPropOfObject、setPropOfObject、 __getObjByNameOrObj、__getDeepestObjAndProp、__setDataByOption、anythingToSCArg，加上 SafeObject 的 isSafeObjectLike、getActualObject、toSafeObject）拼起来做 FNV-1a 哈希， 和配置里记的 eb13b2a5 比；扩展改了其中任何一个方法，哈希对不上，替身就不装，退回扩展自己的实现。集市版哈希对不上，不带快路径。