uniword 1.0.0

data/lib/uniword/template/helpers/conditional_helper.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    module Helpers
+      # Helper for processing conditional markers in templates.
+      #
+      # Handles {{@if condition}} ... {{@end}} blocks by:
+      # 1. Evaluating condition
+      # 2. Removing content if false
+      # 3. Keeping content if true
+      #
+      # Responsibility: Conditional processing only
+      # Single Responsibility Principle: Does NOT parse or validate
+      #
+      # @example Process conditional
+      #   helper = ConditionalHelper.new(context)
+      #   helper.process(start_marker, end_marker, document)
+      class ConditionalHelper
+        # Initialize helper with context
+        #
+        # @param context [TemplateContext] Rendering context
+        def initialize(context)
+          @context = context
+        end
+
+        # Process conditional markers
+        #
+        # @param start_marker [TemplateMarker] Conditional start marker
+        # @param end_marker [TemplateMarker] Conditional end marker
+        # @param document [Document] Document to modify
+        # @return [void]
+        def process(start_marker, end_marker, document)
+          # Evaluate condition
+          resolver = @context.create_resolver
+          condition_result = resolver.evaluate(start_marker.condition)
+
+          # If condition is false, remove elements between markers
+          return if condition_result
+
+          remove_conditional_content(start_marker, end_marker, document)
+        end
+
+        private
+
+        # Remove content between conditional markers
+        #
+        # @param start_marker [TemplateMarker] Start marker
+        # @param end_marker [TemplateMarker] End marker
+        # @param document [Document] Document
+        # @return [void]
+        def remove_conditional_content(start_marker, end_marker, document)
+          # Find elements between markers
+          elements_to_remove = extract_conditional_elements(start_marker, end_marker, document)
+
+          # Remove each element from document
+          elements_to_remove.each do |element|
+            remove_element(element, document)
+          end
+        end
+
+        # Extract elements between markers
+        #
+        # @param start_marker [TemplateMarker] Start marker
+        # @param end_marker [TemplateMarker] End marker
+        # @param document [Document] Document
+        # @return [Array<Element>] Elements to remove
+        def extract_conditional_elements(start_marker, end_marker, document)
+          elements = []
+          in_block = false
+
+          document.paragraphs.each do |para|
+            # Check if this is the start marker's element
+            if para == start_marker.element
+              in_block = true
+              elements << para # Include start marker element
+              next
+            end
+
+            # Collect elements in block
+            next unless in_block
+
+            elements << para
+
+            # Check if this is the end marker's element
+            break if para == end_marker.element
+          end
+
+          elements
+        end
+
+        # Remove element from document
+        #
+        # @param element [Element] Element to remove
+        # @param document [Document] Document
+        # @return [void]
+        def remove_element(element, document)
+          # Remove from paragraphs
+          document.body.paragraphs.delete(element) if document.body.respond_to?(:paragraphs)
+
+          # Clear document cache
+          document.clear_element_cache if document.respond_to?(:clear_element_cache)
+        end
+      end
+    end
+  end
+end

data/lib/uniword/template/helpers/filter_helper.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    module Helpers
+      # Helper for applying filters to template values.
+      #
+      # Supports value transformations:
+      # - format: Date/time formatting
+      # - upcase: Uppercase text
+      # - downcase: Lowercase text
+      # - titleize: Title case text
+      # - capitalize: Capitalize first letter
+      # - currency: Format as currency
+      #
+      # Syntax: {{variable | filter}} or {{variable | filter: arg}}
+      #
+      # Responsibility: Filter application only
+      # Single Responsibility Principle: Does NOT parse or render
+      #
+      # @example Apply filters
+      #   helper = FilterHelper.new
+      #   result = helper.apply("hello", "upcase") # => "HELLO"
+      #   result = helper.apply(date, "format", "%Y-%m-%d")
+      class FilterHelper
+        # Apply filter to value
+        #
+        # @param value [Object] Value to filter
+        # @param filter_name [String] Filter name
+        # @param args [Array] Filter arguments
+        # @return [Object] Filtered value
+        def apply(value, filter_name, *args)
+          case filter_name.to_s
+          when 'format'
+            apply_format(value, args.first || '%Y-%m-%d')
+          when 'upcase'
+            value.to_s.upcase
+          when 'downcase'
+            value.to_s.downcase
+          when 'titleize'
+            titleize(value.to_s)
+          when 'capitalize'
+            value.to_s.capitalize
+          when 'currency'
+            apply_currency(value, args.first || 'USD')
+          when 'number'
+            apply_number_format(value, args.first)
+          when 'truncate'
+            truncate(value.to_s, args.first&.to_i || 30)
+          when 'strip'
+            value.to_s.strip
+          when 'reverse'
+            value.to_s.reverse
+          else
+            # Unknown filter - return value unchanged
+            value
+          end
+        end
+
+        private
+
+        # Apply date/time formatting
+        #
+        # @param value [Object] Value to format
+        # @param format_string [String] Format string
+        # @return [String] Formatted value
+        def apply_format(value, format_string)
+          if value.respond_to?(:strftime)
+            value.strftime(format_string)
+          else
+            value.to_s
+          end
+        rescue StandardError
+          value.to_s
+        end
+
+        # Apply currency formatting
+        #
+        # @param value [Object] Numeric value
+        # @param currency [String] Currency code
+        # @return [String] Formatted currency
+        def apply_currency(value, currency)
+          num = value.to_f
+          formatted = format('%.2f', num)
+          "#{currency} #{formatted}"
+        rescue StandardError
+          value.to_s
+        end
+
+        # Apply number formatting
+        #
+        # @param value [Object] Numeric value
+        # @param precision [String, Integer] Decimal precision
+        # @return [String] Formatted number
+        def apply_number_format(value, precision)
+          num = value.to_f
+          prec = precision ? precision.to_i : 2
+          format("%.#{prec}f", num)
+        rescue StandardError
+          value.to_s
+        end
+
+        # Convert to title case
+        #
+        # @param text [String] Text to convert
+        # @return [String] Title case text
+        def titleize(text)
+          text.split(/\s+/).map(&:capitalize).join(' ')
+        end
+
+        # Truncate text to length
+        #
+        # @param text [String] Text to truncate
+        # @param length [Integer] Maximum length
+        # @return [String] Truncated text
+        def truncate(text, length)
+          return text if text.length <= length
+
+          "#{text[0...length]}..."
+        end
+      end
+    end
+  end
+end

data/lib/uniword/template/helpers/loop_helper.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    module Helpers
+      # Helper for processing loop markers in templates.
+      #
+      # Handles {{@each collection}} ... {{@end}} blocks by:
+      # 1. Extracting elements between markers
+      # 2. Cloning for each collection item
+      # 3. Filling with scoped data
+      #
+      # Responsibility: Loop processing only
+      # Single Responsibility Principle: Does NOT parse or validate
+      #
+      # @example Process loop
+      #   helper = LoopHelper.new(context)
+      #   helper.process(start_marker, end_marker, document)
+      class LoopHelper
+        # Initialize helper with context
+        #
+        # @param context [TemplateContext] Rendering context
+        def initialize(context)
+          @context = context
+        end
+
+        # Process loop markers
+        #
+        # @param start_marker [TemplateMarker] Loop start marker
+        # @param end_marker [TemplateMarker] Loop end marker
+        # @param document [Document] Document to modify
+        # @return [void]
+        def process(start_marker, _end_marker, _document)
+          # Resolve collection from current context
+          resolver = @context.create_resolver
+          collection = resolver.resolve(start_marker.collection)
+
+          # Convert to array if needed
+          Array(collection)
+
+          # For now, we'll mark this as processed
+          # Full implementation would clone elements between markers
+          # and render each with scoped context
+          #
+          # This is a placeholder for the actual loop processing logic
+          # which would need deep cloning and element insertion
+        end
+
+        private
+
+        # Extract elements between markers
+        #
+        # @param start_marker [TemplateMarker] Start marker
+        # @param end_marker [TemplateMarker] End marker
+        # @param document [Document] Document
+        # @return [Array<Element>] Elements in loop
+        def extract_loop_elements(start_marker, end_marker, document)
+          elements = []
+          in_loop = false
+
+          document.paragraphs.each do |para|
+            # Check if this is the start marker's element
+            in_loop = true if para == start_marker.element
+
+            # Collect elements in loop
+            elements << para if in_loop && para != start_marker.element
+
+            # Check if this is the end marker's element
+            break if para == end_marker.element
+          end
+
+          elements
+        end
+
+        # Clone and fill element with data
+        #
+        # @param element [Element] Element to clone
+        # @param item_data [Object] Data for this iteration
+        # @return [Element] Cloned and filled element
+        def clone_and_fill(element, item_data)
+          # Create scoped context for this item
+          @context.push_scope(item_data)
+
+          # Clone element (shallow copy for now)
+          cloned = element.dup
+
+          # Fill variables in cloned element
+          fill_variables(cloned)
+
+          # Restore context
+          @context.pop_scope
+
+          cloned
+        end
+
+        # Fill variables in element
+        #
+        # @param element [Element] Element to fill
+        # @return [void]
+        def fill_variables(element)
+          resolver = @context.create_resolver
+
+          # Find and replace variables in element
+          # This is simplified - full implementation would
+          # recursively process all text nodes
+          return unless element.respond_to?(:text)
+
+          text = element.text
+          # Simple variable replacement ({{var}})
+          text.scan(/\{\{([^@].+?)\}\}/).each do |match|
+            var_name = match[0]
+            value = resolver.resolve(var_name)
+            element.text = text.gsub("{{#{var_name}}}", value.to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/template/helpers/variable_helper.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    module Helpers
+      # Helper for variable substitution in template elements.
+      #
+      # Replaces element content with resolved variable values.
+      # Handles different element types (Paragraph, Run, TableCell).
+      #
+      # Responsibility: Variable substitution only
+      # Single Responsibility Principle: Does NOT resolve or validate
+      #
+      # @example Replace paragraph content
+      #   helper = VariableHelper.new
+      #   helper.replace(paragraph, "New Content")
+      class VariableHelper
+        # Replace element content with value
+        #
+        # @param element [Element] Element to modify
+        # @param value [Object] Value to insert
+        # @return [void]
+        def replace(element, value)
+          # Convert value to string
+          text = value.to_s
+
+          case element
+          when Uniword::Wordprocessingml::Paragraph
+            replace_paragraph(element, text)
+          when Uniword::Wordprocessingml::Run
+            replace_run(element, text)
+          when Uniword::Wordprocessingml::TableCell
+            replace_cell(element, text)
+          else
+            # Try to treat as paragraph-like
+            replace_paragraph(element, text) if element.respond_to?(:runs)
+          end
+        end
+
+        private
+
+        # Replace paragraph content
+        #
+        # @param paragraph [Paragraph] Paragraph to modify
+        # @param text [String] New text content
+        # @return [void]
+        def replace_paragraph(paragraph, text)
+          # Clear existing runs
+          paragraph.runs.clear
+
+          # Add new text
+          run = Uniword::Wordprocessingml::Run.new(text: text)
+          paragraph.runs << run
+        end
+
+        # Replace run content
+        #
+        # @param run [Run] Run to modify
+        # @param text [String] New text content
+        # @return [void]
+        def replace_run(run, text)
+          run.text = text
+        end
+
+        # Replace cell content
+        #
+        # @param cell [TableCell] Cell to modify
+        # @param text [String] New text content
+        # @return [void]
+        def replace_cell(cell, text)
+          # Replace first paragraph's content
+          if cell.paragraphs.any?
+            replace_paragraph(cell.paragraphs.first, text)
+          else
+            # Create new paragraph with text
+            para = Uniword::Wordprocessingml::Paragraph.new
+            run = Uniword::Wordprocessingml::Run.new(text: text)
+            para.runs << run
+            cell.paragraphs << para
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uniword/template/helpers.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    module Helpers
+      autoload :ConditionalHelper, "#{__dir__}/helpers/conditional_helper"
+      autoload :LoopHelper, "#{__dir__}/helpers/loop_helper"
+      autoload :VariableHelper, "#{__dir__}/helpers/variable_helper"
+      autoload :FilterHelper, "#{__dir__}/helpers/filter_helper"
+    end
+  end
+end

data/lib/uniword/template/template.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# All Template classes autoloaded via lib/uniword/template.rb
+
+module Uniword
+  module Template
+    # Main template class for Word document templates.
+    #
+    # Represents a Word document with embedded Uniword template syntax
+    # in comments. Coordinates parsing and rendering to produce filled
+    # documents from data.
+    #
+    # Workflow:
+    # 1. Load template from .docx file
+    # 2. Extract markers from comments (via TemplateParser)
+    # 3. Render with data (via TemplateRenderer)
+    # 4. Save filled document
+    #
+    # @example Load and render template
+    #   template = Template.load('report_template.docx')
+    #   data = { title: "Annual Report", sections: [...] }
+    #   document = template.render(data)
+    #   document.save('filled_report.docx')
+    #
+    # @attr_reader [Document] document Template document
+    # @attr_reader [Array<TemplateMarker>] markers Extracted template markers
+    class Template
+      attr_reader :document, :markers
+
+      # Load template from .docx file
+      #
+      # @param template_path [String] Path to template file
+      # @return [Template] Loaded template
+      def self.load(template_path)
+        doc = Uniword::DocumentFactory.from_file(template_path)
+        new(doc)
+      end
+
+      # Initialize template with document
+      #
+      # @param document [Document] Template document
+      def initialize(document)
+        @document = document
+        @markers = extract_markers
+      end
+
+      # Render template with data
+      #
+      # Creates a new document by filling the template with provided data.
+      # Supports both Hash and custom object data sources.
+      #
+      # @param data [Hash, Object] Data to fill template
+      # @param context [Hash] Additional context variables
+      # @return [Document] Rendered document
+      #
+      # @example Render with hash
+      #   doc = template.render(title: "My Document")
+      #
+      # @example Render with custom object
+      #   doc = template.render(my_model_object)
+      #
+      # @example Render with context
+      #   doc = template.render(data, context: { author: "John" })
+      def render(data, context: {})
+        renderer = TemplateRenderer.new(self, data, context)
+        renderer.render
+      end
+
+      # Preview template structure
+      #
+      # Returns information about markers for debugging and validation.
+      #
+      # @return [Hash] Template structure info
+      def preview
+        {
+          markers: @markers.count,
+          variables: variables,
+          loops: loops,
+          conditionals: conditionals.count
+        }
+      end
+
+      # Get all variable markers
+      #
+      # @return [Array<String>] Variable names
+      def variables
+        @markers.select(&:variable?).map(&:expression)
+      end
+
+      # Get all loop markers
+      #
+      # @return [Array<Hash>] Loop information
+      def loops
+        loop_starts = @markers.select(&:loop_start?)
+        loop_starts.map { |m| { collection: m.collection, position: m.position } }
+      end
+
+      # Get all conditional markers
+      #
+      # @return [Array<TemplateMarker>] Conditional markers
+      def conditionals
+        @markers.select(&:conditional_start?)
+      end
+
+      # Check if document is a template
+      #
+      # @return [Boolean] true if contains markers
+      def template?
+        @markers.any?
+      end
+
+      # Validate template structure
+      #
+      # @return [Array<String>] Validation errors (empty if valid)
+      def validate
+        validator = TemplateValidator.new(self)
+        validator.validate
+      end
+
+      # Check if template is valid
+      #
+      # @return [Boolean] true if valid
+      def valid?
+        validate.empty?
+      end
+
+      # Inspect template for debugging
+      #
+      # @return [String] Readable representation
+      def inspect
+        "#<Uniword::Template markers=#{@markers.count} " \
+          "variables=#{variables.count} " \
+          "loops=#{loops.count}>"
+      end
+
+      private
+
+      # Extract markers from document
+      #
+      # @return [Array<TemplateMarker>] Extracted markers
+      def extract_markers
+        parser = TemplateParser.new(@document)
+        parser.parse
+      end
+    end
+  end
+end

data/lib/uniword/template/template_context.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    # Manages rendering context and scope during template processing.
+    #
+    # Handles nested scopes for loops and maintains the current data context.
+    # Provides clean scope isolation for loop iterations.
+    #
+    # Responsibility: Context management only
+    # Single Responsibility Principle: Does NOT parse, render, or resolve
+    #
+    # @example Simple context
+    #   context = TemplateContext.new(title: "My Document")
+    #   context.current_data # => {title: "My Document"}
+    #
+    # @example Nested context for loop
+    #   context = TemplateContext.new(chapters: [...])
+    #   context.push_scope(chapters.first)
+    #   # Now context.current_data is the first chapter
+    #   context.pop_scope
+    #   # Back to original context
+    class TemplateContext
+      attr_reader :root_data, :additional_context
+
+      # Initialize context with data
+      #
+      # @param root_data [Hash, Object] Root data object
+      # @param additional_context [Hash] Additional context variables
+      def initialize(root_data, additional_context = {})
+        @root_data = root_data
+        @additional_context = additional_context
+        @scope_stack = [root_data]
+      end
+
+      # Get current data scope
+      #
+      # @return [Object] Current scope data
+      def current_data
+        @scope_stack.last
+      end
+
+      # Push new scope onto stack
+      #
+      # Used when entering a loop or conditional block to create
+      # a new data context.
+      #
+      # @param scope_data [Object] Data for new scope
+      # @return [Object] The pushed scope data
+      def push_scope(scope_data)
+        @scope_stack.push(scope_data)
+        scope_data
+      end
+
+      # Pop scope from stack
+      #
+      # Returns to previous scope level.
+      #
+      # @return [Object] The popped scope data
+      def pop_scope
+        # Always keep at least root scope
+        return nil if @scope_stack.size <= 1
+
+        @scope_stack.pop
+      end
+
+      # Get current scope depth
+      #
+      # @return [Integer] Number of nested scopes
+      def depth
+        @scope_stack.size
+      end
+
+      # Check if in nested scope
+      #
+      # @return [Boolean] true if depth > 1
+      def nested?
+        depth > 1
+      end
+
+      # Create resolver for current scope
+      #
+      # @return [VariableResolver] Resolver with current context
+      def create_resolver
+        VariableResolver.new(current_data, @additional_context)
+      end
+
+      # Reset context to root scope
+      #
+      # @return [void]
+      def reset
+        @scope_stack = [@root_data]
+      end
+
+      # Inspect context for debugging
+      #
+      # @return [String] Readable representation
+      def inspect
+        "#<TemplateContext depth=#{depth} current=#{current_data.class.name}>"
+      end
+    end
+  end
+end