# 機能設計書 98-標準ライブラリ

## 概要

本ドキュメントはNushellの標準ライブラリ（nu-std）について記述する。Nushellスクリプトで書かれたユーティリティコマンドとモジュール群の設計を定義する。

### 本機能の処理概要

標準ライブラリは、Nushell自体で実装されたコマンドやモジュールのコレクションである。アサーション、ベンチマーク、ディレクトリスタック、ロギング、数学関数など、シェルスクリプティングで頻繁に使用される機能を提供する。

**業務上の目的・背景**：Nushellの組み込みコマンドだけでは対応しきれない高レベルのユーティリティ機能を、Nushellスクリプトとして提供する。これにより、ユーザーはより複雑なタスクを簡潔に記述でき、また標準ライブラリ自体がNushellスクリプティングの良いサンプルとなる。

**機能の利用シーン**：
- テストスクリプトでのアサーション
- パフォーマンス測定のベンチマーク
- 複数ディレクトリ間の移動（dirsモジュール）
- 構造化ログ出力
- 日付・時刻の操作
- 数学計算
- XML処理

**主要な処理内容**：
1. 仮想ファイルシステムでのモジュール読み込み
2. preludeモジュールの自動ロード
3. 各サブモジュールの提供

**関連システム・外部連携**：なし（純粋なNushellスクリプト）

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLIコマンドとして提供され、特定の画面とは関連しない |

## 機能種別

ユーティリティライブラリ / スクリプトモジュール

## 入力仕様

### 入力パラメータ

標準ライブラリは複数のモジュールで構成される。主要モジュールの入力を以下に示す。

#### std/assert

| コマンド | パラメータ | 型 | 説明 |
|---------|-----------|-----|------|
| assert | condition | bool | アサート条件 |
| assert | message? | string | エラーメッセージ |
| assert equal | left, right | any | 比較する値 |
| assert less | left, right | any | 比較する値 |
| assert greater | left, right | any | 比較する値 |
| assert error | code | closure | エラーが発生すべきクロージャ |

#### std/dirs

| コマンド | パラメータ | 型 | 説明 |
|---------|-----------|-----|------|
| dirs add | paths | string... | 追加するディレクトリ |
| dirs next | N | int | 移動するスロット数（デフォルト: 1） |
| dirs prev | N | int | 移動するスロット数（デフォルト: 1） |
| dirs goto | dir_idx? | int | ジャンプ先インデックス |

#### std/log

| コマンド | パラメータ | 型 | 説明 |
|---------|-----------|-----|------|
| log critical | message | string | ログメッセージ |
| log error | message | string | ログメッセージ |
| log warning | message | string | ログメッセージ |
| log info | message | string | ログメッセージ |
| log debug | message | string | ログメッセージ |
| log set-level | level | int | ログレベル |

### 入力データソース

- 環境変数（$env.NU_LOG_LEVEL, $env.DIRS_LIST等）
- パイプライン入力（各コマンドによる）

## 出力仕様

### 出力データ

各モジュールの出力はコマンドにより異なる。

#### 主要な出力例

| モジュール | コマンド | 出力 |
|-----------|---------|------|
| assert | assert equal | 成功時は何も出力しない、失敗時はエラー |
| dirs | dirs | ディレクトリスタックのテーブル |
| log | log info | stderrへのログ出力 |
| bench | bench | ベンチマーク結果のレコード |

### 出力先

- パイプライン出力
- stderr（logモジュール）
- 環境変数更新（dirsモジュール）

## 処理フロー

### 処理シーケンス

```
標準ライブラリのロード:
1. StateWorkingSetの作成
2. 仮想ファイルの作成
   ├─ std/mod.nu
   ├─ std/prelude/mod.nu
   ├─ std/assert/mod.nu
   ├─ std/bench/mod.nu
   ├─ std/dirs/mod.nu
   ├─ std/dt/mod.nu
   ├─ std/formats/mod.nu
   ├─ std/help/mod.nu
   ├─ std/input/mod.nu
   ├─ std/iter/mod.nu
   ├─ std/log/mod.nu
   ├─ std/math/mod.nu
   ├─ std/util/mod.nu
   ├─ std/xml/mod.nu
   ├─ std/config/mod.nu
   ├─ std/testing/mod.nu
   ├─ std/clip/mod.nu
   └─ std/random/mod.nu
3. 仮想ディレクトリの構築
4. std-rfcサブモジュールの追加
5. preludeのパース実行
6. engine_stateへのマージ
```

### フローチャート

```mermaid
flowchart TD
    A[load_standard_library] --> B[StateWorkingSet作成]
    B --> C[stdモジュールの仮想ファイル作成]
    C --> D[サブモジュールの仮想ファイル作成]
    D --> E[仮想ディレクトリの構築]
    E --> F[std-rfcモジュールの追加]
    F --> G[preludeのパース]
    G --> H[engine_stateへマージ]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-98-01 | 仮想ファイルシステム | 標準ライブラリは仮想ファイルとしてバイナリに組み込み | 起動時 |
| BR-98-02 | prelude自動ロード | std/preludeは起動時に自動的にuseされる | 常時 |
| BR-98-03 | ログレベル制御 | NU_LOG_LEVELで出力するログレベルを制御 | logモジュール使用時 |
| BR-98-04 | ディレクトリスタック | DIRS_LISTとDIRS_POSITIONで状態管理 | dirsモジュール使用時 |

### 計算ロジック

**ログレベルの定義**:
- CRITICAL: 50
- ERROR: 40
- WARNING: 30
- INFO: 20
- DEBUG: 10

**assertの比較ロジック**:
- equal: `$left == $right`
- not equal: `$left != $right`
- less: `$left < $right`
- greater: `$left > $right`
- less or equal: `$left <= $right`
- greater or equal: `$left >= $right`

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Assertion failed | error make | アサーション条件が満たされない | 条件を修正 |
| not a directory | error make | dirs addで無効なパス | 有効なディレクトリを指定 |
| invalid_dirs_index | error make | dirs gotoで範囲外のインデックス | 有効なインデックスを指定 |

### リトライ仕様

特になし。

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

該当なし。

## パフォーマンス要件

- 起動時のpreludeロードは高速に実行
- 仮想ファイルシステムによりディスクI/Oなし

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

- 標準ライブラリはバイナリに組み込まれ改変不可
- ユーザー定義モジュールによる上書きは可能

## 備考

- std-rfcはRFC（Request for Comments）段階の実験的モジュール
- sqliteフィーチャー有効時のみstd-rfc/kvモジュールが利用可能
- preludeからエクスポートされるコマンドは自動的に利用可能

---

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

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

### 推奨読解順序

#### Step 1: ライブラリのロード処理を理解する

Rustによるローダー実装を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lib.rs | `crates/nu-std/src/lib.rs` | load_standard_library関数（18-190行目） |
| 1-2 | lib.rs | `crates/nu-std/src/lib.rs` | create_virt_file関数（11-16行目） |

**主要処理フロー（lib.rs）**:
1. **23行目**: StateWorkingSet作成
2. **29-34行目**: std/mod.nuの仮想ファイル作成
3. **37-69行目**: サブモジュールのリスト定義
4. **71-85行目**: サブモジュールの仮想ファイル・ディレクトリ作成
5. **158-185行目**: preludeのパースとマージ

#### Step 2: モジュール構造を理解する

標準ライブラリのエントリーポイントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | mod.nu | `crates/nu-std/std/mod.nu` | モジュールエクスポート（1-38行目） |

**読解のコツ**: `export use`と`export module`の違いに注目。useは直接コマンドをエクスポート、moduleはサブモジュールとしてエクスポート。

#### Step 3: assertモジュールを理解する

アサーションの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | mod.nu | `crates/nu-std/std/assert/mod.nu` | main（assert本体）（18-34行目） |
| 3-2 | mod.nu | `crates/nu-std/std/assert/mod.nu` | equal（116-133行目） |
| 3-3 | mod.nu | `crates/nu-std/std/assert/mod.nu` | error（69-81行目） |

**主要処理フロー（assert/mod.nu）**:
1. **24行目**: 条件がfalseならerror make
2. **25-32行目**: メッセージとラベルの構築
3. **103-108行目**: compare関数で汎用比較

#### Step 4: dirsモジュールを理解する

ディレクトリスタックの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | mod.nu | `crates/nu-std/std/dirs/mod.nu` | export-env（19-30行目） |
| 4-2 | mod.nu | `crates/nu-std/std/dirs/mod.nu` | add（35-51行目） |
| 4-3 | mod.nu | `crates/nu-std/std/dirs/mod.nu` | _fetch（125-147行目） |

**主要処理フロー（dirs/mod.nu）**:
1. **19-30行目**: 環境変数の初期化（DIRS_LIST, DIRS_POSITION）
2. **48行目**: リストへの挿入
3. **139-140行目**: 位置計算（mod演算）
4. **145行目**: cd実行

#### Step 5: logモジュールを理解する

ログ出力の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | mod.nu | `crates/nu-std/std/log/mod.nu` | ログレベル定義（11-17行目） |
| 5-2 | mod.nu | `crates/nu-std/std/log/mod.nu` | custom（253-313行目） |
| 5-3 | mod.nu | `crates/nu-std/std/log/mod.nu` | info等（214-232行目） |

**主要処理フロー（log/mod.nu）**:
1. **260-262行目**: 現在のログレベルより低いならreturn
2. **272-281行目**: プレフィックスの決定
3. **304-311行目**: フォーマット文字列の置換と出力

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

```
load_standard_library()
    │
    ├─ create_virt_file()
    │      └─ working_set.add_file()
    │      └─ working_set.add_virtual_path()
    │
    ├─ std モジュール構築
    │      ├─ std/mod.nu
    │      │      ├─ export use std/util *
    │      │      ├─ export module std/assert
    │      │      ├─ export module std/bench
    │      │      ├─ export module std/dirs
    │      │      └─ ... (他のモジュール)
    │      │
    │      └─ サブモジュール
    │             ├─ std/assert/mod.nu
    │             │      ├─ export def main
    │             │      ├─ export def equal
    │             │      └─ ...
    │             ├─ std/dirs/mod.nu
    │             │      ├─ export-env
    │             │      ├─ export def add
    │             │      └─ ...
    │             └─ std/log/mod.nu
    │                    ├─ export def critical
    │                    ├─ export def error
    │                    └─ ...
    │
    ├─ std-rfc モジュール構築
    │      └─ std-rfc/*/mod.nu
    │
    └─ nu_parser::parse("use std/prelude *")
           └─ engine_state.merge_delta()
```

### データフロー図

```
[起動時]                  [ロード処理]                    [利用時]

include_str!     ─────▶  create_virt_file    ─────────▶  use std/assert
(バイナリ組み込み)           │                              │
                           ├─ add_file()                   └─ assert equal
                           └─ add_virtual_path()

                                    │
                                    ▼
                           parse("use std/prelude *")
                                    │
                                    ▼
                           engine_state.merge_delta()

[dirsモジュール]
$env.DIRS_LIST    ─────▶  dirs add           ─────────▶  $env.DIRS_LIST更新
$env.DIRS_POSITION        │                              $env.DIRS_POSITION更新
                          └─ _fetch()
                                 └─ cd

[logモジュール]
$env.NU_LOG_LEVEL ─────▶  log info           ─────────▶  print --stderr
                          │
                          └─ custom()
                                 └─ フォーマット置換
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lib.rs | `crates/nu-std/src/lib.rs` | Rust | ライブラリローダー |
| mod.nu | `crates/nu-std/std/mod.nu` | Nushell | 標準ライブラリエントリーポイント |
| prelude/mod.nu | `crates/nu-std/std/prelude/mod.nu` | Nushell | 自動ロードされるコマンド |
| assert/mod.nu | `crates/nu-std/std/assert/mod.nu` | Nushell | アサーションモジュール |
| bench/mod.nu | `crates/nu-std/std/bench/mod.nu` | Nushell | ベンチマークモジュール |
| dirs/mod.nu | `crates/nu-std/std/dirs/mod.nu` | Nushell | ディレクトリスタック |
| dt/mod.nu | `crates/nu-std/std/dt/mod.nu` | Nushell | 日付時刻ユーティリティ |
| formats/mod.nu | `crates/nu-std/std/formats/mod.nu` | Nushell | フォーマット変換 |
| help/mod.nu | `crates/nu-std/std/help/mod.nu` | Nushell | ヘルプ拡張 |
| input/mod.nu | `crates/nu-std/std/input/mod.nu` | Nushell | 入力ユーティリティ |
| iter/mod.nu | `crates/nu-std/std/iter/mod.nu` | Nushell | イテレータユーティリティ |
| log/mod.nu | `crates/nu-std/std/log/mod.nu` | Nushell | ロギングモジュール |
| math/mod.nu | `crates/nu-std/std/math/mod.nu` | Nushell | 数学関数 |
| util/mod.nu | `crates/nu-std/std/util/mod.nu` | Nushell | 汎用ユーティリティ |
| xml/mod.nu | `crates/nu-std/std/xml/mod.nu` | Nushell | XML処理 |
| config/mod.nu | `crates/nu-std/std/config/mod.nu` | Nushell | 設定ユーティリティ |
| testing/mod.nu | `crates/nu-std/std/testing/mod.nu` | Nushell | テストフレームワーク |
| clip/mod.nu | `crates/nu-std/std/clip/mod.nu` | Nushell | クリップボード操作 |
| random/mod.nu | `crates/nu-std/std/random/mod.nu` | Nushell | 乱数ユーティリティ |
