axlsx_worksheet_builder 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86a36ede4b7181a6f615de7c8f104a3695513d59243bb028e03204cd14fb48f3
+  data.tar.gz: e150d4ed14a1637fcadebc8d8fb985374a101ea5267fb954b604872202c8b284
+SHA512:
+  metadata.gz: a5a07760bee6385df39d3b2961848686fcafe298fff949d3d965592d814cc2ad96de4154b8e541afd4cade233bb9e4730544b5f0ba9f6ebe6ee689a4b60480f9
+  data.tar.gz: c313576179a829f9a5e42774098d8ce984610368094e585b3aae9a71805cc0a1cf28203eee01f55cce15064ce87d8d5b65ca86f1f0f7ca7fcc12d7c3ea4cde9f

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.1

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [1.0.0] - 2026-03-03
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dreeven-oss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,73 @@
+# AxlsxWorksheetBuilder
+
+Inspired from code originally written by [Samuel Trottier](https://github.com/SamuelTrottier).
+
+
+## Installation
+
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add axlsx_worksheet_builder
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install axlsx_worksheet_builder
+```
+
+## Usage
+
+Add a simple table to an existing axlsx worksheet.
+
+### Iterate through an array of hash
+```ruby
+authors = [
+  {name: "Alice", dob: "1959-01-02", books: [{title: "Book 1"}, {title: "Book 2"}]},
+  {name: "Bob", dob: "1962-03-04", books: [{title: "Book A"}]}
+]
+AxlsxWorksheetBuilder::build(sheet, authors) do |worksheet|
+  worksheet.add_column("Author name", property: :name)
+  worksheet.add_column("Year of birth") { |author| Date.parse(author[:dob])&.year }
+  worksheet.add_column("Number of books") { |author| author[:books]&.size || 0 }
+end
+```
+
+### Iterate through an array of objects
+```ruby
+authors = [
+  Author.new(name: "Alice", dob: "1959-01-02"),
+  Author.new(name: "Bob", dob: "1959-01-02")
+]
+AxlsxWorksheetBuilder::build(sheet, authors) do |worksheet|
+  worksheet.add_column("Author name", property: :name)
+  worksheet.add_column("Year of birth") { |author| Date.parse(author.dob)&.year }
+end
+```
+
+### Iterate through an Array property
+```ruby
+authors = [{name: "Martin", books: [{title: "Book 1"}, {title: "Book 2"}]}]
+AxlsxWorksheetBuilder::build(sheet, authors) do |worksheet|
+  worksheet.iterate_through_property(:books)
+  worksheet.add_column("Author name", property: :name)
+  worksheet.add_column("Number of books") { |author| author.books.count }
+  worksheet.add_column("Book title") { |author, book| books.title }
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dreeven-oss/axlsx_worksheet_builder.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/axlsx_worksheet_builder/builder.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module AxlsxWorksheetBuilder
+  ##
+  # Builder instance
+  # @param
+  #   worksheet [Axlsx::Worksheet] The worksheet to be built
+  class Builder
+    attr_accessor :column_headers, :value_getters, :column_types, :worksheet
+
+    def initialize(worksheet)
+      @column_headers = []
+      @value_getters = []
+      @iterated_properties = []
+      @column_types = []
+      @worksheet = worksheet
+    end
+
+    ##
+    # Adds a new column to the worksheet
+    # @param
+    #   column_header [String] The header of the column
+    #   &bloc [Proc] A proc that will be called to get the value of the column for each row
+    #                This proc will receive as argument each relevant object for the row, see iterate_through_properties
+    #   property [Symbol] The property of the object to be added to the column for each row
+    #   type [Symbol] The type for the column (:string, :float, :integer, :date, :time or :boolean)
+    # @example
+    #   add_column("Author name", property: :name)
+    #   add_column("Author name") { |author| author.name }
+    #   add_column("Author name") do |author|
+    #     if author.name.present?
+    #       author.name
+    #     else
+    #       "Anonymous"
+    #     end
+    #   end
+    #   # In case of a nested iteration(iterate_through_properties),
+    #   # the values of the properties being iterated through get passed to the proc
+    #   add_column("Book title") |author, book| { books.title }
+    def add_column(column_header, property: nil, type: nil, &block)
+      column_headers << column_header
+      column_types << type
+      value_getters << ({
+        getter_proc: block,
+        property: property
+      })
+    end
+
+    def build_sheet(data)
+      worksheet.add_row column_headers
+      data.each do |entry|
+        add_entry_rows(entry, @iterated_properties, [entry])
+      end
+    end
+
+    ##
+    # Iterates through the property of each object in data
+    # @param
+    #   property [Symbol] The property of the object to be iterated through
+    # @example
+    #   # Given a data representing a list of authors with their books:
+    #   # [{name: "Martin", books: [{title: "Book 1"}, {title: "Book 2"}]}]
+    #   # the following code would create a row for each book of each author
+    #   iterate_through_properties(:books)
+    def iterate_through_property(property)
+      @iterated_properties = [property]
+    end
+
+    ##
+    # Iterates through the properties of each object in data
+    # The proc passed to add_column will receive as argument each objects being iterated through
+    # @param
+    #   properties [Array<Symbol>] The properties of the object to be iterated through
+    # @example
+    #   # Given a data representing a list of authors with their books and the chapter of each book:
+    #   # [{name: "Martin", books: [{title: "Book 1", chapter: ["Chapter 1", "Chapter 2"]}]}]
+    #   # the following code would create a row for each chapter of each book of each author
+    #   iterate_through_properties(:books, :chapter)
+    #   # In the previous case, the add_column proc would receive the following arguments:
+    #   # (author, book, chapter)
+    def iterate_through_properties(*properties)
+      @iterated_properties = properties
+    end
+
+    private
+
+    def add_entry_rows(entry, local_iterated_properties, precedent_entries)
+      properties = local_iterated_properties.clone
+      property = properties.shift
+      if property
+        process_entries(entry, property, precedent_entries, properties)
+      else
+        add_worksheet_row(entry, precedent_entries)
+      end
+    end
+
+    def process_entries(entry, property, precedent_entries, properties)
+      entries = entry_poperty(entry, property)
+      entries.each do |entry_property|
+        prec_entries = precedent_entries.clone
+
+        prec_entries.push(entry_property)
+        add_entry_rows(entry_property, properties, prec_entries)
+      end
+    end
+
+    def add_worksheet_row(entry, precedent_entries)
+      row = value_getters.map do |value_getter|
+        property = value_getter[:property]
+        if !property.nil?
+          entry_poperty(entry, property)
+        else
+          arguments = precedent_entries[0..(value_getter[:getter_proc].parameters.count - 1)]
+          value_getter[:getter_proc].call(*arguments)
+        end
+      end
+      worksheet.add_row row, types: column_types
+    end
+
+    def entry_poperty(entry, property)
+      entry.send(property)
+    rescue StandardError
+      entry[property]
+    end
+  end
+end

data/lib/axlsx_worksheet_builder/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AxlsxWorksheetBuilder
+  VERSION = "1.0.1"
+end

data/lib/axlsx_worksheet_builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "axlsx"
+require_relative "axlsx_worksheet_builder/version"
+require_relative "axlsx_worksheet_builder/builder"
+
+##
+# Axlsx Worksheet Builder
+module AxlsxWorksheetBuilder
+  class Error < StandardError; end
+  class InvalidWorksheet < ArgumentError; end
+
+  ##
+  # Builds the worksheet row, given the columns being added in the block
+  # @param
+  #   worksheet [Axlsx::Worksheet] The worksheet to be built
+  #   data [Array] The data to be added to the worksheet
+  # @example
+  #   # The following code will build the worksheet with a row for each book of each author
+  #   authors = [{name: "Martin", books: [{title: "Book 1"}, {title: "Book 2"}]}]
+  #   AxlsxWorksheetBuilder::build(sheet, authors) do |worksheet|
+  #     worksheet.iterate_through_property(:books)
+  #     worksheet.add_column("Author name", property: :name)
+  #     worksheet.add_column("Number of books") { |author| author.books.count }
+  #     worksheet.add_column("Book title") { |author, book| books.title }
+  #   end
+  def self.build(worksheet, data)
+    raise InvalidWorksheet, "Worksheet must be an Axlsx::Worksheet" unless worksheet.is_a?(Axlsx::Worksheet)
+
+    builder = Builder.new(worksheet)
+    yield builder
+    builder.build_sheet(data)
+  end
+end

data/sig/axlsx_worksheet_builder.rbs

@@ -0,0 +1,4 @@
+module AxlsxWorksheetBuilder
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: axlsx_worksheet_builder
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- drvn-eb
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: caxlsx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Simple axlsx worksheet generator for iterated data
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".tool-versions"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/axlsx_worksheet_builder.rb
+- lib/axlsx_worksheet_builder/builder.rb
+- lib/axlsx_worksheet_builder/version.rb
+- sig/axlsx_worksheet_builder.rbs
+homepage: https://github.com/dreeven-oss/axlsx_worksheet_builder
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dreeven-oss/axlsx_worksheet_builder
+  source_code_uri: https://github.com/dreeven-oss/axlsx_worksheet_builder
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Axlsx Worksheet Builder
+test_files: []