Skip to content

Latest commit

 

History

History
220 lines (173 loc) · 28.4 KB

converter-roadmap.md

File metadata and controls

220 lines (173 loc) · 28.4 KB

変換器の 4 段の構造: 段の間で渡すもの・日本語モードの経路・残りの移し方(設計)

🆕 Smalruby 独自 — upstream に存在しない、Smalruby のために新規追加された機能

converter-stages.md は、Ruby → ブロックの変換器を 解析・分析・変換・仕上げ の 4 段に分けた形と、 そこまでの移し方を書いている。この文書は、その続きとして次を決める。

  1. 段の境界で 何を渡すか(段の約束)と、約束から外れている所。
  2. 日本語モード(日本語タブ)の変換を、この 4 段にどうつなぐか。
  3. ブロック → Ruby(生成器)をどう扱うか。
  4. 振る舞いを変えずに残りを移す順番、リスク、実装の Issue の案。
  • 橋渡しの決まり(何をどのブロックと注釈 @ruby:* で表すか)は bridging-patterns.md。
  • 日本語モードの方針と基本設計は ../dncl/policy.md と ../dncl/design.md。 記法(何をどう書くか)はそちらが正で、この文書は 変換の作り だけを扱う。

1. 段の約束(渡すもの)

日本語のテキスト ─┐
                 │ 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 つの入れ物にし、変換はそれを通してだけ書く

2. 日本語モードの経路

いまの作り

日本語 → (前処理: 標準の形を 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 をそのまま使える

4 段とのつながり

  • 日本語の前の段は、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 が守ること」)。

3. ブロック → Ruby(生成器)

生成器(src/lib/ruby-generator/)は Blockly の生成器の形で、段に分け直さない。 ブロックを 1 行で書ける記法と表のテストで、生成を先に確かめられるようになったので、課題だったテストは解けている。 呼び出しの表(send-table.js)は、「表の opcode にはすべて生成器がある」ことを確かめるのに使い続ける。 日本語の経路の逆向き(d)は生成器の Ruby を prism で解析するので、生成器の出す形が少し変わっても日本語が崩れない。

4. 振る舞いを変えずに移す順番

どの段階も、先に表のテストと、いまの出力の記録(ゴールデン)を作り、差が 0 のまま移す。 これまでの段の移し方と同じく、変換器と往復のテストに書かれた Ruby をすべて流し、移す前と後の結果(エラーの行・列・文、ブロック、変数・リスト、コメント)を比べる。

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 つずつ行う。

日本語 ⇔ Ruby

順 すること 差が 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 のあいだは、記法を足すたびにコーパスに足す。

5. リスク

リスク 手当て
古い行の変換が黙って受け付けていた揺れ(全角・罫線の文字・空白)を、新しい解析が受け付けない 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、ステージ、衣装と音のあるスプライト)で流して比べる

6. 決めたこと(ライブラリと切りかえ)

項目 決めたこと
日本語のライブラリのライセンス MIT(ほかの処理系や教材でも使ってもらいやすい。スモウルビー本体の AGPL-3.0 とは分ける)
ライブラリの名前 ja-notation(仮の名前。公開の前に見直してよい)
最初の置き場所 scratch-gui の中のディレクトリ(packages/scratch-gui/src/lib/ja-notation/)に境界のテスト付きで置く。形が決まってからワークスペースのパッケージへ取り出す
切りかえたあと古い経路を残すか 残さない。コーパスとゴールデンで差が 0 を確かめてから切りかえ(J3・J4)、同じ変更で古い経路を消す

7. 実装の Issue の案

Ruby → ブロック:

  1. refactor(ruby): 拡張機能の呼び出しを呼び出しの表へ移す(拡張機能ごとに 1 つ。往復テストを先に表へ移す)。
  2. refactor(ruby): my-blocks.js が分析の procedures.definitions を読むようにし、その場の下調べを消す。
  3. refactor(ruby): ローカル変数の範囲ごとの番号(_x_1_)を分析の段で決める。
  4. refactor(ruby): 変換が書くものを 1 つの BlockStore にまとめ、巻き戻しの記録をその中に持つ。
  5. perf(ruby): 解析の段で「子 → 親」の索引を作り、エラーで文を指す処理とコメントの結びつけで根からたどり直さない。

日本語 ⇔ Ruby(日本語モードの EPIC の中で):

  1. test(dncl): 表のテストに日本語の列を足し、日本語のプログラムのコーパスといまの出力のゴールデンを作る(J0)。
  2. feat(dncl): 日本語の構文木(JaAST)と、標準の形の解析・組み立て・Ruby を書く処理をライブラリの形で作る(テストの中だけで動かす。J1)。
  3. feat(dncl): DNCL 風の形の読みこみを、同じ解析に入れる(J2)。
  4. refactor(dncl): 日本語 → Ruby を新しい経路に切りかえ、行の対応・日本語の言葉の誤りもそこから出し、古い前処理と行の変換を消す(J3)。
  5. refactor(dncl): Ruby → 日本語を、prism の構文木 → JaAST → 日本語を書く経路に切りかえる(J4)。
  6. feat(dncl): 添字の始まりなどの設定を JaAST の設定にし、組み立てで構文木を変えて表す(J5)。
  7. chore(dncl): ライブラリをワークスペースのパッケージに取り出し、テストのデータを JSON にする(J6。Ruby での実装と公開は別の Issue)。

License

The documentation is under the same license as the repository.