NEPLg2 tutorial 全面書き直し計画

読者

主対象は、NEPLg2 の構文と stdlib を初めて使う開発者とする。compiler 内部や unsafe memory model の詳細は扱わない。ただし、所有権、Result、Option、byte / text の区別など、通常コードを書くために必要な安全設計は早い段階で説明する。

コード例の標準形

すべてのコード例は実行可能な neplg2:test にする。説明だけの疑似コードは使わない。

標準の test 形:

#entry main
#indent 4
#target std

#import "std/test" as *

fn main <()->i32> ():
    let checks <Vec<Result<(),str>>>:
        checks_new
        |> checks_push check_eq_i32 "label" 1 1
    let shown <Vec<Result<(),str>>> checks_print_report checks
    checks_exit_code shown

標準の I/O 形:

#entry main
#indent 4
#target std

#import "std/stdio" as *

fn main <()->()> ():
    println "Hello, NEPL!";

古い signature 表記、不要な raw memory、内部 layout 依存、panic 前提の unwrap は tutorial から除外する。

文章スタイル

• 1 章 1 テーマにする。
• 1 つの章に実行例は 1〜3 個までにする。
• 先に「何の問題を解くか」を示し、その後にコードを置く。
• コード内コメントは日本語で短く、処理目的を説明する。
• 未実装予定機能は tutorial 本文には入れず、予定章として appendix に置く。

Part 0: 実行環境と最小構成

1. 00_index.n.md: tutorial 全体の案内、NEPLg2 の基本方針。
2. 01_hello_world.n.md: #entry / #target std / println。
3. 02_test_harness.n.md: std/test、checks_new、checks_exit_code。

Part 1: 値、式、関数

1. 03_values_and_types.n.md: i32 / u8 / bool / str / ()、型注釈。
2. 04_prefix_calls.n.md: prefix call、nested call、pipe を使わない基本形。
3. 05_functions_and_blocks.n.md: fn、block、tail expression、; の意味。
4. 06_if_and_match.n.md: if expression、match、bool / integer literal match。

Part 2: 失敗を型で扱う

1. 07_option.n.md: Option、some / none、match。
2. 08_result.n.md: Result、Ok / Err、panic しない失敗処理。
3. 09_validation_project.n.md: 小さな入力検証関数を Result で組む。

Part 3: 文字列、byte、char

1. 10_string_and_text.n.md: str、byte length、UTF-8 boundary、str_slice_result。
2. 11_bytebuf_and_text_io.n.md: ByteBuf、checked UTF-8 conversion、binary と text の区別。
3. 12_char_and_ascii.n.md: char 実装後に追加。char literal、ASCII classifier、str_char_*。

char 実装後の current tutorial では、12 章を index に載せ、char literal と str_char_* API の実行例を含める。

Part 4: collection と所有権

1. 13_vec_basics.n.md: Vec の作成、push、len、free。
2. 14_collection_reads.n.md: Copy read、borrowed read、owned remove の違い。
3. 15_move_and_borrow.n.md: move、shared borrow、mutable borrow、use-after-move が compile error になる例。
4. 16_drop_and_cleanup.n.md: free / Drop / container cleanup の基本。

raw memory、MemPtr、alloc_raw は通常 tutorial では扱わない。必要なら unsafe/internal appendix に分ける。

Part 5: module、trait、generic

1. 17_imports_and_modules.n.md: #import、alias、名前空間。
2. 18_generics.n.md: type parameter、Vec<T>、Option<T>。
3. 19_traits_and_bounds.n.md: Copy / Clone / Drop / custom trait の最小例。
4. 20_namespace_and_methods.n.md: Trait::method / enum constructor / module alias。

Part 6: 実践プロジェクト

1. 21_project_fizzbuzz.n.md: stdout project。
2. 22_project_parser_small.n.md: str を走査して token-like value を作る。char 実装後に char literal 版へ更新。
3. 23_project_config_validator.n.md: Result と diagnostics の小 project。
4. 24_project_byte_output.n.md: ByteBuilder で小さな binary/text output を作る。

Part 7: Advanced / Appendix

1. 90_competitive_programming_intro.n.md: 競プロ track の導入。
2. 91_sort_search_prefixsum.n.md: sort / binary search / prefix sum。
3. 92_graph_bfs_dp.n.md: BFS / DP。
4. 95_target_and_wasi_notes.n.md: std / wasix / llvm の注意。
5. 99_migration_notes.n.md: 古い tutorial からの移行表。

既存の 22〜27 の競プロ章は、Advanced track として再編集する。入門本編には混ぜない。

Stage 0: baseline 固定

• 現行 tutorials/getting_started の doctest 実行結果を確認する。
• 失敗がある場合は、tutorial rewrite issue に記録する。
• index と章名の現状 snapshot を残す。

Stage 1: 新 index と章 template

• 00_index.n.md を新章立てへ更新する。
• 新章共通の code style を固定する。
• 古い章は一時的に残し、リンクから外すか 99_migration_notes へ移す。

Stage 2: Core 入門章

• Part 0〜2 を先に書く。
• std/test と Result を早期に導入し、以後の章で共通 test pattern を使う。

Stage 3: Text / char 章

• str と byte length の章を先に書く。
• char 実装後、char 章と既存 text examples を更新する。
• char 未実装の間は decimal character code を tutorial 本文で推奨しない。

Stage 4: Collection / ownership 章

• raw memory を使わず、現在の collection public API で書く。
• move / borrow / cleanup の compile_fail examples を focused に入れる。

Stage 5: Advanced track

• 競プロ章は現在の stdlib API と ownership 方針で再実装する。
• catalog ではなく、少数の実用パターンに絞る。