xlsx_composer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eb4ddd7e108efe7858b8c3ef358a003e9a0b5d94f3be1500aacee95cd7c9c9ca
+  data.tar.gz: ff4408f5e1a9edf7fdbcaf9eeb9d935cb6e907fdddb80e12e5310395e0fd0521
+SHA512:
+  metadata.gz: ac1e35c9a14f3d0a8ea9f6cf9f4b61b2d7cba0dee6d21885676a205f748c9d72ab735b04fb4af9bfb3b782865d2ee5b933e7b90505c1cb4b6ef28a917b09ffdc
+  data.tar.gz: 1bf88f371a14a58e2160958fbf4518204d4c9ac724ec7460aedd4eef636edb11b66f6b3ba6e9909e1c08f1e4d405e794942b59aa57e5de2f1c0a12b0e62f77ca

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.1.0] - 2026-02-05
+- Initial release.
+- Cursor-based navigation helpers (`go_to`, `next_row`, `next_col`, etc.).
+- Built-in reusable formats and per-class custom formats via `add_format`.
+- Base composer class for worksheet templates.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"xlsx_composer" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["hugo.passos@hotmail.com"](mailto:"hugo.passos@hotmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Hugo Passos
+
+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,223 @@
+# XlsxComposer
+
+**XlsxComposer** is a small Ruby library built on top of **WriteXLSX** that makes the creation of **complex and dynamic Excel spreadsheets** easier, more readable, and more maintainable.
+
+It does **not** try to replace WriteXLSX.  
+Instead, it provides a higher-level abstraction focused on **navigation, composition, and formatting**, which are usually the hardest parts when spreadsheets stop being static.
+
+
+## Motivation
+
+`WriteXLSX` does an excellent job at generating `.xlsx` files.  
+However, when spreadsheets become **dynamic**, code tends to become harder to read and maintain:
+
+- manual row and column index management
+- lots of hard-coded coordinates
+- duplicated formatting logic
+- fragile templates that only work for fixed layouts
+
+**XlsxComposer** introduces a *cursor-based* approach to spreadsheet writing:
+
+- move through the sheet with `next_row`, `next_col`, `go_to`, etc.
+- reuse the same template for variable-length data
+- define and reuse formats easily
+- compose spreadsheets incrementally instead of calculating coordinates upfront
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "xlsx_composer"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+
+## Basic usage
+
+```ruby
+require "xlsx_composer"
+
+workbook = XlsxComposer.workbook("example.xlsx")
+
+sheet = XlsxComposer::Worksheet.new(workbook, "Demo")
+
+sheet.go_to("1", "A")
+sheet.write_row(["Year", "Revenue"], sheet.bold)
+
+sheet.next_row
+sheet.write_row([2024, 1000], sheet.thousands_mark)
+
+sheet.next_row
+sheet.write_row([2025, 1250], sheet.thousands_mark)
+
+workbook.close
+```
+
+
+## Cursor-based navigation
+
+Instead of calculating coordinates manually, you move a cursor across the sheet.
+
+### Available navigation methods
+
+```ruby
+go_to(row, col)      # go_to("3", "B")
+go_to_row(row)
+go_to_col(col)
+
+next_row
+previous_row
+next_col
+previous_col
+
+next_rows(n)
+previous_rows(n)
+next_cols(n)
+previous_cols(n)
+```
+
+- Rows are **1-based**
+- Columns use **Excel notation** (`A`, `Z`, `AA`, `BA`, etc.)
+
+
+## Dynamic templates
+
+The main idea behind XlsxComposer is **that the same spreadsheet template can generate different shapes of data.**
+
+### Example: contracts with variable durations
+
+Imagine a `Contract` entity that produces yearly results:
+- some contracts last 3 years
+- others last 5, 10, or more
+- the layout is the same, only the number of rows changes
+
+```ruby
+class ContractWorksheet < XlsxComposer::Base
+  def worksheet_name
+    "Contract Summary"
+  end
+
+  def run(contract)
+    write_row(["Year", "Value"], bold)
+
+    contract.years.each do |year|
+      next_row
+      write_row([year.number, year.value], thousands_mark)
+    end
+  end
+end
+```
+
+The same template works regardless of how many years the contract has.
+
+
+## Formatting
+
+### Built-in formats
+
+XlsxComposer ships with a set of common, reusable formats:
+
+```ruby
+bold
+bold_center
+bold_title
+bold_percent
+
+thousands_mark
+currency_brl
+
+font_size_ten
+font_size_ten_thousands_mark
+font_size_ten_currency_brl
+font_size_ten_percent
+```
+
+Formats are cached per worksheet and reused internally by WriteXLSX.
+
+Usage example:
+
+```ruby
+write_row(["Total"], bold)
+write_row([1000], currency_brl)
+```
+
+
+## Adding custom formats
+
+You can define additional formats per worksheet class using `add_format`.
+
+```ruby
+class ReportWorksheet < XlsxComposer::Base
+  add_format :header, bold: 1, size: 14, align: "center"
+  add_format :highlight, bold: 1, align: "center", bg_color: "yellow"
+
+  def worksheet_name
+    "Report"
+  end
+
+  def run
+    write_row(["Report"], header)
+    next_row
+    write_row(["Important"], highlight)
+  end
+end
+```
+
+### Dynamic formats
+
+Formats can also be defined using a block:
+
+```ruby
+add_format(:conditional) do
+  if some_condition?
+    { bold: 1, color: "red" }
+  else
+    { bold: 1 }
+  end
+end
+```
+
+
+## Global vs class-specific formats
+
+- **Global formats** live in `XlsxComposer::Formatter` and are available everywhere.
+- **Class-specific formats** are defined via `add_format` and scoped to that worksheet composer.
+
+Both are cached on the underlying worksheet and backed by WriteXLSX `Format` objects.
+
+
+## Why not just WriteXLSX?
+
+You absolutely can — and should — use WriteXLSX directly for simple spreadsheets.
+
+XlsxComposer becomes valuable when:
+
+- spreadsheets are generated from templates
+- layouts are dynamic
+- rows and columns are added conditionally or iteratively
+- formatting logic starts spreading across the codebase
+- readability and maintainability matter
+
+Think of XlsxComposer as a **composition layer**, not a replacement.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/hugopassos/xlsx_composer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/hugopassos/xlsx_composer/blob/main/CODE_OF_CONDUCT.md).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+
+## Code of Conduct
+
+Everyone interacting in the XlsxComposer project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hugopassos/xlsx_composer/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/xlsx_composer/base.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module XlsxComposer
+  class Base
+    extend Forwardable
+
+    class << self
+      def extra_formats
+        @extra_formats ||= {}
+      end
+
+      def add_format(name, override: false, **args, &block)
+        name = name.to_sym
+        raise ArgumentError, "Invalid format name: #{name.inspect}" unless name.match?(/\A[a-z_]\w*\z/i)
+
+        if !override && (instance_methods.include?(name) || private_instance_methods.include?(name))
+          raise ArgumentError, "Method already defined: #{name} (use override: true)"
+        end
+
+        extra_formats[name] = block || args
+
+        define_method(name) do
+          composer_worksheet.get_format(name)
+        end
+      end
+    end
+
+    def initialize(workbook: nil, worksheet: nil)
+      raise ArgumentError, "Provide workbook: or worksheet:" if workbook.nil? && worksheet.nil?
+
+      if worksheet
+        @composer_worksheet = worksheet
+      else
+        raise "Method `worksheet_name` must be defined" unless respond_to?(:worksheet_name, true)
+        @composer_worksheet = XlsxComposer::Worksheet.new(workbook, worksheet_name)
+      end
+
+      define_class_formats!
+    end
+
+    def compose(&block)
+      instance_exec(&block)
+    end
+
+    def close_workbook
+      workbook.close
+    end
+
+    private
+
+    attr_reader :composer_worksheet
+
+    def define_class_formats!
+      self.class.extra_formats.each do |name, spec|
+        args = spec.is_a?(Proc) ? instance_exec(&spec) : spec
+        composer_worksheet.format(name, **args)
+      end
+    end
+
+    def_delegators :@composer_worksheet,
+                  :workbook, :worksheet,
+                  :write_row, :write_col, :merge_rows, :merge_cols,
+                  :row_index, :col_index, :go_to, :go_to_row, :go_to_col,
+                  :next_row, :next_col, :previous_row, :previous_col,
+                  :reset_row, :reset_col, :next_rows, :next_cols,
+                  :previous_rows, :previous_cols,
+                  :row_height, :col_width, :bold, :bold_center,
+                  :bold_title, :bold_percent, :bold_rotation_ninety,
+                  :thousands_mark, :currency_brl,
+                  :font_size_ten, :font_size_ten_thousands_mark,
+                  :font_size_ten_currency_brl, :font_size_ten_percent
+  end
+end

data/lib/xlsx_composer/formatter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module XlsxComposer
+  module Formatter
+    def bold = format(:bold, bold: 1)
+
+    def bold_center = format(:bold_center, bold: 1, align: "center")
+
+    def bold_title = format(:font_size_sixteen_bold, bold: 1, size: 16)
+
+    def bold_percent = format(:percent_bold, bold: 1, num_format: "0%")
+
+    def bold_rotation_ninety = format(bold: 1, rotation: 90, align: "vcenter")
+
+    def thousands_mark = format(:thousands_mark, num_format: "#,##0")
+
+    def currency_brl = format(:currency_brl, num_format: "R$ #,##0.00")
+
+    def font_size_ten = format(:font_size_ten, size: 10)
+
+    def font_size_ten_thousands_mark = format(:font_size_ten_thousands_mark, size: 10, num_format: "#,##0")
+
+    def font_size_ten_currency_brl = format(:font_size_ten_currency_brl, size: 10, num_format: "R$ #,##0.00")
+
+    def font_size_ten_percent = format(:font_size_ten_percent, size: 10, num_format: "0%")
+
+    def row_height(value)
+      worksheet.set_row(row_index, value)
+    end
+
+    def col_width(value)
+      worksheet.set_column(col_index, col_index, value)
+    end
+
+    def format(name, **args)
+      name = name.to_sym
+      @__formats_cache ||= {}
+      @__formats_cache[name] ||= workbook.add_format(**args)
+    end
+
+    def get_format(name)
+      name = name.to_sym
+      @__formats_cache ||= {}
+      @__formats_cache.fetch(name) do
+        raise KeyError, "Format not defined: #{name}"
+      end
+    end
+  end
+end

data/lib/xlsx_composer/indexer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module XlsxComposer
+  module Indexer
+    def next_row = @row_index += 1
+
+    def next_col = @col_index += 1
+
+    def previous_row = @row_index -= 1
+
+    def previous_col = @col_index -= 1
+
+    def reset_row = @row_index = 0
+
+    def reset_col = @col_index = 0
+
+    def next_rows(quantity) = @row_index += quantity
+
+    def next_cols(quantity) = @col_index += quantity
+
+    def previous_rows(quantity) = @row_index -= quantity
+
+    def previous_cols(quantity) = @col_index -= quantity
+
+    def go_to(row, col)
+      @row_index = row.to_i - 1
+      @col_index = col_to_index(col)
+    end
+
+    def go_to_row(row)
+      @row_index = row.to_i - 1
+    end
+
+    def go_to_col(col)
+      @col_index = col_to_index(col)
+    end
+
+    private
+
+    # "A" => 0, "Z" => 25, "AA" => 26, "AB" => 27, ..., "BA" => 52 ...
+    def col_to_index(col)
+      str = col.to_s.strip.upcase
+      raise ArgumentError, "Invalid column: #{col.inspect}" unless str.match?(/\A[A-Z]+\z/)
+
+      str.chars.reduce(0) { |acc, ch| acc * 26 + (ch.ord - 64) } - 1
+    end
+  end
+end

data/lib/xlsx_composer/version.rb

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

data/lib/xlsx_composer/worksheet.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module XlsxComposer
+  class Worksheet
+    include XlsxComposer::Indexer
+    include XlsxComposer::Formatter
+
+    attr_reader :row_index, :col_index, :workbook, :worksheet
+
+    def initialize(workbook, worksheet_name)
+      @workbook = workbook
+      @worksheet = workbook.add_worksheet(worksheet_name)
+      @row_index = 0
+      @col_index = 0
+    end
+
+    def write_row(content, format = nil)
+      worksheet.write_row(*current_index, content, format)
+    end
+
+    def write_col(content, format = nil)
+      worksheet.write_col(*current_index, content, format)
+    end
+
+    def merge_rows(number_of_rows, content, format = nil)
+      worksheet.merge_range(
+        row_index,
+        col_index,
+        row_index + number_of_rows - 1,
+        col_index,
+        content,
+        format
+      )
+    end
+
+    def merge_cols(number_of_cols, content, format = nil)
+      worksheet.merge_range(
+        row_index,
+        col_index,
+        row_index,
+        col_index + number_of_cols - 1,
+        content,
+        format
+      )
+    end
+
+    private
+
+    def current_index
+      [row_index, col_index]
+    end
+  end
+end

data/lib/xlsx_composer.rb

@@ -0,0 +1,13 @@
+require "nkf"
+require "write_xlsx"
+require_relative "xlsx_composer/version"
+require_relative "xlsx_composer/indexer"
+require_relative "xlsx_composer/formatter"
+require_relative "xlsx_composer/worksheet"
+require_relative "xlsx_composer/base"
+
+module XlsxComposer
+  def self.workbook(path, **opts)
+    WriteXLSX.new(path, **opts)
+  end
+end

data/sig/xlsx_composer.rbs

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

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: xlsx_composer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hugo Passos
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: write_xlsx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+- !ruby/object:Gem::Dependency
+  name: nkf
+  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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: XlsxComposer provides cursor-based navigation and reusable templates
+  for generating dynamic Excel spreadsheets using WriteXLSX.
+email:
+- hugo.passos@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/xlsx_composer.rb
+- lib/xlsx_composer/base.rb
+- lib/xlsx_composer/formatter.rb
+- lib/xlsx_composer/indexer.rb
+- lib/xlsx_composer/version.rb
+- lib/xlsx_composer/worksheet.rb
+- sig/xlsx_composer.rbs
+homepage: https://github.com/hugopassos/xlsx_composer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hugopassos/xlsx_composer
+  source_code_uri: https://github.com/hugopassos/xlsx_composer
+  changelog_uri: https://github.com/hugopassos/xlsx_composer/blob/main/CHANGELOG.md
+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: A composition layer on top of WriteXLSX for dynamic spreadsheets
+test_files: []