rbcsv 0.1.4 → 0.1.7

data/DEVELOPMENT.md

@@ -0,0 +1,491 @@
+# RbCsv 開発ガイド
+
+このドキュメントでは、rbcsvの開発環境のセットアップ、ビルド方法、テスト手順、リリース手順について詳しく説明します。
+
+## 必要な環境
+
+- **Ruby**: 3.2.0以降（gemspec要件）
+- **Rust**: 最新の安定版を推奨（MSRV: 1.75+）
+- **Bundler**: gem管理
+- **Git**: バージョン管理
+- **RubyGems**: 3.3.11以降
+
+### システム要件
+
+- **macOS**: Apple Silicon (arm64) / Intel (x86_64)
+- **Linux**: x86_64 / aarch64
+- **Windows**: x86_64（実験的サポート）
+
+## プロジェクト構成
+
+```
+r_csv/
+├── lib/
+│   ├── rbcsv.rb                    # メインのRubyエントリーポイント
+│   └── rbcsv/
+│       ├── version.rb              # バージョン定義
+│       └── rbcsv.bundle            # コンパイル済みネイティブ拡張（生成される）
+├── ext/
+│   └── rbcsv/
+│       ├── src/
+│       │   ├── lib.rs              # Rust拡張のエントリーポイント、Magnus初期化
+│       │   ├── parser.rs           # CSV解析コア、CsvParseOptions定義
+│       │   ├── ruby_api.rs         # Ruby APIバインディング、オプション処理
+│       │   └── error.rs            # エラーハンドリング
+│       ├── Cargo.toml              # Rust依存関係（Magnus 0.8.1使用）
+│       └── extconf.rb              # Ruby拡張ビルド設定
+├── spec/
+│   ├── rbcsv_spec.rb               # メインのRubyテスト
+│   └── spec_helper.rb              # テスト設定
+├── docs/                           # ドキュメント
+├── target/                         # Rustビルド出力（git無視）
+├── tmp/                            # Ruby拡張ビルド中間ファイル（git無視）
+├── *.gem                           # ビルド済みgemファイル
+├── rbcsv.gemspec                   # Gem仕様
+├── Rakefile                        # ビルドタスク（rb_sys使用）
+├── Gemfile                         # Ruby依存関係
+├── Cargo.toml                      # ワークスペース設定
+├── CHANGELOG.md                    # 変更履歴
+├── README.md                       # 使用法ガイド
+└── DEVELOPMENT.md                  # このファイル
+```
+
+## 開発環境のセットアップ
+
+### 1. リポジトリのクローン
+
+```bash
+git clone https://github.com/fs0414/rbcsv.git
+cd rbcsv
+```
+
+### 2. Ruby依存関係のインストール
+
+```bash
+bundle install
+```
+
+### 3. ネイティブ拡張のビルド
+
+```bash
+# 推奨方法（rb_sys使用）
+rake compile
+
+# 代替方法（開発時）
+bundle exec rake compile
+```
+
+### 4. 動作確認
+
+```bash
+# 基本的な動作確認
+ruby -I lib -e "require 'rbcsv'; p RbCsv.parse('a,b\n1,2', {})"
+# 期待される出力: [["a", "b"], ["1", "2"]]
+
+# オプション付きテスト
+ruby -I lib -e "require 'rbcsv'; p RbCsv.parse(' a , b \n 1 , 2 ', {trim: true})"
+# 期待される出力: [["a", "b"], ["1", "2"]]
+```
+
+## ビルドプロセス
+
+### 自動ビルド（推奨）
+
+```bash
+# 全体ビルド（コンパイル、テスト、リント）
+rake
+
+# 拡張のみコンパイル
+rake compile
+
+# クリーンビルド
+rake clean
+rake compile
+```
+
+### 手動ビルド手順
+
+```bash
+# 1. 前回のビルドをクリーン
+rm -rf lib/rbcsv/rbcsv.bundle tmp/ target/
+
+# 2. Rust拡張のコンパイル
+cd ext/rbcsv
+cargo build --release
+cd ../..
+
+# 3. バンドルファイルのコピー（macOSの場合）
+cp target/release/librbcsv.dylib lib/rbcsv/rbcsv.bundle
+
+# Linuxの場合
+# cp target/release/librbcsv.so lib/rbcsv/rbcsv.bundle
+```
+
+### ビルドのトラブルシューティング
+
+#### ABIバージョンの不一致
+
+```bash
+# エラー例: "incompatible ABI version"
+rm -rf lib/rbcsv/rbcsv.bundle tmp/ target/
+bundle exec rake compile
+```
+
+#### Rust/Cargoの問題
+
+```bash
+# Rust依存関係の更新
+cd ext/rbcsv
+cargo update
+cargo clean
+cargo build --release
+cd ../..
+```
+
+#### Magnus APIエラー
+
+```bash
+# 最新のMagnus 0.8.1では、ReprValueトレイトの明示的インポートが必要
+# ruby_api.rs で以下が含まれていることを確認:
+use magnus::{value::ReprValue};
+```
+
+## テスト手順
+
+### Ruby統合テスト
+
+```bash
+# 全テスト実行
+bundle exec rspec
+
+# 特定のテストファイル
+bundle exec rspec spec/rbcsv_spec.rb
+
+# 詳細出力
+bundle exec rspec --format documentation
+```
+
+### Rustユニットテスト
+
+```bash
+# 全Rustテスト
+cd ext/rbcsv
+cargo test
+
+# 詳細出力
+cargo test -- --nocapture
+
+# 特定のテスト
+cargo test test_parse_basic
+cd ../..
+```
+
+### パフォーマンステスト
+
+```bash
+# ベンチマーク実行
+ruby benchmark.rb
+
+# カスタムテストファイルでのテスト
+ruby test.rb
+```
+
+### コードスタイルチェック
+
+```bash
+# Rubyコード（RuboCop）
+bundle exec rubocop
+
+# Rustコード
+cd ext/rbcsv
+cargo fmt --check
+cargo clippy -- -D warnings
+cd ../..
+```
+
+## API設計
+
+### 現在のAPI（v0.1.6+）
+
+```ruby
+# 統一されたオプションベースAPI
+RbCsv.parse(csv_string, options = {})
+RbCsv.read(file_path, options = {})
+
+# 利用可能なオプション
+options = {
+  trim: true/false    # 空白文字の除去（デフォルト: false）
+  # 将来の拡張:
+  # headers: true/false
+  # delimiter: ','
+}
+```
+
+### 実装アーキテクチャ
+
+1. **parser.rs**: CsvParseOptionsと核となるCSV解析機能
+2. **ruby_api.rs**: Rubyハッシュオプションの処理とMagnus API
+3. **lib.rs**: Magnus初期化と関数登録
+4. **error.rs**: エラーハンドリングとRuby例外の変換
+
+## リリース手順
+
+### 1. 準備フェーズ
+
+```bash
+# 開発状況の確認
+git status
+git log --oneline -10
+
+# 全テストの実行
+rake clean
+rake
+
+# コードスタイルチェック
+bundle exec rubocop
+cd ext/rbcsv && cargo clippy && cd ../..
+```
+
+### 2. バージョン更新
+
+```bash
+# lib/rbcsv/version.rb を編集
+vim lib/rbcsv/version.rb
+```
+
+```ruby
+module RbCsv
+  VERSION = "x.y.z"  # セマンティックバージョニング
+end
+```
+
+### 3. CHANGELOG.md の更新
+
+```markdown
+## [x.y.z] - YYYY-MM-DD
+
+### 追加
+- 新機能の説明
+
+### 変更
+- 既存機能の変更点
+
+### 修正
+- バグ修正の説明
+
+### 削除
+- 削除された機能（非互換性のある変更）
+
+### セキュリティ
+- セキュリティ関連の修正
+```
+
+### 4. ビルドとテスト
+
+```bash
+# フルクリーンビルド
+rake clean
+bundle install
+rake compile
+
+# 統合テスト
+rake spec
+
+# 動作確認
+ruby -I lib -e "require 'rbcsv'; puts RbCsv::VERSION"
+ruby -I lib -e "require 'rbcsv'; p RbCsv.parse('a,b\n1,2', {})"
+```
+
+### 5. Gemビルド
+
+```bash
+# Gemファイル生成
+gem build rbcsv.gemspec
+
+# 生成確認
+ls -la rbcsv-*.gem
+```
+
+### 6. 変更のコミット
+
+```bash
+git add -A
+git commit -m "Release v${VERSION}
+
+主な変更:
+- 変更点1の説明
+- 変更点2の説明
+- バグ修正やパフォーマンス改善"
+```
+
+### 7. タグ作成とプッシュ
+
+```bash
+VERSION=$(ruby -I lib -e "require 'rbcsv/version'; puts RbCsv::VERSION")
+git tag "v${VERSION}"
+git push origin main
+git push origin "v${VERSION}"
+```
+
+### 8. Gem公開（オプション）
+
+```bash
+# RubyGems.orgへの公開
+gem push rbcsv-${VERSION}.gem
+
+# 公開確認
+gem list rbcsv --remote
+```
+
+## 開発のベストプラクティス
+
+### コードスタイル
+
+#### Ruby
+- 標準的なRuby Style Guideに従う
+- RuboCop設定を使用（`.rubocop.yml`）
+- frozen_string_literalを有効化
+
+#### Rust
+```bash
+# フォーマット
+cargo fmt
+
+# リント
+cargo clippy -- -D warnings
+
+# ドキュメント生成
+cargo doc --open
+```
+
+### テスト戦略
+
+1. **単体テスト**: 各Rustモジュールに対するcargo test
+2. **統合テスト**: Ruby APIレベルでのRSpecテスト
+3. **パフォーマンステスト**: 大きなCSVファイルでのベンチマーク
+4. **エッジケーステスト**: 不正なCSV、空ファイル、エンコーディング問題
+
+### デバッグ
+
+#### Rust側のデバッグ
+
+```rust
+// 開発ビルドでのみ有効
+#[cfg(debug_assertions)]
+eprintln!("Debug: {:?}", variable);
+
+// ログ出力（log crateを使用）
+log::debug!("Debug information: {:?}", data);
+```
+
+#### Ruby側のデバッグ
+
+```ruby
+# 詳細エラー情報
+begin
+  RbCsv.parse(invalid_csv, {})
+rescue => e
+  puts "Error: #{e.class} - #{e.message}"
+  puts e.backtrace
+end
+```
+
+## よくある問題と解決策
+
+### ビルド関連
+
+**問題**: "incompatible ABI version"
+```bash
+# 解決策: クリーンして同じRubyバージョンで再ビルド
+rm -rf lib/rbcsv/rbcsv.bundle tmp/
+bundle exec rake compile
+```
+
+**問題**: Rustコンパイルエラー
+```bash
+# 解決策: Rust依存関係の更新
+cd ext/rbcsv
+cargo update
+cargo clean
+cargo build --release
+cd ../..
+```
+
+### 実行時問題
+
+**問題**: 空配列が返される
+- **原因**: CSVリーダーの`has_headers`設定
+- **解決策**: 最新バージョン（v0.1.4+）を使用
+
+**問題**: 日本語CSV文字化け
+- **原因**: エンコーディング問題
+- **解決策**: UTF-8での保存を確認、またはエンコーディング変換
+
+### パフォーマンス問題
+
+**問題**: 大きなファイルでメモリ不足
+- **解決策**: ストリーミング処理の実装を検討（将来の機能）
+
+**問題**: 予想より遅い処理速度
+- **チェック項目**:
+  - ファイルI/O vs メモリ処理
+  - trimオプションの使用
+  - デバッグビルド vs リリースビルド
+
+## コントリビューションガイドライン
+
+### 開発フロー
+
+1. **Issue作成**: バグ報告や機能要求
+2. **フォーク**: 個人リポジトリへのフォーク
+3. **ブランチ作成**: `feature/new-feature` または `fix/bug-name`
+4. **開発**: コードの実装とテスト追加
+5. **テスト**: 全テストの実行と確認
+6. **プルリクエスト**: 説明と変更内容の詳細
+
+### コミットメッセージ
+
+```
+[種類] 簡潔な説明（50文字以内）
+
+詳細な説明（必要に応じて）：
+- 変更の理由
+- 実装方法
+- 影響範囲
+
+関連Issue: #123
+```
+
+種類の例:
+- `feat`: 新機能
+- `fix`: バグ修正
+- `docs`: ドキュメント
+- `style`: コードスタイル
+- `refactor`: リファクタリング
+- `test`: テスト追加
+- `chore`: その他（依存関係更新など）
+
+## ロードマップ
+
+### 短期目標（v0.2.x）
+- [ ] カスタム区切り文字サポート
+- [ ] ヘッダー行処理
+- [ ] エラーハンドリングの改善
+
+### 中期目標（v0.3.x）
+- [ ] ストリーミング処理
+- [ ] 非同期処理サポート
+- [ ] Windows完全サポート
+
+### 長期目標（v1.0.x）
+- [ ] 安定したAPI
+- [ ] 包括的なドキュメント
+- [ ] パフォーマンス最適化完了
+
+## 参考リンク
+
+- [Magnus Documentation](https://docs.rs/magnus/)
+- [rb_sys Documentation](https://docs.rs/rb_sys/)
+- [Ruby Extension Guide](https://docs.ruby-lang.org/en/master/extension_rdoc.html)
+- [Cargo Book](https://doc.rust-lang.org/cargo/)
+- [RubyGems Guides](https://guides.rubygems.org/)

data/ext/rbcsv/Cargo.toml

@@ -11,4 +11,9 @@ crate-type = ["cdylib"]
 
 [dependencies]
 csv = "1.3.1"
-magnus = { version = "0.6.2" }
+magnus = { version = "0.8.1" }
+# rb-sys = { version = "0.9", features = ["link-ruby"] }
+log = "0.4"
+
+[dev-dependencies]
+env_logger = "0.10"

data/ext/rbcsv/src/error.rs

@@ -0,0 +1,87 @@
+use std::error::Error as StdError;
+use std::fmt;
+
+#[derive(Debug)]
+pub struct CsvError {
+    message: String,
+    kind: ErrorKind,
+}
+
+#[derive(Debug)]
+pub enum ErrorKind {
+    // IO関連エラー
+    Io,
+    // CSV解析エラー
+    Parse,
+    // UTF-8エンコーディングエラー
+    Encoding,
+    // フィールド数の不一致
+    FieldCountMismatch,
+    // 空のCSVデータ
+    EmptyData,
+    // その他のエラー
+    #[allow(dead_code)]
+    Other,
+}
+
+impl fmt::Display for CsvError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        match self.kind {
+            ErrorKind::Io => write!(f, "IO Error: {}", self.message),
+            ErrorKind::Parse => write!(f, "Parse Error: {}", self.message),
+            ErrorKind::Encoding => write!(f, "Encoding Error: {}", self.message),
+            ErrorKind::FieldCountMismatch => write!(f, "Field Count Mismatch: {}", self.message),
+            ErrorKind::EmptyData => write!(f, "Empty Data: {}", self.message),
+            ErrorKind::Other => write!(f, "Error: {}", self.message),
+        }
+    }
+}
+
+impl StdError for CsvError {}
+
+impl CsvError {
+    pub fn new(kind: ErrorKind, message: impl Into<String>) -> Self {
+        CsvError {
+            message: message.into(),
+            kind,
+        }
+    }
+
+    pub fn io(message: impl Into<String>) -> Self {
+        Self::new(ErrorKind::Io, message)
+    }
+
+    pub fn parse(message: impl Into<String>) -> Self {
+        Self::new(ErrorKind::Parse, message)
+    }
+
+    pub fn encoding(message: impl Into<String>) -> Self {
+        Self::new(ErrorKind::Encoding, message)
+    }
+
+    #[allow(dead_code)]
+    pub fn field_count_mismatch(expected: usize, actual: usize) -> Self {
+        Self::new(
+            ErrorKind::FieldCountMismatch,
+            format!("Expected {} fields, but got {}", expected, actual),
+        )
+    }
+
+    pub fn empty_data() -> Self {
+        Self::new(ErrorKind::EmptyData, "CSV data is empty")
+    }
+}
+
+// csv crateのエラーからの変換
+impl From<csv::Error> for CsvError {
+    fn from(err: csv::Error) -> Self {
+        match err.kind() {
+            csv::ErrorKind::Io(_) => CsvError::io(err.to_string()),
+            csv::ErrorKind::Utf8 { .. } => CsvError::encoding(err.to_string()),
+            csv::ErrorKind::UnequalLengths { .. } => {
+                CsvError::new(ErrorKind::FieldCountMismatch, err.to_string())
+            }
+            _ => CsvError::parse(err.to_string()),
+        }
+    }
+}

data/ext/rbcsv/src/lib.rs

@@ -1,69 +1,19 @@
-#[cfg(not(test))]
-use magnus::{Error, exception, function, prelude::*, Ruby};
+mod error;
+mod parser;
+mod ruby_api;
 
-#[cfg(test)]
-type Error = Box<dyn std::error::Error>;
+use magnus::{Object, Ruby};
+use ruby_api::{parse, parse_trim, read, read_trim};
 
-fn parse(s: String) -> Result<Vec<Vec<String>>, Error> {
-    let mut reader = csv::ReaderBuilder::new()
-        .has_headers(false)  // ヘッダーを無効にして、すべての行を処理
-        .from_reader(s.as_bytes());
-
-    let mut records = Vec::new();
-
-    for result in reader.records() {
-        match result {
-            Ok(record) => {
-                let row: Vec<String> = record.iter().map(|field| field.to_string()).collect();
-                records.push(row);
-            }
-            #[cfg(not(test))]
-            Err(e) => return Err(Error::new(exception::runtime_error(), format!("CSV parse error: {}", e))),
-            #[cfg(test)]
-            Err(e) => return Err(Box::new(e)),
-        }
-    }
-
-    Ok(records)
-}
-
-#[cfg(not(test))]
 #[magnus::init]
-fn init(ruby: &Ruby) -> Result<(), Error> {
+fn init(ruby: &Ruby) -> Result<(), magnus::Error> {
     let module = ruby.define_module("RbCsv")?;
-    module.define_singleton_method("parse", function!(parse, 1))?;
-    Ok(())
-}
-
-#[cfg(test)]
-mod tests {
 
-    use super::*;
+    module.define_singleton_method("parse", magnus::function!(parse, 1))?;
+    module.define_singleton_method("parse!", magnus::function!(parse_trim, 1))?;
+    module.define_singleton_method("read", magnus::function!(read, 1))?;
+    module.define_singleton_method("read!", magnus::function!(read_trim, 1))?;
 
-    #[test]
-    fn test_parse() {
-        let csv_data = "name,age,city\nAlice,25,Tokyo\nBob,30,Osaka";
-        let result = parse(csv_data.to_string());
-
-        assert!(result.is_ok());
-
-        let records = result.unwrap();
-        assert_eq!(records.len(), 3);  // ヘッダー行も含むため3行
-        assert_eq!(records[0], vec!["name", "age", "city"]);
-        assert_eq!(records[1], vec!["Alice", "25", "Tokyo"]);
-        assert_eq!(records[2], vec!["Bob", "30", "Osaka"]);
-    }
-
-    #[test]
-    fn test_parse_simple() {
-        let csv_data = "a,b\n1,2";
-        let result = parse(csv_data.to_string());
-
-        assert!(result.is_ok());
-
-        let records = result.unwrap();
-        assert_eq!(records.len(), 2);
-        assert_eq!(records[0], vec!["a", "b"]);
-        assert_eq!(records[1], vec!["1", "2"]);
-    }
+    Ok(())
 }
+