uniword 1.0.0

data/lib/uniword/assembly/toc_instruction.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  module Assembly
+    # Table of Contents field instruction.
+    #
+    # Represents the TOC field code that Word uses to generate and update TOC.
+    # Example field code: { TOC \o "1-3" \h \z \u }
+    #
+    # @example Create TOC instruction
+    #   instr = TocInstruction.new(
+    #     outline_levels: "1-3",
+    #     hyperlinks: true,
+    #     hidden_formats: true,
+    #     use_paragraph_outline: true
+    #   )
+    class TocInstruction < Lutaml::Model::Serializable
+      # @return [String, nil] Outline levels to include (e.g., "1-3")
+      attribute :outline_levels, :string
+
+      # @return [Boolean] Include hyperlinks in TOC
+      attribute :hyperlinks, :boolean, default: -> { true }
+
+      # @return [Boolean] Use hidden formats
+      attribute :hidden_formats, :boolean, default: -> { true }
+
+      # @return [Boolean] Use paragraph outline level
+      attribute :use_paragraph_outline, :boolean, default: -> { true }
+
+      # @return [Boolean] Preserve tab stops
+      attribute :preserve_tabs, :boolean, default: -> { false }
+
+      # @return [String, nil] Custom separator
+      attribute :separator, :string
+
+      # @return [String, nil] Custom leader
+      attribute :leader, :string
+
+      # Generate the field instruction string.
+      #
+      # @return [String] The TOC field instruction
+      #
+      # @example
+      #   instr.to_s # => "TOC \\o \"1-3\" \\h \\z \\u"
+      def to_s
+        parts = ['TOC']
+
+        parts << "\\o \"#{outline_levels}\"" if outline_levels
+        parts << '\\h' if hyperlinks
+        parts << '\\z' if hidden_formats
+        parts << '\\u' if use_paragraph_outline
+        parts << '\\w' if preserve_tabs
+        parts << "\\s \"#{separator}\"" if separator
+        parts << "\\l \"#{leader}\"" if leader
+
+        parts.join(' ')
+      end
+
+      # Parse a TOC field instruction string.
+      #
+      # @param str [String] The field instruction string
+      # @return [TocInstruction] Parsed instruction
+      #
+      # @example
+      #   TocInstruction.parse('TOC \\o "1-3" \\h \\z')
+      def self.parse(str)
+        return nil if str.nil? || str.strip.empty?
+
+        instr = new
+
+        # Parse outline levels: \o "1-3"
+        instr.outline_levels = ::Regexp.last_match(1) if str =~ /\\o\s+"([^"]+)"/
+
+        # Parse switches
+        instr.hyperlinks = str.include?('\\h')
+        instr.hidden_formats = str.include?('\\z')
+        instr.use_paragraph_outline = str.include?('\\u')
+        instr.preserve_tabs = str.include?('\\w')
+
+        # Parse separator: \s "separator"
+        instr.separator = ::Regexp.last_match(1) if str =~ /\\s\s+"([^"]+)"/
+
+        # Parse leader: \l "leader"
+        instr.leader = ::Regexp.last_match(1) if str =~ /\\l\s+"([^"]+)"/
+
+        instr
+      end
+    end
+  end
+end

data/lib/uniword/assembly/variable_substitutor.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Assembly
+    # Performs variable substitution in document text.
+    #
+    # Responsibility: Replace {variable} placeholders with values.
+    # Single Responsibility: Only handles text substitution.
+    #
+    # The VariableSubstitutor:
+    # - Finds {variable} placeholders in text
+    # - Replaces with provided values
+    # - Supports nested variables (e.g., {doc.title})
+    # - Type-safe substitution with validation
+    # - Preserves formatting during substitution
+    #
+    # @example Basic substitution
+    #   sub = VariableSubstitutor.new({ title: "My Doc" })
+    #   result = sub.substitute("Title: {title}")
+    #   # => "Title: My Doc"
+    #
+    # @example Document substitution
+    #   sub = VariableSubstitutor.new(variables)
+    #   sub.substitute_document(document)
+    class VariableSubstitutor
+      # @return [Hash] Variables for substitution
+      attr_reader :variables
+
+      # Pattern to match variable placeholders
+      VARIABLE_PATTERN = /\{([a-zA-Z0-9_.]+)\}/
+
+      # Initialize substitutor with variables.
+      #
+      # @param variables [Hash] Variable name to value mapping
+      #
+      # @example Create substitutor
+      #   sub = VariableSubstitutor.new({
+      #     title: "ISO 8601",
+      #     date: "2026-01-15"
+      #   })
+      def initialize(variables = {})
+        @variables = normalize_variables(variables)
+      end
+
+      # Substitute variables in text.
+      #
+      # @param text [String] Text with {variable} placeholders
+      # @return [String] Text with variables replaced
+      #
+      # @example Substitute in text
+      #   result = sub.substitute("Title: {title}, Date: {date}")
+      def substitute(text)
+        return text unless text.is_a?(String)
+
+        text.gsub(VARIABLE_PATTERN) do |_match|
+          var_name = ::Regexp.last_match(1)
+          resolve_variable(var_name)
+        end
+      end
+
+      # Substitute variables in document.
+      #
+      # @param document [Document] Document to process
+      # @return [Document] Document with substituted text
+      #
+      # @example Process document
+      #   sub.substitute_document(document)
+      def substitute_document(document)
+        # Process all paragraphs
+        document.paragraphs.each do |paragraph|
+          substitute_paragraph(paragraph)
+        end
+
+        # Process sections (headers/footers)
+        if document.respond_to?(:sections)
+          document.sections.each do |section|
+            # Process headers if section has them
+            if section.respond_to?(:headers)
+              section.headers.each do |header|
+                header.paragraphs.each do |paragraph|
+                  substitute_paragraph(paragraph)
+                end
+              end
+            end
+
+            # Process footers if section has them
+            next unless section.respond_to?(:footers)
+
+            section.footers.each do |footer|
+              footer.paragraphs.each do |paragraph|
+                substitute_paragraph(paragraph)
+              end
+            end
+          end
+        end
+
+        document
+      end
+
+      # Add or update variable.
+      #
+      # @param name [String, Symbol] Variable name
+      # @param value [Object] Variable value
+      # @return [void]
+      #
+      # @example Set variable
+      #   sub.set_variable(:author, "John Doe")
+      def set_variable(name, value)
+        @variables[normalize_key(name)] = value
+      end
+
+      # Get variable value.
+      #
+      # @param name [String, Symbol] Variable name
+      # @return [Object, nil] Variable value
+      def get_variable(name)
+        resolve_variable_path(normalize_key(name))
+      end
+
+      # Check if variable is defined.
+      #
+      # @param name [String, Symbol] Variable name
+      # @return [Boolean] True if variable exists
+      def variable?(name)
+        key = normalize_key(name)
+        resolve_variable_path(key) != nil
+      end
+
+      # List all variables.
+      #
+      # @return [Array<String>] Variable names
+      def variable_names
+        collect_all_keys(@variables)
+      end
+
+      private
+
+      # Normalize variables hash.
+      #
+      # @param vars [Hash] Variables
+      # @return [Hash] Normalized variables
+      def normalize_variables(vars)
+        result = {}
+
+        vars.each do |key, value|
+          result[normalize_key(key)] = if value.is_a?(Hash)
+                                         normalize_variables(value)
+                                       else
+                                         value
+                                       end
+        end
+
+        result
+      end
+
+      # Normalize variable key.
+      #
+      # @param key [String, Symbol] Key
+      # @return [String] Normalized key
+      def normalize_key(key)
+        key.to_s
+      end
+
+      # Resolve variable by name.
+      #
+      # @param name [String] Variable name (may be nested)
+      # @return [String] Resolved value
+      def resolve_variable(name)
+        value = resolve_variable_path(name)
+
+        if value.nil?
+          # Return original placeholder if not found
+          "{#{name}}"
+        else
+          # Convert to string
+          value.to_s
+        end
+      end
+
+      # Resolve nested variable path.
+      #
+      # @param path [String] Variable path (e.g., 'doc.title')
+      # @return [Object, nil] Resolved value
+      def resolve_variable_path(path)
+        parts = path.split('.')
+        current = @variables
+
+        parts.each do |part|
+          return nil unless current.is_a?(Hash)
+          return nil unless current.key?(part)
+
+          current = current[part]
+        end
+
+        current
+      end
+
+      # Substitute variables in paragraph.
+      #
+      # @param paragraph [Paragraph] Paragraph to process
+      # @return [void]
+      def substitute_paragraph(paragraph)
+        paragraph.runs.each do |run|
+          substitute_run(run)
+        end
+      end
+
+      # Substitute variables in run.
+      #
+      # @param run [Run] Run to process
+      # @return [void]
+      def substitute_run(run)
+        return unless run.text
+
+        content = run.text.to_s
+        run.text = substitute(content)
+      end
+
+      # Collect all keys from nested hash.
+      #
+      # @param hash [Hash] Hash to process
+      # @param prefix [String] Key prefix
+      # @return [Array<String>] All keys
+      def collect_all_keys(hash, prefix = '')
+        keys = []
+
+        hash.each do |key, value|
+          full_key = prefix.empty? ? key : "#{prefix}.#{key}"
+          keys << full_key
+
+          keys.concat(collect_all_keys(value, full_key)) if value.is_a?(Hash)
+        end
+
+        keys
+      end
+    end
+  end
+end

data/lib/uniword/assembly.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Assembly
+    autoload :AssemblyManifest, "#{__dir__}/assembly/assembly_manifest"
+    autoload :ComponentRegistry, "#{__dir__}/assembly/component_registry"
+    autoload :CrossReferenceResolver, "#{__dir__}/assembly/cross_reference_resolver"
+    autoload :DocumentAssembler, "#{__dir__}/assembly/document_assembler"
+    autoload :Toc, "#{__dir__}/assembly/toc"
+    autoload :TocEntry, "#{__dir__}/assembly/toc_entry"
+    autoload :TocInstruction, "#{__dir__}/assembly/toc_instruction"
+    autoload :VariableSubstitutor, "#{__dir__}/assembly/variable_substitutor"
+  end
+end

data/lib/uniword/batch/batch_result.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require 'csv'
+
+module Uniword
+  module Batch
+    # Aggregates and reports results from batch document processing.
+    #
+    # Responsibility: Track processing results, statistics, and failures.
+    # Single Responsibility - only manages result aggregation and reporting.
+    #
+    # @example Tracking batch results
+    #   result = BatchResult.new
+    #   result.add_success(file: 'doc1.docx', duration: 1.5)
+    #   result.add_failure(file: 'doc2.docx', error: 'Invalid format')
+    #   puts result.summary
+    #
+    # @example Export results
+    #   result.export_json('results.json')
+    #   result.export_csv('results.csv')
+    class BatchResult
+      attr_reader :successes, :failures, :start_time, :end_time
+
+      # Initialize batch result tracker
+      def initialize
+        @successes = []
+        @failures = []
+        @start_time = Time.now
+        @end_time = nil
+      end
+
+      # Mark processing as completed
+      #
+      # @return [self]
+      def complete!
+        @end_time = Time.now
+        self
+      end
+
+      # Add a successful processing result
+      #
+      # @param file [String] File path that was processed
+      # @param duration [Float] Processing duration in seconds
+      # @param stages [Array<String>] List of stages executed
+      # @param metadata [Hash] Additional metadata
+      # @return [self]
+      def add_success(file:, duration: 0.0, stages: [], metadata: {})
+        @successes << {
+          file: file,
+          duration: duration,
+          stages: stages,
+          metadata: metadata,
+          timestamp: Time.now
+        }
+        self
+      end
+
+      # Add a failed processing result
+      #
+      # @param file [String] File path that failed
+      # @param error [String, Exception] Error message or exception
+      # @param stage [String, nil] Stage where failure occurred
+      # @param metadata [Hash] Additional metadata
+      # @return [self]
+      def add_failure(file:, error:, stage: nil, metadata: {})
+        error_message = error.is_a?(Exception) ? error.message : error.to_s
+        error_class = error.is_a?(Exception) ? error.class.name : 'Error'
+
+        @failures << {
+          file: file,
+          error: error_message,
+          error_class: error_class,
+          stage: stage,
+          metadata: metadata,
+          timestamp: Time.now
+        }
+        self
+      end
+
+      # Get total number of files processed
+      #
+      # @return [Integer] Total count
+      def total_count
+        successes.size + failures.size
+      end
+
+      # Get number of successful files
+      #
+      # @return [Integer] Success count
+      def success_count
+        successes.size
+      end
+
+      # Get number of failed files
+      #
+      # @return [Integer] Failure count
+      def failure_count
+        failures.size
+      end
+
+      # Get success rate as percentage
+      #
+      # @return [Float] Success rate (0.0 to 100.0)
+      def success_rate
+        return 0.0 if total_count.zero?
+
+        (success_count.to_f / total_count * 100).round(2)
+      end
+
+      # Get elapsed processing time in seconds
+      #
+      # @return [Float] Elapsed time
+      def elapsed_time
+        end_time = @end_time || Time.now
+        (end_time - @start_time).round(2)
+      end
+
+      # Get average processing time per successful document
+      #
+      # @return [Float] Average time in seconds
+      def average_duration
+        return 0.0 if successes.empty?
+
+        total = successes.sum { |s| s[:duration] }
+        (total / successes.size).round(2)
+      end
+
+      # Check if batch processing was successful (no failures)
+      #
+      # @return [Boolean] true if all files processed successfully
+      def success?
+        failures.empty?
+      end
+
+      # Get summary statistics
+      #
+      # @return [Hash] Summary statistics
+      def summary
+        {
+          total: total_count,
+          successes: success_count,
+          failures: failure_count,
+          success_rate: success_rate,
+          elapsed_time: elapsed_time,
+          average_duration: average_duration
+        }
+      end
+
+      # Get formatted summary text
+      #
+      # @return [String] Summary text
+      def summary_text
+        lines = []
+        lines << 'Batch Processing Results'
+        lines << ('=' * 40)
+        lines << "Total files:      #{total_count}"
+        lines << "Successful:       #{success_count}"
+        lines << "Failed:           #{failure_count}"
+        lines << "Success rate:     #{success_rate}%"
+        lines << "Elapsed time:     #{elapsed_time}s"
+        lines << "Average duration: #{average_duration}s" if success_count.positive?
+        lines.join("\n")
+      end
+
+      # Export results to JSON file
+      #
+      # @param path [String] Output file path
+      # @return [self]
+      def export_json(path)
+        data = {
+          summary: summary,
+          successes: successes,
+          failures: failures
+        }
+
+        File.write(path, JSON.pretty_generate(data))
+        self
+      end
+
+      # Export results to YAML file
+      #
+      # @param path [String] Output file path
+      # @return [self]
+      def export_yaml(path)
+        data = {
+          'summary' => summary,
+          'successes' => successes.map { |s| stringify_keys(s) },
+          'failures' => failures.map { |f| stringify_keys(f) }
+        }
+
+        File.write(path, YAML.dump(data))
+        self
+      end
+
+      # Export results to CSV file
+      #
+      # @param path [String] Output file path
+      # @return [self]
+      def export_csv(path)
+        CSV.open(path, 'wb') do |csv|
+          # Header row
+          csv << %w[File Status Duration Error Stage]
+
+          # Success rows
+          successes.each do |success|
+            csv << [
+              success[:file],
+              'SUCCESS',
+              success[:duration],
+              '',
+              success[:stages].join(', ')
+            ]
+          end
+
+          # Failure rows
+          failures.each do |failure|
+            csv << [
+              failure[:file],
+              'FAILURE',
+              '',
+              failure[:error],
+              failure[:stage] || ''
+            ]
+          end
+        end
+        self
+      end
+
+      private
+
+      # Convert hash keys to strings
+      #
+      # @param hash [Hash] Hash with symbol keys
+      # @return [Hash] Hash with string keys
+      def stringify_keys(hash)
+        hash.transform_keys(&:to_s).transform_values do |value|
+          value.is_a?(Hash) ? stringify_keys(value) : value
+        end
+      end
+    end
+  end
+end