rbcsv 0.1.8 → 0.2.0

data/docs/write_functionality_implementation.md

@@ -0,0 +1,197 @@
+# CSV書き込み機能実装ガイド
+
+## 概要
+
+本ドキュメントは、RbCsv gemにおけるCSV書き込み機能（`RbCsv.write()`）の実装プロセスを詳細に記録したものです。実装から重要なバグ修正、そして最終的なリリースまでの一連の流れを説明しています。
+
+## 実装目標
+
+CSVデータを配列からファイルに書き込む機能を追加し、既存の読み込み機能との完全な互換性を確保する。
+
+```ruby
+# 目標API
+data = [
+  ['name', 'age', 'city'],
+  ['Alice', '25', 'Tokyo'],
+  ['Bob', '30', 'Osaka']
+]
+RbCsv.write('output.csv', data)
+```
+
+## 実装アーキテクチャ
+
+### 1. コア実装層（Rust）
+
+#### `ext/rbcsv/src/parser.rs`
+```rust
+pub fn write_csv_file(file_path: &str, data: &[Vec<String>]) -> Result<(), CsvError>
+```
+
+**主要機能:**
+- データ検証（空配列チェック、フィールド数整合性）
+- ファイルパス検証（親ディレクトリ存在確認）
+- CSV Writer設定とデータ書き込み
+- エラーハンドリング（権限エラー、IOエラー）
+
+#### `ext/rbcsv/src/ruby_api.rs`
+```rust
+pub fn write(ruby: &Ruby, file_path: String, data: Vec<Vec<String>>) -> Result<(), MagnusError>
+```
+
+**役割:**
+- RubyとRust間のAPIブリッジ
+- データ型変換（Ruby Array → Rust Vec）
+- エラー変換（Rust Error → Ruby Exception）
+
+#### `ext/rbcsv/src/error.rs`
+```rust
+// 新規追加エラータイプ
+WritePermission,    // 書き込み権限エラー
+InvalidData,        // 無効なデータエラー
+```
+
+### 2. Ruby API層
+
+#### `ext/rbcsv/src/lib.rs`
+```rust
+module.define_singleton_method("write", magnus::function!(write, 2))?;
+```
+
+Ruby側からの呼び出しを可能にするAPIメソッド登録。
+
+## データ検証ロジック
+
+### 1. 空データチェック
+```rust
+if data.is_empty() {
+    return Err(CsvError::invalid_data("CSV data is empty"));
+}
+```
+
+### 2. フィールド数整合性チェック
+```rust
+let expected_len = data[0].len();
+for (line_num, row) in data.iter().enumerate() {
+    if row.len() != expected_len {
+        let error_msg = format!(
+            "Field count mismatch at line {}: expected {} fields, got {} fields",
+            line_num + 1, expected_len, row.len()
+        );
+        return Err(CsvError::invalid_data(error_msg));
+    }
+}
+```
+
+### 3. ファイルパス検証
+```rust
+let path = Path::new(file_path);
+if let Some(parent) = path.parent() {
+    if !parent.exists() {
+        return Err(CsvError::io(format!("Parent directory does not exist: {}", parent.display())));
+    }
+}
+```
+
+## エラーハンドリング戦略
+
+### 1. 権限エラー
+```rust
+if e.kind() == std::io::ErrorKind::PermissionDenied {
+    return Err(CsvError::write_permission(format!("Permission denied: {}", file_path)));
+}
+```
+
+### 2. データ検証エラー
+- 空データ：`CSV data is empty`
+- フィールド数不一致：`Field count mismatch at line X: expected Y fields, got Z fields`
+
+### 3. IOエラー
+- ファイル作成失敗：`Failed to create file 'path': error`
+- フラッシュ失敗：`Failed to flush data to file 'path': error`
+
+## テスト戦略
+
+### 1. Rust単体テスト（`ext/rbcsv/src/parser.rs`）
+```rust
+#[test]
+fn test_write_csv_file_basic() { /* 基本書き込みテスト */ }
+
+#[test]
+fn test_write_csv_file_empty_data() { /* 空データエラーテスト */ }
+
+#[test]
+fn test_write_csv_file_field_count_mismatch() { /* フィールド数不一致テスト */ }
+```
+
+### 2. RSpec統合テスト（`spec/rbcsv_spec.rb`）
+```ruby
+describe ".write" do
+  it "writes CSV data to file"
+  it "overwrites existing file"
+  it "raises error for empty data"
+  it "raises error for inconsistent field count"
+  it "can write and read back the same data"
+end
+```
+
+### 3. 実行可能テストスクリプト（`test_write_functionality.rb`）
+8つの包括的テストケース：
+- 基本的なCSV書き込み
+- 往復テスト（write → read）
+- ファイル上書き
+- エラーハンドリング（空データ、フィールド数不一致）
+- Unicode文字対応
+- 特殊文字処理
+
+## CSV標準準拠
+
+### RFC 4180準拠
+- カンマ区切り
+- ダブルクォート内のダブルクォートエスケープ（`"""`）
+- 改行文字の適切な処理
+- フィールド内のカンマ、改行の適切なクォート
+
+### csv crateの活用
+```rust
+let mut writer = csv::WriterBuilder::new()
+    .has_headers(false)
+    .from_writer(file);
+```
+
+Rustの`csv` crateを使用することで、標準準拠のCSV出力を保証。
+
+## 実装完了基準
+
+1. ✅ **機能実装**: write機能の完全実装
+2. ✅ **データ検証**: 包括的な入力データ検証
+3. ✅ **エラーハンドリング**: 詳細なエラーメッセージ
+4. ✅ **テストカバレッジ**: Rust + Ruby + 実行可能テスト
+5. ✅ **ドキュメント**: DEVELOPMENT.mdの更新
+6. ✅ **往復互換性**: write/readの完全互換性
+
+## パフォーマンス考慮事項
+
+### 1. メモリ効率
+- ストリーミング書き込み（大容量データ対応）
+- 不要なデータコピーの回避
+
+### 2. エラー早期検出
+- データ検証を書き込み前に実行
+- 失敗時のリソース無駄遣い防止
+
+### 3. ファイルハンドリング
+- 適切なファイルフラッシュ
+- エラー時のファイル状態管理
+
+## 次のステップ
+
+1. **パフォーマンステスト**: 大容量データでのベンチマーク
+2. **設定オプション追加**: 区切り文字カスタマイズ等
+3. **ストリーミングAPI**: メモリ効率の更なる向上
+4. **非同期書き込み**: 大容量データの非同期処理
+
+## 参考資料
+
+- [RFC 4180 - CSV形式仕様](https://tools.ietf.org/html/rfc4180)
+- [Rust csv crate documentation](https://docs.rs/csv/)
+- [Magnus framework documentation](https://docs.rs/magnus/)

data/examples/README.md

@@ -0,0 +1,221 @@
+# RbCsv Examples
+
+このディレクトリには、RbCsvライブラリの使用方法を示すサンプルコードとテストスクリプトが含まれています。
+
+## ディレクトリ構成
+
+```
+examples/
+├── basic/              # 基本的な使用例
+├── features/           # 特定機能のテスト・デモ
+├── benchmarks/         # パフォーマンステストとベンチマーク
+└── README.md          # このファイル
+```
+
+## 実行方法
+
+全ての例を実行する前に、ライブラリがビルドされていることを確認してください：
+
+```bash
+# プロジェクトルートで実行
+bundle exec rake compile
+```
+
+## 📁 basic/ - 基本的な使用例
+
+### `basic_usage.rb`
+RbCsvの基本的な機能（parse, read, write）の使用例です。
+
+```bash
+cd examples/basic
+ruby basic_usage.rb
+```
+
+**機能:**
+- CSV文字列のパース
+- CSVファイルの読み込み
+- CSVファイルの書き込み
+
+### `quick_test.rb`
+簡単な動作確認用スクリプトです。
+
+```bash
+cd examples/basic
+ruby quick_test.rb
+```
+
+### `test_fixed.rb`
+特定のバグ修正後の動作確認用スクリプトです。
+
+```bash
+cd examples/basic
+ruby test_fixed.rb
+```
+
+### `test_install.rb`
+インストール後の動作確認用スクリプトです。
+
+```bash
+cd examples/basic
+ruby test_install.rb
+```
+
+## 🔧 features/ - 特定機能のテスト・デモ
+
+### `test_typed_functionality.rb`
+型認識機能（parse_typed, read_typed系）の詳細なテストとデモです。
+
+```bash
+cd examples/features
+ruby test_typed_functionality.rb
+```
+
+**機能:**
+- `parse_typed()`: 数値文字列を数値型に自動変換
+- `parse_typed!()`: trim + 型変換
+- `read_typed()`: ファイル読み込み + 型変換
+- `read_typed!()`: ファイル読み込み + trim + 型変換
+
+**型変換例:**
+- `"123"` → `123` (Integer)
+- `"45.6"` → `45.6` (Float)
+- `"1.23e-4"` → `0.000123` (Float)
+- `"hello"` → `"hello"` (String)
+
+### `test_write_functionality.rb`
+CSV書き込み機能の包括的なテストです。
+
+```bash
+cd examples/features
+ruby test_write_functionality.rb
+```
+
+**機能:**
+- 基本的なCSV書き込み
+- ファイル上書き動作
+- エラーハンドリング（空データ、フィールド数不一致など）
+- 書き込み→読み込みの往復テスト
+
+## 📊 benchmarks/ - パフォーマンステスト
+
+### `benchmark.rb`
+標準ライブラリのCSVとRbCsvの包括的なパフォーマンス比較です。
+
+```bash
+cd examples/benchmarks
+ruby benchmark.rb
+```
+
+**自動機能:**
+- サンプルCSVファイルを自動生成（1000レコード）
+- 大容量テストデータを自動作成（50,000レコード）
+- ベンチマーク後の自動クリーンアップ
+
+**測定項目:**
+- **基本パース性能**: `parse` vs `parse_typed` vs Ruby CSV
+- **ファイル読み込み性能**: `read` vs `read_typed` vs Ruby CSV
+- **大容量データ処理**: 50,000レコードでの性能比較
+- **メモリ使用量**: パース処理でのメモリ効率性
+- **データ処理性能**: フィルタリングと検索の速度比較
+- **型変換比較**: 手動変換 vs 自動型認識の性能差
+- **データ精度検証**: 結果の正確性確認
+
+**期待される結果:**
+- RbCsv は Ruby標準CSV より 2-4倍 高速
+- `parse_typed` は型変換コストを大幅削減
+- メモリ使用量も効率的
+
+### `output_comparison.rb`
+標準ライブラリのCSVとRbCsvの出力形式比較です。
+
+```bash
+cd examples/benchmarks
+ruby output_comparison.rb
+```
+
+**要求事項:**
+- `sample.csv` ファイルが必要
+
+## 🚀 実行例
+
+### 基本的なCSV処理
+
+```ruby
+require_relative '../../lib/rbcsv'
+
+# CSV文字列のパース
+csv_data = "name,age,city\nAlice,25,Tokyo\nBob,30,Osaka"
+result = RbCsv.parse(csv_data)
+# => [["name", "age", "city"], ["Alice", "25", "Tokyo"], ["Bob", "30", "Osaka"]]
+```
+
+### 型認識パース
+
+```ruby
+require_relative '../../lib/rbcsv'
+
+# 数値を自動的に数値型に変換
+csv_data = "name,age,score\nAlice,25,85.5\nBob,30,92"
+result = RbCsv.parse_typed(csv_data)
+# => [["name", "age", "score"], ["Alice", 25, 85.5], ["Bob", 30, 92]]
+#    注意: 25は整数、85.5は浮動小数点数として返される
+```
+
+### CSVファイルの書き込みと読み込み
+
+```ruby
+require_relative '../../lib/rbcsv'
+
+# データの準備
+data = [
+  ["product", "price", "quantity"],
+  ["Apple", "100", "50"],
+  ["Orange", "80.5", "30"]
+]
+
+# ファイルに書き込み
+RbCsv.write("output.csv", data)
+
+# ファイルから読み込み（型認識付き）
+result = RbCsv.read_typed("output.csv")
+# => [["product", "price", "quantity"], ["Apple", 100, 50], ["Orange", 80.5, 30]]
+#    注意: price と quantity が数値型として読み込まれる
+```
+
+## 💡 トラブルシューティング
+
+### よくあるエラー
+
+**1. LoadError: cannot load such file**
+```bash
+# 解決方法: ライブラリをビルドしてください
+bundle exec rake compile
+```
+
+**2. RuntimeError: Invalid Data Error**
+```bash
+# 原因: CSVデータの形式が不正
+# 解決方法: データの整合性を確認してください（空データ、フィールド数不一致など）
+```
+
+**3. 相対パスエラー**
+```bash
+# 解決方法: examples/ディレクトリのサブディレクトリから実行してください
+cd examples/basic
+ruby basic_usage.rb
+```
+
+## 📝 新しい例の追加
+
+新しい例を追加する場合：
+
+1. 適切なディレクトリを選択（basic, features, benchmarks）
+2. `require_relative '../../lib/rbcsv'` を使用
+3. スクリプトの先頭にコメントで目的と使用方法を記述
+4. このREADMEを更新
+
+## 🔗 関連ドキュメント
+
+- [メインREADME](../README.md) - 基本的な使用方法
+- [開発ガイド](../DEVELOPMENT.md) - 開発者向け詳細情報
+- [RSpecテスト](../spec/) - 自動テストスイート

data/{test.rb → examples/basic/basic_usage.rb}

@@ -1,4 +1,4 @@
-require_relative 'lib/rbcsv'
+require_relative '../../lib/rbcsv'
 
 # バージョン確認
 # puts RCsv.version_info
@@ -17,3 +17,4 @@ puts "Parsed data:"
 parsed_data.each { |row| puts row.inspect }
 
 puts "csv parse done."
+

data/{test_fixed.rb → examples/basic/test_fixed.rb}

@@ -1,4 +1,4 @@
-require_relative 'lib/r_csv'
+require_relative '../../lib/rbcsv'
 
 # バージョン確認
 # puts RCsv.version_info