philiprehberger-csv_builder 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9810b1f04bb59659c6636dab4aefe4213551a4bdd8b75b5ad9b4311e2d42694b
-  data.tar.gz: 4b9e23bc25d7cbf74ca3aaaf9d549ec2de92a5b43fd4aca0f061d08b21240615
+  metadata.gz: 2f0d8a20ab069951c75151dcb5d3892a7c86ba7ed94b8ab09a9ef03baf2bf0a2
+  data.tar.gz: 7b1efd9f802aa42886292127d3a4417f0aabaf5d5673049819c915cd3b4e5b76
 SHA512:
-  metadata.gz: 9b6811067d8f0813b944ed4a0a562a4f90220be41733953209000b3287552a663e0774f66ac2f53053dbccce04e6f90f30e1e43d9b727da7b3c0857b5ce93e27
-  data.tar.gz: ee2920705b11bc315d152ef2c5a781164150d5e47181f61d01eaad1390f1e23c6734eaf8c14a8f588df78985b13f82d1f10f0cf53473c3c00c607b1c956a38b1
+  metadata.gz: 8f99b2921a5871ac26e0d516f773cf644a310c6f3a72f2b999acb2f18fa4c2f3b049723421bd0247344736e65d7b0c186d9091bafdbde955fea80d3fdaf52b50
+  data.tar.gz: 791c95f2680441487f40314c5e265c6b4f7294c2260ec21e67670572f25b817ee958f7cd506794482b30447fc64b069facfc6f47a612b567f3828a4a1fdda1d5

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-03
+
+### Added
+- Custom CSV delimiters via `delimiter:` option
+- Custom quote character via `quote_char:` option
+- Column header aliasing via `header:` option on columns
+- Record filtering via `filter`
+- Auto-incrementing row numbers via `row_number`
+- Streaming output via `to_io`
+
+## [0.1.5] - 2026-03-31
+
+### Added
+- Add GitHub issue templates, dependabot config, and PR template
+
+## [0.1.4] - 2026-03-31
+
+### Changed
+- Standardize README badges, support section, and license format
+
 ## [0.1.3] - 2026-03-24
 
 ### Fixed

data/README.md

@@ -2,7 +2,7 @@
 
 [![Tests](https://github.com/philiprehberger/rb-csv-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-csv-builder/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-csv_builder.svg)](https://rubygems.org/gems/philiprehberger-csv_builder)
-[![License](https://img.shields.io/github/license/philiprehberger/rb-csv-builder)](LICENSE)
+[![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-csv-builder)](https://github.com/philiprehberger/rb-csv-builder/commits/main)
 
 Declarative CSV builder with column mapping and streaming output
 
@@ -71,6 +71,109 @@ end
 builder.to_file('output.csv')
 ```
 
+### Custom Delimiters
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records, delimiter: "\t") do
+  column :name
+  column :email
+end
+
+puts builder.to_csv
+# name	email
+# Alice	alice@example.com
+# Bob	bob@example.com
+```
+
+You can also set a custom quote character:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records, quote_char: "'") do
+  column :name
+  column :email
+end
+```
+
+### Column Aliases
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name, header: 'Full Name'
+  column :email, header: 'Email Address'
+  column(:status, header: 'Active?') { |r| r[:active] ? 'Yes' : 'No' }
+end
+
+puts builder.to_csv
+# Full Name,Email Address,Active?
+# Alice,alice@example.com,Yes
+# Bob,bob@example.com,No
+```
+
+### Filtering
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  column :email
+  filter { |r| r[:active] }
+end
+
+puts builder.to_csv
+# name,email
+# Alice,alice@example.com
+```
+
+Multiple filters are combined with AND logic:
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  filter { |r| r[:active] }
+  filter { |r| r[:name].start_with?('A') }
+end
+```
+
+### Row Numbers
+
+```ruby
+builder = Philiprehberger::CsvBuilder.build(records) do
+  column :name
+  column :email
+  row_number
+end
+
+puts builder.to_csv
+# #,name,email
+# 1,Alice,alice@example.com
+# 2,Bob,bob@example.com
+```
+
+Customize the header label:
+
+```ruby
+row_number(header: 'Row')
+```
+
+### Streaming
+
+```ruby
+File.open('output.csv', 'w') do |file|
+  builder = Philiprehberger::CsvBuilder.build(records) do
+    column :name
+    column :email
+  end
+
+  builder.to_io(file)
+end
+```
+
+Works with any IO object, including `StringIO`:
+
+```ruby
+io = StringIO.new
+builder.to_io(io)
+```
+
 ### Headers
 
 ```ruby
@@ -86,10 +189,13 @@ builder.headers  # => ["name", "email"]
 
 | Method | Description |
 |--------|-------------|
-| `CsvBuilder.build(records, &block)` | Build a CSV using the column DSL |
-| `Builder#column(name, &block)` | Define a column with optional transform |
+| `CsvBuilder.build(records, delimiter:, quote_char:, &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#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 |
+| `Builder#to_io(io)` | Stream CSV to any IO object |
 | `Builder#headers` | Return column header names |
 
 ## Development
@@ -100,6 +206,24 @@ bundle exec rspec
 bundle exec rubocop
 ```
 
+## Support
+
+If you find this project useful:
+
+⭐ [Star the repo](https://github.com/philiprehberger/rb-csv-builder)
+
+🐛 [Report issues](https://github.com/philiprehberger/rb-csv-builder/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
+
+💡 [Suggest features](https://github.com/philiprehberger/rb-csv-builder/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement)
+
+❤️ [Sponsor development](https://github.com/sponsors/philiprehberger)
+
+🌐 [All Open Source Projects](https://philiprehberger.com/open-source-packages)
+
+💻 [GitHub Profile](https://github.com/philiprehberger)
+
+🔗 [LinkedIn Profile](https://www.linkedin.com/in/philiprehberger)
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/philiprehberger/csv_builder/builder.rb

@@ -14,19 +14,45 @@ module Philiprehberger
       attr_reader :records
 
       # @param records [Array] the source records
-      def initialize(records)
+      # @param delimiter [String] the column separator (default: ",")
+      # @param quote_char [String] the quote character (default: '"')
+      def initialize(records, delimiter: ',', quote_char: '"')
         @records = records
         @columns = []
+        @filters = []
+        @row_number_header = nil
+        @delimiter = delimiter
+        @quote_char = quote_char
       end
 
       # Define a column
       #
       # @param name [Symbol, String] the column name
+      # @param header [String, nil] optional custom header label
       # @yield [record] optional block to transform the value
       # @yieldparam record [Object] the source record
       # @return [self]
-      def column(name, &block)
-        @columns << Column.new(name, &block)
+      def column(name, header: nil, &block)
+        @columns << Column.new(name, header: header, &block)
+        self
+      end
+
+      # Add a filter to exclude records
+      #
+      # @yield [record] block that returns true to include the record
+      # @yieldparam record [Object] the source record
+      # @return [self]
+      def filter(&block)
+        @filters << block
+        self
+      end
+
+      # Add an auto-incrementing row number as the first column
+      #
+      # @param header [String] the header label for the row number column
+      # @return [self]
+      def row_number(header: '#')
+        @row_number_header = header
         self
       end
 
@@ -34,17 +60,29 @@ module Philiprehberger
       #
       # @return [Array<String>]
       def headers
-        @columns.map(&:header)
+        base = @columns.map(&:header)
+        @row_number_header ? [@row_number_header] + base : base
+      end
+
+      # Return the filtered records
+      #
+      # @return [Array]
+      def filtered_records
+        result = @records
+        @filters.each do |f|
+          result = result.select(&f)
+        end
+        result
       end
 
       # Generate the CSV as a string
       #
       # @return [String]
       def to_csv
-        CSV.generate do |csv|
+        CSV.generate(**csv_options) do |csv|
           csv << headers
-          @records.each do |record|
-            csv << @columns.map { |col| col.extract(record) }
+          filtered_records.each_with_index do |record, index|
+            csv << build_row(record, index)
           end
         end
       end
@@ -56,6 +94,35 @@ module Philiprehberger
       def to_file(path)
         File.write(path, to_csv)
       end
+
+      # Stream CSV to any IO object
+      #
+      # @param io [IO, StringIO] the IO object to write to
+      # @return [void]
+      def to_io(io)
+        csv = CSV.new(io, **csv_options)
+        csv << headers
+        filtered_records.each_with_index do |record, index|
+          csv << build_row(record, index)
+        end
+      end
+
+      private
+
+      # @return [Hash] CSV library options
+      def csv_options
+        { col_sep: @delimiter, quote_char: @quote_char }
+      end
+
+      # Build a single row array for the given record
+      #
+      # @param record [Object] the source record
+      # @param index [Integer] zero-based row index
+      # @return [Array]
+      def build_row(record, index)
+        row = @columns.map { |col| col.extract(record) }
+        @row_number_header ? [index + 1] + row : row
+      end
     end
   end
 end

data/lib/philiprehberger/csv_builder/column.rb

@@ -11,9 +11,11 @@ module Philiprehberger
       attr_reader :transform
 
       # @param name [Symbol, String] the column name (also used as the record key)
+      # @param header [String, nil] optional custom header label
       # @param transform [Proc, nil] optional block to transform the value
-      def initialize(name, &transform)
+      def initialize(name, header: nil, &transform)
         @name = name.to_sym
+        @custom_header = header
         @transform = block_given? ? transform : nil
       end
 
@@ -37,7 +39,7 @@ module Philiprehberger
       #
       # @return [String]
       def header
-        @name.to_s
+        @custom_header || @name.to_s
       end
     end
   end

data/lib/philiprehberger/csv_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CsvBuilder
-    VERSION = '0.1.3'
+    VERSION = '0.2.0'
   end
 end

data/lib/philiprehberger/csv_builder.rb

@@ -11,14 +11,16 @@ module Philiprehberger
     # Build a CSV from records using a declarative DSL
     #
     # @param records [Array] the source records
+    # @param delimiter [String] the column separator (default: ",")
+    # @param quote_char [String] the quote character (default: '"')
     # @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, &block)
+    def self.build(records, delimiter: ',', quote_char: '"', &block)
       raise Error, 'A block is required' unless block
 
-      builder = Builder.new(records)
+      builder = Builder.new(records, delimiter: delimiter, quote_char: quote_char)
       builder.instance_eval(&block)
       builder
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-csv_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-25 00:00:00.000000000 Z
+date: 2026-04-03 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.
@@ -25,11 +25,11 @@ files:
 - lib/philiprehberger/csv_builder/builder.rb
 - lib/philiprehberger/csv_builder/column.rb
 - lib/philiprehberger/csv_builder/version.rb
-homepage: https://github.com/philiprehberger/rb-csv-builder
+homepage: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-csv_builder
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/philiprehberger/rb-csv-builder
+  homepage_uri: https://philiprehberger.com/open-source-packages/ruby/philiprehberger-csv_builder
   source_code_uri: https://github.com/philiprehberger/rb-csv-builder
   changelog_uri: https://github.com/philiprehberger/rb-csv-builder/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/philiprehberger/rb-csv-builder/issues