stacking-order 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13c66a0c61b2744526f1e6113775629730d07cda8d528630c103f5ae276bce4f
-  data.tar.gz: b8133c884d749092af5cb11e4b8b6879127cefb6a1f557fb95ba2eac888d738c
+  metadata.gz: c9e10302ad7c8d1fe7f55e367d265f7599f92ea98243aba62b69765c427a1a1c
+  data.tar.gz: 68c1ee82c92146a6a1c5ff12f30973bbbfda1e949a7f7052efad132a5fa4fa14
 SHA512:
-  metadata.gz: 0eb9c0442393fea05b44c548f4ce5f249cdc64e0e13843cfc8200ba15e0f08797eda11f3ed9856b00cc521d36ef0d815d7f66cd6bcb7fd562f0c58c373afc4d5
-  data.tar.gz: 0d2a23b921e1341f76e0373844150e3fa633d83f186cbb3e6b2ee8817150d98898933ec7cd492ea621831e83f7007203d7bbe2b1caf6198a4742b54809534628
+  metadata.gz: c2aeeca823b3f3c028ee658f94b4e5fa6dfdb85eb99624e5aeb692a32b9ec003bd6d23cc710f5db4c57a2e2427da623c4364f47969ab80b79e5c6319713e9dff
+  data.tar.gz: 05051e8a1be1e70a61aee89ab026f318c34b3cc66fec8992bfbc1a302eeb3c2040888dc051cf0409135a820b824713c1c14e099becf554088a979deb2eee20b8

data/README.md

@@ -2,8 +2,14 @@
 
 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.
+remains in sequential order.
+
+It is useful for printing badges, tickets, or any other grid-based layout that is
+cut in bulk.
+
+It has a `two_sided_flipped` option to support printing on both sides of the
+paper, with the second side flipped, which can be used for printing traditional
+Tibetan books (called pechas) or for similar texts from various traditions.
 
 ## Installation
 
@@ -28,6 +34,9 @@ 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.order(entries: 8, rows: 2, columns: 2, two_sided_flipped: true)
+# => [1, 5, 6, 2, 3, 7, 8, 4]
+
 StackingOrder.visualize(entries: 6, rows: 2, columns: 2)
 # Prints page-by-page grids plus the stack order after cutting.
 ```
@@ -78,11 +87,12 @@ 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.
+This gem powers [stacked-pdf-generator](https://github.com/jeremy/stacked-pdf-generator), which provides the pdfjam/podofocrop
+tooling for producing final print-ready stacks.
+
+In turn, stacked-pdf-generator is used by [pecha-printer](https://github.com/jerefrer/pecha-printer) and the hosted service at
+<https://pecha-printer.frerejeremy.me>. Publishing the stacking logic separately lets other
+Ruby/Rails projects (or CLI scripts) reuse it without needing the full PDF pipeline.
 
 ## Development
 

data/lib/stacking_order/version.rb

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

data/lib/stacking_order.rb

@@ -14,13 +14,17 @@ module StackingOrder
   # @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:)
+  def order(entries:, rows:, columns:, two_sided_flipped: false)
     validate_arguments!(entries, rows, columns)
 
     return [] if entries.zero?
 
     cells_per_page = rows * columns
     num_pages = (entries.to_f / cells_per_page).ceil
+    # In two-sided printing, every physical sheet of paper carries a front
+    # and a back PDF page. An odd page count leaves the last paper with
+    # content only on the front, producing cut folios whose backs are blank.
+    num_pages += 1 if two_sided_flipped && num_pages.odd?
 
     result = []
 
@@ -31,6 +35,10 @@ module StackingOrder
       end
     end
 
+    if two_sided_flipped
+      result = apply_two_sided_flip(result, rows, columns)
+    end
+
     result.pop while result.last.nil?
     result
   end
@@ -38,8 +46,8 @@ module StackingOrder
   # 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)
+  def visualize(entries:, rows:, columns:, two_sided_flipped: false, io: $stdout)
+    result = order(entries: entries, rows: rows, columns: columns, two_sided_flipped: two_sided_flipped)
     cells_per_page = rows * columns
     num_pages = (entries.to_f / cells_per_page).ceil
 
@@ -73,6 +81,35 @@ module StackingOrder
     end
   end
 
+  def apply_two_sided_flip(result, rows, columns)
+    cells_per_page = rows * columns
+    result.each_slice(cells_per_page).with_index.flat_map do |page, page_index|
+      padded_page = pad_page(page, cells_per_page)
+      page_index.odd? ? flip_page_rows(padded_page, rows, columns) : padded_page
+    end
+  end
+
+  def pad_page(page, cells_per_page)
+    return page if page.length == cells_per_page
+
+    page + Array.new(cells_per_page - page.length)
+  end
+
+  def flip_page_rows(page, rows, columns)
+    if rows == 1
+      row_slice = page.slice(0, columns) || []
+      return row_slice.reverse
+    end
+
+    flipped = []
+    rows.times do |row_index|
+      source_row_index = rows - 1 - row_index
+      row_slice = page.slice(source_row_index * columns, columns) || []
+      flipped.concat(row_slice)
+    end
+    flipped
+  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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: stacking-order
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Jeremy
 bindir: exe
 cert_chain: []
-date: 2025-11-25 00:00:00.000000000 Z
+date: 2026-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest