philiprehberger-csv_builder 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc5cd28c86059cae0603624ace5e07a070875268b942adf798d664755e028e91
-  data.tar.gz: 5cc96a1439b056f18e53cb2eb8af749ee2be05c74fcae55bd1aa31fb694a2016
+  metadata.gz: 921263332f87142c3cfcdc4483e601a9ab51ce54cd53481988cc75b3b46eb7ed
+  data.tar.gz: fa347e0127c702eca2a1c4104ca1b5eada5c43458660884c9b6f9028753a8f80
 SHA512:
-  metadata.gz: 867447e6eb9146acaa103b6167683745ca589f2d5cc59e78de72b9cf8191e956e6f639a2cc313b7c2d6e8249bb841e0ee3f3ced92e61fef4f18d8aba4ab2afbe
-  data.tar.gz: 9464cab4f2cc762d16458a066a2268dff54bbfb72a897e9188837e5b34a78b490b9cf11018d63cb5ba43ffb10880465bbd792dd1cd405d038e158e85585dcabf
+  metadata.gz: a9fcc0e96415c5b1d5b55e257963c48881ec879809b652ae7604138d524df50264577650e60bb239cf6b838b5fbae2bd03e6b76d5d6cdb0b3225528dd6a5d9a6
+  data.tar.gz: c7a65b052c99facd38baee4f16f2cca0bbd36ae5906ce6ca1302da36797c6b1b585066e096b1aec8432dacbd8d1167ab23f9cb522123e4253c3088b8643c14b4

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-11
+
+### Added
+- UTF-8 BOM support via `bom: true` option for Excel-compatible output
+- Custom output encoding via `encoding:` option
+
+### Fixed
+- Bug report template now requires Ruby version and gem version fields
+- Feature request template now includes "Alternatives considered" field
+
+## [0.4.0] - 2026-04-10
+
+### Added
+- `Builder#footer(&block)` appends a computed summary row after all data rows
+- `Builder#limit(n)` caps output to N rows
+- `Builder#offset(n)` skips the first N filtered/sorted records
+
 ## [0.3.0] - 2026-04-09
 
 ### Added
@@ -57,3 +74,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - File output via `to_file`
 - Support for hash records with symbol and string keys
 - Proper CSV escaping for values with commas and quotes
+
+[0.5.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.5.0
+[0.4.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.4.0
+[0.3.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.3.0
+[0.2.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.2.0
+[0.1.5]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.1.5
+[0.1.4]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.1.4
+[0.1.3]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.1.3
+[0.1.2]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.1.2
+[0.1.1]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.1.1
+[0.1.0]: https://github.com/philiprehberger/rb-csv-builder/releases/tag/v0.1.0

data/README.md

@@ -173,6 +173,51 @@ builder = Philiprehberger::CsvBuilder.build(records) do
 end
 ```
 
+### Footer Row
+
+Append a computed summary row after all data rows:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  column(:amount) { |r| r[:amount] }
+  footer { |recs| ['Total', recs.sum { |r| r[:amount] }] }
+end
+```
+
+### Pagination
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  offset 10   # skip first 10 records
+  limit 25    # output at most 25 rows
+end
+```
+
+`offset` and `limit` are applied after filtering and sorting.
+
+### Excel-Compatible Output (BOM)
+
+Prepend a UTF-8 BOM so Excel opens the CSV with correct encoding:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records, bom: true) do
+  column :name
+  column :email
+end
+
+builder.to_file('export.csv')
+```
+
+### Custom Encoding
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records, encoding: 'ISO-8859-1') do
+  column :name
+end
+```
+
 ### Streaming
 
 ```ruby
@@ -208,10 +253,13 @@ builder.headers  # => ["name", "email"]
 
 | Method | Description |
 |--------|-------------|
-| `CsvBuilder.build(records, delimiter:, quote_char:, &block)` | Build a CSV using the column DSL |
+| `CsvBuilder.build(records, delimiter:, quote_char:, bom:, encoding:, &block)` | Build a CSV using the column DSL |
 | `Builder#column(name, header:, &block)` | Define a column with optional alias and transform |
 | `Builder#filter(&block)` | Filter records (block returns true to include) |
 | `Builder#sort_by(direction:, &block)` | Sort records by block key (`:asc` or `:desc`) |
+| `Builder#footer(&block)` | Append a computed footer row (block receives filtered records) |
+| `Builder#limit(n)` | Cap output to N rows |
+| `Builder#offset(n)` | Skip first N filtered/sorted records |
 | `Builder#row_number(header:)` | Add auto-incrementing row number column |
 | `Builder#to_csv` | Generate CSV as a string |
 | `Builder#to_file(path)` | Write CSV to a file |

data/lib/philiprehberger/csv_builder/builder.rb

@@ -16,7 +16,9 @@ module Philiprehberger
       # @param records [Array] the source records
       # @param delimiter [String] the column separator (default: ",")
       # @param quote_char [String] the quote character (default: '"')
-      def initialize(records, delimiter: ',', quote_char: '"')
+      # @param bom [Boolean] prepend UTF-8 BOM (default: false)
+      # @param encoding [String] output encoding name (default: "UTF-8")
+      def initialize(records, delimiter: ',', quote_char: '"', bom: false, encoding: 'UTF-8')
         @records = records
         @columns = []
         @filters = []
@@ -25,6 +27,11 @@ module Philiprehberger
         @quote_char = quote_char
         @sort_by = nil
         @sort_direction = :asc
+        @limit_count = nil
+        @offset_count = nil
+        @footer_block = nil
+        @bom = bom
+        @encoding = encoding
       end
 
       # Sort records before CSV output
@@ -36,13 +43,42 @@ module Philiprehberger
       # @raise [Error] if direction is not :asc or :desc
       def sort_by(direction: :asc, &block)
         raise Error, 'A block is required for sort_by' unless block
-        raise Error, "direction must be :asc or :desc (got #{direction.inspect})" unless %i[asc desc].include?(direction)
+        raise Error, "direction must be :asc or :desc (got #{direction.inspect})" unless %i[asc
+                                                                                            desc].include?(direction)
 
         @sort_by = block
         @sort_direction = direction
         self
       end
 
+      # Limit the number of output rows
+      #
+      # @param n [Integer] maximum rows
+      # @return [self]
+      def limit(n)
+        @limit_count = n
+        self
+      end
+
+      # Skip the first N filtered/sorted records
+      #
+      # @param n [Integer] number of rows to skip
+      # @return [self]
+      def offset(n)
+        @offset_count = n
+        self
+      end
+
+      # Append a computed footer row after all data rows
+      #
+      # @yield [Array] filtered records
+      # @yieldreturn [Array] footer row values
+      # @return [self]
+      def footer(&block)
+        @footer_block = block
+        self
+      end
+
       # Define a column
       #
       # @param name [Symbol, String] the column name
@@ -94,6 +130,8 @@ module Philiprehberger
           result = result.sort_by(&@sort_by)
           result = result.reverse if @sort_direction == :desc
         end
+        result = result.drop(@offset_count) if @offset_count
+        result = result.first(@limit_count) if @limit_count
         result
       end
 
@@ -101,12 +139,16 @@ module Philiprehberger
       #
       # @return [String]
       def to_csv
-        CSV.generate(**csv_options) do |csv|
+        recs = filtered_records
+        csv_string = CSV.generate(**csv_options) do |csv|
           csv << headers
-          filtered_records.each_with_index do |record, index|
+          recs.each_with_index do |record, index|
             csv << build_row(record, index)
           end
+          csv << @footer_block.call(recs) if @footer_block
         end
+        csv_string = csv_string.encode(@encoding) unless @encoding == 'UTF-8'
+        @bom ? "\xEF\xBB\xBF#{csv_string}" : csv_string
       end
 
       # Write the CSV to a file
@@ -114,7 +156,7 @@ module Philiprehberger
       # @param path [String] the output file path
       # @return [void]
       def to_file(path)
-        File.write(path, to_csv)
+        File.binwrite(path, to_csv)
       end
 
       # Stream CSV to any IO object
@@ -122,11 +164,14 @@ module Philiprehberger
       # @param io [IO, StringIO] the IO object to write to
       # @return [void]
       def to_io(io)
+        io.write("\xEF\xBB\xBF") if @bom
+        recs = filtered_records
         csv = CSV.new(io, **csv_options)
         csv << headers
-        filtered_records.each_with_index do |record, index|
+        recs.each_with_index do |record, index|
           csv << build_row(record, index)
         end
+        csv << @footer_block.call(recs) if @footer_block
       end
 
       private

data/lib/philiprehberger/csv_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvBuilder
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/csv_builder.rb

@@ -13,14 +13,20 @@ module Philiprehberger
     # @param records [Array] the source records
     # @param delimiter [String] the column separator (default: ",")
     # @param quote_char [String] the quote character (default: '"')
+    # @param bom [Boolean] prepend UTF-8 BOM for Excel compatibility (default: false)
+    # @param encoding [String] output encoding name (default: "UTF-8")
     # @yield [builder] the builder instance for defining columns
     # @yieldparam builder [Builder]
     # @return [Builder] the configured builder
     # @raise [Error] if no block is given
-    def self.build(records, delimiter: ',', quote_char: '"', &block)
+    def self.build(records, delimiter: ',', quote_char: '"', bom: false, encoding: 'UTF-8', &block)
       raise Error, 'A block is required' unless block
 
-      builder = Builder.new(records, delimiter: delimiter, quote_char: quote_char)
+      builder = Builder.new(
+        records,
+        delimiter: delimiter, quote_char: quote_char,
+        bom: bom, encoding: encoding
+      )
       builder.instance_eval(&block)
       builder
     end

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_builder
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-11 00:00:00.000000000 Z
 dependencies: []
 description: Build CSV files from record collections using a declarative DSL with
-  column definitions, custom transforms, and file output support.
+  column definitions, custom transforms, filtering, sorting, pagination via limit/offset,
+  computed footer rows, row numbers, streaming output, and custom delimiters.
 email:
 - me@philiprehberger.com
 executables: []