# 機能設計書：96-options（Option型）

## 1. 概要

### 本機能の処理概要
optionsモジュールは、値が存在するか存在しないかを型安全に表現するOption型を提供する標準ライブラリモジュールである。`Option[T]`型は値`x`を持つ`some(x)`状態、または値を持たない`none(T)`状態のいずれかを取り、nilポインタの代替として安全な値の不在表現を実現する。関数型プログラミングにおけるMaybeモナドに相当し、map/flatMap/filterなどのモナド操作をサポートする。

### 関連画面
本機能は標準ライブラリのコアユーティリティであり、特定の画面には関連しない。

### 機能種別
ライブラリ機能（ユーティリティ型・モナド実装）

## 2. 入力仕様

### Option型の構造
```nim
type
  Option*[T] = object
    when T is SomePointer:
      val: T
    else:
      val: T
      has: bool
```

ポインタ型（`ptr`、`pointer`、`ref`、`proc`、`iterator {.closure.}`）の場合は`nil`が`none`を表すため`has`フィールドは不要。非ポインタ型の場合は`has`フィールドで値の有無を管理する。

### 入力パラメータ一覧

| プロシージャ | パラメータ | 型 | 説明 |
|-------------|----------|-----|------|
| some | val | T | 格納する値 |
| option | val | T | 格納する値（nilの場合はnoneになる） |
| none | T | typedesc | Option型の型パラメータ |
| get | self | Option[T] | Optionインスタンス |
| get | otherwise | T | デフォルト値 |
| map | callback | proc(T) / proc(T): R | コールバック関数 |
| flatMap | callback | proc(T): Option[R] | Option返却コールバック |
| filter | callback | proc(T): bool | フィルタ条件 |

## 3. 出力仕様

### 戻り値一覧

| プロシージャ | 戻り値型 | 説明 |
|-------------|---------|------|
| some | Option[T] | 値を持つOption |
| option | Option[T] | 値を持つOption（nilならnone） |
| none | Option[T] | 空のOption |
| isSome | bool | 値が存在するか |
| isNone | bool | 値が存在しないか |
| get | T / lent T | 格納値またはデフォルト値 |
| map | void / Option[R] | 変換結果 |
| flatMap | Option[R] | 変換結果 |
| filter | Option[T] | フィルタ結果 |
| flatten | Option[T] | ネスト解除結果 |
| unsafeGet | lent T | 格納値（未検証） |

### 例外

| 例外型 | 発生条件 | メッセージ |
|-------|---------|----------|
| UnpackDefect | none状態でgetを呼び出した場合 | "Can't obtain a value from a `none`" |

## 4. 処理フロー

### 4.1 Option生成フロー

```
[some(val)呼び出し]
    |
    v
[型判定: T is SomePointer?]
    |
    +-- Yes --> [assert not val.isNil] --> [Option[T](val: val)]
    |
    +-- No ---> [Option[T](has: true, val: val)]
    |
    v
[Option[T]を返却]
```

### 4.2 値取得フロー（get）

```
[get(self)呼び出し]
    |
    v
[isSome判定]
    |
    +-- true --> [self.valを返却]
    |
    +-- false -> [UnpackDefectを発生]
```

### 4.3 map/flatMapフロー

```
[map(self, callback)呼び出し]
    |
    v
[isSome判定]
    |
    +-- true --> [some(callback(self.val))]を返却
    |
    +-- false -> [none(R)]を返却
```

## 5. ビジネスルール

### BR-01: ポインタ型の最適化
ポインタ型（`ref`、`ptr`、`pointer`、`proc`、`iterator {.closure.}`）に対しては、`nil`値が`none`状態を表すため、追加の`has`フィールドを持たない。これによりメモリ効率が向上する。

### BR-02: some関数のnil禁止
`some`関数にポインタ型の`nil`値を渡すことは禁止される（assertで検証）。nilをOptionに変換する場合は`option`関数を使用する。

### BR-03: 不変借用によるget
`get`関数は`lent T`を返却し、コピーを避けて効率的なアクセスを提供する。可変アクセスが必要な場合は`var Option[T]`に対する`get`を使用する。

### BR-04: flatMapの実装
`flatMap`は`map`と`flatten`の合成として実装される。

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

本機能はデータベース操作を行わない。

## 7. エラー処理

### エラーハンドリング方針

| 状況 | 処理 |
|-----|------|
| noneからのget | UnpackDefect例外を発生（Defect継承のためcatch非推奨） |
| someにnil渡し | assertによる即時エラー |

### 安全なアクセスパターン

```nim
# パターン1: isSomeチェック
if opt.isSome:
  echo opt.get

# パターン2: デフォルト値
echo opt.get(defaultValue)

# パターン3: map使用
opt.map(proc(x: T) = echo x)
```

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

本機能はトランザクション処理を行わない。

## 9. パフォーマンス要件

### 時間計算量

| 操作 | 計算量 | 備考 |
|-----|-------|------|
| some/none/option | O(1) | 即座に構築 |
| isSome/isNone | O(1) | フィールド参照のみ |
| get | O(1) | フィールド参照のみ |
| map/flatMap/filter | O(f) | コールバック依存 |
| flatten | O(1) | 参照のみ |

### 空間計算量

| 型 | サイズ | 備考 |
|---|-------|------|
| Option[SomePointer] | sizeof(T) | ポインタサイズのみ |
| Option[非ポインタ] | sizeof(T) + sizeof(bool) | hasフィールド追加 |

### インライン化
主要なプロシージャには`{.inline.}`が付与され、関数呼び出しオーバーヘッドを削減している。

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

### 型安全性
- nilポインタの代替として型安全な不在表現を提供
- コンパイル時に型チェックが行われる
- UnpackDefectはDefect継承でありcatch非推奨（プログラマーエラー）

### 注意点
- `unsafeGet`は未検証アクセスを行うため、事前に`isSome`チェックが必須

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

### 11.1 推奨される読み解き順序

1. **型定義の理解**（90-102行目）
   - `Option[T]`の内部構造
   - `SomePointer`による分岐
   - `UnpackDefect`例外型

2. **生成関数**（104-159行目）
   - `option`: ポインタのnilをnoneに変換
   - `some`: 値を持つOptionを生成（nilは禁止）
   - `none`: 空のOptionを生成

3. **状態確認**（161-189行目）
   - `isSome`: 値の存在確認
   - `isNone`: 値の不在確認

4. **値取得**（191-232行目）
   - `get`: 値取得（例外あり）
   - `get(otherwise)`: デフォルト値付き取得
   - `var get`: 可変参照取得

5. **モナド操作**（234-334行目）
   - `map`: 値変換
   - `flatten`: ネスト解除
   - `flatMap`: モナディック合成
   - `filter`: 条件フィルタ

6. **演算子・ユーティリティ**（336-382行目）
   - `==`: 等価比較
   - `$`: 文字列化
   - `unsafeGet`: 未検証取得

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

```
Option[T]型
├── 生成
│   ├── some[T](val: T): Option[T]
│   ├── option[T](val: T): Option[T]
│   └── none(T: typedesc): Option[T]
├── 状態確認
│   ├── isSome[T](self: Option[T]): bool
│   └── isNone[T](self: Option[T]): bool
├── 値取得
│   ├── get[T](self: Option[T]): lent T
│   ├── get[T](self: Option[T], otherwise: T): T
│   ├── get[T](self: var Option[T]): var T
│   └── unsafeGet[T](self: Option[T]): lent T
├── モナド操作
│   ├── map[T](self: Option[T], callback: proc(T))
│   ├── map[T, R](self: Option[T], callback: proc(T): R): Option[R]
│   ├── flatten[T](self: Option[Option[T]]): Option[T]
│   ├── flatMap[T, R](self: Option[T], callback: proc(T): Option[R]): Option[R]
│   │   └── flatten (内部呼び出し)
│   └── filter[T](self: Option[T], callback: proc(T): bool): Option[T]
└── ユーティリティ
    ├── `==`[T](a, b: Option[T]): bool
    └── `$`[T](self: Option[T]): string
        └── name (typetraitsから)
```

### 11.3 データフロー図

```
値生成:
  入力値(T) --> [some/option] --> Option[T](val: T, has: true)
  なし     --> [none]        --> Option[T](val: default, has: false)

値取得:
  Option[T] --> [isSome] --> true  --> [get] --> T
                         --> false --> UnpackDefect

モナド変換:
  Option[T] --> [map(f: T->R)] --> Option[R]
                                     |
  Option[Option[T]] --> [flatten] ---+
                                     |
  Option[T] --> [flatMap(f: T->Option[R])] --> Option[R]
```

### 11.4 関連ファイル一覧

| ファイル | 役割 | 行数 |
|---------|------|------|
| lib/pure/options.nim | Option型の実装 | 382 |
| lib/pure/typetraits.nim | name関数（$で使用） | 377 |
| lib/std/assertions.nim | assert（nimPreviewSlimSystem時） | - |

### 11.5 重要な実装詳細

#### SomePointer型制約（83-88行目）
```nim
when (NimMajor, NimMinor) >= (1, 1):
  type
    SomePointer = ref | ptr | pointer | proc | iterator {.closure.}
else:
  type
    SomePointer = ref | ptr | pointer
```

Nim 1.1以降では`proc`と`iterator {.closure.}`もポインタ型として扱われ、nil表現の最適化が適用される。

#### 等価比較の最適化（336-353行目）
```nim
proc `==`*[T](a, b: Option[T]): bool {.inline.} =
  when T is SomePointer:
    a.val == b.val
  else:
    (a.isSome and b.isSome and a.val == b.val) or (a.isNone and b.isNone)
```

ポインタ型の場合は単純にポインタ比較で済み、非ポインタ型の場合は両方のhas状態を考慮した比較を行う。

#### 文字列化の後方互換性（355-372行目）
```nim
when defined(nimLagacyOptionsDollar):
  result = "Some("  # 旧形式
else:
  result = "some("  # 新形式
```

`nimLagacyOptionsDollar`定義時は旧形式（Some/None）を使用し、それ以外は新形式（some/none）を使用する。
