comma 4.9.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebf4796fc5d10dd1af410b86168ed9bce3083bd8182606000062ef572771d0a8
-  data.tar.gz: d3b8bfbe4556b3954e3d1205dcff81390b9491546581771d0cfb1862df3fc45b
+  metadata.gz: ce045c478a147d8f8cf10cb1228ba6ba810b459ad61cfccd9b91f4029dad9c73
+  data.tar.gz: 75da1697c5e08af1a1bae4567780d2b9e0a535de873b910f6760479be5a3b519
 SHA512:
-  metadata.gz: a365b5fa5f0e9ae46dfb0ac321fd1e4838589fd162ae16fb21e9262ac7e367c0d99031a52e5c8f02259bdf9e38f82ee72dd5b3e498c9ee90e8de4aed6073e6c6
-  data.tar.gz: dd02d4b771ea4139820ba98b6f99d0d4fe2ff6626fade1d47e4190c5d6640d06079347195b4c224a499b2cc8c380a74261d1e0b292c59a98d50a1e3583927397
+  metadata.gz: d921a85f27d283ad74aba9a0996daa982af4ad3cf6599a1a473234b50fe25e9e5224cca78315de35aa52a1a88610beb172ae514e35f8f0c8abd162ab334c24c5
+  data.tar.gz: 81e45224e2949885afaa99859391c229358163b1ce840ff57b900bb13ac1f3d71b0b54f3b4dfbc4d4ee54ae5e945f15b1dc1bd7a788998028fc45b01e84ee49c

data/.github/copilot-instructions.md

@@ -0,0 +1,56 @@
+# Copilot instructions for `comma`
+
+## Build, test, and lint commands
+
+This repository is a Ruby gem. Ruby 3.0+ is required, and the CI matrix exercises Ruby 3.0-3.4 against Rails/ActiveRecord appraisals from 6.0 through 7.1.
+
+```sh
+# install dependencies for the base Gemfile
+bundle install
+
+# install all appraisal Gemfiles used by CI
+bundle exec appraisal install
+
+# build the gem
+bundle exec rake build
+
+# lint
+bundle exec rubocop -P
+# or
+bundle exec rake rubocop
+
+# base test suite (runs non-Rails specs when framework gems are absent)
+bundle exec rspec spec
+# or
+bundle exec rake spec
+
+# run one example from the base suite
+bundle exec rspec spec/comma/comma_spec.rb:205
+
+# run the full multi-gemfile matrix locally
+bundle exec appraisal rake spec
+
+# run a single spec file under a specific appraisal
+bundle exec appraisal active7.1.3 bundle exec rspec spec/comma/rails/active_record_spec.rb
+
+# CI equivalent for a single matrix entry
+BUNDLE_GEMFILE=gemfiles/rails7.1.3.gemfile bundle exec rspec spec/controllers/users_controller_spec.rb
+```
+
+## High-level architecture
+
+- `lib/comma/object.rb` adds the core DSL globally via `Object.comma`. Each class stores named format blocks in `comma_formats`, and subclasses inherit a shallow copy of those formats.
+- `lib/comma/extractor.rb` is the shared execution engine. It `instance_eval`s a stored format block and collects stringified results. The two concrete extractors split responsibilities:
+  - `lib/comma/data_extractor.rb` resolves values from the instance or an associated object and applies optional block-based transformations.
+  - `lib/comma/header_extractor.rb` derives headers from the same DSL and can map association columns to the associated model class for humanized labels.
+- `lib/comma/generator.rb` is the only place that turns object rows into CSV output. `Array`, `ActiveRecord::Relation`, `Mongoid::Criteria`, and `DataMapper::Collection` each delegate to it from their own extension files.
+- `lib/comma.rb` wires framework integrations lazily with `ActiveSupport.on_load`. That file is also where the Rails `render csv:` renderer is registered, so controller behavior is part of the gem's load path rather than test-only glue.
+- Integration specs use the miniature app under `spec/rails_app/` plus inline model definitions inside spec files. The base suite still runs without Rails, Mongoid, DataMapper, or ActiveRecord because integration examples are wrapped in `if defined?(...)` guards in the specs.
+
+## Key conventions
+
+- The CSV DSL is method-call driven. Inside a `comma` block, a bare method adds one column, a string argument overrides the header label, and symbol/hash arguments traverse associations. The same block definition drives both headers and row data.
+- Style composition uses `__use__ :style_name`, and computed/static columns use `__static_column__`. Preserve those internal DSL entry points when changing extractor behavior.
+- Header labels default to `HeaderExtractor.value_humanizer`, which is mutable global state. Specs that override it reset it afterward; follow the same pattern for any future changes.
+- `ActiveRecord::Relation#to_comma` intentionally uses `find_each` only for unordered, unlimited relations. If a relation has `limit` or `order`, it falls back to `each`; when Rails is loaded it also emits a warning instead of forcing batched iteration.
+- Specs commonly define throwaway classes inline to document DSL behavior instead of introducing fixtures or helper classes. Prefer extending the existing focused examples in `spec/comma/*` unless a change genuinely needs the Rails test app.

data/.github/workflows/build.yml

@@ -5,12 +5,21 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.0', '3.1', '3.2', '3.3', '3.4']
-        gemfile: ['active6.0.6', 'active6.1.7.6', 'active7.0.8', 'active7.1.3', 'rails6.0.6', 'rails6.1.7.6', 'rails7.0.8', 'rails7.1.3']
+        ruby: ['3.1', '3.2', '3.3', '3.4', '4.0']
+        gemfile: ['active7.1.6', 'active7.2.3.2', 'active8.0.5.1', 'active8.1.3.1', 'rails7.1.6', 'rails7.2.3.2', 'rails8.0.5.1', 'rails8.1.3.1']
+        exclude:
+          - ruby: '3.1'
+            gemfile: 'active8.0.5.1'
+          - ruby: '3.1'
+            gemfile: 'active8.1.3.1'
+          - ruby: '3.1'
+            gemfile: 'rails8.0.5.1'
+          - ruby: '3.1'
+            gemfile: 'rails8.1.3.1'
     runs-on: ubuntu-latest
     env:
       BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
-      BUNDLE_FORCE_RUBY_PLATFORM: ${{ matrix.ruby == '3.4' }}
+      BUNDLE_FORCE_RUBY_PLATFORM: ${{ matrix.ruby == '3.4' || matrix.ruby == '4.0' }}
       RUBY_OPT: --disable=did_you_mean
     services:
       mongodb:

data/.rubocop_todo.yml

@@ -55,7 +55,6 @@ Layout/SpaceAroundMethodCallOperator:
 # AllowedMethods: enums
 Lint/ConstantDefinitionInBlock:
   Exclude:
-    - 'spec/comma/comma_spec.rb'
     - 'spec/comma/rails/active_record_spec.rb'
     - 'spec/comma/rails/data_mapper_collection_spec.rb'
     - 'spec/comma/rails/mongoid_spec.rb'
@@ -108,13 +107,14 @@ Style/BlockDelimiters:
     - 'spec/comma/data_extractor_spec.rb'
     - 'spec/comma/header_extractor_spec.rb'
 
-# Offense count: 11
+# Offense count: 12
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
     - 'lib/comma/array.rb'
+    - 'lib/comma/collection_export.rb'
     - 'lib/comma/data_extractor.rb'
     - 'lib/comma/data_mapper_collection.rb'
     - 'lib/comma/extractor.rb'
@@ -122,13 +122,14 @@ Style/Documentation:
     - 'lib/comma/header_extractor.rb'
     - 'lib/comma/mongoid.rb'
     - 'lib/comma/object.rb'
+    - 'lib/comma/options.rb'
     - 'lib/comma/relation.rb'
 
-# Offense count: 3
+# Offense count: 2
 Style/MissingRespondToMissing:
   Exclude:
     - 'lib/comma/data_extractor.rb'
-    - 'lib/comma/header_extractor.rb'
+    - 'lib/comma/extractor.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).

data/Appraisals

@@ -1,43 +1,41 @@
 # frozen_string_literal: true
 
-appraise 'rails6.0.6' do
-  gem 'rails', '6.0.6'
+appraise 'rails7.1.6' do
+  gem 'rails', '7.1.6'
   gem 'rspec-rails'
-  gem 'test-unit'
 end
 
-appraise 'active6.0.6' do
-  gem 'activesupport', '6.0.6'
-  gem 'activerecord', '6.0.6'
+appraise 'active7.1.6' do
+  gem 'activesupport', '7.1.6'
+  gem 'activerecord', '7.1.6'
 end
 
-appraise 'rails6.1.7.6' do
-  gem 'rails', '6.1.7.6'
+appraise 'rails7.2.3.2' do
+  gem 'rails', '7.2.3.2'
   gem 'rspec-rails'
-  gem 'test-unit'
 end
 
-appraise 'active6.1.7.6' do
-  gem 'activesupport', '6.1.7.6'
-  gem 'activerecord', '6.1.7.6'
+appraise 'active7.2.3.2' do
+  gem 'activesupport', '7.2.3.2'
+  gem 'activerecord', '7.2.3.2'
 end
 
-appraise 'rails7.0.8' do
-  gem 'rails', '7.0.8'
+appraise 'rails8.0.5.1' do
+  gem 'rails', '8.0.5.1'
   gem 'rspec-rails'
 end
 
-appraise 'active7.0.8' do
-  gem 'activesupport', '7.0.8'
-  gem 'activerecord', '7.0.8'
+appraise 'active8.0.5.1' do
+  gem 'activesupport', '8.0.5.1'
+  gem 'activerecord', '8.0.5.1'
 end
 
-appraise 'rails7.1.3' do
-  gem 'rails', '7.1.3'
+appraise 'rails8.1.3.1' do
+  gem 'rails', '8.1.3.1'
   gem 'rspec-rails'
 end
 
-appraise 'active7.1.3' do
-  gem 'activesupport', '7.1.3'
-  gem 'activerecord', '7.1.3'
+appraise 'active8.1.3.1' do
+  gem 'activesupport', '8.1.3.1'
+  gem 'activerecord', '8.1.3.1'
 end

data/Gemfile.lock

@@ -1,33 +1,37 @@
 PATH
   remote: .
   specs:
-    comma (4.9.0)
+    comma (5.1.0)
       activesupport (>= 4.2.0)
       csv (>= 3.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (7.1.3)
-      activesupport (= 7.1.3)
-    activesupport (7.1.3)
+    activemodel (7.2.3.1)
+      activesupport (= 7.2.3.1)
+    activesupport (7.2.3.1)
       base64
+      benchmark (>= 0.3)
       bigdecimal
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+      concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
-      minitest (>= 5.1)
-      mutex_m
-      tzinfo (~> 2.0)
+      logger (>= 1.4.2)
+      minitest (>= 5.1, < 6)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
     appraisal (1.0.3)
       bundler
       rake
       thor (>= 0.14.0)
     ast (2.4.2)
     base64 (0.3.0)
+    benchmark (0.5.0)
     bigdecimal (4.1.2)
-    concurrent-ruby (1.3.6)
+    cgi (0.3.7)
+    concurrent-ruby (1.3.7)
     connection_pool (2.5.5)
     coveralls (0.8.23)
       json (>= 1.8, < 3)
@@ -42,9 +46,11 @@ GEM
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     json (2.7.1)
-    mini_portile2 (2.8.5)
-    minitest (5.14.4)
+    logger (1.7.0)
+    mini_portile2 (2.8.9)
+    minitest (5.27.0)
     mutex_m (0.3.0)
+    ostruct (0.5.2)
     parallel (1.24.0)
     parser (3.3.0.4)
       ast (~> 2.4.1)
@@ -54,26 +60,26 @@ GEM
     rake (13.0.1)
     regexp_parser (2.9.0)
     rexml (3.4.2)
-    rspec (3.5.0)
-      rspec-core (~> 3.5.0)
-      rspec-expectations (~> 3.5.0)
-      rspec-mocks (~> 3.5.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
     rspec-activemodel-mocks (1.1.0)
       activemodel (>= 3.0)
       activesupport (>= 3.0)
       rspec-mocks (>= 2.99, < 4.0)
-    rspec-core (3.5.2)
-      rspec-support (~> 3.5.0)
-    rspec-expectations (3.5.0)
+    rspec-core (3.13.1)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
+      rspec-support (~> 3.13.0)
     rspec-its (1.2.0)
       rspec-core (>= 3.0.0)
       rspec-expectations (>= 3.0.0)
-    rspec-mocks (3.5.0)
+    rspec-mocks (3.13.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.5.0)
-    rspec-support (3.5.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
     rubocop (1.30.1)
       parallel (~> 1.10)
       parser (>= 3.1.0.0)
@@ -89,12 +95,13 @@ GEM
       rubocop (>= 0.90.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
     simplecov (0.16.1)
       docile (~> 1.1)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
-    sqlite3 (1.7.0)
+    sqlite3 (2.8.1)
       mini_portile2 (~> 2.8.0)
     sync (0.5.0)
     term-ansicolor (1.7.1)
@@ -112,14 +119,18 @@ PLATFORMS
 DEPENDENCIES
   appraisal (~> 1.0.0)
   base64
+  benchmark
   bigdecimal
+  cgi
   comma!
   coveralls
   drb
-  minitest (= 5.14.4)
+  logger
+  minitest (= 5.27.0)
   mutex_m
+  ostruct
   rake (~> 13.0.1)
-  rspec (~> 3.5.0)
+  rspec (~> 3.13)
   rspec-activemodel-mocks
   rspec-its
   rubocop (~> 1.30.0)

data/README.md

@@ -1,6 +1,6 @@
 # Comma
 
-A library to generate comma seperated value (CSV) for Ruby objects like ActiveRecord and Array
+A library for generating comma-separated values (CSV) from Ruby objects, arrays, and supported ORM collections.
 
 [![Gem Version](https://badge.fury.io/rb/comma.svg)](http://badge.fury.io/rb/comma) [![Build Status](https://github.com/comma-csv/comma/actions/workflows/build.yml/badge.svg)](https://github.com/comma-csv/comma/actions/workflows/build.yml) [![Code Climate](https://codeclimate.com/github/comma-csv/comma.svg)](https://codeclimate.com/github/comma-csv/comma)
 
@@ -8,7 +8,9 @@ A library to generate comma seperated value (CSV) for Ruby objects like ActiveRe
 
 ### Prerequisites
 
-You need to use ruby 3.0 or later. If you generate CSV from ActiveRecord models, you need to have ActiveRecord 6.0 or later.
+You need Ruby 3.1 or later.
+
+For Rails / ActiveRecord integration, this repository is currently tested against ActiveRecord and Rails 7.1 and 7.2 on Ruby 3.1 through 4.0, and Rails 8.0 and 8.1 on Ruby 3.2 through 4.0 (Rails 8.x requires Ruby >= 3.2).
 
 ### Installing
 
@@ -17,33 +19,183 @@ Comma is distributed as a gem, best installed via Bundler.
 Include the gem in your Gemfile:
 
 ```ruby
-gem 'comma', '~> 4.8.0'
+gem 'comma', '~> 5.1.0'
 ```
 
 Or, if you want to live life on the edge, you can get master from the main comma repository:
 
 ```ruby
-gem 'comma',  git: 'git://github.com/comma-csv/comma.git'
+gem 'comma', git: 'https://github.com/comma-csv/comma.git'
 ```
 
 Then, run `bundle install`.
 
 ### Usage
 
-See [this page](https://github.com/comma-csv/comma/wiki) for usages.
+Define a CSV format on your object with `comma`. Calling `to_comma` on a single object returns the row values, while calling it on an array or supported collection generates CSV output:
+
+```ruby
+class User
+  attr_reader :first_name, :last_name
+
+  def initialize(first_name, last_name)
+    @first_name = first_name
+    @last_name = last_name
+  end
+
+  comma do
+    first_name
+    last_name
+    full_name 'Name'
+  end
+
+  def full_name
+    "#{first_name} #{last_name}".strip
+  end
+end
+
+user = User.new('Ada', 'Lovelace')
+user.to_comma
+# => ["Ada", "Lovelace", "Ada Lovelace"]
+
+users = [User.new('Ada', 'Lovelace'), User.new('Grace', 'Hopper')]
+users.to_comma
+# => "First name,Last name,Name\nAda,Lovelace,Ada Lovelace\nGrace,Hopper,Grace Hopper\n"
+```
+
+You can also define named styles and select them when generating CSV:
+
+```ruby
+class User
+  comma :short do
+    first_name
+    last_name
+  end
+end
+
+users.to_comma(:short)
+```
+
+### Dynamic columns
+
+Formats are evaluated separately to produce headers and to produce each row. For CSVs whose columns are configured at runtime, resolve and order the full field-definition list before declaring the `comma` format, and keep that format isolated to the current export so another export cannot redefine it midway through generation.
+
+The following self-contained example uses `Struct` rather than Ruby 3.2+'s
+`Data`. It resolves the runtime field list once, attaches the format to a row
+class created only for that export, emits headers from `field.label`, and reads
+each value from the wrapped user's associated dynamic values via `field.key`:
+
+```ruby
+DynamicField = Struct.new(:key, :label)
+DynamicValue = Struct.new(:field_key, :value)
+
+class User
+  attr_reader :name
+
+  def initialize(name, dynamic_values)
+    @name = name
+    @dynamic_values_by_field = dynamic_values.to_h do |value|
+      [value.field_key, value.value]
+    end
+  end
+
+  def dynamic_value(field_key)
+    @dynamic_values_by_field[field_key]
+  end
+end
+
+def export_users(users, resolved_fields)
+  fields = resolved_fields.to_a
+  row_class = Struct.new(:user)
+
+  row_class.comma :export do
+    __static_column__ 'Name' do |row|
+      row.user.name
+    end
+
+    fields.each do |field|
+      __static_column__ field.label do |row|
+        row.user.dynamic_value(field.key)
+      end
+    end
+  end
+
+  rows = users.map { |user| row_class.new(user) }
+  rows.to_comma(:export)
+end
+
+users = [
+  User.new('Ada', [
+    DynamicValue.new(:favorite_color, 'Blue'),
+    DynamicValue.new(:support_tier, 'Gold')
+  ]),
+  User.new('Grace', [
+    DynamicValue.new(:favorite_color, 'Green'),
+    DynamicValue.new(:support_tier, 'Silver')
+  ])
+]
+
+fields = [
+  DynamicField.new(:favorite_color, 'Favorite color'),
+  DynamicField.new(:support_tier, 'Support tier')
+]
+
+export_users(users, fields)
+# => "Name,Favorite color,Support tier\nAda,Blue,Gold\nGrace,Green,Silver\n"
+```
+
+In the example, `field.label` supplies each runtime header and `row.user.dynamic_value(field.key)` reads the matching value from the associated `dynamic_values` records.
+
+When field definitions come from tenant or platform configuration, fetch and order them once for the requested export before the `comma` block is defined. That lets header generation and row generation iterate over the same field list, preserving header/value alignment. Creating `row_class` inside `export_users` also isolates the `:export` format to that one CSV, so a simultaneous export builds its own class instead of overwriting the format being used here.
+
+In Rails controllers, requiring the gem registers `render csv:` support:
+
+```ruby
+def index
+  render csv: User.all
+end
+```
+
+See the [wiki](https://github.com/comma-csv/comma/wiki) for more usage examples.
 
 ## Running the tests
 
-To run the test suite across multiple gem file sets, we're using [Appraisal](https://github.com/thoughtbot/appraisal), use the following commands:
+Install dependencies:
+
+```sh
+bundle install
+bundle exec appraisal install
+```
+
+Run the default test suite and linter:
+
+```sh
+bundle exec rspec spec
+bundle exec rubocop -P
+```
+
+Run a single example:
 
 ```sh
-$ bundle exec appraisal install
-$ bundle exec appraisal rake spec
+bundle exec rspec spec/comma/comma_spec.rb:205
+```
+
+To run the test suite across the Rails / ActiveRecord gemfile matrix, this repository uses [Appraisal](https://github.com/thoughtbot/appraisal):
 
+```sh
+bundle exec appraisal rake spec
+```
+
+You can also run a specific spec under one appraisal:
+
+```sh
+bundle exec appraisal rails7.1.6 bundle exec rspec spec/controllers/users_controller_spec.rb
 ```
 
 ## Contributing
 
+Please make sure `bundle exec rspec spec`, `bundle exec rubocop -P`, and any relevant `bundle exec appraisal ...` commands pass before opening a pull request.
+
 ## Versioning
 
 We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/comma-csv/comma/tags).
@@ -56,4 +208,4 @@ We use [SemVer](http://semver.org/) for versioning. For the versions available,
 
 ## License
 
-This project is licensed under the MIT License - see the [MIT-LICENSE](https://github.com/comma-csv/comma/blob/master/MIT-LICENSE) file fore details.
+This project is licensed under the MIT License - see the [MIT-LICENSE](https://github.com/comma-csv/comma/blob/master/MIT-LICENSE) file for details.

data/comma.gemspec

@@ -15,6 +15,7 @@ Gem::Specification.new do |s|
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.require_paths = ['lib']
+  s.required_ruby_version = '>= 3.1'
 
   s.licenses = ['MIT']
 
@@ -23,12 +24,16 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency 'appraisal', ['~> 1.0.0']
   s.add_development_dependency 'base64'
+  s.add_development_dependency 'benchmark'
   s.add_development_dependency 'bigdecimal'
+  s.add_development_dependency 'cgi'
   s.add_development_dependency 'drb'
-  s.add_development_dependency 'minitest', '5.14.4'
+  s.add_development_dependency 'logger'
+  s.add_development_dependency 'minitest', '5.27.0'
   s.add_development_dependency 'mutex_m'
+  s.add_development_dependency 'ostruct'
   s.add_development_dependency 'rake', '~> 13.0.1'
-  s.add_development_dependency 'rspec', ['~> 3.5.0']
+  s.add_development_dependency 'rspec', ['~> 3.13']
   s.add_development_dependency 'rspec-activemodel-mocks'
   s.add_development_dependency 'rspec-its'
 end

data/gemfiles/{active6.0.6.gemfile → active7.1.6.gemfile}

@@ -6,7 +6,7 @@ gem "coveralls", :require => false
 gem "rubocop", "~> 1.30.0", :require => false
 gem "rubocop-performance", :require => false
 gem "sqlite3"
-gem "activesupport", "6.0.6"
-gem "activerecord", "6.0.6"
+gem "activesupport", "7.1.6"
+gem "activerecord", "7.1.6"
 
 gemspec :path => "../"