liquid_xlsx 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77859fcf54ec602752b61cb982570912a6da4acfe35da51bf159a6afa641e552
-  data.tar.gz: adf22d59468df31118460448d0e6f4c84b3f2a16facc4cb5ff849ef652202ecc
+  metadata.gz: 619408f5440742c3210d5a61c30e44b16165d94ab673cefbb132b310310e0076
+  data.tar.gz: 208342e1abeed7c51352a204522030f16a36d8d7a3a08e1f6e07ca4a32f08a2d
 SHA512:
-  metadata.gz: 7a6de15d7778d554d86582f64e641d9dd328ef743adc4dba868e06c936b39eaed6093fca1ca533ebb5745856304710013a11d61af41b80df3b40ed5a56e08109
-  data.tar.gz: 76e95b63732e91ef4202efc71d80b1f791d84108d1857c9eac9d74ea3f0695d65ef7591ff7c4dcf28cf92d89c3b96caca81089de997a4fcf4ada199346532f3d
+  metadata.gz: 9edb7d9a0473e8220bf4a8f78f492369db9fea4a1b9c07fc4ce92c71f3d999848ce7e64ae53650c84f34541ef091e133f49aad47e96189c7163043c5f902ee13
+  data.tar.gz: f9054e1f438f9253f8a03e5e1dd8c806d9ab9e4465ccfbaa95df14d4bc0d8b42935213ad7adf820bd106fc992a5a4ec70d13974e93979128c54cda85bccffd97

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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

data/README.md

@@ -44,6 +44,7 @@ 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
@@ -133,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:
@@ -223,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` (и результат
@@ -683,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, форсировать пересчёт
@@ -698,6 +769,7 @@ LiquidXlsx.render(
 
 | Опция                  | По умолчанию | Описание                                                |
 |------------------------|--------------|---------------------------------------------------------|
+| `streaming`            | `false`      | Потоковый рендер в файл с ограничениями шаблона |
 | `strict_variables`     | `false`      | При `true` отсутствующая переменная → `MissingVariableError` |
 | `strict_filters`       | `false`      | При `true` неизвестный фильтр → исключение Liquid       |
 | `recalculate_formulas` | `false`      | Удалить `calcChain.xml`, форсировать пересчёт в Excel   |
@@ -807,7 +879,9 @@ LiquidXlsx::Error
 ├── RenderError                  ошибка рендера (включая {% sheet %}/{% image_tag %}),
 │   └── MissingVariableError     при strict_variables: true
 ├── UnsupportedTemplateError     merge через границу блока, неизвестный формат
-│                                картинки, отсутствие template-листа
+│   │                            картинки, отсутствие template-листа
+│   └── StreamingUnsupportedError  формулы, images, sheet или merges ниже цикла
+│                                  в потоковом режиме
 ├── InvalidXlsxError             битый .xlsx на входе
 └── OutputWriteError             ошибка записи выходного файла
 ```
@@ -898,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/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

data/lib/liquid_xlsx/streaming_renderer.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # An independent AST walker: output rows and loop iterations are never retained.
+  class StreamingRenderer < Renderer
+    # MRI sizes its young heap relative to live input, including large Arrays.
+    # Occasional minor collections bound transient XML garbage without changing
+    # process-wide GC configuration or retaining output metadata.
+    GC_ROW_INTERVAL = 16_384
+
+    TEXT_ESCAPES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", "\r" => "&#13;" }.freeze
+    ATTRIBUTE_ESCAPES = TEXT_ESCAPES.merge('"' => "&quot;", "\n" => "&#10;", "\t" => "&#9;").freeze
+
+    def prepare
+      @rows = worksheet.parse_rows
+      @merges = worksheet.merge_cells
+      validate_cells
+      @ast = TemplateParser.new(@rows, worksheet.name).parse
+      @merge_state = RenderState.new(MergeCellsTransformer.new, @merges, FormulaTranslator.new)
+      prepare_nodes(@ast)
+      @merge_state.check_block_boundaries(worksheet.name)
+      # Only endpoints of header merges need mapping, bounded by template size.
+      @merge_rows = @merges.flat_map { |m| [m[:start_row], m[:end_row]] }.uniq.to_h { |r| [r, true] }
+      self
+    end
+
+    # True when the sheet iterates a collection; a one-shot source must feed only one sheet.
+    def loops?
+      @loops == true
+    end
+
+    def render(data, **_unused)
+      prepare unless @ast
+      file = Tempfile.new(["liquid_xlsx_rows", ".xml"])
+      file.binmode
+      unless @rows.any? { |row| row[:cells].any? { |cell| cell[:template] } }
+        part = FilePart.new(file, worksheet.to_xml, "")
+        return part
+      end
+
+      context = streaming_context(data)
+      @output = file
+      @row_buffer = +""
+      @row_number = 0
+      @max_col_index = 0
+      @max_col = "A"
+      walk(@ast, context)
+      file.flush
+      worksheet.update_merge_cells(@merge_state.build_merge_ranges)
+      prefix, suffix = worksheet.streaming_envelope(@row_number, @max_col)
+      part = FilePart.new(file, prefix, suffix)
+      part
+    ensure
+      file&.close! unless part
+      @output = nil
+      @row_buffer = nil
+    end
+
+    private
+
+    def validate_cells
+      first_loop = @rows.find do |row|
+        row[:cells].any? { |c| c[:template]&.strip&.match?(TemplateParser::FOR_START) }
+      end
+      @rows.each do |row|
+        row[:cells].each do |cell|
+          if cell[:raw_cell].at_xpath("xmlns:f")
+            unsupported("Formulas are not supported in streaming mode", row[:row_number], cell[:col])
+          end
+          # Inspect all visible runs as well, including tags in unused branches.
+          text = cell[:text].to_s + cell[:raw_cell].xpath("xmlns:is//xmlns:t").map(&:text).join
+          next unless text.match?(/\{%-?\s*(?:image_tag|sheet)\b/)
+
+          unsupported("image_tag and sheet tags are not supported in streaming mode", row[:row_number], cell[:col])
+        end
+      end
+      return unless first_loop
+
+      @merges.each do |merge|
+        next if merge[:end_row] < first_loop[:row_number]
+
+        ref = CellReference.new(merge[:ref].split(":").first)
+        unsupported("Merges at or below the first loop are not supported in streaming mode", ref.row, ref.col)
+      end
+    end
+
+    def unsupported(message, row, col)
+      raise StreamingUnsupportedError.new(message, sheet: worksheet.name, row: row, cell: "#{col}#{row}")
+    end
+
+    def prepare_nodes(nodes)
+      nodes.each do |node|
+        case node
+        when Nodes::RowNode
+          row = node.row_data
+          row[:stream_attrs] = (row[:row_attrs] || {}).filter_map do |key, value|
+            %( #{key}="#{escape_attribute(value)}") if value
+          end.join
+          row[:cells].each do |cell|
+            cell[:stream_index] = CellReference.col_to_index(cell[:col])
+            cell[:stream_style] = cell[:style] ? %( s="#{escape_attribute(cell[:style])}") : ""
+            text = cell[:template]
+            match = text&.strip&.match(SINGLE_VAR)
+            cell[:stream_lookup] = Liquid::Expression.parse(match[1]) if match
+            cell[:stream_string_fast] = text&.match?(SINGLE_VAR)
+            cell[:stream_static] = static_cell(cell) unless text
+          end
+        when Nodes::ForNode
+          @loops = true
+          prepare_nodes(node.body)
+          prepare_nodes(node.else_body || [])
+        when Nodes::IfNode
+          @merge_state.enter_block(:if, node.if_row, node.endif_row)
+          prepare_nodes(node.branches.flat_map { |b| b[:body] })
+        end
+      end
+    end
+
+    def streaming_context(data)
+      normalized = normalize_data(data)
+      # Normalize the root without walking or duplicating collection arrays.
+      normalized = normalized.to_h { |key, value| [key.to_s, streaming_value(value)] } if normalized.is_a?(Hash)
+      context = StreamingContext.new(normalized, {}, {}, true)
+      context.strict_variables = @options.fetch(:strict_variables, false)
+      context.strict_filters = @options.fetch(:strict_filters, false)
+      context.add_filters(@options[:filters]) if @options[:filters]
+      apply_resource_limits(context)
+      context
+    end
+
+    def streaming_value(value)
+      return value unless value.is_a?(Hash)
+      return value if value.each_key.all?(String)
+
+      value.to_h { |key, item| [key.to_s, streaming_value(item)] }
+    end
+
+    def streaming_item(item)
+      return item if item.is_a?(Hash) && item.each_key.all?(String)
+
+      stringify_value(item)
+    end
+
+    def walk(nodes, context)
+      nodes.each do |node|
+        case node
+        when Nodes::RowNode then write_row(node.row_data, context)
+        when Nodes::ForNode then walk_for(node, context)
+        when Nodes::IfNode
+          branch = node.branches.find do |candidate|
+            candidate[:condition].nil? || evaluate_condition(candidate[:condition], context, node.if_row)
+          end
+          walk(branch[:body], context) if branch
+        end
+      end
+    end
+
+    def walk_for(node, context)
+      collection = if context.strict_variables
+                     strict_collection_lookup(context, node)
+                   else
+                     safe_context_lookup(context, node.collection_name)
+                   end
+      collection = [] if collection.nil?
+      unless collection.respond_to?(:each)
+        raise RenderError.new("Cannot iterate over #{collection.class}: expected an object with #each",
+                              sheet: worksheet.name, row: node.for_row)
+      end
+      size = collection.size if collection.respond_to?(:size)
+      size = nil unless size.is_a?(Integer)
+      loop_info = {}
+      loop_info["length"] = size if size
+      index = 0
+      collection.each do |item|
+        loop_info["index"] = index + 1
+        loop_info["index0"] = index
+        loop_info["first"] = index.zero?
+        if size
+          loop_info["last"] = index == size - 1
+          loop_info["rindex"] = size - index
+          loop_info["rindex0"] = size - index - 1
+        end
+        context.stack do
+          context[node.variable_name] = streaming_item(item)
+          context["forloop"] = loop_info
+          walk(node.body, context)
+        end
+        index += 1
+      end
+      walk(node.else_body, context) if index.zero? && node.else_body
+    end
+
+    def write_row(row, context)
+      @row_number += 1
+      number = @row_number.to_s
+      xml = @row_buffer.clear
+      xml << '<row r="' << number << '"' << row[:stream_attrs] << ">"
+      row[:cells].each do |cell|
+        if cell[:template]
+          value = streaming_cell_value(cell, context, row[:row_number])
+          next if (value.nil? || value == "") && !cell[:style]
+
+          xml << '<c r="' << cell[:col] << number << '"' << cell[:stream_style]
+          append_value(xml, value)
+        else
+          content = cell[:stream_static]
+          next unless content
+
+          xml << '<c r="' << cell[:col] << number << '"' << content
+        end
+        xml << "</c>"
+        if cell[:stream_index] > @max_col_index
+          @max_col_index = cell[:stream_index]
+          @max_col = cell[:col]
+        end
+      end
+      xml << "</row>\n"
+      @output.write(xml)
+      GC.start(full_mark: false) if (@row_number % GC_ROW_INTERVAL).zero?
+      @merge_state.record_row(row[:row_number], @row_number) if @merge_rows[row[:row_number]]
+    end
+
+    def streaming_cell_value(cell, context, row)
+      if (expression = cell[:stream_lookup])
+        value = begin
+          context.evaluate(expression)
+        rescue Liquid::UndefinedVariable, Liquid::UndefinedDropMethod
+          nil
+        end
+        return value if value.is_a?(String) && cell[:stream_string_fast] && !@options[:liquid_resource_limits]
+        return value if numeric_for_excel?(value) || value == true || value == false
+        return date_time_to_serial(value) if date_time?(value)
+
+        return render_liquid_cell(cell, context, row)
+      end
+      render_cell_template(cell, context, nil, row)
+    end
+
+    # The compiled lookup already performed the original type-preserving probe.
+    # Go straight to Liquid on fallback so nil/Drop methods are read twice, as
+    # before, rather than probing a third time through render_cell_template.
+    def render_liquid_cell(cell, context, row)
+      ref = "#{cell[:col]}#{row}"
+      context.registers[:liquid_xlsx_source_row] = row
+      context.registers[:liquid_xlsx_source_cell] = ref
+      coerce_value(cached_parse(cell[:template]).render(context))
+    rescue Liquid::UndefinedVariable, Liquid::UndefinedDropMethod => e
+      raise MissingVariableError.new("Missing variable: #{e.message}", sheet: worksheet.name,
+                                                                       row: row, cell: ref, template: cell[:template])
+    rescue Liquid::Error => e
+      raise RenderError.new("Liquid render error: #{e.message}", sheet: worksheet.name,
+                                                                 row: row, cell: ref, template: cell[:template])
+    end
+
+    def static_cell(cell)
+      style = cell[:stream_style]
+      if cell[:type] == "s" && cell[:text]
+        %(#{style} t="s"><v>#{escape_text(cell[:value].to_s)}</v>)
+      elsif cell[:type] != "inlineStr" && cell[:value]
+        type = cell[:type] ? %( t="#{escape_attribute(cell[:type])}") : ""
+        %(#{style}#{type}><v>#{escape_text(cell[:value])}</v>)
+      elsif cell[:text].nil? || cell[:text].empty?
+        serialize_value("", style) if cell[:style]
+      else
+        serialize_value(cell[:text], style)
+      end
+    end
+
+    # Static cell content is compiled once; dynamic cells append directly into
+    # the reused row buffer, avoiding two XML-sized temporary strings per cell.
+    def serialize_value(value, style)
+      xml = style.dup
+      append_value(xml, value)
+      xml
+    end
+
+    def append_value(xml, value)
+      case value
+      when String
+        text = Worksheet.sanitize_text(value)
+        xml << ' t="inlineStr"><is><t'
+        xml << ' xml:space="preserve"' if text.match?(/\A\s|\s\z/) || text.include?("\n")
+        xml << ">" << escape_text(text) << "</t></is>"
+      when Numeric then xml << "><v>" << value.to_s << "</v>"
+      when true, false then xml << ' t="b"><v>' << (value ? "1" : "0") << "</v>"
+      else append_value(xml, value.to_s)
+      end
+    end
+
+    def escape_text(text)
+      return text unless text.match?(/[&<>\r]/)
+
+      text.gsub(/[&<>\r]/, TEXT_ESCAPES)
+    end
+
+    def escape_attribute(text)
+      text.to_s.gsub(/[&<>"\r\n\t]/, ATTRIBUTE_ESCAPES)
+    end
+  end
+end

data/lib/liquid_xlsx/template.rb

@@ -14,7 +14,12 @@ module LiquidXlsx
     # @param data [Hash, Liquid::Drop, #to_liquid] data to render (Hash/Drop,
     #   or any object whose `#to_liquid` returns one)
     # @param output_path [String]
-    def render_to_file(data, output_path)
+    def render_to_file(data, output_path, **options)
+      unless options.empty?
+        configured = self.class.new(@template_path, @options.merge(options))
+        return configured.render_to_file(data, output_path)
+      end
+
       package = render_package(data)
       package.write(output_path)
     rescue LiquidXlsx::Error
@@ -22,6 +27,8 @@ module LiquidXlsx
     rescue Zip::Error, Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::EISDIR => e
       raise OutputWriteError,
             "Failed to write output '#{output_path}': #{e.class}: #{e.message}"
+    ensure
+      package&.close_file_parts
     end
 
     # Render template and return binary content.
@@ -29,6 +36,8 @@ module LiquidXlsx
     #   or any object whose `#to_liquid` returns one)
     # @return [String] binary .xlsx content
     def render(data)
+      raise ArgumentError, "Streaming requires render_to_file; binary output is not supported" if @options[:streaming]
+
       package = render_package(data)
       package.to_binary
     rescue LiquidXlsx::Error
@@ -63,7 +72,10 @@ module LiquidXlsx
               "Failed to read template '#{@template_path}': #{e.class}: #{e.message}"
       end
 
+      workbook_rendered = true
       package
+    ensure
+      package&.close_file_parts unless workbook_rendered
     end
   end
 end

data/lib/liquid_xlsx/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LiquidXlsx
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/liquid_xlsx/workbook.rb

@@ -16,6 +16,8 @@ module LiquidXlsx
     #   or any object whose `#to_liquid` returns one)
     # @return [Package] modified package
     def render(data)
+      return render_streaming(data) if @options[:streaming]
+
       all_image_ops = []
 
       if @options[:dynamic_sheets]
@@ -47,6 +49,31 @@ module LiquidXlsx
 
     private
 
+    # Preflight every worksheet before executing user data or creating row files.
+    def render_streaming(data)
+      renderers = package.sheets.map do |sheet_info|
+        worksheet = Worksheet.new(worksheet_xml!(sheet_info), sheet_info[:name], @shared_strings)
+        renderer = StreamingRenderer.new(worksheet, @options)
+        renderer.prepare
+        [sheet_info[:r_id], renderer]
+      end
+      looping = renderers.map(&:last).select(&:loops?)
+      if looping.size > 1
+        raise StreamingUnsupportedError.new(
+          "Only one worksheet may contain loops in streaming mode",
+          sheet: looping[1].worksheet.name
+        )
+      end
+      renderers.each do |r_id, renderer|
+        package.save_worksheet_xml(r_id, renderer.render(data))
+      end
+      if @options[:recalculate_formulas]
+        package.remove_calc_chain if package.calc_chain_xml
+        package.set_recalculation_flags
+      end
+      package
+    end
+
     # Worksheet part behind a <sheet> entry of workbook.xml.
     #
     # A workbook that lists a sheet whose part cannot be resolved is broken, and

data/lib/liquid_xlsx/worksheet.rb

@@ -303,6 +303,30 @@ module LiquidXlsx
       @doc.to_xml(indent: 0, encoding: "UTF-8")
     end
 
+    # Serialize only the small worksheet envelope; rows are supplied from disk.
+    def streaming_envelope(total_rows, max_col)
+      root = @doc.root
+      ns = { "xmlns" => root.namespace.href }
+      sheet_data = root.at_xpath("xmlns:sheetData", ns)
+      unless sheet_data
+        sheet_data = Nokogiri::XML::Node.new("sheetData", @doc)
+        self.class.insert_child_in_order(root, sheet_data)
+      end
+      sheet_data.children.remove
+      token = +"liquid_xlsx_rows"
+      comments = @doc.xpath("//comment()").map(&:content)
+      token << "_" while comments.include?(token)
+      marker = Nokogiri::XML::Comment.new(@doc, token)
+      sheet_data.add_child(marker)
+      dim = root.at_xpath("xmlns:dimension", ns)
+      unless dim
+        dim = Nokogiri::XML::Node.new("dimension", @doc)
+        self.class.insert_child_in_order(root, dim)
+      end
+      dim["ref"] = "A1:#{max_col}#{[total_rows, 1].max}"
+      to_xml.split("<!--#{token}-->", 2)
+    end
+
     # Extract row-level attributes to preserve.
     def row_attributes(row_elem)
       {

data/lib/liquid_xlsx.rb

@@ -15,9 +15,12 @@ require_relative "liquid_xlsx/tags/sheet_tag"
 require_relative "liquid_xlsx/tags/image_tag"
 require_relative "liquid_xlsx/image"
 require_relative "liquid_xlsx/drawing_builder"
+require_relative "liquid_xlsx/file_part"
 require_relative "liquid_xlsx/package"
 require_relative "liquid_xlsx/worksheet"
 require_relative "liquid_xlsx/renderer"
+require_relative "liquid_xlsx/streaming_context"
+require_relative "liquid_xlsx/streaming_renderer"
 require_relative "liquid_xlsx/workbook"
 require_relative "liquid_xlsx/template"
 require_relative "liquid_xlsx/validation/issue"
@@ -64,6 +67,7 @@ module LiquidXlsx
     #   Liquid::Drop, or any object whose `#to_liquid` returns a Hash/Drop.
     # @param strict_variables [Boolean] raise error on missing variables
     # @param strict_filters [Boolean] raise error on unknown filters
+    # @param streaming [Boolean] stream worksheet rows to disk (restricted templates)
     # @param dynamic_sheets [Boolean] enable {% sheet %} tag for dynamic sheet creation
     # @param hide_control_sheets [Boolean] hide sheets that contained {% sheet %} tags
     # @param hide_template_sheets [Boolean] hide template sheets after cloning
@@ -79,7 +83,7 @@ module LiquidXlsx
                recalculate_formulas: false, remove_template_comments: false,
                dynamic_sheets: false, hide_control_sheets: true,
                hide_template_sheets: false, images: nil,
-               liquid_resource_limits: nil, filters: nil)
+               liquid_resource_limits: nil, filters: nil, streaming: false)
       tpl = Template.new(template, {
                            strict_variables: strict_variables,
                            strict_filters: strict_filters,
@@ -90,7 +94,8 @@ module LiquidXlsx
                            hide_template_sheets: hide_template_sheets,
                            images: images || {},
                            liquid_resource_limits: liquid_resource_limits,
-                           filters: filters
+                           filters: filters,
+                           streaming: streaming
                          })
       # rubocop:enable Metrics/ParameterLists
       tpl.render_to_file(data, output)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: liquid_xlsx
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ivan Khlipitkin
@@ -100,6 +100,7 @@ files:
 - lib/liquid_xlsx/cell_reference.rb
 - lib/liquid_xlsx/drawing_builder.rb
 - lib/liquid_xlsx/errors.rb
+- lib/liquid_xlsx/file_part.rb
 - lib/liquid_xlsx/filters.rb
 - lib/liquid_xlsx/formula_translator.rb
 - lib/liquid_xlsx/image.rb
@@ -107,6 +108,8 @@ files:
 - lib/liquid_xlsx/package.rb
 - lib/liquid_xlsx/renderer.rb
 - lib/liquid_xlsx/shared_strings.rb
+- lib/liquid_xlsx/streaming_context.rb
+- lib/liquid_xlsx/streaming_renderer.rb
 - lib/liquid_xlsx/tags/image_tag.rb
 - lib/liquid_xlsx/tags/sheet_tag.rb
 - lib/liquid_xlsx/template.rb