# 機能設計書 73-チュートリアル

## 概要

本ドキュメントは、Nushellのチュートリアル機能（tutor）の設計仕様を定義する。tutorコマンドは、Nushellの基本的な使い方を学習するためのインタラクティブなチュートリアルを提供する。

### 本機能の処理概要

tutorコマンドは、Nushellの初心者や新機能を学びたいユーザーのために、シェル内で直接参照できるチュートリアルコンテンツを提供する機能である。テーブル、セル、変数、クロージャなど、Nushellの基本概念を順を追って学習できる。

**業務上の目的・背景**：Nushellは従来のシェルとは異なる概念（構造化データ、パイプライン、クロージャなど）を持つため、初心者にとって学習障壁が高い。tutorコマンドにより、外部ドキュメントを参照することなく、シェル内で段階的に学習を進められる。

**機能の利用シーン**：
- Nushellを初めて使うユーザーが基本操作を学ぶ場合
- 特定のトピック（変数、クロージャ等）について復習したい場合
- コードサンプルを含む説明を参照したい場合

**主要な処理内容**：
1. チュートリアルトピックの選択と表示
2. トピック一覧の表示（`tutor list`）
3. キーワード検索（`--find`フラグ）
4. コードブロックのシンタックスハイライト

**関連システム・外部連携**：
- nu-highlightコマンド：コードブロックのシンタックスハイライト

**権限による制御**：特になし。全ユーザーが使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインREPL | 主画面 | tutorコマンドの実行とチュートリアルテキストの表示 |

## 機能種別

ドキュメンテーション・学習支援機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| search | String | No | チュートリアルトピック名、または'list'で一覧表示 | 定義済みトピック名 |
| --find (-f) | String | No | チュートリアル内を検索するフレーズ | - |

### 入力データソース

組み込みの静的チュートリアルコンテンツ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| チュートリアルテキスト | String | シンタックスハイライト付きのチュートリアル内容 |

### 出力先

標準出力（パイプライン出力）

## 処理フロー

### 処理シーケンス

```
1. コマンド引数の解析
   └─ searchパラメータの取得
   └─ --findフラグの取得

2. 処理分岐
   ├─ --find指定: フレーズ検索
   │     └─ 全トピックを検索
   │     └─ 該当トピック名を一覧表示
   │
   ├─ search="list": トピック一覧表示
   │
   ├─ search=トピック名: 該当トピック表示
   │
   └─ 引数なし: デフォルトウェルカム表示

3. コードブロックのシンタックスハイライト
   └─ バッククォート区切りでコードを抽出
   └─ nu-highlightコマンドで色付け

4. 結果の返却
```

### フローチャート

```mermaid
flowchart TD
    A[tutor コマンド開始] --> B{--find 指定?}

    B -->|Yes| C[全トピックを検索]
    C --> D[該当トピック一覧を表示]

    B -->|No| E{search 引数あり?}
    E -->|No| F[デフォルトウェルカム表示]

    E -->|Yes| G{search = 'list'?}
    G -->|Yes| H[トピック一覧を表示]

    G -->|No| I{トピック検索}
    I -->|見つかった| J[該当トピックを表示]
    I -->|見つからない| F

    D --> K[シンタックスハイライト処理]
    F --> K
    H --> K
    J --> K

    K --> L[結果を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-73-1 | トピック検索 | 複数のエイリアス名（table/tables/row等）で同じトピックを検索可能 | searchパラメータ指定時 |
| BR-73-2 | コードハイライト | バッククォートで囲まれた部分をコードとして色付け | 全てのチュートリアル出力 |
| BR-73-3 | フレーズ検索 | トピック内のテキストを検索し、該当するトピック名を返す | --findフラグ指定時 |

### 計算ロジック

特になし

## データベース操作仕様

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 存在しないトピック指定 | デフォルトウェルカムメッセージを表示 |

### リトライ仕様

リトライは行わない。

## トランザクション仕様

該当なし

## パフォーマンス要件

特になし（静的コンテンツの表示のみ）

## セキュリティ考慮事項

- コードブロックのハイライトにはnu-highlightコマンドを使用するが、コードは実行されない

## 備考

利用可能なトピック:
- begin: チュートリアル開始
- table/tables/row/rows/column/columns: テーブル操作
- cell/cells: セル操作
- expr/expressions/subexpression: 式と部分式
- echo: echoコマンド
- each/iteration/iter: 繰り返し処理
- var/vars/variable/variables: 変数
- block/blocks: ブロック
- closure/closures: クロージャ
- shorthand/shorthands: セルパス省略記法

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

チュートリアルの検索空間の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | tutor.rs | `crates/nu-command/src/misc/tutor.rs` | search_space配列の構造（トピック名エイリアスとコンテンツ関数） |

**読解のコツ**: search_spaceはタプルの配列で、最初の要素がトピック名のエイリアス配列、2番目がコンテンツを返す関数。

#### Step 2: エントリーポイントを理解する

tutorコマンドのメイン処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tutor.rs | `crates/nu-command/src/misc/tutor.rs` | Tutorコマンドの引数定義とrun関数 |

**主要処理フロー**:
1. **64-72行目**: 引数（search, find）の取得
2. **75-103行目**: search_spaceの定義
3. **105-118行目**: --find指定時の検索処理
4. **119-135行目**: トピック検索と表示

#### Step 3: コンテンツ関数を理解する

各トピックのコンテンツ生成を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tutor.rs | `crates/nu-command/src/misc/tutor.rs` | 各トピック関数（begin_tutor, table_tutor等） |

**主要処理フロー**:
- **138-148行目**: default_tutor - ウェルカムメッセージ
- **151-179行目**: begin_tutor - 開始チュートリアル
- **182-218行目**: table_tutor - テーブルチュートリアル

#### Step 4: シンタックスハイライト処理を理解する

コードブロックのハイライト処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | tutor.rs | `crates/nu-command/src/misc/tutor.rs` | display関数 |

**主要処理フロー**:
- **432-469行目**: display関数 - バッククォート区切りでコードを抽出
- **443-461行目**: nu-highlightコマンドでコードブロックを色付け

### プログラム呼び出し階層図

```
Tutor::run (tutor.rs)
    │
    └─ tutor()
           │
           ├─ --find指定: search_space全検索
           │      └─ トピック名一覧を生成
           │
           ├─ "list"指定: トピック一覧を生成
           │
           ├─ トピック名指定: 該当トピック関数呼び出し
           │      ├─ begin_tutor()
           │      ├─ table_tutor()
           │      ├─ cell_tutor()
           │      ├─ expression_tutor()
           │      ├─ echo_tutor()
           │      ├─ each_tutor()
           │      ├─ variable_tutor()
           │      ├─ block_tutor()
           │      ├─ closure_tutor()
           │      └─ shorthand_tutor()
           │
           └─ display()
                  └─ nu-highlight (シンタックスハイライト)
```

### データフロー図

```
[入力]                    [処理]                      [出力]

--find "phrase" ──────▶ 全トピック検索 ─────────▶ トピック名一覧

"list" ───────────────▶ トピック名抽出 ─────────▶ トピック名一覧

"topic名" ────────────▶ トピック関数呼び出し ──▶ チュートリアルテキスト
                              │
                              ▼
                         display()
                              │
                              ▼
                       シンタックスハイライト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tutor.rs | `crates/nu-command/src/misc/tutor.rs` | ソース | Tutorコマンド定義と全チュートリアルコンテンツ |
| mod.rs | `crates/nu-command/src/misc/mod.rs` | ソース | miscモジュール定義 |
