runtimeリファクタ&README追加

Author: na-trium-144

app/terminal/README.md

@@ -0,0 +1,118 @@
+# my.code(); Runtime API
+
+## runtime.ts
+
+各言語のランタイムはRuntimeContextインターフェースの実装を返すフックを実装する必要があります。
+
+runtime.ts の `useRuntime(lang)` は各言語のフックを呼び出し、その中で指定された言語のランタイムを返します。
+
+関数はすべてuseCallbackやuseMemoなどを用いレンダリングごとに同じインスタンスを返すように実装してください。
+
+### 共通
+
+* ready: `boolean`
+    * ランタイムの初期化が完了したか、不要である場合true
+* tabSize: `number`
+    * REPLおよびコードエディターののタブ幅を指定します。
+* mutex?: `MutexInterface`
+    * ランタイムに排他制御が必要な場合、MutexInterfaceのインスタンスを返してください。
+* interrupt?: `() => Promise<void>`
+    * 実行中のコマンドを中断します。呼び出し側でmutexのロックはされません
+
+### REPL用
+
+* runCommand?: `(command: string) => Promise<ReplOutput[]>`
+    * コマンドを実行します。実行結果をReplOutputの配列で返します。
+    * runCommandを呼び出す際には呼び出し側 (主に repl.tsx) でmutexをロックします。複数のコマンドを連続実行したい場合があるからです。
+* checkSyntax?: `(code: string) => Promise<SyntaxStatus>`
+    * コードの構文チェックを行います。行がコマンドとして完結していれば`complete`、次の行に続く場合(if文の条件式の途中など)は`incomplete`を返してください。
+    * REPLでEnterを押した際の動作に影響します。
+    * 呼び出し側でmutexのロックはされません
+* splitReplExamples?: `(code: string) => ReplCommands[]`
+    * markdown内に記述されているREPLのサンプルコードをパースします。例えば
+    ```
+    >>> if True:
+    ...     print("Hello")
+    Hello
+    ```
+    をsplitReplExamplesに通すと
+    ```ts
+    [
+      {
+        command: 'if True:\n    print("Hello")',
+        output: {
+          type: 'output',
+          content: 'Hello'
+        }
+      }
+    ]
+    ```
+    が返されるようにします。
+* prompt?: `string`
+    * REPLの1行目のプロンプト文字列を指定します。
+* promptMore?: `string`
+    * REPLの2行目以降のプロンプト文字列を指定します。
+
+### ファイル実行用
+
+* runFiles: `(filenames: string[]) => Promise<ReplOutput[]>`
+    * 指定されたファイルを実行します。ファイルの中身はEmbedContextから取得されます。
+    * 呼び出し側でmutexのロックはされません
+* getCommandlineStr: `(filenames: string[]) => string`
+    * 指定されたファイルを実行するためのコマンドライン引数文字列を返します。表示用です。
+
+## embedContext.tsx
+
+Replの実行結果(`replOutputs`)、ユーザーが編集したファイル(`files`)、ファイルの実行結果(`execResults`)の情報を保持します。
+
+## terminal.tsx
+
+xterm.jsを制御する useTerminal() フックを提供します。
+リサイズやテーマ切り替えなどの処理を行います。
+
+引数:
+* getRows?: `(cols: number) => number`
+    * ターミナルの幅がcolsの場合の高さの最小値を指定します。
+    * 未指定または5未満の場合5になります。
+    * 内部でuseRefを使用しターミナル初期化完了の瞬間のgetRows関数インスタンスが呼び出されるので、一時オブジェクトでも大丈夫
+* onReady?: `() => void`
+    * ターミナルが初期化された際に呼び出されます。
+    * 内部でuseRefを使用しターミナル初期化完了の瞬間のonReady関数インスタンスが呼び出されるので、一時オブジェクトでも大丈夫
+
+返り値:
+* terminalRef: `RefObject<HTMLDivElement>`
+    * ターミナルを描画するためのdiv要素にこのrefを渡してください。
+* terminalInstanceRef: `RefObject<Terminal | null>`
+    * xterm.jsのTerminalインスタンスへのrefです。
+* termReady: `boolean`
+    * ターミナルが初期化されたかどうかを示します。
+
+## repl.tsx
+
+ReplTerminal コンポーネントを提供します。
+useRuntimeとuseTerminalを呼び出し、REPLの入出力、キーハンドリング処理を行います。
+
+また、実行したコマンド結果はEmbedContextに送信されます。
+
+シンタックスハイライトはprism.jsでパースしたものを独自処理で色付けしています。(highlight.ts 内の highlightCodeToAnsi 関数)
+パース処理の実装は不要ですがhighlight.tsに言語定義のインポートとswitch文分岐の追加が必要です。
+
+## editor.tsx
+
+EditorComponent コンポーネントを提供します。
+
+ファイルの内容はEmbedContextと同期されます。
+
+## exec.tsx
+
+実行ボタンと結果を表示する ExecFile コンポーネントを提供します。
+
+実行結果はEmbedContextに送信されます。
+
+## 各言語の実装
+
+### Pyodide (Python)
+
+Pyodide を web worker で動かしています。
+ランタイムの初期化に時間がかかるため、バックグラウンドで初期化を行います。
+

app/terminal/exec.tsx

@@ -8,19 +8,17 @@ import {
   useTerminal,
 } from "./terminal";
 import { writeOutput } from "./repl";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { useEmbedContext } from "./embedContext";
-import { useRuntime } from "./runtime";
-
-export type ExecLang = "python" | "cpp";
+import { RuntimeLang, useRuntime } from "./runtime";
 
 interface ExecProps {
   /*
    * Pythonの場合はメインファイル1つのみを指定する。
    * C++の場合はソースコード(.cpp)を全部指定する。
    */
   filenames: string[];
-  language: ExecLang;
+  language: RuntimeLang;
   content: string;
 }
 export function ExecFile(props: ExecProps) {
@@ -33,70 +31,65 @@ export function ExecFile(props: ExecProps) {
       }
     },
   });
-  const sectionContext = useEmbedContext();
+  const { setExecResult } = useEmbedContext();
 
-  const runtime = useRuntime(props.language);
+  const { ready, runFiles, getCommandlineStr } = useRuntime(props.language);
 
-  // 表示するコマンドライン文字列
-  let commandline: string;
-  if (props.language === "python") {
-    if (props.filenames.length !== 1) {
-      throw new Error("Pythonの実行にはファイル名が1つ必要です");
-    }
-    commandline = `python ${props.filenames[0]}`;
-  } else if (props.language === "cpp") {
-    if (!props.filenames || props.filenames.length === 0) {
-      throw new Error("C++の実行には filenames プロパティが必要です");
+  // ユーザーがクリックした時(triggered) && ランタイムが準備できた時に、実際にinitCommandを実行する(executing)
+  const [executionState, setExecutionState] = useState<
+    "idle" | "triggered" | "executing"
+  >("idle");
+  useEffect(() => {
+    if (executionState === "triggered" && ready) {
+      setExecutionState("executing");
+      (async () => {
+        clearTerminal(terminalInstanceRef.current!);
+        terminalInstanceRef.current!.write(systemMessageColor("実行中です..."));
+        const outputs = await runFiles(props.filenames);
+        clearTerminal(terminalInstanceRef.current!);
+        writeOutput(terminalInstanceRef.current!, outputs, false);
+        // TODO: 1つのファイル名しか受け付けないところに無理やりコンマ区切りで全部のファイル名を突っ込んでいる
+        setExecResult(props.filenames.join(","), outputs);
+        setExecutionState("idle");
+      })();
     }
-    commandline = runtime.getCommandlineStr
-      ? runtime.getCommandlineStr(props.filenames)
-      : `g++ ${props.filenames.join(" ")}`;
-  } else {
-    props.language satisfies never;
-    commandline = `エラー: 非対応の言語 ${props.language}`;
-  }
-
-  const runtimeInitializing = runtime.initializing;
-  const beforeExec = runtime.ready ? null : runtime.init;
-  const exec = () => runtime.runFiles(props.filenames);
+  }, [
+    executionState,
+    ready,
+    props.filenames,
+    runFiles,
+    setExecResult,
+    terminalInstanceRef,
+  ]);
 
-  // 実行中です... と表示される
-  const [isExecuting, setIsExecuting] = useState<boolean>(false);
-
-  const onClick = async () => {
-    if (beforeExec) {
-      clearTerminal(terminalInstanceRef.current!);
-      terminalInstanceRef.current!.write(
-        systemMessageColor("(初期化しています...しばらくお待ちください)")
-      );
-      await beforeExec();
-    }
-    clearTerminal(terminalInstanceRef.current!);
-    terminalInstanceRef.current!.write(systemMessageColor("実行中です..."));
-    setIsExecuting(true);
-    const outputs = await exec();
-    setIsExecuting(false);
-    clearTerminal(terminalInstanceRef.current!);
-    writeOutput(terminalInstanceRef.current!, outputs, false);
-    // TODO: 1つのファイル名しか受け付けないところに無理やりコンマ区切りで全部のファイル名を突っ込んでいる
-    sectionContext?.setExecResult(props.filenames.join(","), outputs);
-  };
   return (
     <div className="relative">
       <div>
         <button
           className="btn btn-soft btn-primary rounded-tl-lg rounded-none"
-          onClick={onClick}
-          disabled={!termReady || runtimeInitializing}
+          onClick={() => {
+            if (!ready) {
+              clearTerminal(terminalInstanceRef.current!);
+              terminalInstanceRef.current!.write(
+                systemMessageColor(
+                  "(初期化しています...しばらくお待ちください)"
+                )
+              );
+            }
+            setExecutionState("triggered");
+          }}
+          disabled={!termReady || executionState !== "idle"}
         >
           ▶ 実行
         </button>
-        <code className="text-sm ml-4">{commandline}</code>
+        <code className="text-sm ml-4">
+          {getCommandlineStr(props.filenames)}
+        </code>
       </div>
       <div className="bg-base-300 p-4 pt-2 rounded-b-lg">
         <div ref={terminalRef} />
       </div>
-      {(runtimeInitializing || isExecuting) && (
+      {executionState !== "idle" && (
         <div className="absolute z-10 inset-0 cursor-wait" />
       )}
     </div>

app/terminal/highlight.ts

@@ -1,8 +1,25 @@
 import Prism from "prismjs";
 import chalk from "chalk";
+import { RuntimeLang } from "./runtime";
 // Python言語定義をインポート
 import "prismjs/components/prism-python";
 
+type PrismLang = "python";
+
+function getPrismLanguage(language: RuntimeLang): PrismLang {
+  switch (language) {
+    case "python":
+      return "python";
+    case "cpp":
+      throw new Error(
+        `highlight for ${language} is disabled because it should not support REPL`
+      );
+    default:
+      language satisfies never;
+      throw new Error(`Prism language not implemented for: ${language}`);
+  }
+}
+
 const nothing = (text: string): string => text;
 
 // PrismのトークンクラスとANSIコードをマッピング
@@ -50,12 +67,15 @@ const prismToAnsi: Record<string, (text: string) => string> = {
  * @param {string} code ハイライト対象のPythonコード
  * @returns {string} ANSIで色付けされた文字列
  */
-export function highlightCodeToAnsi(code: string, language: string): string {
+export function highlightCodeToAnsi(
+  code: string,
+  language: RuntimeLang
+): string {
   // Prismでハイライト処理を行い、HTML文字列を取得
   const highlightedHtml = Prism.highlight(
     code,
-    Prism.languages[language],
-    language
+    Prism.languages[getPrismLanguage(language)],
+    getPrismLanguage(language)
   );
 
   // 一時的なDOM要素を作成してパース

app/terminal/python/embedded.tsx

@@ -10,7 +10,7 @@ export default function PythonPage() {
       <ReplTerminal
         terminalId=""
         language="python"
-        initMessage="Welcome to Pyodide Terminal!"
+        initContent={">>> print('hello, world!')\nhello, world!"}
       />
       <EditorComponent
         language="python"