uniword 1.0.0

data/lib/uniword/infrastructure/zip_extractor.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'zip'
+
+module Uniword
+  module Infrastructure
+    # Extracts content from ZIP archives (e.g., DOCX files).
+    #
+    # Responsibility: Handle ZIP file extraction operations.
+    # Does NOT handle: Document parsing or deserialization.
+    #
+    # DOCX files are ZIP archives containing XML files and media.
+    # This class provides low-level ZIP extraction functionality.
+    #
+    # @example Extract content from a DOCX file
+    #   extractor = Uniword::Infrastructure::ZipExtractor.new
+    #   content = extractor.extract("document.docx")
+    #   xml = content["word/document.xml"]
+    class ZipExtractor
+      # Extract all files from a ZIP archive or stream.
+      #
+      # @param path [String, IO, StringIO] The path to the ZIP file or stream
+      # @return [Hash<String, String>] Hash mapping file paths to contents
+      # @raise [ArgumentError] if path is invalid
+      # @raise [Zip::Error] if ZIP extraction fails
+      def extract(path)
+        # Handle streams directly
+        return extract_from_stream(path) if path.is_a?(IO) || path.is_a?(StringIO)
+
+        validate_path(path)
+
+        content = {}
+
+        Zip::File.open(path) do |zip_file|
+          zip_file.each do |entry|
+            next if entry.directory?
+
+            content[entry.name] = entry.get_input_stream.read.force_encoding('UTF-8')
+          end
+
+          # Explicitly extract theme if present
+          theme_entry = zip_file.find_entry('word/theme/theme1.xml')
+          if theme_entry && !content.key?('word/theme/theme1.xml')
+            content['word/theme/theme1.xml'] =
+              theme_entry.get_input_stream.read.force_encoding('UTF-8')
+          end
+        end
+
+        content
+      end
+
+      # Extract from IO or StringIO stream
+      #
+      # @param stream [IO, StringIO] The stream to extract from
+      # @return [Hash<String, String>] Hash mapping file paths to contents
+      def extract_from_stream(stream)
+        content = {}
+
+        Zip::File.open_buffer(stream) do |zip_file|
+          zip_file.each do |entry|
+            next if entry.directory?
+
+            content[entry.name] = entry.get_input_stream.read.force_encoding('UTF-8')
+          end
+
+          # Explicitly extract theme if present
+          theme_entry = zip_file.find_entry('word/theme/theme1.xml')
+          if theme_entry && !content.key?('word/theme/theme1.xml')
+            content['word/theme/theme1.xml'] =
+              theme_entry.get_input_stream.read.force_encoding('UTF-8')
+          end
+        end
+
+        content
+      end
+
+      # Extract a specific file from a ZIP archive.
+      #
+      # @param path [String] The path to the ZIP file
+      # @param entry_path [String] The path of the file within the ZIP
+      # @return [String, nil] The file content, or nil if not found
+      # @raise [ArgumentError] if path is invalid
+      def extract_file(path, entry_path)
+        validate_path(path)
+
+        Zip::File.open(path) do |zip_file|
+          entry = zip_file.find_entry(entry_path)
+          return nil unless entry
+
+          entry.get_input_stream.read.force_encoding('UTF-8')
+        end
+      end
+
+      # List all files in a ZIP archive.
+      #
+      # @param path [String] The path to the ZIP file
+      # @return [Array<String>] Array of file paths within the ZIP
+      # @raise [ArgumentError] if path is invalid
+      def list_files(path)
+        validate_path(path)
+
+        files = []
+
+        Zip::File.open(path) do |zip_file|
+          zip_file.each do |entry|
+            files << entry.name unless entry.directory?
+          end
+        end
+
+        files
+      end
+
+      private
+
+      # Validate the file path.
+      #
+      # @param path [String, IO, StringIO] The path or stream to validate
+      # @return [void]
+      # @raise [ArgumentError] if path is invalid
+      def validate_path(path)
+        raise ArgumentError, 'Path cannot be nil' if path.nil?
+
+        # Allow IO and StringIO objects
+        return if path.is_a?(IO) || path.is_a?(StringIO)
+
+        # For strings, validate as file path
+        raise ArgumentError, 'Path cannot be empty' if path.respond_to?(:empty?) && path.empty?
+        raise ArgumentError, "File not found: #{path}" unless File.exist?(path)
+        raise ArgumentError, "Path is a directory: #{path}" if File.directory?(path)
+      end
+    end
+  end
+end

data/lib/uniword/infrastructure/zip_packager.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require 'zip'
+require 'fileutils'
+
+module Uniword
+  module Infrastructure
+    # Packages content into ZIP archives (e.g., DOCX files).
+    #
+    # Responsibility: Handle ZIP file creation and packaging operations.
+    # Does NOT handle: Document serialization or format-specific logic.
+    #
+    # DOCX files are ZIP archives containing XML files and media.
+    # This class provides low-level ZIP packaging functionality.
+    #
+    # @example Package content into a DOCX file
+    #   packager = Uniword::Infrastructure::ZipPackager.new
+    #   content = {
+    #     "word/document.xml" => xml_content,
+    #     "[Content_Types].xml" => types_content
+    #   }
+    #   packager.package(content, "output.docx")
+    class ZipPackager
+      # Package content into a ZIP file.
+      #
+      # @param content [Hash<String, String>] Hash mapping file paths to contents
+      # @param output_path [String] The path for the output ZIP file
+      # @return [void]
+      # @raise [ArgumentError] if arguments are invalid
+      #
+      # @note On Windows, Zip::File::CREATE mode fails when target exists
+      # because Rubyzip tries to atomically rename a temp file over it.
+      # We use a temp file approach to avoid this issue.
+      def package(content, output_path)
+        validate_content(content)
+        validate_output_path(output_path)
+
+        # Ensure output directory exists
+        FileUtils.mkdir_p(File.dirname(output_path))
+
+        # Use temp file to avoid Windows atomic rename issues
+        # Rubyzip's CREATE mode fails when output_path exists
+        temp_path = "#{output_path}.#{Process.pid}.tmp"
+
+        Zip::File.open(temp_path, Zip::File::CREATE) do |zip_file|
+          content.each do |entry_path, entry_content|
+            zip_file.get_output_stream(entry_path) do |stream|
+              # Binary data (ASCII-8BIT) is written as-is;
+              # text content is ensured to be UTF-8
+              final_content =
+                if entry_content.encoding == Encoding::ASCII_8BIT
+                  entry_content
+                else
+                  entry_content.encode(
+                    'UTF-8', invalid: :replace, undef: :replace
+                  )
+                end
+              stream.write(final_content)
+            end
+          end
+        end
+
+        # On Windows, the handle may still be held briefly after block ends
+        # and FileUtils.mv (rename) can fail with EACCES on locked files.
+        # Use File.binwrite + unlink instead, which is more Windows-friendly.
+        retries = 10
+        begin
+          FileUtils.rm_f(output_path)
+          # Wait for Windows to release the lock
+          sleep(0.5)
+          # Copy content instead of renaming to avoid rename locks
+          File.binwrite(output_path, File.binread(temp_path))
+          FileUtils.rm_f(temp_path)
+        rescue Errno::EACCES
+          retries -= 1
+          if retries > 0
+            sleep(0.5)
+            retry
+          else
+            raise
+          end
+        end
+      ensure
+        # Clean up temp file if it still exists
+        FileUtils.rm_f(temp_path) if defined?(temp_path) && temp_path && File.exist?(temp_path)
+      end
+
+      # Add a file to an existing ZIP archive.
+      #
+      # @param zip_path [String] The path to the ZIP file
+      # @param entry_path [String] The path for the file within the ZIP
+      # @param entry_content [String] The content to add
+      # @return [void]
+      # @raise [ArgumentError] if arguments are invalid
+      #
+      # @note On Windows, we must close the original ZIP handle before
+      # attempting to overwrite it. We extract content first, then close
+      # the handle, then package to a temp file and move.
+      def add_file(zip_path, entry_path, entry_content)
+        validate_zip_path(zip_path)
+        raise ArgumentError, 'Entry path cannot be nil' if entry_path.nil?
+        raise ArgumentError, 'Entry path cannot be empty' if entry_path.empty?
+
+        # Extract existing content into a local variable
+        content = {}
+        Zip::File.open(zip_path) do |zip_file|
+          zip_file.each do |entry|
+            next if entry.directory?
+            content[entry.name] = entry.get_input_stream.read
+          end
+        end
+        # Handle is now fully closed before we modify the file
+
+        # Add new entry and write to a temp file first, then move
+        content[entry_path] = entry_content
+        write_to_zip_file(content, zip_path)
+      end
+
+      # Remove a file from a ZIP archive.
+      #
+      # @param zip_path [String] The path to the ZIP file
+      # @param entry_path [String] The path of the file to remove
+      # @return [Boolean] true if file was removed, false if not found
+      # @raise [ArgumentError] if arguments are invalid
+      #
+      # @note On Windows, we must close the original ZIP handle before
+      # attempting to overwrite it. We extract content first, then close
+      # the handle, then write to a temp file and move.
+      def remove_file(zip_path, entry_path)
+        validate_zip_path(zip_path)
+
+        # Extract existing content into a local variable
+        content = {}
+        found = false
+        Zip::File.open(zip_path) do |zip_file|
+          zip_file.each do |entry|
+            next if entry.directory?
+            if entry.name == entry_path
+              found = true
+            else
+              content[entry.name] = entry.get_input_stream.read
+            end
+          end
+        end
+        # Handle is now fully closed before we modify the file
+
+        return false unless found
+
+        write_to_zip_file(content, zip_path)
+        true
+      end
+
+      private
+
+      # Write content to a ZIP file using a temp file and atomic move.
+      # This avoids Windows file locking issues by ensuring we never
+      # write directly to the target file while it might be open.
+      #
+      # @param content [Hash<String, String>] Hash mapping file paths to contents
+      # @param output_path [String] The path for the output ZIP file
+      # @return [void]
+      def write_to_zip_file(content, output_path)
+        temp_path = "#{output_path}.#{Process.pid}.#{rand(1000)}.tmp"
+
+        Zip::File.open(temp_path, Zip::File::CREATE) do |zip_file|
+          content.each do |entry_path, entry_content|
+            zip_file.get_output_stream(entry_path) do |stream|
+              final_content =
+                if entry_content.encoding == Encoding::ASCII_8BIT
+                  entry_content
+                else
+                  entry_content.encode(
+                    'UTF-8', invalid: :replace, undef: :replace
+                  )
+                end
+              stream.write(final_content)
+            end
+          end
+        end
+
+        # On Windows, the handle may still be held briefly after block ends
+        # and FileUtils.mv (rename) can fail with EACCES on locked files.
+        # Use File.binwrite + unlink instead, which is more Windows-friendly.
+        retries = 10
+        begin
+          FileUtils.rm_f(output_path)
+          # Wait for Windows to release the lock
+          sleep(0.5)
+          # Copy content instead of renaming to avoid rename locks
+          File.binwrite(output_path, File.binread(temp_path))
+          FileUtils.rm_f(temp_path)
+        rescue Errno::EACCES
+          retries -= 1
+          if retries > 0
+            sleep(0.5)
+            retry
+          else
+            raise
+          end
+        end
+      ensure
+        FileUtils.rm_f(temp_path) if File.exist?(temp_path)
+      end
+
+      # Validate the content hash.
+      #
+      # @param content [Object] The content to validate
+      # @return [void]
+      # @raise [ArgumentError] if content is invalid
+      def validate_content(content)
+        raise ArgumentError, 'Content cannot be nil' if content.nil?
+        raise ArgumentError, 'Content must be a Hash' unless content.is_a?(Hash)
+        raise ArgumentError, 'Content cannot be empty' if content.empty?
+
+        content.each do |path, data|
+          raise ArgumentError, 'Entry path cannot be nil' if path.nil?
+          raise ArgumentError, 'Entry path cannot be empty' if path.empty?
+          raise ArgumentError, "Entry content cannot be nil for #{path}" if data.nil?
+        end
+      end
+
+      # Validate the output path.
+      #
+      # @param path [String] The path to validate
+      # @return [void]
+      # @raise [ArgumentError] if path is invalid
+      def validate_output_path(path)
+        raise ArgumentError, 'Output path cannot be nil' if path.nil?
+        raise ArgumentError, 'Output path cannot be empty' if path.empty?
+
+        dir = File.dirname(path)
+        return unless File.exist?(dir)
+        return if File.directory?(dir)
+
+        raise ArgumentError, "Parent path is not a directory: #{dir}"
+      end
+
+      # Validate the ZIP path for modification operations.
+      #
+      # @param path [String] The path to validate
+      # @return [void]
+      # @raise [ArgumentError] if path is invalid
+      def validate_zip_path(path)
+        raise ArgumentError, 'ZIP path cannot be nil' if path.nil?
+        raise ArgumentError, 'ZIP path cannot be empty' if path.empty?
+      end
+    end
+  end
+end

data/lib/uniword/infrastructure.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Uniword
+  module Infrastructure
+    autoload :ZipExtractor, "#{__dir__}/infrastructure/zip_extractor"
+    autoload :ZipPackager, "#{__dir__}/infrastructure/zip_packager"
+    autoload :MimeParser, "#{__dir__}/infrastructure/mime_parser"
+    autoload :MimePackager, "#{__dir__}/infrastructure/mime_packager"
+  end
+end

data/lib/uniword/lazy_loader.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Uniword
+  # Module for lazy loading attributes to reduce memory footprint.
+  #
+  # Lazy loading delays the loading of data until it is actually needed,
+  # which helps reduce memory usage for large documents.
+  #
+  # @example Using lazy attributes
+  #   class Document
+  #     extend LazyLoader
+  #
+  #     lazy_attr :paragraphs do
+  #       # Load paragraphs only when accessed
+  #       parse_paragraphs_from_xml
+  #     end
+  #   end
+  module LazyLoader
+    # Define a lazy attribute that loads only when first accessed.
+    #
+    # The loader block is executed once on first access, and the result
+    # is cached for subsequent accesses.
+    #
+    # @param name [Symbol] The attribute name
+    # @param loader [Proc] Block that returns the attribute value
+    # @return [void]
+    #
+    # @example Define a lazy attribute
+    #   lazy_attr :images do
+    #     load_images_from_disk
+    #   end
+    def lazy_attr(name, &loader)
+      raise ArgumentError, 'Block required for lazy_attr' unless loader
+
+      # Define getter method
+      define_method(name) do
+        instance_variable = "@#{name}"
+
+        # Return cached value if already loaded
+        if instance_variable_defined?(instance_variable)
+          return instance_variable_get(instance_variable)
+        end
+
+        # Load and cache the value
+        value = instance_exec(&loader)
+        instance_variable_set(instance_variable, value)
+        value
+      end
+
+      # Define predicate method to check if loaded
+      define_method("#{name}_loaded?") do
+        instance_variable_defined?("@#{name}")
+      end
+
+      # Define method to clear cached value
+      define_method("clear_#{name}") do
+        remove_instance_variable("@#{name}") if instance_variable_defined?("@#{name}")
+      end
+    end
+
+    # Define a lazy collection attribute with batch loading.
+    #
+    # Similar to lazy_attr but optimized for collections that can be
+    # loaded in batches or filtered on demand.
+    #
+    # @param name [Symbol] The collection attribute name
+    # @param loader [Proc] Block that returns the collection
+    # @return [void]
+    #
+    # @example Define a lazy collection
+    #   lazy_collection :tables do
+    #     load_tables_from_xml
+    #   end
+    def lazy_collection(name, &loader)
+      raise ArgumentError, 'Block required for lazy_collection' unless loader
+
+      # Define getter that returns array
+      define_method(name) do
+        instance_variable = "@#{name}"
+
+        # Return cached collection if already loaded
+        if instance_variable_defined?(instance_variable)
+          return instance_variable_get(instance_variable)
+        end
+
+        # Load and cache the collection
+        collection = instance_exec(&loader)
+        collection = [] if collection.nil?
+        collection = Array(collection) unless collection.is_a?(Array)
+
+        instance_variable_set(instance_variable, collection)
+        collection
+      end
+
+      # Define method to check if collection is loaded
+      define_method("#{name}_loaded?") do
+        instance_variable_defined?("@#{name}")
+      end
+
+      # Define method to clear cached collection
+      define_method("clear_#{name}") do
+        remove_instance_variable("@#{name}") if instance_variable_defined?("@#{name}")
+      end
+
+      # Define method to get collection size without loading all items
+      define_method("#{name}_count") do
+        instance_variable = "@#{name}"
+        if instance_variable_defined?(instance_variable)
+          return instance_variable_get(instance_variable).size
+        end
+
+        # If not loaded, try to get count without loading
+        # This is a hook for subclasses to override
+        send(name).size
+      end
+    end
+  end
+end

data/lib/uniword/line_numbering.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Uniword
+  # Represents line numbering configuration for a section
+  #
+  # Line numbering displays line numbers in the margin of a document section.
+  # It's commonly used in legal documents and academic papers.
+  #
+  # @example Continuous line numbering
+  #   ln = LineNumbering.new(
+  #     start: 1,
+  #     count_by: 1,
+  #     restart: 'continuous'
+  #   )
+  #
+  # @example Line numbering restarting on each page
+  #   ln = LineNumbering.new(
+  #     count_by: 5,
+  #     restart: 'newPage',
+  #     distance: 360
+  #   )
+  #
+  # @attr [Integer] start Starting line number
+  # @attr [Integer] count_by Increment for numbering (e.g., 5 = 5, 10, 15...)
+  # @attr [String] restart When to restart numbering
+  # @attr [Integer] distance Distance from text in twips
+  class LineNumbering < Lutaml::Model::Serializable
+    # Restart options
+    RESTART_OPTIONS = %w[continuous newPage newSection].freeze
+
+    attribute :start, :integer, default: -> { 1 }
+    attribute :count_by, :integer, default: -> { 1 }
+    attribute :restart, :string, default: -> { 'newPage' }
+    attribute :distance, :integer, default: -> { 360 } # 0.25 inch
+
+    def initialize(**attributes)
+      super
+      validate_restart
+      validate_start
+      validate_count_by
+    end
+
+    # Create continuous line numbering (never restarts)
+    #
+    # @param count_by [Integer] Increment
+    # @param distance [Integer] Distance from text
+    # @return [LineNumbering] New instance
+    def self.continuous(count_by: 1, distance: 360)
+      new(
+        start: 1,
+        count_by: count_by,
+        restart: 'continuous',
+        distance: distance
+      )
+    end
+
+    # Create line numbering that restarts on each page
+    #
+    # @param count_by [Integer] Increment
+    # @param distance [Integer] Distance from text
+    # @return [LineNumbering] New instance
+    def self.per_page(count_by: 1, distance: 360)
+      new(
+        start: 1,
+        count_by: count_by,
+        restart: 'newPage',
+        distance: distance
+      )
+    end
+
+    # Create line numbering that restarts on each section
+    #
+    # @param count_by [Integer] Increment
+    # @param distance [Integer] Distance from text
+    # @return [LineNumbering] New instance
+    def self.per_section(count_by: 1, distance: 360)
+      new(
+        start: 1,
+        count_by: count_by,
+        restart: 'newSection',
+        distance: distance
+      )
+    end
+
+    # Check if numbering is continuous (never restarts)
+    #
+    # @return [Boolean] true if continuous
+    def continuous?
+      restart == 'continuous'
+    end
+
+    # Check if numbering restarts on each page
+    #
+    # @return [Boolean] true if per page
+    def per_page?
+      restart == 'newPage'
+    end
+
+    # Check if numbering restarts on each section
+    #
+    # @return [Boolean] true if per section
+    def per_section?
+      restart == 'newSection'
+    end
+
+    private
+
+    def validate_restart
+      return unless restart && !RESTART_OPTIONS.include?(restart)
+
+      raise ArgumentError,
+            "Invalid restart option: #{restart}. Must be one of: #{RESTART_OPTIONS.join(', ')}"
+    end
+
+    def validate_start
+      return unless start && start < 1
+
+      raise ArgumentError, "Start must be at least 1, got: #{start}"
+    end
+
+    def validate_count_by
+      return unless count_by && count_by < 1
+
+      raise ArgumentError, "Count_by must be at least 1, got: #{count_by}"
+    end
+  end
+end

data/lib/uniword/loggable.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Uniword
+  # A mixin module that provides logging capabilities to classes.
+  #
+  # Classes that include this module gain access to logging methods
+  # that delegate to the global Uniword logger.
+  #
+  # @example
+  #   class MyClass
+  #     include Uniword::Loggable
+  #
+  #     def do_something
+  #       log_debug("Starting operation")
+  #       # ... do work ...
+  #       log_info("Operation completed")
+  #     rescue => e
+  #       log_error("Operation failed: #{e.message}")
+  #     end
+  #   end
+  module Loggable
+    # Returns the Uniword logger instance
+    #
+    # @return [Logger] The Uniword logger
+    def logger
+      Uniword.logger
+    end
+
+    # Log a debug message
+    #
+    # @param message [String] The message to log
+    def log_debug(message)
+      logger.debug(message)
+    end
+
+    # Log an info message
+    #
+    # @param message [String] The message to log
+    def log_info(message)
+      logger.info(message)
+    end
+
+    # Log a warning message
+    #
+    # @param message [String] The message to log
+    def log_warn(message)
+      logger.warn(message)
+    end
+
+    # Log an error message
+    #
+    # @param message [String] The message to log
+    def log_error(message)
+      logger.error(message)
+    end
+  end
+end