export_to 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d42bfa7144883c0c4771feeb77e75b8555d957c573a319cc770238f8a28bdc62
-  data.tar.gz: eb76e5d51d0b5ee9e2c88bd6e2badffa4b383aef5ca1817765594d9d997a5538
+  metadata.gz: 48ade8d2d2cc83728bcbbebf003187ac72d515f42e65645e67a91ba4021936ce
+  data.tar.gz: ea3754d3619c1d7fcf73c26c7eb2205f6de0caf43e9fd9731b155a4feda6f595
 SHA512:
-  metadata.gz: fb193c89469a61cc10f62535edaca799f5cc4a5de0a4a8f78f3412488aa2b01f423b5743cf366bc25c076ea68150bd51396d892f7ab5667451e5b5016ac5189f
-  data.tar.gz: d5405dc6670c5961ed6af6bd3f2352e5bd4c01e8dd180c56d79d96800971b2a8f7f9eda1484b9cc43cc6a896379417de561207f4ff83a7a1a11a7385bd6744ea
+  metadata.gz: 0a63b654da5d5bcf77bb87853e3c0f8c3cd7b0d985a40204e6ef259ad12da528e96f8077523464a5d7ba202a450b08c8f483431d0ffe022901e0421399de1e72
+  data.tar.gz: f311a3013ffac1fd95eca922865e9df4c427db2a9dd7c0dca8f8c3bf2188b2716aca16dc869d2d9909a5a2d6afaa237edfd429912aef1accbd62b6329e93f586

data/CHANGELOG.md

@@ -0,0 +1,113 @@
+# 更新紀錄（Changelog）
+
+本檔記錄此專案所有值得注意的變更。
+
+格式參考 [Keep a Changelog](https://keepachangelog.com/zh-TW/1.1.0/)，版本號遵循 [Semantic Versioning](https://semver.org/lang/zh-TW/)。
+
+## [Unreleased]
+
+### Added
+
+- 新增 `CHANGELOG.md`。
+- 完整的 `README.md`：概述、環境需求、安裝、DSL 用法、開發與發版流程。
+- CLAUDE.md 規則：每個 PR 都必須同步更新 `README.md` 與 `CHANGELOG.md`；`README.md` 與 `CHANGELOG.md` 一律用繁體中文撰寫。
+
+### Changed
+
+- `README.md`、`CHANGELOG.md` 改以繁體中文（zh-TW）撰寫。
+
+## [1.3.0] - 2026-10-27
+
+### Fixed
+
+- `ExportTo::Base#each` 每次呼叫都會 raise `NoMethodError (undefined method 'rows!')`。現在會回傳所有列組成的 Array（第一列是標題列，內容與 `#to_csv` 相同）；帶 block 時會逐列 yield 並回傳 exporter 本身，因此 Enumerable 方法（`map`、`to_a` 等）也能使用。`#each!` 沒有變動。
+- `TESTING.md` 與 `bin/test_all` 已過時（只涵蓋 Ruby 2.7–3.1）。現在它們的說明與執行內容都與 `.github/workflows/ci.yml` 的矩陣一致。
+
+### Deprecated
+
+- `ExportTo::Base#to_xls`：自 1.0.0 起它回傳的就是 **XLSX** 資料（與 `#to_xlsx` 相同），而不是舊版 `.xls` 檔。為了不讓既有呼叫端壞掉，回傳值維持不變，但現在會印出一次性的 `[DEPRECATION]` 警告（輸出到 `$stderr`，每個 process 一次）。請改用 `#to_xlsx`；若要真正的 `.xls`，請用 `ExportTo::Exporter::Xls.new(export).to_xls`。未來的 major 版本可能會讓 `#to_xls` 回傳真正的 `.xls` 檔，或將它移除。
+
+### Added
+
+- 測試：`#each`、`#to_xls` 的相容性（仍回傳 XLSX）與其棄用警告、`#to_xlsx` / `ExportTo::Exporter::Xls` 的輸出格式。
+
+## [1.2.1] - 2026-10-27
+
+### Added
+
+- 支援 Rails 8.0 / 8.1 與 Ruby 3.4（`activesupport` 現在放寬到 `< 8.2`；`csv` gem 改為明確相依；移除 `required_ruby_version` 的上限；新增 `ruby_3.3_rails_8.*` / `ruby_3.4_rails_8.*` gemfile 與對應的 CI job）。
+- GitHub Actions `publish.yml`：新版本進到 `master` 時，透過 Trusted Publishing 自動發佈到 RubyGems。
+- CLAUDE.md 加入發版規則。
+
+### Changed
+
+- 移除每個 gemfile 各自的舊 lockfile，這些 lockfile 會讓 CI 在較舊的 Ruby 上失敗。
+
+## [1.2.0] - 2026-01-08
+
+### Added
+
+- 新增 Ruby 3.2 與 3.3 的測試 gemfile（`ruby_3.2_rails_7.0`、`ruby_3.2_rails_7.1`、`ruby_3.3_rails_7.1`）與 CI job。
+
+### Changed
+
+- gemspec 的 `required_ruby_version` 上限由 `< 3.2.0` 提高到 `< 3.4.0`。
+
+## [1.1.2] - 2026-01-07
+
+### Changed
+
+- 更新各 gemfile 的 lockfile。
+
+## [1.1.1] - 2026-01-07
+
+### Added
+
+- 多版本 Ruby / Rails 測試環境：每個版本各自的 gemfile、GitHub Actions 矩陣、`bin/test_all`、`bin/check_dependencies` 與 `TESTING.md`。
+
+### Fixed
+
+- 測試不再依賴寫死的 macOS 路徑。
+
+## [1.1.0] - 2023-02-02
+
+### Changed
+
+- 修正並微調 XLSX exporter（`ExportTo::Exporter::Xlsx`）。
+
+## [1.0.0] - 2023-02-02
+
+### Changed
+
+- 內部改寫：匯出邏輯移到 `ExportTo::Exporter::Csv` / `Xls` / `Xlsx`；`ExportTo::Base` 提供 `to_csv`、`to_xlsx` 與 `to_xls`。
+- `activesupport` 限制為 `>= 6, < 7`；開發相依套件放寬為 `bundler >= 2.0`、`rake >= 13`。
+
+## [0.1.2] - 2019-06-19
+
+### Changed
+
+- CSV 輸出現在會強制幫每個欄位加上引號。
+
+## [0.1.1] - 2018-12-05
+
+### Fixed
+
+- 修正匯出時出現 "File exists" 的 bug。
+
+## [0.1.0] - 2018-10-21
+
+### Added
+
+- 首次發佈：`ExportTo::Base` DSL（`set`、`joins`、`presenter`、`each_with`）、帶有列計數器的 presenter、空的 join relation 處理，以及 `to_xlsx`。
+
+[Unreleased]: https://github.com/superlanding/export_to/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/superlanding/export_to/compare/v1.2.1...v1.3.0
+[1.2.1]: https://github.com/superlanding/export_to/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/superlanding/export_to/compare/v1.1.2...v1.2.0
+[1.1.2]: https://github.com/superlanding/export_to/compare/v1.1.1...v1.1.2
+[1.1.1]: https://github.com/superlanding/export_to/releases/tag/v1.1.1
+[1.1.0]: https://github.com/superlanding/export_to/commit/48957da
+[1.0.0]: https://github.com/superlanding/export_to/commit/8d7f937
+[0.1.2]: https://github.com/superlanding/export_to/commit/d276482
+[0.1.1]: https://github.com/superlanding/export_to/commit/12dd5c1
+[0.1.0]: https://github.com/superlanding/export_to/commit/d605bf9

data/CLAUDE.md

@@ -7,3 +7,15 @@
 - 跳版規則（Semantic Versioning）：修 bug 跳 patch（x.y.Z）；新增相容功能跳 minor（x.Y.0）；不相容變更跳 major（X.0.0）。
 - 版號只改在 PR 裡。AI 帳號只能開 branch 與 PR，不得合併到 master；只有真人帳號可以合併。合併就等於批准發佈。
 - 不得為了讓測試通過而改變程式原本的行為。
+
+## 文件與更新紀錄（README / CHANGELOG）
+
+- **每一個 PR 都必須同步更新文件**：
+  - 只要行為、用法、設定、相依套件或支援的 Ruby / Rails 版本有變，就要更新 `README.md`。
+  - 一律要在 `CHANGELOG.md` 新增一筆條目（[Keep a Changelog](https://keepachangelog.com/zh-TW/1.1.0/) 格式，分類用 Added / Changed / Deprecated / Removed / Fixed / Security）。
+- **語言規則**：`README.md` 與 `CHANGELOG.md` 一律用繁體中文（zh-TW，台灣用語）撰寫；程式碼、識別字（class / 方法 / 變數名稱）、指令、檔名與路徑維持英文，不要翻譯。
+- `CHANGELOG.md` 的寫法：
+  - 沒有跳版號的 PR：寫在最上方的 `## [Unreleased]` 底下。
+  - 有跳版號的 PR：把條目寫在新的版本章節 `## [x.y.z] - YYYY-MM-DD`（日期為合併日），並同步更新檔尾的版本比較連結。
+  - 版本號必須與 rubygems.org 上實際發佈的版本一致，不得寫還沒發佈的版本。
+- 只改文件、CI 或 CLAUDE.md 的 PR 不需要跳版號，但仍要在 `CHANGELOG.md` 的 `Unreleased` 補一筆。

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    export_to (1.2.1)
+    export_to (1.3.0)
       activesupport (>= 6.0, < 8.2)
       csv
       fast_excel (~> 0.4)

data/README.md

@@ -1,64 +1,156 @@
 # ExportTo
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/export_to`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Gem Version](https://badge.fury.io/rb/export_to.svg)](https://rubygems.org/gems/export_to)
+[![CI](https://github.com/superlanding/export_to/actions/workflows/ci.yml/badge.svg)](https://github.com/superlanding/export_to/actions/workflows/ci.yml)
 
-TODO: Delete this and the text above, and describe your gem
+用一套簡單的宣告式 DSL，把一批資料（ActiveRecord relation、Struct 陣列，或任何有 `each` 的物件）匯出成 **CSV** 或 **XLSX**（透過較底層的 exporter，也能匯出舊版 **XLS**）。
 
-## Installation
+你只要在 `ExportTo::Base` 的子類別裡宣告一次欄位（標題、來源屬性、寬度、格式、值的轉換），需要計算欄位時可以加上 presenter，也可以加上 `joins` relation 把一筆資料展開成多列，最後呼叫 `to_csv` / `to_xlsx` 即可。
 
-Add this line to your application's Gemfile:
+## 環境需求
+
+| Ruby | CI 測試的 Rails / ActiveSupport 版本 |
+|------|------------------------------------|
+| 2.7  | 6.1 |
+| 3.0  | 6.1, 7.0 |
+| 3.1  | 6.1, 7.0, 7.1 |
+| 3.2  | 7.0, 7.1 |
+| 3.3  | 7.1, 8.0, 8.1 |
+| 3.4  | 8.0, 8.1 |
+
+gemspec 要求 Ruby `>= 2.7.0` 與 `activesupport >= 6.0, < 8.2`。實際支援範圍以 [`.github/workflows/ci.yml`](.github/workflows/ci.yml) 為準。
+
+Runtime 相依套件：`fast_excel`（XLSX）、`spreadsheet`（XLS）、`csv`、`iconv`、`activesupport`。
+
+## 安裝
+
+在應用程式的 Gemfile 加入這一行：
 
 ```ruby
-gem 'export_to'
+gem "export_to"
 ```
 
-And then execute:
+然後執行：
 
-    $ bundle
+```bash
+bundle install
+```
 
-Or install it yourself as:
+或自行執行 `gem install export_to` 安裝。
 
-    $ gem install export_to
+## 使用方式
 
-## Usage
+### 1. 定義 exporter
 
-TODO: Write usage instructions here
+```ruby
+class UserExport < ExportTo::Base
+  # set <標題>, <key>, <欄位選項>, &可選的轉換 block
+  set "Name",   :full_name, width: 30
+  set "Mobile", :mobile,    width: 20, format: { bold: true }
+  set "Amount", :amount,    width: 12 do |value|
+    value + 100                    # block 會收到儲存格的值，並回傳最終要輸出的值
+  end
+  set "Source", "web"              # key 為 String 時，每一列都會寫入這個固定值
+
+  excel worksheet: "Users", height: 24   # 可選的 XLSX 設定（工作表名稱、列高）
+
+  presenter do                     # 可選：計算欄位
+    def full_name
+      "#{first_name} #{last_name}" # 找不到的方法會委派給該筆 record
+    end
+
+    def amount
+      relation? ? relation.amount : 0
+    end
+  end
+
+  joins :wallets                   # 可選：record.wallets 裡每一筆各佔一列
+end
+```
 
-## Ruby & Rails Version Support
+- **`set(title, key, options = {}, &block)`**：每次呼叫新增一個欄位，依呼叫順序排列。
+  - `key` 為 **Symbol** 時，會從 presenter 讀取（presenter 會委派給 record）；`nil` 會變成 `""`。
+  - `key` 為 **String** 時，直接當作固定內容使用。
+  - XLSX 專用的 `options`：`width:`（欄寬）與 `format:`（`FastExcel` 的 format hash，例如 `{ bold: true }`）。
+  - 可選的 block 用來後處理儲存格的值。
+- **`excel(worksheet: "Name", height: 20)`**：工作表名稱（預設 `"Default"`）與資料列的列高（預設 `20`）。標題列為粗體、置中並帶有背景色。
+- **`presenter { ... }`**：定義 `YourExport::Presenter`（是上層 exporter 的 presenter 的子類別）。在裡面可以使用 `model`、`relation`、`relation?`、`x`（record 的索引）與 `y`（`joins` relation 內的索引）。
+- **`joins(:relation_name)`**：當 `record.relation_name` 有資料時，每個元素各自成為一列，且 `relation` 就是該元素；presenter 會先找 `relation` 上的方法，找不到再找 `model`。relation 為空的 record 會產生單獨一列（此時 `relation?` 為 `false`）。
+- **`each_with { |presenter| ... }`**：hook，會在讀取各欄位之前，以每一列的 presenter 呼叫一次。
+- **`self.each_method = :find_in_batches`**：改用 `records.find_in_batches` 而不是 `records.each` 來迭代，適合很大的 ActiveRecord relation。
 
-This gem supports:
-- Ruby 2.7 with Rails 6.1
-- Ruby 3.0 with Rails 6.1, 7.0
-- Ruby 3.1 with Rails 6.1, 7.0, 7.1
-- Ruby 3.2 with Rails 7.0, 7.1
-- Ruby 3.3 with Rails 7.1
+### 2. 匯出
 
-## Development
+```ruby
+users  = User.includes(:wallets).where(active: true)   # 或任何可列舉的物件
+export = UserExport.new(users)
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+export.to_csv    # => String，每個欄位都有加引號（"Name","Mobile",...）
+export.to_xlsx   # => .xlsx 檔案的二進位 String
+export.each      # => 所有列組成的 Array，第一列是標題列：[["Name", "Mobile", ...], ["Eddie Li", ...], ...]
+export.each { |columns| ... }   # 逐列 yield（第一列是標題列），並回傳 exporter 本身；Enumerable 方法也能用
+```
 
-### Testing Multiple Ruby Versions
+兩位使用者的 CSV 輸出範例（第二位有兩個 wallet）：
 
-To test against all supported Ruby versions at once:
+```
+"Name","Mobile","Amount","Source"
+"Eddie Li","+8869","100","web"
+"Vegeta Lu","+8868","1100","web"
+"Vegeta Lu","+8868","2100","web"
+```
+
+在 Rails controller 裡提供下載：
+
+```ruby
+def export
+  send_data UserExport.new(User.all).to_xlsx,
+            filename: "users.xlsx",
+            type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+end
+```
+
+### 已知限制
+
+以下是目前程式碼的實際行為：
+
+- `ExportTo::Base#to_xls` **已棄用，而且名稱有誤導性**：自 1.0.0 起它回傳的是與 `#to_xlsx` 相同的 **XLSX** 資料（不是舊版 `.xls` 檔）。保留這個行為是為了不讓既有呼叫端壞掉；呼叫時會印出一次性的 `[DEPRECATION]` 警告。請改用 `#to_xlsx`。若需要真正的舊版 `.xls` 檔，請用 `ExportTo::Exporter::Xls.new(export).to_xls`（不會套用任何樣式選項）。
+- `width:` / `format:` 與 `excel` 選項只對 XLSX 輸出有效。
+- 子類別會共用上層 class 的欄位定義陣列（`class_attribute`），所以如果某個 exporter 本身也會單獨使用，就不要在它的子類別裡呼叫 `set`。
+
+## 開發
+
+clone 下來之後，先執行 `bin/setup` 安裝相依套件，接著跑測試：
 
 ```bash
-bin/test_all
+bundle exec rake test        # 也可以用 rake t / rake（預設 task）
+bin/console                  # 互動式 console
 ```
 
-To check dependency compatibility:
+每個 Ruby / Rails 組合在 `gemfiles/` 內都有各自的 gemfile（CI 會把 `BUNDLE_GEMFILE` 指到它）：
 
 ```bash
-bin/check_dependencies
+BUNDLE_GEMFILE=$PWD/gemfiles/ruby_3.4_rails_8.1.gemfile bundle install
+BUNDLE_GEMFILE=$PWD/gemfiles/ruby_3.4_rails_8.1.gemfile bundle exec rake test
 ```
 
-For more detailed testing instructions, see [TESTING.md](TESTING.md).
+`bin/test_all` 會跑過所有支援的 Ruby 版本（需要 rbenv 或 rvm），`bin/check_dependencies` 會檢查相依套件的相容性；詳見 [TESTING.md](TESTING.md)。
+
+## 發版
+
+發版透過 RubyGems [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) 自動完成（repo 內不存放任何 API key）：
+
+1. 在你的 PR 裡修改 `lib/export_to/version.rb` 的 `ExportTo::VERSION`（遵循 [Semantic Versioning](https://semver.org/lang/zh-TW/)：修 bug 跳 patch、相容的新功能跳 minor、不相容的變更跳 major）。
+2. 在 `CHANGELOG.md` 新增對應的 `## [x.y.z] - YYYY-MM-DD` 區塊。
+3. 由真人 review 後合併進 `master`（AI 帳號只能開 PR）。
+4. [`.github/workflows/publish.yml`](.github/workflows/publish.yml) 會在 `master` 上執行：如果 gemspec 的版本還沒上 rubygems.org，就執行 `rake release`（打包 gem、打 `vX.Y.Z` tag、發佈）。沒有跳版號的合併不會發佈任何東西。
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+只改文件 / CI 的 PR 不需要跳版號。請見 [CLAUDE.md](CLAUDE.md)：每個 PR 也都必須更新 `README.md`（行為或用法有變時）並在 `CHANGELOG.md` 新增一筆條目。
 
-## Contributing
+## 貢獻
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/superlanding/export_to.
+歡迎到 GitHub 回報問題與提交 pull request：https://github.com/superlanding/export_to。
 
-## License
+## 授權
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+本 gem 以 [MIT License](https://opensource.org/licenses/MIT) 條款開源。

data/TESTING.md

@@ -1,103 +1,45 @@
 # Testing Guide
 
-This gem supports multiple Ruby and Rails versions:
-- Ruby 2.7 with Rails 6.1
-- Ruby 3.0 with Rails 6.1, 7.0
-- Ruby 3.1 with Rails 6.1, 7.0, 7.1
+Tests use Minitest + shoulda-context (`test/**/*_test.rb`) and run against several Ruby / Rails combinations.
 
-## Multi-Version Testing
+The supported matrix is defined in **one place**: [`.github/workflows/ci.yml`](.github/workflows/ci.yml). Each combination has a gemfile `gemfiles/ruby_<ruby>_rails_<rails>.gemfile`. Lists of versions are intentionally not copied here so they cannot go stale; see the [README](README.md#requirements) for the current table.
 
-### Local Testing
+## Run the tests for one combination
 
-#### Test all Ruby versions at once
-
-Run the test suite against all supported Ruby versions:
+CI selects the gemfile with `BUNDLE_GEMFILE`; do the same locally (switch to the matching Ruby first, e.g. with rbenv):
 
 ```bash
-bin/test_all
+export BUNDLE_GEMFILE=$PWD/gemfiles/ruby_3.4_rails_8.1.gemfile
+bundle install
+bundle exec rake test       # also: rake t / rake
 ```
 
-This script will:
-- Automatically switch between Ruby versions (requires rbenv or rvm)
-- Install dependencies for each version
-- Run the test suite for each version
-- Display a summary of results
-
-#### Test a specific Ruby/Rails version combination
+## Run the whole CI matrix locally
 
 ```bash
-# Ruby 2.7 with Rails 6.1
-export BUNDLE_GEMFILE=gemfiles/ruby_2.7_rails_6.1.gemfile
-bundle install
-bundle exec rake test
-
-# Ruby 3.0 with Rails 6.1
-export BUNDLE_GEMFILE=gemfiles/ruby_3.0_rails_6.1.gemfile
-bundle install
-bundle exec rake test
-
-# Ruby 3.0 with Rails 7.0
-export BUNDLE_GEMFILE=gemfiles/ruby_3.0_rails_7.0.gemfile
-bundle install
-bundle exec rake test
-
-# Ruby 3.1 with Rails 7.1
-export BUNDLE_GEMFILE=gemfiles/ruby_3.1_rails_7.1.gemfile
-bundle install
-bundle exec rake test
+bin/test_all
 ```
 
-### Dependency Checking
+`bin/test_all` needs rbenv or rvm. For every entry of its `TEST_MATRIX` (kept equal to the CI matrix) it switches to the newest installed patch version of that Ruby, runs `bundle install` with the matching gemfile, runs `rake test` and prints a summary. A Ruby that is not installed is reported as a failure. When you change `ci.yml`, update `TEST_MATRIX` in `bin/test_all` as well.
 
-Check if all dependencies are compatible with all Ruby versions:
+## Check dependencies
 
 ```bash
 bin/check_dependencies
 ```
 
-This script will verify that all dependencies can be installed and will report any outdated gems.
-
-## CI/CD
-
-The gem uses GitHub Actions for continuous integration. Every push and pull request will automatically test against all supported combinations:
-- Ruby 2.7 / Rails 6.1
-- Ruby 3.0 / Rails 6.1, 7.0
-- Ruby 3.1 / Rails 6.1, 7.0, 7.1
-
-See `.github/workflows/ci.yml` for the full configuration.
-
-## Gemfiles Structure
-
-The `gemfiles/` directory contains version-specific Gemfiles for each Ruby/Rails combination:
-- `ruby_2.7_rails_6.1.gemfile` - Ruby 2.7 with Rails 6.1
-- `ruby_3.0_rails_6.1.gemfile` - Ruby 3.0 with Rails 6.1
-- `ruby_3.0_rails_7.0.gemfile` - Ruby 3.0 with Rails 7.0
-- `ruby_3.1_rails_6.1.gemfile` - Ruby 3.1 with Rails 6.1
-- `ruby_3.1_rails_7.0.gemfile` - Ruby 3.1 with Rails 7.0
-- `ruby_3.1_rails_7.1.gemfile` - Ruby 3.1 with Rails 7.1
+Verifies that the dependencies can be installed for the supported versions and reports outdated gems.
 
-Each gemfile has its own lockfile committed to the repository to ensure consistent dependency versions across environments.
+## Adding a Ruby / Rails combination
 
-## Requirements
+1. Add `gemfiles/ruby_<ruby>_rails_<rails>.gemfile` (copy a neighbouring one and change the `activesupport` / `railties` versions).
+2. Add the combination to the matrix in `.github/workflows/ci.yml` and to `TEST_MATRIX` in `bin/test_all`.
+3. Update the table in the README.
 
-### For Local Multi-Version Testing
+## Lockfiles
 
-You need either:
-- **rbenv** with Ruby 2.7, 3.0, and 3.1 installed
-- **rvm** with Ruby 2.7, 3.0, and 3.1 installed
+Some gemfiles have a committed `*.gemfile.lock`, and `Gemfile.lock` is committed too. They contain the gem's own version (`export_to (x.y.z)`), so **keep them consistent: bump the version in those files whenever `lib/export_to/version.rb` changes**.
 
-### Installing Ruby Versions
+## CI
 
-#### Using rbenv:
-```bash
-rbenv install 2.7.8
-rbenv install 3.0.6
-rbenv install 3.1.4
-```
-
-#### Using rvm:
-```bash
-rvm install 2.7.8
-rvm install 3.0.6
-rvm install 3.1.4
-```
+GitHub Actions runs every matrix entry on every push to `master` and on every pull request that targets `master`.

data/bin/test_all

@@ -6,13 +6,22 @@
 set -e
 
 # Define test matrix: ruby_version:rails_version
+# Keep in sync with the matrix in .github/workflows/ci.yml (and gemfiles/).
+# ruby_version is "major.minor"; the newest installed patch version is used.
 TEST_MATRIX=(
-  "2.7.6:6.1"
-  "3.0.7:6.1"
-  "3.0.7:7.0"
-  "3.1.7:6.1"
-  "3.1.7:7.0"
-  "3.1.7:7.1"
+  "2.7:6.1"
+  "3.0:6.1"
+  "3.0:7.0"
+  "3.1:6.1"
+  "3.1:7.0"
+  "3.1:7.1"
+  "3.2:7.0"
+  "3.2:7.1"
+  "3.3:7.1"
+  "3.3:8.0"
+  "3.3:8.1"
+  "3.4:8.0"
+  "3.4:8.1"
 )
 
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
@@ -60,13 +69,14 @@ for test_case in "${TEST_MATRIX[@]}"; do
 
   # Set Ruby version
   if [ "$RUBY_MANAGER" == "rbenv" ]; then
-    if ! rbenv versions | grep -q "^[* ]*${ruby_version}"; then
+    installed_version="$(rbenv versions --bare | grep -E "^${ruby_version//./\\.}\\." | sort -V | tail -n 1)"
+    if [ -z "${installed_version}" ]; then
       echo -e "${RED}Ruby ${ruby_version} not installed in rbenv. Skipping...${NC}"
       FAILED=$((FAILED + 1))
       FAILED_TESTS+=("Ruby ${ruby_version} / Rails ${rails_version} (Ruby not installed)")
       continue
     fi
-    export RBENV_VERSION="${ruby_version}"
+    export RBENV_VERSION="${installed_version}"
   elif [ "$RUBY_MANAGER" == "rvm" ]; then
     if ! rvm list | grep -q "ruby-${ruby_version}"; then
       echo -e "${RED}Ruby ${ruby_version} not installed in rvm. Skipping...${NC}"

data/gemfiles/ruby_3.1_rails_7.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    export_to (1.2.1)
+    export_to (1.3.0)
       activesupport (>= 6.0, < 8.2)
       csv
       fast_excel (~> 0.4)

data/gemfiles/ruby_3.3_rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    export_to (1.2.1)
+    export_to (1.3.0)
       activesupport (>= 6.0, < 8.2)
       csv
       fast_excel (~> 0.4)

data/gemfiles/ruby_3.3_rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    export_to (1.2.1)
+    export_to (1.3.0)
       activesupport (>= 6.0, < 8.2)
       csv
       fast_excel (~> 0.4)

data/gemfiles/ruby_3.4_rails_8.0.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    export_to (1.2.1)
+    export_to (1.3.0)
       activesupport (>= 6.0, < 8.2)
       csv
       fast_excel (~> 0.4)
@@ -183,7 +183,7 @@ CHECKSUMS
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   erb (6.0.7) sha256=c5ca6dc25b0ef974a44dc8f59fe847577122483b1968a38dec305c60bf91ee92
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
-  export_to (1.2.1)
+  export_to (1.3.0)
   fast_excel (0.5.0) sha256=59c418bdcf586a6030798d4e3a9f575742badaceaf7bb90f38eee5feb5bdc478
   ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
   ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39

data/gemfiles/ruby_3.4_rails_8.1.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    export_to (1.2.1)
+    export_to (1.3.0)
       activesupport (>= 6.0, < 8.2)
       csv
       fast_excel (~> 0.4)
@@ -182,7 +182,7 @@ CHECKSUMS
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   erb (6.0.7) sha256=c5ca6dc25b0ef974a44dc8f59fe847577122483b1968a38dec305c60bf91ee92
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9
-  export_to (1.2.1)
+  export_to (1.3.0)
   fast_excel (0.5.0) sha256=59c418bdcf586a6030798d4e3a9f575742badaceaf7bb90f38eee5feb5bdc478
   ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
   ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39

data/lib/export_to/base.rb

@@ -25,17 +25,25 @@ module ExportTo
       ExportTo::Exporter::Xlsx.new(self).export
     end
 
-    # 舊版 Excel
+    # 注意：名稱叫 xls，但自 1.0.0 起實際回傳的是 XLSX 內容（與 #to_xlsx 相同），
+    # 為了不破壞既有呼叫端，行為維持不變，僅在第一次呼叫時印出 deprecation 警告。
+    # 請改用 #to_xlsx；需要真正的舊版 .xls 請用 ExportTo::Exporter::Xls.new(export).to_xls
     def to_xls
-      ExportTo::Exporter::Xlsx.new(self).export
+      self.class.warn_to_xls_deprecated(caller_locations(1, 1).first)
+      to_xlsx
     end
 
+    # 回傳所有列（第一列是表頭）的二維陣列，與 CSV / XLSX 看到的內容一致。
+    # 給 block 時逐列 yield columns 並回傳 self（Enumerable 的方法因此可用）。
     def each
       data = []
-      rows! do |columns, model, x|
+      each! do |columns, _model, _index|
         data.push(columns)
       end
-      data
+      return data unless block_given?
+
+      data.each { |columns| yield(columns) }
+      self
     end
 
     def each!
@@ -92,6 +100,16 @@ module ExportTo
     end
 
     class << self
+      # to_xls 只警告一次（每個 process），避免洗版 log
+      def warn_to_xls_deprecated(location = nil)
+        return if Base.to_xls_warned
+        Base.to_xls_warned = true
+        where = location ? " (called from #{location})" : ""
+        Kernel.warn "[DEPRECATION] ExportTo::Base#to_xls returns XLSX data, not a legacy .xls file; " \
+                    "use #to_xlsx instead. #to_xls keeps this behavior for compatibility#{where}."
+      end
+
+      attr_accessor :to_xls_warned
 
       protected
 

data/lib/export_to/version.rb

@@ -1,3 +1,3 @@
 module ExportTo
-  VERSION = "1.2.1"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: export_to
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - eddie
@@ -152,6 +152,7 @@ files:
 - ".github/workflows/publish.yml"
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - CLAUDE.md
 - Gemfile
 - Gemfile.lock