uniword 1.0.0

data/lib/uniword/template/template_marker.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    # Represents a template marker extracted from Word comments.
+    #
+    # A marker is an instruction embedded in a Word document comment that
+    # tells the template engine how to process content (variable substitution,
+    # loops, conditionals).
+    #
+    # Marker Types:
+    # - :variable - Simple variable substitution {{variable_name}}
+    # - :loop_start - Start of repeating section {{@each collection}}
+    # - :loop_end - End of repeating section {{@end}}
+    # - :conditional_start - Start of conditional {{@if condition}}
+    # - :conditional_end - End of conditional {{@end}}
+    #
+    # @example Variable marker
+    #   marker = TemplateMarker.new(
+    #     type: :variable,
+    #     expression: 'title',
+    #     element: paragraph,
+    #     position: 0
+    #   )
+    #
+    # @example Loop marker
+    #   marker = TemplateMarker.new(
+    #     type: :loop_start,
+    #     collection: 'clauses',
+    #     element: paragraph,
+    #     position: 5
+    #   )
+    #
+    # @attr_reader [Symbol] type Marker type
+    # @attr_reader [String] collection Collection name for loops
+    # @attr_reader [String] condition Condition expression for conditionals
+    # @attr_reader [String] expression Variable expression
+    # @attr_reader [Element] element The document element this marker is attached to
+    # @attr_reader [Integer] position Document position for sorting
+    class TemplateMarker
+      attr_reader :type, :collection, :condition, :expression,
+                  :element, :position
+
+      # Initialize a template marker
+      #
+      # @param attributes [Hash] Marker attributes
+      # @option attributes [Symbol] :type Marker type
+      # @option attributes [String] :collection Collection name (for loops)
+      # @option attributes [String] :condition Condition (for conditionals)
+      # @option attributes [String] :expression Variable expression
+      # @option attributes [Element] :element Document element
+      # @option attributes [Integer] :position Document position
+      def initialize(attributes)
+        @type = attributes[:type]
+        @collection = attributes[:collection]
+        @condition = attributes[:condition]
+        @expression = attributes[:expression]
+        @element = attributes[:element]
+        @position = attributes[:position]
+      end
+
+      # Check if marker is a loop start
+      #
+      # @return [Boolean] true if loop start
+      def loop_start?
+        @type == :loop_start
+      end
+
+      # Check if marker is a loop end
+      #
+      # @return [Boolean] true if loop end
+      def loop_end?
+        @type == :loop_end
+      end
+
+      # Check if marker is a conditional start
+      #
+      # @return [Boolean] true if conditional start
+      def conditional_start?
+        @type == :conditional_start
+      end
+
+      # Check if marker is a conditional end
+      #
+      # @return [Boolean] true if conditional end
+      def conditional_end?
+        @type == :conditional_end
+      end
+
+      # Check if marker is a variable
+      #
+      # @return [Boolean] true if variable
+      def variable?
+        @type == :variable
+      end
+
+      # Get marker name for display
+      #
+      # @return [String] Marker name
+      def name
+        case @type
+        when :variable
+          @expression
+        when :loop_start
+          @collection
+        when :conditional_start
+          @condition
+        else
+          @type.to_s
+        end
+      end
+
+      # Inspect marker for debugging
+      #
+      # @return [String] Readable representation
+      def inspect
+        "#<TemplateMarker type=#{@type} name=#{name.inspect} position=#{@position}>"
+      end
+    end
+  end
+end

data/lib/uniword/template/template_parser.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+# All Template classes autoloaded via lib/uniword/template.rb
+
+module Uniword
+  module Template
+    # Parses template syntax from Word document comments.
+    #
+    # Extracts template markers (variables, loops, conditionals) from
+    # comments attached to document elements. Converts Uniword template
+    # syntax into structured marker objects.
+    #
+    # Responsibility: Marker extraction only
+    # Single Responsibility Principle: Does NOT render or validate
+    #
+    # Template Syntax:
+    # - {{variable}} - Variable substitution
+    # - {{object.property}} - Nested property access
+    # - {{@each collection}} - Loop start
+    # - {{@end}} - Loop/conditional end
+    # - {{@if condition}} - Conditional start
+    # - {{@unless condition}} - Negative conditional
+    #
+    # @example Parse simple template
+    #   parser = TemplateParser.new(document)
+    #   markers = parser.parse
+    #   # Returns array of TemplateMarker objects
+    class TemplateParser
+      # Initialize parser with document
+      #
+      # @param document [Document] Document to parse
+      def initialize(document)
+        @document = document
+        @markers = []
+      end
+
+      # Parse all markers from document
+      #
+      # Iterates through paragraphs and tables, extracting markers
+      # from comments. Returns markers sorted by document position.
+      #
+      # @return [Array<TemplateMarker>] Sorted array of markers
+      def parse
+        @markers = []
+
+        # Parse paragraphs
+        parse_paragraphs(@document.paragraphs)
+
+        # Parse tables
+        parse_tables(@document.tables) if @document.tables.any?
+
+        # Sort markers by document order
+        @markers.sort_by(&:position)
+      end
+
+      private
+
+      # Parse markers from paragraphs
+      #
+      # @param paragraphs [Array<Paragraph>] Paragraphs to parse
+      # @return [void]
+      def parse_paragraphs(paragraphs)
+        paragraphs.each_with_index do |para, index|
+          # Check paragraph's own comments
+          if para.respond_to?(:comments) && para.comments
+            para.comments.each do |comment|
+              marker = parse_comment_text(comment.text, para, index)
+              @markers << marker if marker
+            end
+          end
+
+          # Check run comments
+          next unless para.respond_to?(:runs)
+
+          para.runs.each do |run|
+            next unless run.respond_to?(:comments) && run.comments
+
+            run.comments.each do |comment|
+              marker = parse_comment_text(comment.text, run, index)
+              @markers << marker if marker
+            end
+          end
+        end
+      end
+
+      # Parse markers from tables
+      #
+      # @param tables [Array<Table>] Tables to parse
+      # @return [void]
+      def parse_tables(tables)
+        tables.each_with_index do |table, table_index|
+          # Calculate base position for table
+          base_position = @document.paragraphs.size + (table_index * 100)
+
+          # Parse table rows
+          next unless table.respond_to?(:rows)
+
+          table.rows.each_with_index do |row, row_index|
+            row_position = base_position + (row_index * 10)
+
+            # Check row comments
+            if row.respond_to?(:comments) && row.comments
+              row.comments.each do |comment|
+                marker = parse_comment_text(comment.text, row, row_position)
+                @markers << marker if marker
+              end
+            end
+
+            # Parse cells
+            next unless row.respond_to?(:cells)
+
+            row.cells.each_with_index do |cell, _cell_index|
+              # Parse cell paragraphs
+              parse_paragraphs(cell.paragraphs) if cell.respond_to?(:paragraphs)
+            end
+          end
+        end
+      end
+
+      # Parse comment text to extract marker
+      #
+      # @param text [String] Comment text
+      # @param element [Element] Document element
+      # @param position [Integer] Document position
+      # @return [TemplateMarker, nil] Marker or nil if not valid syntax
+      def parse_comment_text(text, element, position)
+        return nil unless text
+
+        # Remove whitespace
+        clean_text = text.strip
+
+        # Parse different marker types
+        case clean_text
+        when /^\{\{@each\s+(\w+(\.\w+)*)\}\}$/
+          # Loop start: {{@each collection}}
+          TemplateMarker.new(
+            type: :loop_start,
+            collection: ::Regexp.last_match(1),
+            element: element,
+            position: position
+          )
+
+        when /^\{\{@end\}\}$/
+          # Loop/conditional end: {{@end}}
+          TemplateMarker.new(
+            type: :loop_end,
+            element: element,
+            position: position
+          )
+
+        when /^\{\{@if\s+(.+)\}\}$/
+          # Conditional: {{@if condition}}
+          TemplateMarker.new(
+            type: :conditional_start,
+            condition: ::Regexp.last_match(1),
+            element: element,
+            position: position
+          )
+
+        when /^\{\{@unless\s+(.+)\}\}$/
+          # Negative conditional: {{@unless condition}}
+          # Convert to @if with negation
+          TemplateMarker.new(
+            type: :conditional_start,
+            condition: "!(#{::Regexp.last_match(1)})",
+            element: element,
+            position: position
+          )
+
+        when /^\{\{([^@].+?)\}\}$/
+          # Variable: {{variable}} or {{object.property}}
+          TemplateMarker.new(
+            type: :variable,
+            expression: ::Regexp.last_match(1).strip,
+            element: element,
+            position: position
+          )
+
+        else
+          # Not a valid template marker
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/uniword/template/template_renderer.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+# All Template classes autoloaded via lib/uniword/template.rb
+# Helpers autoloaded via lib/uniword/template/helpers.rb
+
+module Uniword
+  module Template
+    # Renders templates by processing markers and filling with data.
+    #
+    # Takes a template and data, processes all markers in order,
+    # and produces a filled document. Handles variable substitution,
+    # loops, and conditionals.
+    #
+    # Responsibility: Template rendering only
+    # Single Responsibility Principle: Does NOT parse or validate
+    #
+    # @example Render simple template
+    #   renderer = TemplateRenderer.new(template, data, {})
+    #   document = renderer.render
+    class TemplateRenderer
+      # Initialize renderer
+      #
+      # @param template [Template] Template to render
+      # @param data [Hash, Object] Data to fill template
+      # @param additional_context [Hash] Additional context
+      def initialize(template, data, additional_context = {})
+        @template = template
+        @data = data
+        @additional_context = additional_context
+        @context = TemplateContext.new(data, additional_context)
+      end
+
+      # Render template with data
+      #
+      # Creates a new document by cloning the template document
+      # and processing all markers.
+      #
+      # @return [Document] Rendered document
+      def render
+        # Clone template document
+        output = clone_document(@template.document)
+
+        # Process markers
+        process_markers(output)
+
+        # Remove template comments
+        remove_template_comments(output)
+
+        output
+      end
+
+      private
+
+      # Clone document for output
+      #
+      # @param document [Document] Document to clone
+      # @return [Document] Cloned document
+      def clone_document(document)
+        # Create new document with same structure
+        # For now, we'll work with the document directly
+        # In production, this would create a deep copy
+        document
+      end
+
+      # Process all markers in document
+      #
+      # @param document [Document] Document to process
+      # @return [void]
+      def process_markers(document)
+        # Group markers by type for efficient processing
+        variable_markers = []
+        loop_pairs = []
+        conditional_pairs = []
+
+        # Find loop and conditional pairs
+        @template.markers.each do |marker|
+          case marker.type
+          when :variable
+            variable_markers << marker
+          when :loop_start
+            # Find matching end
+            end_marker = find_matching_end(marker, :loop_end)
+            loop_pairs << [marker, end_marker] if end_marker
+          when :conditional_start
+            # Find matching end
+            end_marker = find_matching_end(marker, :loop_end)
+            conditional_pairs << [marker, end_marker] if end_marker
+          end
+        end
+
+        # Process in order: conditionals, loops, then variables
+        conditional_pairs.each do |start_marker, end_marker|
+          process_conditional(start_marker, end_marker, document)
+        end
+        loop_pairs.each do |start_marker, end_marker|
+          process_loop(start_marker, end_marker, document)
+        end
+        variable_markers.each { |marker| process_variable(marker, document) }
+      end
+
+      # Find matching end marker
+      #
+      # @param start_marker [TemplateMarker] Start marker
+      # @param end_type [Symbol] End marker type to find
+      # @return [TemplateMarker, nil] Matching end marker
+      def find_matching_end(start_marker, end_type)
+        depth = 0
+        found_start = false
+
+        @template.markers.each do |marker|
+          if marker == start_marker
+            found_start = true
+            next
+          end
+
+          next unless found_start
+
+          # Track nesting depth
+          depth += 1 if marker.type == start_marker.type
+          depth -= 1 if marker.type == end_type
+
+          # Found matching end at same nesting level
+          return marker if depth.negative?
+        end
+
+        nil
+      end
+
+      # Process variable marker
+      #
+      # @param marker [TemplateMarker] Variable marker
+      # @param document [Document] Document to modify
+      # @return [void]
+      def process_variable(marker, _document)
+        resolver = @context.create_resolver
+        value = resolver.resolve(marker.expression)
+
+        # Replace element content with value
+        replace_element_content(marker.element, value)
+      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_loop(start_marker, end_marker, document)
+        helper = Helpers::LoopHelper.new(@context)
+        helper.process(start_marker, end_marker, document)
+      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_conditional(start_marker, end_marker, document)
+        helper = Helpers::ConditionalHelper.new(@context)
+        helper.process(start_marker, end_marker, document)
+      end
+
+      # Replace element content with value
+      #
+      # @param element [Element] Element to modify
+      # @param value [Object] Value to insert
+      # @return [void]
+      def replace_element_content(element, value)
+        helper = Helpers::VariableHelper.new
+        helper.replace(element, value)
+      end
+
+      # Remove template comments from document
+      #
+      # @param document [Document] Document to clean
+      # @return [void]
+      def remove_template_comments(document)
+        # Remove comments from paragraphs
+        document.paragraphs.each do |para|
+          next unless para.respond_to?(:comments)
+
+          # Filter out template comments
+          next unless para.respond_to?(:attached_comments)
+
+          para.attached_comments.reject! do |c|
+            template_comment?(c)
+          end
+        end
+      end
+
+      # Check if comment contains template syntax
+      #
+      # @param comment [Comment] Comment to check
+      # @return [Boolean] true if template comment
+      def template_comment?(comment)
+        return false unless comment.respond_to?(:text)
+
+        text = comment.text
+        text.match?(/^\{\{.+\}\}$/)
+      end
+    end
+  end
+end

data/lib/uniword/template/template_validator.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Template
+    # Validates template structure and syntax.
+    #
+    # Checks for common template errors:
+    # - Unclosed loops ({{@each}} without {{@end}})
+    # - Unclosed conditionals ({{@if}} without {{@end}})
+    # - Mismatched nesting
+    # - Invalid syntax
+    #
+    # Responsibility: Template validation only
+    # Single Responsibility Principle: Does NOT parse or render
+    #
+    # @example Validate template
+    #   validator = TemplateValidator.new(template)
+    #   errors = validator.validate
+    #   if errors.any?
+    #     puts "Template errors:"
+    #     errors.each { |e| puts "  - #{e}" }
+    #   end
+    class TemplateValidator
+      # Initialize validator
+      #
+      # @param template [Template] Template to validate
+      def initialize(template)
+        @template = template
+        @errors = []
+      end
+
+      # Validate template
+      #
+      # @return [Array<String>] Validation errors (empty if valid)
+      def validate
+        @errors = []
+
+        validate_loop_nesting
+        validate_conditional_nesting
+        validate_marker_syntax
+
+        @errors
+      end
+
+      private
+
+      # Validate loop nesting
+      #
+      # Checks that all {{@each}} have matching {{@end}}
+      #
+      # @return [void]
+      def validate_loop_nesting
+        depth = 0
+        loop_stack = []
+
+        @template.markers.each do |marker|
+          case marker.type
+          when :loop_start
+            depth += 1
+            loop_stack.push(marker)
+          when :loop_end
+            depth -= 1
+            loop_stack.pop
+
+            if depth.negative?
+              @errors << "Unmatched {{@end}} at position #{marker.position} " \
+                         'without corresponding {{@each}}'
+            end
+          end
+        end
+
+        # Check for unclosed loops
+        return unless depth.positive?
+
+        loop_stack.each do |unclosed|
+          @errors << "Unclosed loop {{@each #{unclosed.collection}}} " \
+                     "at position #{unclosed.position}: missing {{@end}}"
+        end
+      end
+
+      # Validate conditional nesting
+      #
+      # Checks that all {{@if}} have matching {{@end}}
+      #
+      # @return [void]
+      def validate_conditional_nesting
+        # Separate tracking for conditionals since they share {{@end}} with loops
+        conditional_stack = []
+
+        @template.markers.each do |marker|
+          case marker.type
+          when :conditional_start
+            conditional_stack.push(marker)
+          when :loop_end
+            # Could be closing a conditional
+            next if conditional_stack.empty?
+
+            # Check if this {{@end}} could be closing a conditional
+            # This is a simplified check - more sophisticated logic would track
+            # the nesting hierarchy properly
+            conditional_stack.pop if should_close_conditional?(marker, conditional_stack.last)
+          end
+        end
+
+        # Check for unclosed conditionals
+        conditional_stack.each do |unclosed|
+          @errors << "Unclosed conditional {{@if #{unclosed.condition}}} " \
+                     "at position #{unclosed.position}: missing {{@end}}"
+        end
+      end
+
+      # Check if end marker should close conditional
+      #
+      # @param end_marker [TemplateMarker] End marker
+      # @param conditional [TemplateMarker] Conditional start marker
+      # @return [Boolean] true if should close
+      def should_close_conditional?(end_marker, conditional)
+        # Simple heuristic: if end marker is after conditional and before next loop
+        return false unless end_marker && conditional
+
+        end_marker.position > conditional.position
+      end
+
+      # Validate marker syntax
+      #
+      # Checks for invalid or malformed markers
+      #
+      # @return [void]
+      def validate_marker_syntax
+        @template.markers.each do |marker|
+          case marker.type
+          when :variable
+            validate_variable_expression(marker)
+          when :loop_start
+            validate_loop_collection(marker)
+          when :conditional_start
+            validate_conditional_expression(marker)
+          end
+        end
+      end
+
+      # Validate variable expression
+      #
+      # @param marker [TemplateMarker] Variable marker
+      # @return [void]
+      def validate_variable_expression(marker)
+        expr = marker.expression
+
+        if expr.nil? || expr.strip.empty?
+          @errors << "Empty variable expression at position #{marker.position}"
+          return
+        end
+
+        # Check for valid identifier syntax
+        return if expr.match?(/^[a-zA-Z_]\w*(\.[a-zA-Z_]\w*)*$/)
+
+        @errors << "Invalid variable expression '#{expr}' at position #{marker.position}. " \
+                   'Expected format: variable or object.property'
+      end
+
+      # Validate loop collection
+      #
+      # @param marker [TemplateMarker] Loop marker
+      # @return [void]
+      def validate_loop_collection(marker)
+        collection = marker.collection
+
+        if collection.nil? || collection.strip.empty?
+          @errors << "Empty collection name in {{@each}} at position #{marker.position}"
+          return
+        end
+
+        # Check for valid identifier syntax
+        return if collection.match?(/^[a-zA-Z_]\w*(\.[a-zA-Z_]\w*)*$/)
+
+        @errors << "Invalid collection name '#{collection}' at position #{marker.position}. " \
+                   'Expected format: collection or object.collection'
+      end
+
+      # Validate conditional expression
+      #
+      # @param marker [TemplateMarker] Conditional marker
+      # @return [void]
+      def validate_conditional_expression(marker)
+        condition = marker.condition
+
+        if condition.nil? || condition.strip.empty?
+          @errors << "Empty condition in {{@if}} at position #{marker.position}"
+          return
+        end
+
+        # Basic syntax check - more sophisticated validation could be added
+        # Allow: variable, object.property, comparisons
+        valid_pattern = /^[\w.]+(\s*(==|!=|>|<|>=|<=)\s*[\w."']+)?$/
+
+        return if condition.match?(valid_pattern)
+
+        @errors << "Invalid condition syntax '#{condition}' at position #{marker.position}"
+      end
+    end
+  end
+end