liquid_xlsx 0.1.0

data/lib/liquid_xlsx/shared_strings.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # Reads and provides access to shared strings from xl/sharedStrings.xml.
+  class SharedStrings
+    # @param xml [String] XML content of sharedStrings.xml or nil if not present
+    def initialize(xml)
+      @strings = []
+      return unless xml
+      return if xml.strip.empty?
+
+      doc = Nokogiri::XML(xml)
+      ns = doc.root&.namespace
+      return unless ns
+
+      doc.xpath("//xmlns:si", "xmlns" => ns.href).each do |si|
+        t = si.at_xpath("xmlns:t")
+        @strings << if t
+                      t.text
+                    else
+                      # Handle rich text or other cases - extract all text
+                      si.xpath(".//xmlns:t").map(&:text).join
+                    end
+      end
+    end
+
+    # Get string by index.
+    # @param index [Integer]
+    # @return [String, nil]
+    def [](index)
+      @strings[index]
+    end
+
+    # Get the number of shared strings.
+    # @return [Integer]
+    def count
+      @strings.length
+    end
+
+    # Get the raw XML (preserved as-is for re-insertion).
+    # @return [String, nil]
+    def raw_xml
+      # We keep the original content — we never modify shared strings.
+      nil
+    end
+  end
+end

data/lib/liquid_xlsx/tags/image_tag.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  module Tags
+    # Handles the {% image_tag %} Liquid tag for inserting images.
+    #
+    # Syntax:
+    #   {% image_tag <src_expr> [, colspan: N, rowspan: N, to: "F10",
+    #                           width: N, height: N] %}
+    #
+    # Collects image insertion operations in context.registers[:liquid_xlsx_image_ops].
+    # Returns empty string (image lives in the drawing layer, not in the cell).
+    class ImageTag < Liquid::Tag
+      SYNTAX = /\A\s*(.+?)\s*(?:,\s*(.+))?\s*\z/
+      OPT_PAIR = /(\w+)\s*:\s*(?:"([^"]*)"|([^\s,]+))/
+
+      def initialize(tag_name, markup, options)
+        super
+
+        match = markup.match(SYNTAX)
+        raise_syntax("Expected: {% image_tag <expr> [, options] %}") unless match
+
+        @src_expr = match[1]&.strip
+        raise_syntax("Missing source expression") if @src_expr.nil? || @src_expr.empty?
+
+        @options = {}
+        match[2]&.scan(OPT_PAIR) do |key, quoted, bare|
+          val = quoted || bare
+          raise_syntax("Invalid option: #{key.inspect}") unless val
+
+          @options[key] = normalize_option(key, val)
+        end
+      end
+
+      def render(context)
+        src_val = evaluate_expr(@src_expr, context)
+
+        op = {
+          op: :insert_image,
+          source: src_val,
+          sheet_r_id: context.registers[:liquid_xlsx_sheet_r_id],
+          anchor_col: context.registers[:liquid_xlsx_anchor_col],
+          anchor_row: context.registers[:liquid_xlsx_anchor_row],
+          template_anchor_row: context.registers[:liquid_xlsx_template_anchor_row],
+          colspan: @options["colspan"],
+          rowspan: @options["rowspan"],
+          to: @options["to"],
+          width: @options["width"],
+          height: @options["height"],
+          source_sheet: context.registers[:liquid_xlsx_sheet_name],
+          source_cell: context.registers[:liquid_xlsx_source_cell]
+        }
+
+        ops = context.registers[:liquid_xlsx_image_ops] ||= []
+        ops << op
+
+        ""
+      end
+
+      private
+
+      def evaluate_expr(expr, context)
+        # Handle string literals
+        if expr.match?(/\A".*"\z/)
+          return expr[1..-2]
+        end
+
+        context[expr]
+      rescue Liquid::UndefinedVariable, Liquid::UndefinedDropMethod
+        raise RenderError.new(
+          "Undefined variable in image_tag: #{expr}",
+          sheet: context.registers[:liquid_xlsx_sheet_name],
+          row: context.registers[:liquid_xlsx_source_row],
+          cell: context.registers[:liquid_xlsx_source_cell],
+          template: "{% image_tag ... %}"
+        )
+      end
+
+      def normalize_option(key, val)
+        case key
+        when "colspan", "rowspan", "width", "height"
+          return val.to_i if val.match?(/\A\d+\z/)
+
+          raise_syntax("#{key} must be a positive integer, got: #{val.inspect}")
+        when "to"
+          val
+        else
+          raise_syntax("Unknown option: #{key.inspect}")
+        end
+      end
+
+      def raise_syntax(message)
+        raise Liquid::SyntaxError, "image_tag: #{message}"
+      end
+    end
+  end
+end

data/lib/liquid_xlsx/tags/sheet_tag.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  module Tags
+    # Handles the {% sheet %} Liquid tag for dynamic sheet creation.
+    #
+    # Syntax:
+    #   {% sheet name: <expr> template: "SheetName" data: <expr> as: "var_name" %}
+    #
+    # - +name+: Liquid expression for the new sheet name (e.g. "invoice.number")
+    # - +template+: quoted string — name of existing template sheet to clone
+    # - +data+: Liquid expression — object to pass as local variable
+    # - +as+: (optional) quoted string — local variable name, defaults to "item"
+    class SheetTag < Liquid::Tag
+      SYNTAX = /\A\s*(.+)\s*\z/
+      # Known argument keys. Values are split on the positions of these keys
+      # (not on whitespace) so that a name/data value may itself contain
+      # spaces and Liquid filters, e.g.: name: inv.number | append: " - "
+      KNOWN_KEYS = %w[name template data as].freeze
+      KEY_PATTERN = /\b(?:name|template|data|as)\s*:/
+
+      def initialize(tag_name, markup, options)
+        super
+
+        match = markup.match(SYNTAX)
+        unless match
+          raise_template_err(
+            "Invalid sheet tag syntax. Expected: {% sheet name: ... template: ... data: ... %}"
+          )
+        end
+
+        @args = parse_args(match[1])
+
+        raise_template_err("Missing required argument: name") unless @args["name"]
+        raise_template_err("Missing required argument: template") unless @args["template"]
+        raise_template_err("Missing required argument: data") unless @args["data"]
+
+        @name_arg = @args["name"]
+        @template_name = @args["template"][:value]
+        @data_arg = @args["data"]
+
+        # Validate that template and as are literals
+        raise_template_err("template must be a quoted string literal") unless @args["template"][:quoted]
+        raise_template_err("as must be a valid identifier") \
+          if @args["as"] && !@args["as"][:value].match?(/\A[A-Za-z_]\w*\z/)
+
+        @as_name = @args["as"] ? @args["as"][:value] : "item"
+      end
+
+      # Split "name: EXPR template: \"X\" data: EXPR as: VAR" into a hash of
+      # { key => { value:, quoted: } }. Values may contain spaces and Liquid
+      # filters because we cut the markup at the positions of the known keys.
+      #
+      # Keys are matched only OUTSIDE double-quoted strings, so a quoted value
+      # like name: "data: foo" is not mistaken for the `data:` key.
+      def parse_args(markup)
+        occurrences = []
+        in_quote = false
+        i = 0
+        while i < markup.length
+          ch = markup[i]
+          if ch == '"'
+            in_quote = !in_quote
+            i += 1
+            next
+          end
+
+          if !in_quote && (m = markup.match(KEY_PATTERN, i)) && m.begin(0) == i
+            key = m[0][/\A\w+/]
+            occurrences << { key: key, key_start: i, val_start: m.end(0) }
+            i = m.end(0)
+            next
+          end
+
+          i += 1
+        end
+        occurrences.sort_by! { |o| o[:key_start] }
+
+        args = {}
+        occurrences.each_with_index do |occ, i|
+          next_start = i + 1 < occurrences.length ? occurrences[i + 1][:key_start] : markup.length
+          raw = markup[occ[:val_start], next_start - occ[:val_start]]
+          raw = raw.strip.sub(/,\s*\z/, "").strip
+          raise_template_err("Empty value for argument: #{occ[:key].inspect}") if raw.empty?
+          raise_template_err("Duplicate argument: #{occ[:key].inspect}") if args.key?(occ[:key])
+
+          quoted = raw.start_with?('"') && raw.end_with?('"') && raw.length >= 2
+          val = quoted ? raw[1..-2] : raw
+          args[occ[:key]] = { value: val, quoted: quoted }
+        end
+        args
+      end
+
+      def render(context)
+        # Raise error if dynamic_sheets is disabled
+        unless context.registers[:liquid_xlsx_dynamic_sheets]
+          raise RenderError.new(
+            "Dynamic sheet creation is disabled. Pass dynamic_sheets: true.",
+            sheet: context.registers[:liquid_xlsx_sheet_name],
+            row: context.registers[:liquid_xlsx_source_row],
+            cell: context.registers[:liquid_xlsx_source_cell],
+            template: "{% sheet ... %}"
+          )
+        end
+
+        # Resolve name expression through Liquid context (supports filters)
+        name_val = evaluate_arg(@name_arg, context, expression: true)
+        name_val = name_val.to_s.strip
+
+        # Resolve data expression through Liquid context (preserves raw object)
+        data_val = evaluate_arg(@data_arg, context)
+
+        # Build operation with source context for error reporting
+        op = {
+          op: :create_sheet,
+          template_sheet: @template_name,
+          name: name_val,
+          data: data_val,
+          as: @as_name,
+          source_sheet: context.registers[:liquid_xlsx_sheet_name],
+          source_row: context.registers[:liquid_xlsx_source_row],
+          source_cell: context.registers[:liquid_xlsx_source_cell]
+        }
+
+        # Store operation in registers
+        ops = context.registers[:liquid_xlsx_workbook_ops] ||= []
+        ops << op
+
+        ""
+      end
+
+      private
+
+      def evaluate_arg(arg, context, expression: false)
+        # Quoted values are string literals (quotes were consumed by parse_args)
+        return arg[:value] if arg[:quoted]
+
+        if expression
+          # name supports Liquid filters/expressions; rendered to a string
+          ::Liquid::Template.parse("{{ #{arg[:value]} }}",
+                                   environment: LiquidXlsx.liquid_environment).render(context)
+        else
+          # data is resolved as a variable path to preserve the raw object
+          context[arg[:value]]
+        end
+      rescue Liquid::UndefinedVariable, Liquid::UndefinedDropMethod
+        raise RenderError.new(
+          "Undefined variable in sheet tag: #{arg[:value]}",
+          sheet: context.registers[:liquid_xlsx_sheet_name],
+          row: context.registers[:liquid_xlsx_source_row],
+          cell: context.registers[:liquid_xlsx_source_cell],
+          template: "{% sheet ... %}"
+        )
+      end
+
+      def raise_template_err(message)
+        raise Liquid::SyntaxError, message
+      end
+    end
+  end
+end

data/lib/liquid_xlsx/template.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  # Main template class for rendering .xlsx files.
+  class Template
+    # @param template_path [String] path to the .xlsx template
+    # @param options [Hash]
+    def initialize(template_path, options = {})
+      @template_path = template_path
+      @options = options
+    end
+
+    # Render template and save to file.
+    # @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)
+      package = render_package(data)
+      package.write(output_path)
+    rescue LiquidXlsx::Error
+      raise
+    rescue Zip::Error, Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::EISDIR => e
+      raise OutputWriteError,
+            "Failed to write output '#{output_path}': #{e.class}: #{e.message}"
+    end
+
+    # Render template and return binary content.
+    # @param data [Hash, Liquid::Drop, #to_liquid] data to render (Hash/Drop,
+    #   or any object whose `#to_liquid` returns one)
+    # @return [String] binary .xlsx content
+    def render(data)
+      package = render_package(data)
+      package.to_binary
+    rescue LiquidXlsx::Error
+      raise
+    rescue Zip::Error, Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::EISDIR => e
+      raise OutputWriteError,
+            "Failed to generate binary output: #{e.class}: #{e.message}"
+    end
+
+    private
+
+    def render_package(data)
+      package = Package.new(@template_path)
+
+      # Phase 1: read zip entries (no XML parsing yet).
+      begin
+        package.read
+      rescue Zip::Error, Errno::ENOENT, Errno::EACCES => e
+        raise InvalidXlsxError,
+              "Failed to read template '#{@template_path}': #{e.class}: #{e.message}"
+      end
+
+      workbook = Workbook.new(package, @options)
+
+      # Phase 2: render — lazy XML parsing of workbook_xml, rels, worksheet
+      # parts happens here. Nokogiri::XML::SyntaxError means the input xlsx
+      # contains corrupt XML and is not a valid template.
+      begin
+        workbook.render(data)
+      rescue Nokogiri::XML::SyntaxError => e
+        raise InvalidXlsxError,
+              "Failed to read template '#{@template_path}': #{e.class}: #{e.message}"
+      end
+
+      package
+    end
+  end
+end

data/lib/liquid_xlsx/template_nodes.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module LiquidXlsx
+  module Nodes
+    # Base node for the template AST.
+    class Base
+      def rows_after_render
+        raise NotImplementedError
+      end
+    end
+
+    # A single row in the template, unmodified.
+    class RowNode < Base
+      attr_reader :row_data
+
+      # row_data: {:row => row_xml_element, :cells => [cell_hash, ...]}
+      def initialize(row_data)
+        @row_data = row_data
+      end
+
+      def rows_after_render
+        1
+      end
+    end
+
+    # A for loop node: iterates over a collection.
+    class ForNode < Base
+      attr_reader :variable_name, :collection_name, :body, :else_body, :for_row, :endfor_row
+
+      def initialize(variable_name, collection_name, body, else_body = nil, for_row: nil, endfor_row: nil)
+        @variable_name = variable_name
+        @collection_name = collection_name
+        @body = body
+        @else_body = else_body
+        @for_row = for_row
+        @endfor_row = endfor_row
+      end
+
+      def rows_after_render
+        # Dynamic: depends on collection size
+        0 # mark as dynamic
+      end
+    end
+
+    # An if/elsif/else node: conditional block.
+    class IfNode < Base
+      attr_reader :branches, :if_row, :endif_row
+
+      # branches: [{condition:, body:}, ...]
+      # Last branch may have condition: nil for else
+      def initialize(branches, if_row: nil, endif_row: nil)
+        @branches = branches
+        @if_row = if_row
+        @endif_row = endif_row
+      end
+
+      def rows_after_render
+        0 # dynamic
+      end
+    end
+  end
+end