# core/src ファイル構成

このディレクトリには、なでしこ3の言語コアを構成するTypeScriptソースと、そのビルド結果であるJavaScriptファイルが置かれています。
通常の開発では `.mts` ファイルを編集し、ビルドによって対応する `.mjs` ファイルが生成されます。

## 全体の流れ

なでしこ3のプログラムは、主に次の順で処理されます。

1. `nako_prepare.mts` で全角半角や特殊記法を前処理する
2. `nako_lexer.mts` と `nako_lex_rules.mts` でソースをトークン列に分割する
3. `nako_indent_inline.mts`、`nako_from_dncl.mts`、`nako_from_dncl2.mts` などで特殊構文を変換する
4. `nako_parser3.mts` でトークン列をASTに変換する
5. `nako_gen.mts` でASTからJavaScriptコードを生成する
6. `nako3.mts` の `NakoCompiler` が生成コードを評価して実行する

## エントリポイント

| ファイル | 説明 |
| --- | --- |
| `nako3.mts` | 言語コアの中心となる `NakoCompiler` を定義する。前処理、字句解析、構文変換、構文解析、コード生成、実行を統合する。 |
| `nako_core_version.mts` | コアのバージョン情報を定義する。自動生成されるため、通常は直接編集しない。 |

## 前処理と構文変換

| ファイル | 説明 |
| --- | --- |
| `nako_prepare.mts` | ソースコードの前処理を行う。全角半角の正規化、特殊記法の置換、変換履歴の管理などを担当する。 |
| `nako_source_mapping.mts` | 前処理やインデント構文変換の前後で、元ソース位置と変換後ソース位置を対応付ける。エラー位置の補正に使う。 |
| `nako_indent.mts` | 行単位のインデント構文を解析し、ブロック構造や `ここまで` 相当の構造に変換する。 |
| `nako_indent_inline.mts` | 字句解析後のトークン列に対して、インラインインデント構文を処理する。末尾の `:` やインデント量を見てブロック終端を補う。 |
| `nako_indent_chars.mts` | インデントとして扱う空白文字を判定する小さな補助関数を提供する。 |
| `nako_from_dncl.mts` | DNCLモードのトークン変換を行う。DNCL風の記法をなでしこ3の通常構文に寄せる。 |
| `nako_from_dncl2.mts` | DNCL2モードのトークン変換を行う。配列初期化やDNCL2固有の記法を扱う。 |

## 字句解析

| ファイル | 説明 |
| --- | --- |
| `nako_lexer.mts` | なでしこ3の字句解析器。ソースコードをトークン列に分割し、予約語や助詞の処理も行う。 |
| `nako_lex_rules.mts` | 字句解析で使う正規表現ルールとコールバックを定義する。数値、文字列、コメント、単語、単位などを判定する。 |
| `nako_token.mts` | トークン型に関する定義をまとめる。 |
| `nako_reserved_words.mts` | 予約語と、それに対応するトークン種別を定義する。 |
| `nako_josi_list.mts` | 助詞の一覧、削除対象助詞、条件文向け助詞などを定義する。助詞判定用の正規表現も提供する。 |

## 構文解析とAST

| ファイル | 説明 |
| --- | --- |
| `nako_parser_base.mts` | 構文解析器の基底クラス。トークン参照、読み進め、エラー生成など、パーサー共通処理を提供する。 |
| `nako_parser3.mts` | なでしこ3の主構文解析器。式、代入、関数定義、関数呼び出し、制御構文などをASTに変換する。 |
| `nako_parser_const.mts` | 演算子の優先順位、連文助詞、演算子一覧など、構文解析で使う定数を定義する。 |
| `nako_ast.mts` | ASTノードの型定義をまとめる。代入、関数、繰り返し、条件分岐、演算子などの構造を定義する。 |
| `nako_types.mts` | トークンやASTなど、コア全体で使う基本型と空トークン生成関数を定義する。 |

## コード生成と実行補助

| ファイル | 説明 |
| --- | --- |
| `nako_gen.mts` | ASTからJavaScriptコードを生成する。同期/非同期コード、関数、変数、演算子、プラグイン呼び出し、スタンドアロンコード生成を担当する。 |
| `nako_global.mts` | 実行時のグローバル状態を管理する。プラグイン、変数、関数、ログなどを保持する基盤クラス。 |
| `nako_logger.mts` | コンパイル時や実行時のログを扱う。ログレベル、位置情報の文字列化、リスナー通知などを提供する。 |
| `nako_errors.mts` | なでしこ3用のエラークラスを定義する。字句解析、構文解析、実行時、インポートなどのエラーを表す。 |
| `nako_tools.mts` | トークンのデバッグ出力、インデント生成、トークン生成などの補助関数を提供する。 |
| `nako_colors.mts` | ANSIカラー付きテキストをHTML表示向けに変換する補助機能を提供する。 |

## データ処理ライブラリ

| ファイル | 説明 |
| --- | --- |
| `nako_csv.mts` | CSVのパースと文字列化を行う軽量ライブラリ。区切り文字や改行文字の設定も扱う。 |

## 標準プラグイン

| ファイル | 説明 |
| --- | --- |
| `plugin_api.mts` | プラグインAPIの型定義を提供する。プラグイン関数、引数定義、メタ情報などの構造を定める。 |
| `plugin_system.mts` | 言語の基本機能を支える標準プラグイン。表示、変数操作、文字列処理、配列処理、制御補助など、多くの基本命令を提供する。 |
| `plugin_math.mts` | 数学関数を提供する標準プラグイン。三角関数、乱数、丸め、定数などを扱う。 |
| `plugin_csv.mts` | `nako_csv.mts` を使い、CSV処理の命令をなでしこから使えるようにする。 |
| `plugin_toml.mts` | TOML文字列を読むための命令を提供する。 |
| `plugin_promise.mts` | Promiseや非同期処理を扱うための命令を提供する。 |
| `plugin_test.mts` | なでしこコードでテストを書くための命令を提供する。 |

## 生成済みJavaScriptファイル

| ファイル | 説明 |
| --- | --- |
| `*.mjs` | `.mts` から生成されたJavaScriptファイル。実行時やパッケージ利用時に参照される。通常は直接編集せず、対応する `.mts` を編集してビルドする。 |
| `nako_test.mjs` | 簡易テスト用のJavaScriptファイル。対応する `.mts` はなく、現在は小さなテスト補助クラスのみを含む。 |

## 変更時の目安

- 文法やパーサーを変更する場合は、`nako_parser3.mts`、`nako_parser_base.mts`、`nako_parser_const.mts`、`nako_ast.mts` を中心に確認する。
- 字句解析を変更する場合は、`nako_lexer.mts`、`nako_lex_rules.mts`、`nako_reserved_words.mts`、`nako_josi_list.mts` を確認する。
- 生成されるJavaScriptを変更する場合は、`nako_gen.mts` を確認する。
- 標準命令を追加・変更する場合は、目的に応じて `plugin_system.mts` などの `plugin_*.mts` を確認する。
- エラー位置やソースマップに関わる変更では、`nako_source_mapping.mts` と `nako_errors.mts` も確認する。