🆕 Smalruby 独自 — upstream に存在しない、Smalruby のために新規追加された機能
converter-stages.md は、Ruby → ブロックの変換器を 解析・分析・変換・仕上げ の 4 段に分けた形と、
そこまでの移し方を書いている。この文書は、その続きとして次を決める。
- 段の境界で 何を渡すか(段の約束)と、約束から外れている所。
- 日本語モード(日本語タブ)の変換を、この 4 段にどうつなぐか。
- ブロック → Ruby(生成器)をどう扱うか。
- 振る舞いを変えずに残りを移す順番、リスク、実装の Issue の案。
- 橋渡しの決まり(何をどのブロックと注釈
@ruby:*で表すか)はbridging-patterns.md。 - 日本語モードの方針と基本設計は
../dncl/policy.mdと../dncl/design.md。 記法(何をどう書くか)はそちらが正で、この文書は 変換の作り だけを扱う。
日本語のテキスト ─┐
│ 0. 日本語の前の段(2 章): 日本語の構文木 → Ruby の構文木 → Ruby のテキスト + 行の対応
▼
Ruby のテキスト
│ 1. 解析
▼
ParseResult { root, source, index, comments, errors }
│ 2. 分析(純粋な関数。変換器も VM も読まない)
▼
Analysis 凍結した表 { variables, locals, procedures, classes, symbols, errors }
│ 3. 変換(Analysis を読むだけ。作ったものは BlockStore に書く)
▼
BlockStore { blocks, comments, variables, lists, broadcasts, symbols } + 巻き戻しの記録
│ 4. 仕上げ
▼
ConvertResult { blocks, variables, lists, comments, classInfo, extensionIds, errors } と apply()
| 段 | 受けとるもの | 出すもの | してはいけないこと |
|---|---|---|---|
| 解析 | Ruby のテキスト、読みこみ済みの prism | ParseResult(構文木、ソースの索引: バイト → 文字・改行の表、コメント、構文エラー) |
ブロックを作る、変換器の状態を読む |
| 分析 | ParseResult |
凍結した Analysis |
変換器・VM・スプライトを読む、エラーを投げる(誤りは errors に入れる) |
| 変換 | ParseResult・Analysis・変換器の設定(Ruby のバージョン、ステージか、翻訳、呼び出しの表)・スプライトの素材 |
BlockStore |
Analysis を書きかえる、変換の途中で全体を調べ直す |
| 仕上げ | BlockStore・ParseResult・ソース |
ConvertResult。apply() でスプライトへ書きこむ |
ノードごとの変換をする |
段の約束から、いまはまだ外れている所(3 章で移す):
| 外れている所 | いま | 約束の形 |
|---|---|---|
| 拡張機能の呼び出し | pen 以外は registerOnSend の handler |
呼び出しの表(send-table.js)の行 |
procedures.definitions |
表はあるが、my-blocks.js がその場で def を調べている |
変換は表を読む |
symbols |
変換の途中で _context.symbols に集めている |
候補は分析、使われたものだけ BlockStore に入れる(いまの振る舞い) |
ローカル変数の範囲ごとの番号(_x_1_) |
範囲は分析、番号は変換の途中で決める | 番号も分析で決める |
BlockStore |
_context の表と巻き戻しの記録(context-journal.js)が別々にある |
1 つの入れ物にし、変換はそれを通してだけ書く |
日本語 → (前処理: 標準の形を DNCL 風の形へ・文字列) → (1 行ずつ文字列を置きかえ) → Ruby のテキスト → 4 段 → ブロック
ブロック → 生成器 → Ruby のテキスト → (1 行ずつ正規表現で置きかえ) → 日本語
- 日本語 → Ruby は
dncl-to-ruby.js(前処理dncl-v2-preprocessor.js、1 行の変換dncl-line-converter.js、検査dncl-validator.js)。 Ruby → 日本語はruby-to-dncl.jsとruby-to-dncl-line-converter.js。どちらも 構文木を作らず、行ごとの文字列の置きかえ で変換する。 - 配列や関数の名前は、変換の前にテキスト全体を見て、モジュールの変数(
dncl-state.jsのarrayNamesなど)に置く。 - 行の対応は、前処理と行の変換が行を足したり減らしたりするたびに記録する(
dncl-source-map.js)。
行ごとの置きかえなので、次のような不具合が 1 つずつ、別々の場所で起きて、別々に直すことになる。
- 文字列やコメントの中の記号(
←、,など)まで置きかえてしまう。 - 1 行に書いた複数の代入、罫線と字下げだけのブロックの閉じ方など、行をまたぐ形の扱い。
- Ruby → 日本語が Ruby を解析しないので、生成器が出す形が少し変わると、置きかえが外れる。
- モジュールの変数に状態を置くので、変換を同時に 2 つ行えない・テストの順に左右される。
日本語のテキストから 日本語の構文木 を作り、それを Ruby の構文木 に対応させる。 構文木を作る処理はライブラリにして、のちに OSS として公開する。最初は Node(JavaScript)で書き、 それをもとに Ruby でも実装して、日本語 ⇔ Ruby をやりとりできるようにする。
日本語のテキスト
│ a. 日本語の解析 字句 → 日本語の構文木(JaAST。ノードごとに日本語の行と列)
▼
JaAST
│ b. 組み立て JaAST → Ruby の構文木(RubyAST。小さな自前の形)。設定(添字の始まりなど)はここで構文木を変えて表す
▼
RubyAST
│ c. Ruby を書く RubyAST → Ruby のテキストと、Ruby の行 → 日本語の行の対応
▼
Ruby のテキスト → いまの 4 段(解析から) → ブロック
ブロック → 生成器 → Ruby のテキスト
│ d. prism で解析し、prism の構文木 → JaAST
▼
JaAST
│ e. 日本語を書く 標準の形で、設定に合わせて(添字、コメントの記号、冒頭の説明文)
▼
日本語のテキスト
決めること と おすすめ:
| 決めること | おすすめ | わけ |
|---|---|---|
| 組み立てた Ruby をどう渡すか | Ruby のテキストにして、いまの解析の段から通す(b → c → 4 段)。prism のノードを直接作って分析の段へ渡すことはしない | 変換器の入り口が 1 つのままになる。prism のノードのクラスは prism の内部の形で、版が上がると変わる。日本語のプログラムは短く、prism で 2 回目の解析をしても遅くならない |
| RubyAST の形 | prism のノードの 種類の名前(CallNode・IfNode など)と、使う欄だけを持つ、ただのオブジェクト。日本語で書けるものの部分集合だけ |
逆向き(d)は prism の構文木から作るので、名前をそろえると対応が読みやすい。Ruby で実装するときも同じ形を JSON で持てる |
| 日本語の記法の揺れ | 読むとき(a)に全部受け付けて、JaAST では 1 つにする(行番号・罫線・全角・:・DNCL 風の形の閉じ方など)。書くとき(e)は 1 つの形だけを書く |
方針の「見た目の揺れは設定にしない、読むときは全部受け付け、書くときは 1 つ」をそのまま形にする |
| 設定(意味が変わるもの) | JaAST の先頭に設定を持つ(冒頭の説明文から読む)。添字が 1 から始まるときの A[i] → @A[i - 1] は、組み立て(b)で構文木を変えて表し、逆向き(d)で戻す |
文字列の置きかえでなく構文木でするので、式の中のどこにあっても同じに扱える |
| 日本語の関数・表示・入力 | ライブラリは「日本語の名前 → Ruby の呼び出し」の 表を外から受けとる。スモウルビーは、自分の表(表示する をコンソール拡張機能の呼び出しへ、など)を渡す |
ライブラリにスモウルビーやブロックの事情を入れない。OSS にしたとき、ほかの処理系でも使える |
| 行の対応 | Ruby を書く(c)ときに、Ruby の行ごとに JaAST のノードの日本語の行を記録する。変換器のエラー(Ruby の行)と、行 → ブロックの対応(Ruby タブの行のハイライト)は、この表で日本語の行に直す | 支える読み方の ②(行番号で行を指せる)。のちのトレース・実行回数も同じ表を使う |
| 日本語の言葉で出す誤り | 閉じ忘れ・閉じすぎ、もし の後の ならば 抜けなどは、日本語の解析(a)が日本語の行で出す。Ruby の誤り(変換器の誤り)より先に出す |
いまの「DNCL の言葉で言う閉じの誤り」と同じ振る舞いを保つ |
| ライブラリの置き場所(最初) | packages/scratch-gui/src/lib/ja-notation/(6 章で決めた置き場所)。外のモジュールを import しないことをテストで確かめる。形が決まったらワークスペースのパッケージへ、そのあと別のリポジトリへ出す |
最初からパッケージにすると、ビルドの手間(dist/、worktree の準備)が増える。境界のテストがあれば、あとで取り出すのは機械的な作業になる |
| prism への依存 | 日本語 → Ruby(a〜c)は prism を使わない。Ruby → 日本語(d)は、prism の解析の関数を外から受けとる | ライブラリが wasm を持たなくてよい。Ruby で実装するときは Ruby の prism をそのまま使える |
- 日本語の前の段は、Ruby のテキストと行の対応を出すだけ。4 段には手を入れない。
日本語にしかない事情(コンソール、ブロックの絞り込み)は、関数の表と、いまのブロックの絞り込み(
dncl-block-filter.js)で扱う。 - 日本語が出す Ruby は、変換器が受け付ける Ruby の部分集合でなければならない。これを 表のテスト で確かめる:
bridging-patterns.mdの表のテスト(ブロック ⇔ Ruby)に 日本語の列 を足し、日本語 ⇔ Ruby ⇔ ブロックを 1 行で書く(日本語の列がある行は、日本語 → Ruby → ブロックと、ブロック → Ruby → 日本語の両方を流す)。 - 橋渡しの工夫(ローカル変数の名前、戻り値、ハッシュなど)は Ruby の側だけで行う。日本語の構文木は橋渡しの注釈を知らない。
- 依存は無し(Node の標準と、外から受けとる関数だけ)。ESM の JavaScript。
- 入れるもの: 日本語の解析(標準の形と DNCL 風の形の読みこみ)、JaAST の形、組み立て(JaAST → RubyAST)、Ruby を書く、 prism の構文木 → JaAST、日本語を書く、設定の読み書き(冒頭の説明文)。
- 入れないもの: ブロック、Scratch、スモウルビーの関数の表、エディタの見た目(問題の形の描画は Monaco の側)。
- テストのデータ(
日本語 / Rubyの組)は JSON にして、Node と Ruby の実装が同じものを流す。 データは 自作のプログラム だけにする(大学入試センターの問題は使わない。方針の「AI と autopilot が守ること」)。
生成器(src/lib/ruby-generator/)は Blockly の生成器の形で、段に分け直さない。
ブロックを 1 行で書ける記法と表のテストで、生成を先に確かめられるようになったので、課題だったテストは解けている。
呼び出しの表(send-table.js)は、「表の opcode にはすべて生成器がある」ことを確かめるのに使い続ける。
日本語の経路の逆向き(d)は生成器の Ruby を prism で解析するので、生成器の出す形が少し変わっても日本語が崩れない。
どの段階も、先に表のテストと、いまの出力の記録(ゴールデン)を作り、差が 0 のまま移す。 これまでの段の移し方と同じく、変換器と往復のテストに書かれた Ruby をすべて流し、移す前と後の結果(エラーの行・列・文、ブロック、変数・リスト、コメント)を比べる。
| 順 | すること | 固定するテスト |
|---|---|---|
| R1 | 拡張機能の呼び出しを 1 つずつ表へ(music → text2speech → translate → video → microbit → micro:bit More → ev3 → wedo2 → boost → g2s → koshien → mesh など) | その拡張機能の往復テストを先に表へ移す |
| R2 | my-blocks.js が procedures.definitions を読むようにし、その場の下調べを消す |
my-blocks 系の表のテスト、往復テスト |
| R3 | ローカル変数の番号を分析で決める | ローカル変数の表のテスト(P1)、往復テスト |
| R4 | BlockStore を 1 つの入れ物にし、変換はそれを通してだけ書く |
表のテストすべて、orphan-blocks、往復テスト |
| R5 | 解析の段で「子 → 親」の索引を作り、エラーで文を指す処理とコメントの結びつけをそれで引く | エラーの位置のテスト、comment-placement、速さの計測 |
R1 は 1 つの拡張機能ごとに分けられ、ほかと並べて進められる。R2〜R4 は _context の扱いが重なるので、この順に 1 つずつ行う。
| 順 | すること | 差が 0 であることの確かめ方 |
|---|---|---|
| J0 | 安全網: 表のテストに日本語の列を足す。いまの日本語のテスト・教材・docs・生成AI の答えの例から、日本語のプログラムを集めた コーパス を作り、いまの dncl-to-ruby / ruby-to-dncl の出力をゴールデンとして記録する |
ゴールデンのテストが、いまの実装で通る |
| J1 | JaAST の形と、標準の形の日本語の解析(a)。組み立て(b)と Ruby を書く(c) | コーパスのすべてで、新しい経路の Ruby が、いまの Ruby と prism の構文木で等しい(空白・括弧の違いは許す) |
| J2 | DNCL 風の形の読みこみを同じ解析に入れる | 同上 |
| J3 | 日本語 → Ruby を新しい経路に切りかえる。行の対応と日本語の言葉の誤りも新しい経路から出す。古い前処理と行の変換を消す | コーパスで、ブロック・エラーの日本語の行が同じ |
| J4 | Ruby → 日本語を新しい経路(d・e)に切りかえ、古い行の変換を消す | 生成器の出力をすべて流し、日本語がゴールデンと同じ |
| J5 | 設定(添字の始まり・コメントの記号)を JaAST の設定にし、組み立てで構文木を変えて表す | 設定ごとの表のテスト |
| J6 | ライブラリをワークスペースのパッケージに取り出し、テストのデータを JSON にする。そのあと Ruby の実装 | Node と Ruby が同じデータで通る |
- J1〜J2 のあいだは、古い経路が本番で動き、新しい経路はテストの中でだけ動く。切りかえ(J3・J4)は 1 回の変更で行い、古い経路を残さない(二重に直す期間を短くする)。
- 作り直しのあいだも、いまの作りで不具合を直し続ける。直すたびに、その例をコーパスと表のテストに足す(新しい経路が同じ不具合を持たないように)。
- 日本語モードの記法を足す作業(基本設計の実装の Issue)は、J3 より前なら古い経路で、J3 より後なら新しい経路で行う。J1〜J3 のあいだは、記法を足すたびにコーパスに足す。
| リスク | 手当て |
|---|---|
| 古い行の変換が黙って受け付けていた揺れ(全角・罫線の文字・空白)を、新しい解析が受け付けない | J0 のコーパスを広く集める(テスト・教材・docs・レッスン・生成AI の答え)。受け付けない行は、どの行かを示す(貼り付けと同じ) |
| prism の版が上がって、逆向き(d)が読むノードの形が変わる | prism のノードの名前は nodeTypeName で取り、使う欄だけを読む小さな読み手を 1 か所に置く。表のテストが版の上げで落ちれば気づける |
| 古い経路と新しい経路を両方直す期間が長くなる | J1〜J3 をまとめて進め、切りかえで古い経路を消す |
| 日本語の言葉で出す誤りの文や位置が変わる | 誤りの文と行もゴールデンに入れる |
| 読みこみの大きさ(日本語の解析が増える) | Ruby タブ・変換器と同じ束に入れ、起動後の空いた時間に先読みする束の分け方に合わせる。 |
| OSS にするときの権利 | リポジトリは AGPL-3.0。ライブラリは MIT にする(6 章)。ライブラリの中に AGPL のコードを写さない。テストのデータは自作のプログラムだけにする |
| Ruby → ブロックの残り(R2〜R4)で、class やローカル変数の名前が変わる | これまでと同じく、往復テストの Ruby を 4 通り(スプライトの v2・v1、ステージ、衣装と音のあるスプライト)で流して比べる |
| 項目 | 決めたこと |
|---|---|
| 日本語のライブラリのライセンス | MIT(ほかの処理系や教材でも使ってもらいやすい。スモウルビー本体の AGPL-3.0 とは分ける) |
| ライブラリの名前 | ja-notation(仮の名前。公開の前に見直してよい) |
| 最初の置き場所 | scratch-gui の中のディレクトリ(packages/scratch-gui/src/lib/ja-notation/)に境界のテスト付きで置く。形が決まってからワークスペースのパッケージへ取り出す |
| 切りかえたあと古い経路を残すか | 残さない。コーパスとゴールデンで差が 0 を確かめてから切りかえ(J3・J4)、同じ変更で古い経路を消す |
Ruby → ブロック:
refactor(ruby): 拡張機能の呼び出しを呼び出しの表へ移す(拡張機能ごとに 1 つ。往復テストを先に表へ移す)。refactor(ruby):my-blocks.jsが分析のprocedures.definitionsを読むようにし、その場の下調べを消す。refactor(ruby): ローカル変数の範囲ごとの番号(_x_1_)を分析の段で決める。refactor(ruby): 変換が書くものを 1 つのBlockStoreにまとめ、巻き戻しの記録をその中に持つ。perf(ruby): 解析の段で「子 → 親」の索引を作り、エラーで文を指す処理とコメントの結びつけで根からたどり直さない。
日本語 ⇔ Ruby(日本語モードの EPIC の中で):
test(dncl): 表のテストに日本語の列を足し、日本語のプログラムのコーパスといまの出力のゴールデンを作る(J0)。feat(dncl): 日本語の構文木(JaAST)と、標準の形の解析・組み立て・Ruby を書く処理をライブラリの形で作る(テストの中だけで動かす。J1)。feat(dncl): DNCL 風の形の読みこみを、同じ解析に入れる(J2)。refactor(dncl): 日本語 → Ruby を新しい経路に切りかえ、行の対応・日本語の言葉の誤りもそこから出し、古い前処理と行の変換を消す(J3)。refactor(dncl): Ruby → 日本語を、prism の構文木 → JaAST → 日本語を書く経路に切りかえる(J4)。feat(dncl): 添字の始まりなどの設定を JaAST の設定にし、組み立てで構文木を変えて表す(J5)。chore(dncl): ライブラリをワークスペースのパッケージに取り出し、テストのデータを JSON にする(J6。Ruby での実装と公開は別の Issue)。
The documentation is under the same license as the repository.