liquid_xlsx 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 405eceeb12cbc1b76e2bb0fa1ef24f351f544551268799cffd3f1265fa3bda7f
-  data.tar.gz: 13f0be15c97eaf8f21c8e4b4b1c4a2665032f8a8b7fc0ae885a1c1a2fb2cb126
+  metadata.gz: 619408f5440742c3210d5a61c30e44b16165d94ab673cefbb132b310310e0076
+  data.tar.gz: 208342e1abeed7c51352a204522030f16a36d8d7a3a08e1f6e07ca4a32f08a2d
 SHA512:
-  metadata.gz: 1677f21ae1c65f95cf62fe1728cdeadef70e96a051ed33a1ed7acf57eb2b9067e00f3f4d1901caf20d9d23f37edbec601cef7115704404e75eaaca160d1d6405
-  data.tar.gz: 9eda27bf7211ffc329af17e9ddf9992dcda7e551ff9526d62afb8df870e56d88381cd369acf120704ede782e10ded1650c410e97d71ebbf5159bff46b311e630
+  metadata.gz: 9edb7d9a0473e8220bf4a8f78f492369db9fea4a1b9c07fc4ce92c71f3d999848ce7e64ae53650c84f34541ef091e133f49aad47e96189c7163043c5f902ee13
+  data.tar.gz: f9054e1f438f9253f8a03e5e1dd8c806d9ab9e4465ccfbaa95df14d4bc0d8b42935213ad7adf820bd106fc992a5a4ec70d13974e93979128c54cda85bccffd97

data/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.4.0 (2026-10-25)
+
+### Added
+
+- Explicit `streaming: true` rendering to files, including `Template#render_to_file`.
+  Rows are serialized directly to a Tempfile without output DOM nodes or retained
+  row/cell hashes. Worksheet ZIP entries stream from disk with exact byte sizes
+  on rubyzip 2 and 3; temporary row files are released on success and failure.
+- Workbook-wide preflight with `StreamingUnsupportedError` coordinates for
+  formulas, images, sheet tags and merged ranges at or below the first loop.
+  Header merges, nested/consecutive loops, row conditions, shared Liquid context,
+  styles, dimensions, column widths and frozen panes are preserved.
+- Single-pass streaming loops over any object implementing `each`, including
+  sized/unsized and lazy Enumerators. Length-dependent `forloop` fields are only
+  available when `size` returns an Integer; otherwise they are empty or raise
+  `MissingVariableError` in strict mode.
+- Compiled simple-variable expressions in streaming cells. Strings avoid
+  repeated Liquid rendering; nil/missing values retain Liquid error semantics.
+  String-keyed row hashes and collection arrays are not copied.
+- `test_data/bench_stream.rb`: 19-column file-render benchmark for Array/Enumerator
+  input with wall time and peak RSS measurements, with or without YJIT.
+
+The default renderer is unchanged. Streaming binary-string output is explicitly
+rejected with `ArgumentError`.
+
+## 0.3.0 (2026-08-14)
+
+### Added
+
+- `LiquidXlsx.validate(template:)` — check a template without rendering it and
+  without any data. Returns a `Validation::Result` listing every problem found
+  instead of raising on the first one.
+
+  This is deliberately not "render it and see what happens". The renderer parses
+  only the Liquid it actually executes, so a mistake inside an `{% if %}` branch
+  the current document does not take, or inside a loop over an empty collection,
+  stays invisible until some other document hits it. Rendering also stops at the
+  first failure and runs the template against live records — a heavy price for
+  the question "is the file I just uploaded any good?".
+
+  Issue codes: `:invalid_xlsx`, `:missing_worksheet`, `:template_syntax`,
+  `:liquid_syntax`, `:liquid_expression` (warning), `:unknown_filter`,
+  `:sheet_tag_disabled`, `:sheet_template_missing`,
+  `:merged_cell_crosses_block`, `:liquid_in_formula` (warning),
+  `:liquid_in_rich_text` (warning). Each carries the sheet, row and cell it came
+  from, plus a stable `code` a host application can map to its own wording.
+
+  Beyond issues, the result reports what the template *uses*: `roots` (the input
+  variables it expects, with loop variables and `{% assign %}` names excluded),
+  full `variables` paths, and `filters` — so a host application can check them
+  against its own data model without parsing Liquid itself.
+
+- Two silent losses are now reported, both of which used to produce a document
+  with tags left in it and no error anywhere:
+  - Liquid inside a formula is never evaluated (`:liquid_in_formula`).
+  - Liquid inside a rich-text inline string — text split into runs because part
+    of the cell is formatted differently — is not read (`:liquid_in_rich_text`).
+
+- Expressions Liquid silently misreads are reported as warnings
+  (`:liquid_expression`): `{{ invoice.total b c }}` and `{{ invoice..total }}`
+  print the total and quietly drop the rest. Liquid's default lax parser accepts
+  them, so nothing fails — which is exactly why they are worth pointing out.
+  Only fragments the renderer would actually reject are errors.
+
+- `Tags::SheetTag#template_name` / `#as_name` are now public, so the sheet a
+  `{% sheet %}` clones can be checked without rendering the tag.
+
 ## 0.2.2 (2026-08-14)
 
 ### Fixed

data/README.md

@@ -44,7 +44,10 @@ Object API: `LiquidXlsx::Template.new(path).render_to_file(data, out)`, or
 - Formulas and merged ranges shift automatically as loops expand rows
 - `{% sheet %}` — generate whole worksheets from data
 - `{% image_tag %}` — embed PNG / JPEG / GIF
+- Explicit `streaming: true` file rendering for large, restricted templates
 - Errors report the sheet, row and cell they came from
+- `LiquidXlsx.validate` — check a template without data: every problem at once,
+  including the branches a trial render would never reach
 
 **Requirements:** Ruby >= 3.1. Works with both rubyzip 2.x and 3.x.
 
@@ -131,6 +134,75 @@ template.render_to_file(data, "output.xlsx") # рендер + запись в ф
 binary = template.render(data)                # рендер, возвращает бинарную строку
 ```
 
+## Потоковый режим
+
+Для выгрузок на сотни тысяч строк включите `streaming: true`. Каждая готовая
+строка сразу записывается во временный файл; строки результата и DOM листа
+в памяти не накапливаются. Затем лист записывается в ZIP с точным байтовым
+размером, без ZIP64. Временные файлы удаляются и при успехе, и при исключении.
+Без этой опции используется прежний рендер со всеми возможностями.
+
+```ruby
+rows = Enumerator.new do |output|
+  400_000.times do |index|
+    output << { "name" => "Product #{index}", "price" => index + 0.5 }
+  end
+end
+
+LiquidXlsx.render(template: "prices.xlsx", output: "prices_out.xlsx",
+                  data: { "rows" => rows }, streaming: true)
+
+# Объектный API: опция в конструкторе или для отдельного вызова.
+template = LiquidXlsx::Template.new("prices.xlsx", streaming: true)
+template.render_to_file(data, "prices_out.xlsx")
+LiquidXlsx::Template.new("prices.xlsx").render_to_file(data, "prices_out.xlsx", streaming: true)
+```
+
+`Template#render`, возвращающий бинарную строку, при `streaming: true`
+выбрасывает `ArgumentError`: потоковый результат нужно писать в файл.
+
+Поддерживаются вложенные и последовательные циклы, строки `{% if/elsif/else %}`,
+внутриячеечный Liquid, общий контекст `assign/capture`, стили ячеек и строк,
+высоты, ширины колонок, закрепление и объединения **выше первого цикла**.
+Пустые ячейки без стиля не записываются; `dimension` учитывает записанные
+ячейки и число выведенных строк.
+
+До исполнения данных проверяются **все листы и ветки шаблона**. Любая формула
+на листе, объединение в строке первого цикла или ниже (в том числе пересекающее
+его начало), `{% image_tag %}` и `{% sheet %}` вызывают
+`LiquidXlsx::StreamingUnsupportedError` с листом, строкой и ячейкой.
+Объединения через границу условного блока по-прежнему запрещены.
+
+Коллекцией цикла может быть любой объект с `each`: `Array`, `Enumerator`,
+`Enumerator::Lazy`, объект приложения или результат метода Drop. Гем вызывает
+`each` один раз на исполнение цикла; `for ... else` определяется по наличию
+выданных элементов. `size`, если он есть, должен возвращать число элементов
+без обхода коллекции. Только целый `Integer` считается известным размером.
+При неизвестном размере доступны `forloop.index`, `index0`, `first`;
+`length`, `last`, `rindex`, `rindex0` дают пустое значение в lenient-режиме и
+`MissingVariableError` с координатами при `strict_variables: true`.
+
+Для минимального расхода памяти передавайте Enumerator и Hash со строковыми
+ключами на всех уровнях. Такой Hash элемента передаётся в контекст без копии;
+Hash с другими ключами нормализуется при получении элемента. Массивы коллекций
+заранее не обходятся и не копируются. Уже созданный Array остаётся в памяти
+приложения; потоковый рендер устраняет дополнительное накопление результата.
+Шаблон, shared strings и остальные исходные части книги по-прежнему читаются
+в память; расход памяти зависит от их размера и от одной текущей строки.
+В потоковом режиме выполняется minor GC раз в 16 384 выведенные строки, чтобы
+ограничить временные аллокации при большом входном Array; настройки GC процесса
+не меняются. Для XML строк требуется свободное место во временном каталоге (rubyzip также
+использует временные файлы при сборке архива).
+
+Измерение полного рендера до готового файла, с пиковым приростом RSS из
+`/proc/self/status` (`VmHWM`), в отдельном процессе для каждого запуска:
+
+```bash
+bundle exec ruby test_data/bench_stream.rb normal array 20000
+bundle exec ruby test_data/bench_stream.rb streaming array 100000
+bundle exec ruby --yjit test_data/bench_stream.rb streaming enumerator 400000
+```
+
 ## Синтаксис шаблонов
 
 Библиотека разделяет два слоя Liquid:
@@ -221,8 +293,8 @@ LiquidXlsx.render(template: ..., output: ..., data: Report.new("Sales", 42))
   либо `#to_liquid`, возвращающий Hash/Drop. Произвольный объект только с
   методами-атрибутами, но без `to_liquid`, работать не будет — Liquid ищет
   переменные через `[]`.
-- Drop-методы, используемые в `{% for %}`, должны возвращать именно `Array`.
-  `Enumerable`/`ActiveRecord::Relation` напрямую не поддерживаются —
+- Drop-методы, используемые в `{% for %}`, в обычном режиме должны возвращать именно `Array`.
+  `Enumerable`/`ActiveRecord::Relation` в обычном режиме напрямую не поддерживаются —
   материализуйте их через `.to_a` в самом методе.
 - Если Drop-метод возвращает вложенный `Hash`, используйте **строковые** ключи:
   `stringify_keys` рекурсивно нормализует корневой `Hash` (и результат
@@ -681,6 +753,7 @@ LiquidXlsx.render(
   template:,
   output:,
   data:,
+  streaming: false,               # true — строки результата через временный файл
   strict_variables: false,        # true — raise на отсутствующей переменной
   strict_filters: false,          # true — raise на неизвестном фильтре
   recalculate_formulas: false,    # true — удалить calcChain, форсировать пересчёт
@@ -696,6 +769,7 @@ LiquidXlsx.render(
 
 | Опция                  | По умолчанию | Описание                                                |
 |------------------------|--------------|---------------------------------------------------------|
+| `streaming`            | `false`      | Потоковый рендер в файл с ограничениями шаблона |
 | `strict_variables`     | `false`      | При `true` отсутствующая переменная → `MissingVariableError` |
 | `strict_filters`       | `false`      | При `true` неизвестный фильтр → исключение Liquid       |
 | `recalculate_formulas` | `false`      | Удалить `calcChain.xml`, форсировать пересчёт в Excel   |
@@ -727,6 +801,72 @@ LiquidXlsx.render(template: "invoice.xlsx", output: "out.xlsx",
 на `Liquid::Environment` ничего не регистрируется — глобальная конфигурация
 Liquid в приложении остаётся нетронутой.
 
+## Проверка шаблона без рендера
+
+`LiquidXlsx.validate` разбирает шаблон и возвращает список всех найденных
+проблем. Данные не нужны, ничего не исполняется, на первой ошибке разбор не
+останавливается.
+
+```ruby
+result = LiquidXlsx.validate(
+  template: "invoice.xlsx",
+  known_filters: MyApp::Filters.public_instance_methods(false), # необязательно
+  dynamic_sheets: false                                          # как будете рендерить
+)
+
+result.valid?    # => false
+result.errors    # ошибки: документ не напечатается
+result.warnings  # предупреждения: напечатается, но не так, как задумано
+
+result.errors.first.code      # => :liquid_syntax
+result.errors.first.location  # => "Invoice!B12"
+```
+
+Почему это не «отрендерить и посмотреть»: рендер разбирает только тот Liquid,
+который реально исполняет. Опечатка в ветке `{% if %}`, которую этот документ не
+выбрал, или в теле цикла по пустой коллекции при пробном рендере не всплывёт — и
+дождётся другого документа. Плюс рендер выполняет шаблон на живых записях, что
+для проверки только что загруженного файла — лишнее.
+
+### Что находит
+
+| Код | Уровень | Что это |
+|---|---|---|
+| `:invalid_xlsx` | ошибка | файл не читается как книга `.xlsx` |
+| `:missing_worksheet` | ошибка | лист объявлен в `workbook.xml`, а его части в пакете нет |
+| `:template_syntax` | ошибка | непарные структурные теги, тег не на отдельной строке |
+| `:liquid_syntax` | ошибка | Liquid не разберёт фрагмент — рендер упадёт |
+| `:liquid_expression` | предупреждение | Liquid прочтёт выражение иначе, чем написано |
+| `:unknown_filter` | ошибка | фильтра не будет при рендере |
+| `:sheet_tag_disabled` | ошибка | `{% sheet %}` при `dynamic_sheets: false` |
+| `:sheet_template_missing` | ошибка | `{% sheet template: "X" %}`, а листа `X` нет |
+| `:merged_cell_crosses_block` | ошибка | объединение пересекает границу блока |
+| `:liquid_in_formula` | предупреждение | Liquid внутри формулы не вычисляется |
+| `:liquid_in_rich_text` | предупреждение | Liquid в ячейке с разным форматированием не читается |
+
+Разница между `:liquid_syntax` и `:liquid_expression` существенна.
+`{{ invoice.total b c }}` и `{{ invoice..total }}` Liquid принимает: печатает
+сумму, а лишнее молча выбрасывает. Документ выйдет, поэтому это предупреждение,
+а не ошибка — но в шаблоне написано не то, что имелось в виду.
+
+### Что шаблон использует
+
+```ruby
+result.roots      # => ["invoice", "customer"] — что шаблон ждёт на входе
+result.variables  # => [#<VariableUse root: "invoice", segments: ["items", "title"]>, ...]
+result.filters    # => ["money2", "date_words"]
+result.sheets     # => ["Invoice", "Приложение"]
+```
+
+`roots` — именно входные переменные: имена, которые шаблон заводит сам
+(`{% for item in ... %}`, `{% assign %}`, `{% capture %}`), из списка исключены.
+Так приложение может сверить шаблон со своей моделью данных, не разбирая Liquid
+самостоятельно.
+
+У пути есть признак `truncated?`: в `{{ items[i].title }}` за динамическим
+индексом проверять нечего, и об этом сказано явно — чтобы вызывающий код не
+объявил «нет такого поля» там, где поле определяется в рантайме.
+
 ## Обработка ошибок
 
 Все ошибки наследуются от `LiquidXlsx::Error < StandardError`. Там, где
@@ -739,7 +879,9 @@ LiquidXlsx::Error
 ├── RenderError                  ошибка рендера (включая {% sheet %}/{% image_tag %}),
 │   └── MissingVariableError     при strict_variables: true
 ├── UnsupportedTemplateError     merge через границу блока, неизвестный формат
-│                                картинки, отсутствие template-листа
+│   │                            картинки, отсутствие template-листа
+│   └── StreamingUnsupportedError  формулы, images, sheet или merges ниже цикла
+│                                  в потоковом режиме
 ├── InvalidXlsxError             битый .xlsx на входе
 └── OutputWriteError             ошибка записи выходного файла
 ```
@@ -830,7 +972,7 @@ LiquidXlsx.render(
 
 ```bash
 bundle install                        # установка зависимостей
-bundle exec rspec                     # полный набор тестов (420 примеров)
+bundle exec rspec                     # полный набор тестов
 bundle exec rspec spec/integration/   # только интеграционные
 bundle exec rubocop                   # линтер
 bundle exec rubocop -a                # автоисправление

data/lib/liquid_xlsx/errors.rb

@@ -74,6 +74,8 @@ module LiquidXlsx
     end
   end
 
+  class StreamingUnsupportedError < UnsupportedTemplateError; end
+
   class InvalidXlsxError < Error; end
 
   class OutputWriteError < Error; end

data/lib/liquid_xlsx/file_part.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module LiquidXlsx
+  # A worksheet envelope around rows on disk. Ownership passes to Package;
+  # neither the complete XML nor its ZIP input is accumulated in memory.
+  class FilePart
+    attr_reader :file
+
+    def initialize(file, prefix, suffix)
+      @file = file
+      @prefix = prefix
+      @suffix = suffix
+    end
+
+    def bytesize
+      @prefix.bytesize + @file.size + @suffix.bytesize
+    end
+
+    def write_to(output)
+      output.write(@prefix)
+      @file.rewind
+      IO.copy_stream(@file, output)
+      output.write(@suffix)
+    end
+
+    def close
+      @file.close!
+    end
+  end
+end

data/lib/liquid_xlsx/package.rb

@@ -123,6 +123,11 @@ module LiquidXlsx
       end
     end
 
+    # Release owned worksheet files on success and on any render/write failure.
+    def close_file_parts
+      @files.each_value { |content| content.close if content.is_a?(FilePart) }
+    end
+
     # Write modified content to a binary string.
     # @return [String]
     def to_binary
@@ -462,13 +467,25 @@ module LiquidXlsx
     # content it would disagree with what actually gets written.
     # See ZIP_SIZE_KEYWORD — rubyzip 2.x has no such keyword and needs none.
     def write_entry(zip, name, content)
-      if ZIP_SIZE_KEYWORD
+      if content.is_a?(FilePart)
+        write_file_entry(zip, name, content)
+      elsif ZIP_SIZE_KEYWORD
         zip.get_output_stream(name, size: content.bytesize) { |f| f.write(content) }
       else
         zip.get_output_stream(name) { |f| f.write(content) }
       end
     end
 
+    def write_file_entry(zip, name, content)
+      if ZIP_SIZE_KEYWORD
+        zip.get_output_stream(name, size: content.bytesize) { |f| content.write_to(f) }
+      else
+        entry = Zip::Entry.new("", name)
+        entry.size = content.bytesize
+        zip.get_output_stream(entry) { |f| content.write_to(f) }
+      end
+    end
+
     # Open a brand-new archive for writing across rubyzip 2.x and 3.x.
     # See ZIP_CREATE_KEYWORD for why the call has to be spelled two ways.
     def open_new_zip(output_path, &)

data/lib/liquid_xlsx/renderer.rb

@@ -741,18 +741,10 @@ module LiquidXlsx
 
     private
 
+    # Shared with Validator: the renderer only sees blocks it executes, the
+    # validator sees all of them, and the two must judge a crossing the same way.
     def crosses_boundary?(merge_start, merge_end, block_start, block_end)
-      # Merge entirely above or below the block
-      return false if merge_end < block_start || merge_start > block_end
-
-      # Merge strictly inside the block body (between the tag rows)
-      return false if merge_start > block_start && merge_end < block_end
-
-      # Merge entirely on a single structural tag row (it is consumed with it)
-      return false if merge_start == merge_end && (merge_start == block_start || merge_start == block_end)
-
-      # Any other overlap = crossing (including merges that swallow a tag row)
-      true
+      Validation::BlockBoundary.crosses?(merge_start, merge_end, block_start, block_end)
     end
 
     def clone_merge(ref, start_offset, end_offset)

data/lib/liquid_xlsx/streaming_context.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # Liquid does not define Object#to_liquid for arbitrary enumerables. Adapt
+  # only values read from the context, without mutating caller-owned hashes.
+  class StreamingContext < Liquid::Context
+    class Collection
+      def initialize(source)
+        @source = source
+      end
+
+      def to_liquid
+        self
+      end
+
+      def each(&)
+        @source.each(&)
+      end
+
+      def size
+        @source.size if @source.respond_to?(:size)
+      end
+    end
+
+    def lookup_and_evaluate(obj, key, **options)
+      value = super
+      if !value.respond_to?(:to_liquid) && value.respond_to?(:each)
+        Collection.new(value)
+      else
+        value
+      end
+    end
+  end
+end