stacking-order 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13c66a0c61b2744526f1e6113775629730d07cda8d528630c103f5ae276bce4f
+  data.tar.gz: b8133c884d749092af5cb11e4b8b6879127cefb6a1f557fb95ba2eac888d738c
+SHA512:
+  metadata.gz: 0eb9c0442393fea05b44c548f4ce5f249cdc64e0e13843cfc8200ba15e0f08797eda11f3ed9856b00cc521d36ef0d815d7f66cd6bcb7fd562f0c58c373afc4d5
+  data.tar.gz: 0d2a23b921e1341f76e0373844150e3fa633d83f186cbb3e6b2ee8817150d98898933ec7cd492ea621831e83f7007203d7bbe2b1caf6198a4742b54809534628

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jeremy
+
+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,92 @@
+# Stacking Order
+
+A tiny Ruby gem that computes how to arrange records on a paginated grid so that,
+after cutting the printed stack into columns and re-stacking them, the final pile
+remains in sequential order. It is useful for printing badges, tickets, or any
+other grid-based layout that is cut in bulk.
+
+## Installation
+
+```bash
+bundle add stacking-order
+```
+
+Or add this line to your `Gemfile`:
+
+```ruby
+gem 'stacking-order'
+```
+
+## Usage
+
+### Library
+
+```ruby
+require 'stacking_order'
+
+order = StackingOrder.order(entries: 13, rows: 2, columns: 2)
+# => [1, 5, 9, 13, 2, 6, 10, nil, 3, 7, 11, nil, 4, 8, 12]
+# nil entries mark empty slots on the final, partially filled page.
+
+StackingOrder.visualize(entries: 6, rows: 2, columns: 2)
+# Prints page-by-page grids plus the stack order after cutting.
+```
+
+### CLI
+
+```
+$ stacking-order --entries 15 --rows 2 --columns 2
+
+Stacking order (15 positions):
+[1, 5, 9, 13, 2, 6, 10, nil, 3, 7, 11, nil, 4, 8, 12]
+
+
+$ stacking-order --entries 6 --rows 2 --columns 2 --visualize
+
+============================================================
+Visualizing stacking order for 13 entries, 2 row(s), 2 column(s)
+============================================================
+Result: [1, 5, 9, 13, 2, 6, 10, nil, 3, 7, 11, nil, 4, 8, 12]
+
+Pages layout:
+
+Page 1:
+  Row 1:   1 |   5
+  Row 2:   9 |  13
+
+Page 2:
+  Row 1:   2 |   6
+  Row 2:  10 | nil
+
+Page 3:
+  Row 1:   3 |   7
+  Row 2:  11 | nil
+
+Page 4:
+  Row 1:   4 |   8
+  Row 2:  12
+
+After cutting and stacking:
+  Position [1,1] stack (bottom→top): 1, 2, 3, 4
+  Position [1,2] stack (bottom→top): 5, 6, 7, 8
+  Position [2,1] stack (bottom→top): 9, 10, 11, 12
+  Position [2,2] stack (bottom→top): 13
+```
+
+The CLI prints the resulting sequence (or, with `--visualize`, renders the
+page-by-page grids and stack order) and returns non-zero on invalid arguments.
+
+### Real-world usage
+
+This gem powers the stacking order calculations in
+[pecha-printer](https://github.com/jerefrer/pecha-printer), which itself backs
+the hosted service at <https://pecha-printer.frerejeremy.me>. By publishing the
+logic as a gem, the same algorithm can be reused by other Ruby/Rails projects or
+invoked manually via the CLI.
+
+## Development
+
+- Run tests: `bundle exec rake test`
+- Build the gem: `bundle exec rake build`
+
+Pull requests and issues are welcome.

data/exe/stacking-order

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+
+begin
+  require 'stacking_order'
+rescue LoadError
+  lib_path = File.expand_path('../lib', __dir__)
+  $LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
+  require 'stacking_order'
+end
+
+options = {}
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: stacking-order --entries N --rows R --columns C'
+
+  opts.on('-e', '--entries N', Integer, 'Total number of entries') do |value|
+    options[:entries] = value
+  end
+
+  opts.on('-r', '--rows R', Integer, 'Number of rows per page') do |value|
+    options[:rows] = value
+  end
+
+  opts.on('-c', '--columns C', Integer, 'Number of columns per page') do |value|
+    options[:columns] = value
+  end
+
+  opts.on('--visualize', 'Print page-by-page layout and stack order') do
+    options[:visualize] = true
+  end
+
+  opts.on('-v', '--version', 'Print gem version') do
+    puts StackingOrder::VERSION
+    exit 0
+  end
+
+  opts.on('-h', '--help', 'Show this help message') do
+    puts opts
+    exit 0
+  end
+end
+
+begin
+  parser.parse!(ARGV)
+rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+  warn e.message
+  warn parser
+  exit 1
+end
+
+missing = %i[entries rows columns].reject { |key| options[key] }
+if missing.any?
+  warn "Missing required options: #{missing.join(', ')}"
+  warn parser
+  exit 1
+end
+
+begin
+  result = StackingOrder.order(entries: options[:entries], rows: options[:rows], columns: options[:columns])
+rescue ArgumentError => e
+  warn e.message
+  exit 1
+end
+
+if options[:visualize]
+  StackingOrder.visualize(entries: options[:entries], rows: options[:rows], columns: options[:columns])
+else
+  puts "Stacking order (#{result.length} positions):"
+  puts result.inspect
+end

data/lib/stacking_order/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StackingOrder
+  VERSION = '1.0.0'
+end

data/lib/stacking_order.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'stacking_order/version'
+
+# Calculates how to print entries in a grid so that stack-cut pages
+# reassemble into sequential order.
+module StackingOrder
+  module_function
+
+  # Public API for calculating the stacking order for printing entries on pages
+  # with a grid layout. See README for details.
+  #
+  # @param entries [Integer] Total number of entries to print
+  # @param rows [Integer] Number of rows in the grid on each page
+  # @param columns [Integer] Number of columns in the grid on each page
+  # @return [Array<Integer, nil>] The order in which to print entries (with nil for empty cells)
+  def order(entries:, rows:, columns:)
+    validate_arguments!(entries, rows, columns)
+
+    return [] if entries.zero?
+
+    cells_per_page = rows * columns
+    num_pages = (entries.to_f / cells_per_page).ceil
+
+    result = []
+
+    num_pages.times do |page_index|
+      cells_per_page.times do |cell_index|
+        entry_number = (cell_index * num_pages) + page_index + 1
+        result << (entry_number <= entries ? entry_number : nil)
+      end
+    end
+
+    result.pop while result.last.nil?
+    result
+  end
+
+  # Utility method that prints the layout for the provided configuration,
+  # showing the entries on each page and the resulting stacks after cutting.
+  # Useful for debugging or CLI demos.
+  def visualize(entries:, rows:, columns:, io: $stdout)
+    result = order(entries: entries, rows: rows, columns: columns)
+    cells_per_page = rows * columns
+    num_pages = (entries.to_f / cells_per_page).ceil
+
+    io.puts
+    io.puts('=' * 60)
+    io.puts("Visualizing stacking order for #{entries} entries, #{rows} row(s), #{columns} column(s)")
+    io.puts('=' * 60)
+    io.puts("Result: #{result.inspect}")
+    io.puts("\nPages layout:")
+
+    result.each_slice(cells_per_page).with_index do |page, page_num|
+      io.puts("\nPage #{page_num + 1}:")
+      page.each_slice(columns).with_index do |row_values, row_num|
+        formatted = row_values.map { |value| value ? format('%3d', value) : 'nil' }.join(' | ')
+        io.puts("  Row #{row_num + 1}: #{formatted}")
+      end
+    end
+
+    io.puts("\nAfter cutting and stacking:")
+    cells_per_page.times do |cell_idx|
+      row_idx = cell_idx / columns
+      col_idx = cell_idx % columns
+      stack = []
+
+      num_pages.times do |page_idx|
+        pos = (page_idx * cells_per_page) + cell_idx
+        stack << (pos < result.length ? result[pos] : nil)
+      end
+
+      io.puts("  Position [#{row_idx + 1},#{col_idx + 1}] stack (bottom→top): #{stack.compact.join(', ')}")
+    end
+  end
+
+  def validate_arguments!(entries, rows, columns)
+    raise ArgumentError, 'entries must be non-negative' if entries.negative?
+    raise ArgumentError, 'rows must be positive' if rows <= 0
+    raise ArgumentError, 'columns must be positive' if columns <= 0
+  end
+  private_class_method :validate_arguments!
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: stacking-order
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jeremy
+bindir: exe
+cert_chain: []
+date: 2025-11-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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: A tiny utility that reorders records for stack-cut badge printing, available
+  as both a Ruby library and a command-line tool.
+email:
+- jeremy@example.com
+executables:
+- stacking-order
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/stacking-order
+- lib/stacking_order.rb
+- lib/stacking_order/version.rb
+homepage: https://github.com/jeremy/stacking-order
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jeremy/stacking-order
+  source_code_uri: https://github.com/jeremy/stacking-order
+  changelog_uri: https://github.com/jeremy/stacking-order
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Compute cut-and-stack printing orders for grid-based badges.
+test_files: []