@kubohiroya/turbowarp-text-lines 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ja.md CHANGED
@@ -4,10 +4,11 @@
4
4
 
5
5
  [English](README.md) | 日本語
6
6
 
7
- TurboWarpのプロジェクトで複数行テキストを扱います。Text Linesは次の3つのblockを追加します。
7
+ TurboWarpのプロジェクトで複数行テキストを扱います。Text Linesは次の4つのblockを追加します。
8
8
 
9
9
  - テキストの行数を数える。
10
10
  - 位置を指定して1行を取り出す。
11
+ - 全行をJSON配列として取り出す。
11
12
  - テキストの全行でScratchのリストを置き換える。
12
13
 
13
14
  **ユーザーガイド:** [English](https://kubohiroya.github.io/turbowarp-text-lines/) · [日本語](https://kubohiroya.github.io/turbowarp-text-lines/ja/)
@@ -60,7 +61,7 @@ flowchart TD
60
61
  class count,line,list extension
61
62
  ```
62
63
 
63
- 角の丸い2つのreporter blockは値を返します。command blockは選択したリストをその場で書き換えます。
64
+ 角の丸いreporter blockは値を返します。command blockは選択したリストをその場で書き換えます。
64
65
 
65
66
  ## ブロック
66
67
 
@@ -70,6 +71,7 @@ flowchart TD
70
71
  |---|---|---|
71
72
  | 全行を数える | `number of lines in [TEXT]` | `3` |
72
73
  | 1行を読む | `line [LINE] of [TEXT]`(行に`2`を指定) | `Banana` |
74
+ | 全行をJSONで取り出す | `lines of [TEXT] as JSON` | `["Apple","Banana","Cherry"]` |
73
75
  | テキストをリストの項目にする | `put lines of [TEXT] into list [LIST]` | `Apple`、`Banana`、`Cherry` |
74
76
 
75
77
  ### block定義
@@ -80,6 +82,7 @@ flowchart TD
80
82
  |---|---|---|---|
81
83
  | `number of lines in [TEXT]` | Reporter | `lineCount` | 渡されたテキストの行数を返します。 |
82
84
  | `line [LINE] of [TEXT]` | Reporter | `lineAt` | 1始まりの行番号で1行を返します。範囲外の行番号は空文字列を返します。 |
85
+ | `lines of [TEXT] as JSON` | Reporter | `linesJson` | 全行を文字列のJSON配列で返します。項目数は行数と常に一致します。 |
83
86
  | `put lines of [TEXT] into list [LIST]` | Command | `writeLinesToList` | 指定したScratchリストの内容を、渡されたテキストの各行で置き換えます。 |
84
87
 
85
88
  `TEXT`の既定値は`first line\nsecond line`、`LINE`の既定値は`1`、`LIST`は`LIST_MENU`から選びます。
@@ -93,11 +96,25 @@ flowchart TD
93
96
  | 空のテキスト | 空行1行として扱います |
94
97
  | 改行で終わるテキスト | 末尾に空行を1つ加えます |
95
98
  | リストのcommand | 選択したリストの既存項目をすべて置き換えます |
99
+ | JSONのblock | 他のblockと同じ規則で分割するため、配列の項目数は`number of lines in [TEXT]`と常に一致します |
96
100
  | 改行コード | LF(`\n`)、CRLF(`\r\n`)、CR(`\r`)を受け付けます |
97
101
 
98
102
  > [!WARNING]
99
103
  > リストのcommandを実行する前に、残したい内容は控えておいてください。
100
104
 
105
+ ## TurboWarp Structured Dataと組み合わせる
106
+
107
+ `lines of [TEXT] as JSON`の結果は、[TurboWarp Structured Data](https://github.com/kubohiroya/turbowarp-structured-data)がそのまま読めるJSONです。
108
+ Structured Dataの`for each`で行を順に処理できます。
109
+
110
+ ```text
111
+ parse JSON (lines of [TEXT] as JSON) as [lines]
112
+ for each in [lines] at path [$] max [100]
113
+ ```
114
+
115
+ 1回のloopで扱えるのは1,000件まで、Structured Dataが受け付けるJSONは256 KiBまでです。それより長いテキストは、
116
+ `put lines of [TEXT] into list [LIST]`でリストへ入れ、Scratchのリストのblockで扱ってください。
117
+
101
118
  図入りの例と日本語版は[ユーザーガイド](https://kubohiroya.github.io/turbowarp-text-lines/)にあります。
102
119
 
103
120
  ## 開発
package/README.md CHANGED
@@ -4,10 +4,11 @@
4
4
 
5
5
  English | [日本語](README.ja.md)
6
6
 
7
- Use multiline text in TurboWarp projects. Text Lines adds three blocks that can:
7
+ Use multiline text in TurboWarp projects. Text Lines adds four blocks that can:
8
8
 
9
9
  - count the lines in some text;
10
- - return one line by its position; and
10
+ - return one line by its position;
11
+ - return every line as a JSON array; and
11
12
  - replace a Scratch list with every line from the text.
12
13
 
13
14
  **User guide:** [English](https://kubohiroya.github.io/turbowarp-text-lines/) · [日本語](https://kubohiroya.github.io/turbowarp-text-lines/ja/)
@@ -30,7 +31,7 @@ The ready-to-use JavaScript file is committed to this repository. You do not nee
30
31
  Allow the custom extension to load, choose **Run without sandbox**, and
31
32
  click the green flag. The stage shows **Line count: 3**, **Second line: Banana**,
32
33
  and a **Lines** list containing Apple, Banana, and Cherry. Running it again replaces
33
- the list. The sample uses all three Text Lines blocks and no other extensions.
34
+ the list. The sample uses three Text Lines blocks and no other extensions.
34
35
 
35
36
  The SB3 includes the tested Text Lines JavaScript so TurboWarp can offer the
36
37
  unsandboxed permission checkbox. Reopening the downloaded SB3 needs no extra JS download.
@@ -66,7 +67,7 @@ flowchart TD
66
67
  class count,line,list extension
67
68
  ```
68
69
 
69
- The two rounded reporter blocks return a value. The command block changes the selected list immediately.
70
+ The rounded reporter blocks return a value. The command block changes the selected list immediately.
70
71
 
71
72
  ## Block reference
72
73
 
@@ -76,6 +77,7 @@ The two rounded reporter blocks return a value. The command block changes the se
76
77
  |---|---|---|
77
78
  | Count all lines | `number of lines in [TEXT]` | `3` |
78
79
  | Read one line | `line [LINE] of [TEXT]` with line `2` | `Banana` |
80
+ | Get every line as JSON | `lines of [TEXT] as JSON` | `["Apple","Banana","Cherry"]` |
79
81
  | Turn the text into list items | `put lines of [TEXT] into list [LIST]` | `Apple`, `Banana`, `Cherry` |
80
82
 
81
83
  The exact block definitions are generated from [`src/block-definitions.json`](src/block-definitions.json):
@@ -113,6 +115,21 @@ Returns one line using a one-based line number. Invalid line numbers return an e
113
115
 
114
116
  </details>
115
117
 
118
+ ### `lines of [TEXT] as JSON`
119
+
120
+ Returns every line as a JSON array of strings, with as many items as the line count.
121
+
122
+ <details>
123
+ <summary>Block metadata</summary>
124
+
125
+ | Property | Value |
126
+ |---|---|
127
+ | Type | Reporter |
128
+ | Opcode | `linesJson` |
129
+ | `TEXT` | String, default: `first line\nsecond line` |
130
+
131
+ </details>
132
+
116
133
  ### `put lines of [TEXT] into list [LIST]`
117
134
 
118
135
  Replaces the contents of the named Scratch list with the lines of the supplied text.
@@ -140,11 +157,25 @@ Replaces the contents of the named Scratch list with the lines of the supplied t
140
157
  | Empty text | Treats it as one empty line |
141
158
  | Text ending with a line break | Adds an empty final line |
142
159
  | List command | Replaces all existing items in the selected list |
160
+ | JSON block | Splits exactly like the other blocks, so the array always has as many items as `number of lines in [TEXT]` |
143
161
  | Line endings | Accepts LF (`\n`), CRLF (`\r\n`), and CR (`\r`) |
144
162
 
145
163
  > [!WARNING]
146
164
  > Copy any list contents you need to keep before running the list command.
147
165
 
166
+ ## Use with TurboWarp Structured Data
167
+
168
+ `lines of [TEXT] as JSON` returns text that [TurboWarp Structured Data](https://github.com/kubohiroya/turbowarp-structured-data)
169
+ can read directly, so its `for each` block can walk the lines:
170
+
171
+ ```text
172
+ parse JSON (lines of [TEXT] as JSON) as [lines]
173
+ for each in [lines] at path [$] max [100]
174
+ ```
175
+
176
+ One loop handles up to 1,000 items, and Structured Data accepts JSON text up to 256 KiB. For longer text,
177
+ use `put lines of [TEXT] into list [LIST]` and Scratch's own list blocks instead.
178
+
148
179
  For illustrated examples and the Japanese version, open the [complete user guide](https://kubohiroya.github.io/turbowarp-text-lines/).
149
180
 
150
181
  ## Development
@@ -184,44 +184,71 @@ var fixedInputEditors = [...new Set(fields.map((f) => f.opcode))].map((opcode) =
184
184
  settings: null
185
185
  })
186
186
  }));
187
- /** Registration follows the advertised opcode membership and the optional host capability. */
187
+ /**
188
+ * Registration follows the advertised opcode membership and the optional host capability.
189
+ * Loading a project disposes the runtime, which releases the registrations, but the extension
190
+ * stays loaded for the next project: they are registered again once that project has loaded.
191
+ * Only the owner's dispose is final.
192
+ */
188
193
  function fixedInputRegistration(scratch) {
189
194
  const host = scratch ?? {};
190
195
  let active;
191
196
  let membership = "";
192
197
  const removers = [];
193
198
  let stopped = false;
199
+ let released = false;
200
+ let requested = [];
194
201
  const clear = () => {
195
- host.vm?.runtime?.off?.("RUNTIME_DISPOSED", shutdown);
202
+ host.vm?.runtime?.off?.("RUNTIME_DISPOSED", release);
203
+ host.vm?.runtime?.off?.("PROJECT_LOADED", restore);
196
204
  for (const remove of removers.splice(0).reverse()) remove();
197
205
  active = void 0;
198
206
  membership = "";
199
207
  };
208
+ const register = (visibleOpcodes) => {
209
+ const api = host.gui?.blockEditors;
210
+ const definitions = fixedInputEditors.filter((definition) => definition.opcodes.every((opcode) => visibleOpcodes.includes(opcode)));
211
+ const key = definitions.map((definition) => definition.editorId).join(",");
212
+ if (api === active && membership === key) return;
213
+ clear();
214
+ if (api?.apiVersion !== 1 || typeof api.registerFixedInputEditor !== "function" || !definitions.length) return;
215
+ try {
216
+ for (const definition of definitions) {
217
+ const remove = api.registerFixedInputEditor.call(api, definition);
218
+ if (typeof remove !== "function") throw new TypeError("Invalid fixed input cleanup.");
219
+ removers.push(remove);
220
+ }
221
+ active = api;
222
+ membership = key;
223
+ host.vm?.runtime?.on?.("RUNTIME_DISPOSED", release);
224
+ } catch (error) {
225
+ clear();
226
+ throw error;
227
+ }
228
+ };
229
+ /** The runtime of this project is gone; wait for the next project before registering again. */
230
+ const release = () => {
231
+ clear();
232
+ released = true;
233
+ host.vm?.runtime?.on?.("PROJECT_LOADED", restore);
234
+ };
235
+ const restore = () => {
236
+ if (stopped || !released) return;
237
+ released = false;
238
+ try {
239
+ register(requested);
240
+ } catch {}
241
+ };
200
242
  const shutdown = () => {
201
243
  stopped = true;
244
+ released = false;
202
245
  clear();
203
246
  };
204
247
  return {
205
248
  ensure(visibleOpcodes) {
206
- const api = host.gui?.blockEditors;
207
- const definitions = fixedInputEditors.filter((definition) => definition.opcodes.every((opcode) => visibleOpcodes.includes(opcode)));
208
- const key = definitions.map((definition) => definition.editorId).join(",");
209
- if (stopped || api === active && membership === key) return;
210
- clear();
211
- if (api?.apiVersion !== 1 || typeof api.registerFixedInputEditor !== "function" || !definitions.length) return;
212
- try {
213
- for (const definition of definitions) {
214
- const remove = api.registerFixedInputEditor.call(api, definition);
215
- if (typeof remove !== "function") throw new TypeError("Invalid fixed input cleanup.");
216
- removers.push(remove);
217
- }
218
- active = api;
219
- membership = key;
220
- host.vm?.runtime?.on?.("RUNTIME_DISPOSED", shutdown);
221
- } catch (error) {
222
- clear();
223
- throw error;
224
- }
249
+ requested = visibleOpcodes;
250
+ if (stopped || released) return;
251
+ register(visibleOpcodes);
225
252
  },
226
253
  dispose: shutdown
227
254
  };
@@ -255,6 +282,16 @@ var block_definitions_default = {
255
282
  }
256
283
  }
257
284
  },
285
+ {
286
+ "opcode": "linesJson",
287
+ "blockType": "REPORTER",
288
+ "text": "lines of [TEXT] as JSON",
289
+ "description": "Returns every line as a JSON array of strings, with as many items as the line count.",
290
+ "arguments": { "TEXT": {
291
+ "type": "STRING",
292
+ "defaultValue": "first line\nsecond line"
293
+ } }
294
+ },
258
295
  {
259
296
  "opcode": "writeLinesToList",
260
297
  "blockType": "COMMAND",
@@ -357,6 +394,9 @@ var TextLinesExtension = class {
357
394
  if (!Number.isFinite(line) || line < 1 || line > lines.length) return "";
358
395
  return lines[line - 1] ?? "";
359
396
  }
397
+ linesJson(args) {
398
+ return JSON.stringify(splitLines(Scratch.Cast.toString(args.TEXT)));
399
+ }
360
400
  writeLinesToList(args, util) {
361
401
  const listIdOrName = Scratch.Cast.toString(args.LIST);
362
402
  const stage = Scratch.vm.runtime.getTargetForStage();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/turbowarp-text-lines",
3
- "version": "0.5.0",
3
+ "version": "0.6.1",
4
4
  "description": "Use multiline text in TurboWarp projects with line counting, lookup, and list-writing blocks.",
5
5
  "author": {
6
6
  "name": "Hiroya Kubo",