# 機能設計書: syncio - 同期I/O操作

## 1. 機能概要

### 1.1 目的
syncioモジュールは、Nimプログラミング言語における同期I/O操作のための基盤機能を提供する。ファイルの読み書き、標準入出力の操作、バッファ管理など、低レベルのI/O処理を実現する。

### 1.2 機能範囲
- ファイルハンドル管理（オープン、クローズ、再オープン）
- ファイル読み取り操作（バイト、文字、行単位）
- ファイル書き込み操作（バッファ、文字列、数値）
- ファイル位置操作（シーク、位置取得）
- 標準入出力ストリーム（stdin, stdout, stderr）
- プラットフォーム固有のI/O最適化（Windows/POSIX）

### 1.3 関連コンポーネント
- `system` モジュール: 基本型定義
- `formatfloat` モジュール: 浮動小数点数のフォーマット
- `widestrs` モジュール: Windows向けワイド文字列操作

## 2. データ構造

### 2.1 型定義

```nim
type
  CFile {.importc: "FILE", header: "<stdio.h>", incompleteStruct.} = object
  File* = ptr CFile  ## ファイルハンドルを表す型

  FileMode* = enum   ## ファイルオープンモード
    fmRead,          ## 読み取り専用
    fmWrite,         ## 書き込み専用（既存ファイルはクリア）
    fmReadWrite,     ## 読み書き（既存ファイルはクリア）
    fmReadWriteExisting,  ## 読み書き（既存ファイルを保持）
    fmAppend         ## 追記モード

  FileSeekPos* = enum  ## シーク位置の基準
    fspSet,          ## 絶対位置
    fspCur,          ## 現在位置からの相対
    fspEnd           ## 末尾からの相対

  FileHandle* = cint  ## OSファイルハンドル型（POSIX）
  # Windows: FileHandle* = int
```

### 2.2 グローバル変数

| 変数名 | 型 | 説明 |
|--------|------|------|
| `stdin` | File | 標準入力ストリーム |
| `stdout` | File | 標準出力ストリーム |
| `stderr` | File | 標準エラーストリーム |

## 3. 主要機能

### 3.1 ファイルオープン/クローズ

#### open (ファイル名指定)
```nim
proc open*(f: var File, filename: string, mode: FileMode = fmRead,
           bufSize: int = -1): bool
```
- **目的**: ファイルを開く
- **パラメータ**:
  - `f`: ファイルハンドル（出力）
  - `filename`: ファイル名
  - `mode`: オープンモード（デフォルト: 読み取り専用）
  - `bufSize`: バッファサイズ（-1: システムデフォルト, 0: バッファなし）
- **戻り値**: 成功時 `true`、失敗時 `false`
- **ソース位置**: `lib/std/syncio.nim:714-747`

#### close
```nim
proc close*(f: File)
```
- **目的**: ファイルを閉じる
- **ソース位置**: `lib/std/syncio.nim:330-342`

### 3.2 読み取り操作

#### readBuffer
```nim
proc readBuffer*(f: File, buffer: pointer, len: Natural): int
```
- **目的**: バッファに指定バイト数を読み込む
- **ソース位置**: `lib/std/syncio.nim:184-190`

#### readLine
```nim
proc readLine*(f: File, line: var string): bool
proc readLine*(f: File): string
```
- **目的**: 1行を読み込む（LFまたはCRLF区切り）
- **特徴**: 改行文字は結果に含まれない
- **ソース位置**: `lib/std/syncio.nim:395-527`

#### readAll
```nim
proc readAll*(file: File): string
```
- **目的**: ファイル全体を読み込む
- **ソース位置**: `lib/std/syncio.nim:606-621`

### 3.3 書き込み操作

#### write
```nim
proc write*(f: File, s: string)
proc write*(f: File, c: cstring)
proc write*(f: File, i: int)
proc write*(f: File, r: float)
proc write*(f: File, c: char)
```
- **目的**: 各種型のデータを書き込む
- **Windows対応**: UTF-8コンソール出力の特別処理
- **ソース位置**: `lib/std/syncio.nim:216-559`

#### writeLine
```nim
proc writeLine*[Ty](f: File, x: varargs[Ty, `$`])
```
- **目的**: 値を書き込み、改行を追加
- **ソース位置**: `lib/std/syncio.nim:623-629`

### 3.4 ファイル位置操作

| プロシージャ | 説明 | ソース位置 |
|-------------|------|-----------|
| `setFilePos` | ファイル位置を設定 | 795-799 |
| `getFilePos` | 現在のファイル位置を取得 | 801-805 |
| `getFileSize` | ファイルサイズを取得 | 807-812 |
| `endOfFile` | EOFかどうかを判定 | 582-587 |

## 4. プラットフォーム固有処理

### 4.1 Windows固有
- UTF-8コードページの自動設定（コンソールアプリ）
- バイナリモードでのstdin/stdout/stderr設定
- `_wfopen`によるワイド文字ファイル名サポート
- `ReadConsoleW`によるコンソール入力

### 4.2 POSIX固有
- `fseeko`/`ftello`による64ビットオフセットサポート
- ディレクトリ判定（`S_ISDIR`）
- ファイルハンドル継承制御（`FD_CLOEXEC`）

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

### 5.1 推奨読解順序

1. **データ構造の理解** (21-55行目)
   - `File`型、`FileMode`列挙型の定義を確認

2. **Cライブラリラッパー** (82-157行目)
   - `c_fopen`, `c_fread`, `c_fwrite`などのCライブラリ関数ラッパー

3. **基本読み取り操作** (184-215行目)
   - `readBuffer`, `readBytes`, `readChars`の実装

4. **基本書き込み操作** (216-273行目)
   - `write`プロシージャ群の実装

5. **ファイルオープン処理** (714-781行目)
   - `open`プロシージャの実装とプラットフォーム固有処理

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

```
open(filename) [714行目]
├── fopen() [Cライブラリ]
├── c_fstat() [ディレクトリ判定]
├── setInheritable() [継承制御]
└── c_setvbuf() [バッファ設定]

readLine(f, line) [395行目]
├── c_fgets() [Cライブラリ]
├── c_memchr() [改行検索]
└── checkErr() [エラー確認]

write(f, s) [267行目]
├── writeWindows() [Windows固有]
│   └── c_fprintf() [Cライブラリ]
└── writeBuffer() [POSIX]
    └── c_fwrite() [Cライブラリ]
```

### 5.3 データフロー図

```
[ユーザーアプリケーション]
        │
        ▼
┌───────────────────────────────────┐
│        syncio モジュール            │
│  ┌─────────────┐ ┌─────────────┐  │
│  │ 読み取り系   │ │ 書き込み系   │  │
│  │ readLine   │ │ write      │  │
│  │ readAll    │ │ writeLine  │  │
│  │ readBuffer │ │ writeBuffer│  │
│  └──────┬──────┘ └──────┬──────┘  │
│         │               │         │
│  ┌──────▼───────────────▼──────┐  │
│  │    Cライブラリラッパー        │  │
│  │  c_fread, c_fwrite, etc.   │  │
│  └─────────────┬───────────────┘  │
└─────────────────┼─────────────────┘
                  │
                  ▼
      [OSファイルシステム / stdio.h]
```

### 5.4 読解のコツ

- **プラットフォーム分岐**: `when defined(windows)` と `elif defined(posix)` で分岐するコードに注意
- **バッファリング**: `IOFBF`（フルバッファ）と`IONBF`（バッファなし）の使い分けを理解
- **エラー処理**: `checkErr`プロシージャによるエラー処理パターン
- **Windows UTF-8**: `c_fprintf`を使用する理由と`\0`を含む文字列の処理

## 6. 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `lib/std/syncio.nim` | ソース | メイン実装 |
| `lib/system/inclrtl.nim` | ソース | RTL共通インクルード |
| `lib/std/formatfloat.nim` | ソース | 浮動小数点フォーマット |
| `lib/std/widestrs.nim` | ソース | Windows向けワイド文字列 |
| `lib/std/exitprocs.nim` | ソース | 終了時処理 |

## 7. 設計上の考慮事項

### 7.1 パフォーマンス
- バッファサイズの最適化（デフォルト4000バイト）
- 読み取り時のメモリ再利用（`setLen`による事前確保）

### 7.2 互換性
- Windows/POSIX両対応
- 64ビットファイルオフセットサポート
- UTF-8ファイル名サポート（Windows）

### 7.3 エラー処理
- C言語のerrnoに基づくエラー報告
- IOError例外の発生
- EINTR（シグナル割り込み）の自動リトライ
