@kubohiroya/turbowarp-text-lines 0.1.0 → 0.1.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.
@@ -15,3 +15,7 @@ jobs:
15
15
  node-version: 22
16
16
  - run: npm install
17
17
  - run: npm run check
18
+ - uses: actions/upload-artifact@v4
19
+ with:
20
+ name: text-lines-dist
21
+ path: dist/
@@ -0,0 +1,37 @@
1
+ name: Deploy user documentation
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ paths:
7
+ - docs/**
8
+ - .github/workflows/pages.yml
9
+ workflow_dispatch:
10
+
11
+ permissions:
12
+ contents: read
13
+ pages: write
14
+ id-token: write
15
+
16
+ concurrency:
17
+ group: pages
18
+ cancel-in-progress: false
19
+
20
+ jobs:
21
+ deploy:
22
+ environment:
23
+ name: github-pages
24
+ url: ${{ steps.deployment.outputs.page_url }}
25
+ runs-on: ubuntu-latest
26
+ steps:
27
+ - name: Check out repository
28
+ uses: actions/checkout@v6
29
+ - name: Configure GitHub Pages
30
+ uses: actions/configure-pages@v5
31
+ - name: Upload documentation
32
+ uses: actions/upload-pages-artifact@v4
33
+ with:
34
+ path: docs
35
+ - name: Deploy documentation
36
+ id: deployment
37
+ uses: actions/deploy-pages@v4
package/LICENSE ADDED
@@ -0,0 +1,4 @@
1
+ Mozilla Public License Version 2.0
2
+
3
+ This project is licensed under the Mozilla Public License, version 2.0.
4
+ The full license text is available at https://www.mozilla.org/MPL/2.0/.
package/README.md CHANGED
@@ -1,8 +1,62 @@
1
- # TurboWarp Text Lines
1
+ # Text Lines for TurboWarp
2
2
 
3
- A TurboWarp extension for counting, reading, and splitting text by lines.
3
+ Use multiline text in TurboWarp projects. Text Lines adds three blocks that can:
4
4
 
5
- ## Blocks
5
+ - count the lines in some text;
6
+ - return one line by its position; and
7
+ - replace a Scratch list with every line from the text.
8
+
9
+ **User guide:** [English](https://kubohiroya.github.io/turbowarp-text-lines/) · [日本語](https://kubohiroya.github.io/turbowarp-text-lines/ja/)
10
+
11
+ ## Quick start
12
+
13
+ 1. Download [`dist/text-lines.js`](dist/text-lines.js?raw=1).
14
+ 2. In **TurboWarp Desktop**, open **Extensions**, choose **Custom Extension**, and load the downloaded file.
15
+ 3. Enable **Run extension without sandbox** when TurboWarp asks.
16
+
17
+ > [!IMPORTANT]
18
+ > Text Lines needs to run without the sandbox because its command block writes directly to Scratch lists.
19
+
20
+ The ready-to-use JavaScript file is committed to this repository. You do not need Node.js to install the extension.
21
+
22
+ ## See it in action
23
+
24
+ Start with this text:
25
+
26
+ ```text
27
+ Apple
28
+ Banana
29
+ Cherry
30
+ ```
31
+
32
+ Each block uses the same text in a different way:
33
+
34
+ ```mermaid
35
+ flowchart TD
36
+ input["Input text<br/>Apple<br/>Banana<br/>Cherry"]
37
+ input --> count["number of lines in TEXT<br/>returns: 3"]
38
+ input --> line["line 2 of TEXT<br/>returns: Banana"]
39
+ input --> list["put lines of TEXT into list items<br/>list: Apple · Banana · Cherry"]
40
+
41
+ classDef source fill:#ffffff,color:#18212b,stroke:#5b80a5,stroke-width:2px
42
+ classDef extension fill:#5b80a5,color:#ffffff,stroke:#3f658a,stroke-width:2px
43
+ class input source
44
+ class count,line,list extension
45
+ ```
46
+
47
+ The two rounded reporter blocks return a value. The command block changes the selected list immediately.
48
+
49
+ ## Block reference
50
+
51
+ ### Which block should I use?
52
+
53
+ | Goal | Block | Result for the example above |
54
+ |---|---|---|
55
+ | Count all lines | `number of lines in [TEXT]` | `3` |
56
+ | Read one line | `line [LINE] of [TEXT]` with line `2` | `Banana` |
57
+ | Turn the text into list items | `put lines of [TEXT] into list [LIST]` | `Apple`, `Banana`, `Cherry` |
58
+
59
+ The exact block definitions are generated from [`src/block-definitions.json`](src/block-definitions.json):
6
60
 
7
61
  <!-- BEGIN GENERATED BLOCKS -->
8
62
 
@@ -10,16 +64,24 @@ A TurboWarp extension for counting, reading, and splitting text by lines.
10
64
 
11
65
  Returns the number of lines in the supplied text.
12
66
 
67
+ <details>
68
+ <summary>Block metadata</summary>
69
+
13
70
  | Property | Value |
14
71
  |---|---|
15
72
  | Type | Reporter |
16
73
  | Opcode | `lineCount` |
17
74
  | `TEXT` | String, default: `first line\nsecond line` |
18
75
 
76
+ </details>
77
+
19
78
  ### `line [LINE] of [TEXT]`
20
79
 
21
80
  Returns one line using a one-based line number. Invalid line numbers return an empty string.
22
81
 
82
+ <details>
83
+ <summary>Block metadata</summary>
84
+
23
85
  | Property | Value |
24
86
  |---|---|
25
87
  | Type | Reporter |
@@ -27,40 +89,63 @@ Returns one line using a one-based line number. Invalid line numbers return an e
27
89
  | `TEXT` | String, default: `first line\nsecond line` |
28
90
  | `LINE` | Number, default: `1` |
29
91
 
92
+ </details>
93
+
30
94
  ### `put lines of [TEXT] into list [LIST]`
31
95
 
32
96
  Replaces the contents of the named Scratch list with the lines of the supplied text.
33
97
 
98
+ <details>
99
+ <summary>Block metadata</summary>
100
+
34
101
  | Property | Value |
35
102
  |---|---|
36
103
  | Type | Command |
37
104
  | Opcode | `writeLinesToList` |
38
105
  | `TEXT` | String, default: `first line\nsecond line` |
39
- | `LIST` | String, default: `lines` |
106
+ | `LIST` | String, menu: `LIST_MENU` |
107
+
108
+ </details>
40
109
 
41
110
  <!-- END GENERATED BLOCKS -->
42
111
 
43
- Line numbers are one-based. An invalid line number returns an empty string. The list block replaces the contents of the named Scratch list.
112
+ ## Important behavior
44
113
 
45
- The extension accepts LF, CRLF, and CR line endings.
114
+ | Situation | What Text Lines does |
115
+ |---|---|
116
+ | Line numbers | Starts counting at `1`, not `0` |
117
+ | Invalid line number | Returns an empty string |
118
+ | Empty text | Treats it as one empty line |
119
+ | Text ending with a line break | Adds an empty final line |
120
+ | List command | Replaces all existing items in the selected list |
121
+ | Line endings | Accepts LF (`\n`), CRLF (`\r\n`), and CR (`\r`) |
122
+
123
+ > [!WARNING]
124
+ > Copy any list contents you need to keep before running the list command.
125
+
126
+ For illustrated examples and the Japanese version, open the [complete user guide](https://kubohiroya.github.io/turbowarp-text-lines/).
46
127
 
47
128
  ## Development
48
129
 
130
+ Install dependencies and run every check:
131
+
49
132
  ```bash
50
133
  npm install
51
134
  npm run check
52
135
  ```
53
136
 
54
- Regenerate the block documentation after changing `src/block-definitions.json`:
137
+ Useful commands:
55
138
 
56
- ```bash
57
- npm run docs
58
- ```
59
-
60
- The build produces `dist/text-lines.js`.
139
+ | Command | Purpose |
140
+ |---|---|
141
+ | `npm run dev` | Rebuild the extension while files change |
142
+ | `npm run test` | Run the test suite once |
143
+ | `npm run typecheck` | Check TypeScript types |
144
+ | `npm run build` | Build `dist/text-lines.js` |
145
+ | `npm run docs` | Regenerate the block reference from the canonical definitions |
61
146
 
62
- Because the extension writes directly to Scratch list variables, load it as an unsandboxed custom extension.
147
+ When extension source changes, rebuild and commit [`dist/text-lines.js`](dist/text-lines.js). When block definitions change, run `npm run docs` before committing.
63
148
 
64
149
  ## License
65
150
 
66
- MPL-2.0
151
+ [MIT](LICENSE)
@@ -0,0 +1,89 @@
1
+ // Name: Text Lines
2
+ // ID: kubohiroyatextlines
3
+ // Description: Count, read, and split text by lines in TurboWarp.
4
+ // By: Hiroya Kubo
5
+ // License: MPL-2.0
6
+
7
+ (function (Scratch) {
8
+ 'use strict';
9
+
10
+ const extensionName = "Text Lines";
11
+ const blocks = [{ "opcode": "lineCount", "blockType": "REPORTER", "text": "number of lines in [TEXT]", "description": "Returns the number of lines in the supplied text.", "arguments": { "TEXT": { "type": "STRING", "defaultValue": "first line\nsecond line" } } }, { "opcode": "lineAt", "blockType": "REPORTER", "text": "line [LINE] of [TEXT]", "description": "Returns one line using a one-based line number. Invalid line numbers return an empty string.", "arguments": { "TEXT": { "type": "STRING", "defaultValue": "first line\nsecond line" }, "LINE": { "type": "NUMBER", "defaultValue": 1 } } }, { "opcode": "writeLinesToList", "blockType": "COMMAND", "text": "put lines of [TEXT] into list [LIST]", "description": "Replaces the contents of the named Scratch list with the lines of the supplied text.", "arguments": { "TEXT": { "type": "STRING", "defaultValue": "first line\nsecond line" }, "LIST": { "type": "STRING", "menu": "LIST_MENU" } } }];
12
+ const definitions = {
13
+ extensionName,
14
+ blocks
15
+ };
16
+ const blockDefinitions = definitions.blocks;
17
+ class TextLinesExtension {
18
+ getInfo() {
19
+ const translate = Scratch.translate;
20
+ return {
21
+ id: "kubohiroyatextlines",
22
+ name: translate(definitions.extensionName),
23
+ docsURI: "https://kubohiroya.github.io/turbowarp-text-lines/",
24
+ color1: "#5B80A5",
25
+ blocks: blockDefinitions.map((block) => this.toScratchBlock(block)),
26
+ menus: {
27
+ LIST_MENU: {
28
+ acceptReporters: true,
29
+ items: "getLists"
30
+ }
31
+ }
32
+ };
33
+ }
34
+ getLists() {
35
+ const stage = Scratch.vm.runtime.getTargetForStage();
36
+ const editingTarget = Scratch.vm.editingTarget;
37
+ const lists = [
38
+ ...stage ? Object.values(stage.variables) : [],
39
+ ...editingTarget && editingTarget !== stage ? Object.values(editingTarget.variables) : []
40
+ ].filter((variable) => variable.type === "list");
41
+ if (lists.length === 0) return [""];
42
+ return lists.map((list) => ({ text: list.name, value: list.id }));
43
+ }
44
+ lineCount(args) {
45
+ return splitLines(Scratch.Cast.toString(args.TEXT)).length;
46
+ }
47
+ lineAt(args) {
48
+ const lines = splitLines(Scratch.Cast.toString(args.TEXT));
49
+ const line = Math.trunc(Scratch.Cast.toNumber(args.LINE));
50
+ if (!Number.isFinite(line) || line < 1 || line > lines.length) return "";
51
+ return lines[line - 1] ?? "";
52
+ }
53
+ writeLinesToList(args, util) {
54
+ const listIdOrName = Scratch.Cast.toString(args.LIST);
55
+ const stage = Scratch.vm.runtime.getTargetForStage();
56
+ const variable = util.target.lookupVariableById(listIdOrName) ?? stage?.lookupVariableById(listIdOrName) ?? util.target.lookupVariableByNameAndType(listIdOrName, "list") ?? stage?.lookupVariableByNameAndType(listIdOrName, "list");
57
+ if (!variable || variable.type !== "list") throw new Error(`List not found: ${listIdOrName}`);
58
+ variable.value = splitLines(Scratch.Cast.toString(args.TEXT));
59
+ variable._monitorUpToDate = false;
60
+ }
61
+ toScratchBlock(block) {
62
+ return {
63
+ opcode: block.opcode,
64
+ blockType: Scratch.BlockType[block.blockType],
65
+ text: Scratch.translate(block.text),
66
+ arguments: Object.fromEntries(
67
+ Object.entries(block.arguments).map(([name, argument]) => [
68
+ name,
69
+ Object.fromEntries(
70
+ Object.entries({
71
+ type: Scratch.ArgumentType[argument.type],
72
+ defaultValue: argument.defaultValue,
73
+ menu: argument.menu
74
+ }).filter(([, value]) => value !== void 0)
75
+ )
76
+ ])
77
+ )
78
+ };
79
+ }
80
+ }
81
+ function splitLines(text) {
82
+ return text.split(/\r\n|\n|\r/);
83
+ }
84
+ if (!Scratch.extensions.unsandboxed) {
85
+ throw new Error("Text Lines must run unsandboxed to write to Scratch lists.");
86
+ }
87
+ Scratch.extensions.register(new TextLinesExtension());
88
+
89
+ })(Scratch);
@@ -0,0 +1,4 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
2
+ <rect width="64" height="64" rx="16" fill="#5b80a5"/>
3
+ <path d="M17 21h30M17 32h30M17 43h22" fill="none" stroke="#fff" stroke-linecap="round" stroke-width="6"/>
4
+ </svg>