cabriolet 0.1.2 → 0.2.0

data/lib/cabriolet/algorithm_factory.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  # Factory for creating and managing compression/decompression algorithms
+  #
+  # The AlgorithmFactory provides a centralized registry for compression and
+  # decompression algorithms. It handles algorithm registration, validation,
+  # instantiation, and type normalization.
+  #
+  # @example Register and create an algorithm
+  #   factory = AlgorithmFactory.new
+  #   factory.register(:custom, CustomCompressor, category: :compressor)
+  #   algorithm = factory.create(:custom, :compressor, io, input, output, 4096)
+  #
+  # @example Use with integer type constants
+  #   # Constants::COMP_TYPE_MSZIP (1) is normalized to :mszip
+  #   algorithm = factory.create(1, :decompressor, io, input, output, 4096)
+  class AlgorithmFactory
+    # @return [Hash] Registry of algorithms by category and type
+    attr_reader :algorithms
+
+    # Initialize a new algorithm factory
+    #
+    # @param auto_register [Boolean] Whether to automatically register
+    #   built-in algorithms
+    def initialize(auto_register: true)
+      @algorithms = { compressor: {}, decompressor: {} }
+      register_built_in_algorithms if auto_register
+    end
+
+    # Register an algorithm in the factory
+    #
+    # @param type [Symbol] Algorithm type (:none, :mszip, :lzx, :quantum,
+    #   :lzss)
+    # @param algorithm_class [Class] Algorithm class (must inherit from
+    #   Compressors::Base or Decompressors::Base)
+    # @param options [Hash] Registration options
+    # @option options [Symbol] :category Required - :compressor or
+    #   :decompressor
+    # @option options [Integer] :priority Priority for selection (default: 0)
+    # @option options [Symbol, nil] :format Format restriction (optional)
+    #
+    # @return [self] Returns self for method chaining
+    #
+    # @raise [ArgumentError] If category is invalid
+    # @raise [ArgumentError] If algorithm_class doesn't inherit from Base
+    #
+    # @example Register a custom compressor
+    #   factory.register(:custom, MyCompressor,
+    #                    category: :compressor, priority: 10)
+    #
+    # @example Chain multiple registrations
+    #   factory
+    #     .register(:algo1, Algo1, category: :compressor)
+    #     .register(:algo2, Algo2, category: :decompressor)
+    def register(type, algorithm_class, **options)
+      category = options[:category]
+      validate_category!(category)
+      validate_algorithm_class!(algorithm_class, category)
+
+      @algorithms[category][type] = {
+        class: algorithm_class,
+        priority: options.fetch(:priority, 0),
+        format: options[:format],
+      }
+
+      self
+    end
+
+    # Create an instance of a registered algorithm
+    #
+    # @param type [Symbol, Integer] Algorithm type (symbol or constant)
+    # @param category [Symbol] Category (:compressor or :decompressor)
+    # @param io_system [System::IOSystem] I/O system for operations
+    # @param input [System::FileHandle, System::MemoryHandle] Input handle
+    # @param output [System::FileHandle, System::MemoryHandle] Output handle
+    # @param buffer_size [Integer] Buffer size for I/O operations
+    # @param kwargs [Hash] Additional keyword arguments for algorithm
+    #
+    # @return [Compressors::Base, Decompressors::Base] Algorithm instance
+    #
+    # @raise [ArgumentError] If category is invalid
+    # @raise [UnsupportedFormatError] If algorithm type not registered
+    #
+    # @example Create a decompressor
+    #   decompressor = factory.create(:mszip, :decompressor,
+    #                                 io, input, output, 4096)
+    #
+    # @example Create with integer constant
+    #   # Constants::COMP_TYPE_LZX (3) -> :lzx
+    #   compressor = factory.create(3, :compressor,
+    #                               io, input, output, 8192)
+    def create(type, category, io_system, input, output, buffer_size,
+               **kwargs)
+      validate_category!(category)
+
+      normalized_type = normalize_type(type)
+      algorithm_info = @algorithms[category][normalized_type]
+
+      unless algorithm_info
+        raise UnsupportedFormatError,
+              "Unknown #{category} algorithm: #{normalized_type}"
+      end
+
+      algorithm_info[:class].new(io_system, input, output, buffer_size,
+                                 **kwargs)
+    end
+
+    # Check if an algorithm is registered
+    #
+    # @param type [Symbol] Algorithm type
+    # @param category [Symbol] Category (:compressor or :decompressor)
+    #
+    # @return [Boolean] True if registered, false otherwise
+    #
+    # @example Check registration
+    #   factory.registered?(:mszip, :compressor) #=> true
+    #   factory.registered?(:unknown, :compressor) #=> false
+    def registered?(type, category)
+      @algorithms[category]&.key?(type) || false
+    end
+
+    # List registered algorithms
+    #
+    # @param category [Symbol, nil] Optional category filter
+    #
+    # @return [Hash] Hash of registered algorithms
+    #
+    # @example List all algorithms
+    #   factory.list
+    #   #=> { compressor: { mszip: {...}, lzx: {...} },
+    #   #     decompressor: { none: {...}, mszip: {...} } }
+    #
+    # @example List compressors only
+    #   factory.list(:compressor)
+    #   #=> { mszip: {...}, lzx: {...}, quantum: {...}, lzss: {...} }
+    def list(category = nil)
+      if category.nil?
+        {
+          compressor: @algorithms[:compressor].dup,
+          decompressor: @algorithms[:decompressor].dup,
+        }
+      else
+        @algorithms[category]&.dup || {}
+      end
+    end
+
+    # Unregister an algorithm
+    #
+    # @param type [Symbol] Algorithm type to remove
+    # @param category [Symbol] Category (:compressor or :decompressor)
+    #
+    # @return [Boolean] True if removed, false if not found
+    #
+    # @example Unregister an algorithm
+    #   factory.unregister(:mszip, :compressor) #=> true
+    #   factory.unregister(:unknown, :compressor) #=> false
+    # rubocop:disable Naming/PredicatePrefix
+    def unregister(type, category)
+      !@algorithms[category].delete(type).nil?
+    end
+    # rubocop:enable Naming/PredicatePrefix
+
+    private
+
+    # Register all built-in compression and decompression algorithms
+    #
+    # Registers 5 decompressors (none, lzss, mszip, lzx, quantum) and
+    # 4 compressors (lzss, mszip, lzx, quantum).
+    #
+    # @return [void]
+    def register_built_in_algorithms
+      # Register decompressors (5 total)
+      register(:none, Decompressors::None, category: :decompressor)
+      register(:lzss, Decompressors::LZSS, category: :decompressor)
+      register(:mszip, Decompressors::MSZIP, category: :decompressor)
+      register(:lzx, Decompressors::LZX, category: :decompressor)
+      register(:quantum, Decompressors::Quantum, category: :decompressor)
+
+      # Register compressors (4 total - no 'none' compressor)
+      register(:lzss, Compressors::LZSS, category: :compressor)
+      register(:mszip, Compressors::MSZIP, category: :compressor)
+      register(:lzx, Compressors::LZX, category: :compressor)
+      register(:quantum, Compressors::Quantum, category: :compressor)
+    end
+
+    # Normalize algorithm type from integer constant to symbol
+    #
+    # @param type [Symbol, Integer] Type to normalize
+    #
+    # @return [Symbol] Normalized type symbol
+    #
+    # @example Normalize integer constants
+    #   normalize_type(0) #=> :none
+    #   normalize_type(1) #=> :mszip
+    #   normalize_type(2) #=> :quantum
+    #   normalize_type(3) #=> :lzx
+    #   normalize_type(:lzss) #=> :lzss
+    def normalize_type(type)
+      return type if type.is_a?(Symbol)
+
+      case type
+      when Constants::COMP_TYPE_NONE then :none
+      when Constants::COMP_TYPE_MSZIP then :mszip
+      when Constants::COMP_TYPE_QUANTUM then :quantum
+      when Constants::COMP_TYPE_LZX then :lzx
+      else
+        raise UnsupportedFormatError,
+              "Unsupported compression type: #{type}"
+      end
+    end
+
+    # Validate that category is valid
+    #
+    # @param category [Symbol] Category to validate
+    #
+    # @raise [ArgumentError] If category is not :compressor or :decompressor
+    #
+    # @return [void]
+    def validate_category!(category)
+      valid_categories = %i[compressor decompressor]
+      return if valid_categories.include?(category)
+
+      raise ArgumentError,
+            "Invalid category: #{category}. " \
+            "Must be :compressor or :decompressor"
+    end
+
+    # Validate that algorithm class inherits from appropriate base class
+    #
+    # @param klass [Class] Algorithm class to validate
+    # @param category [Symbol] Category (:compressor or :decompressor)
+    #
+    # @raise [ArgumentError] If class doesn't inherit from correct base
+    #
+    # @return [void]
+    def validate_algorithm_class!(klass, category)
+      base_class = if category == :compressor
+                     Compressors::Base
+                   else
+                     Decompressors::Base
+                   end
+
+      return if klass < base_class
+
+      raise ArgumentError,
+            "#{klass} must inherit from #{base_class}"
+    end
+  end
+end

data/lib/cabriolet/base_compressor.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require_relative "file_manager"
+require_relative "system/io_system"
+
+module Cabriolet
+  # Abstract base class for all format compressors
+  #
+  # Implements Template Method pattern:
+  # - Defines common compression workflow in generate()
+  # - Subclasses implement format-specific hooks
+  #
+  # Provides:
+  # - File management via FileManager
+  # - Common initialization pattern
+  # - Template method for generation workflow
+  # - Hook methods for format customization
+  # - Helper methods for common operations
+  #
+  # Subclasses must implement:
+  # - build_structure(options) - Create format-specific structure
+  # - write_format(output_handle, structure) - Write binary data
+  #
+  # Subclasses may override:
+  # - validate_generation_prerequisites!(options) - Custom validation
+  # - post_generation_hook(output_file, structure, bytes) - Cleanup/logging
+  #
+  # @example Creating a format compressor
+  #   class MyFormatCompressor < BaseCompressor
+  #     protected
+  #
+  #     def build_structure(options)
+  #       { header: build_header, files: collect_files }
+  #     end
+  #
+  #     def write_format(output_handle, structure)
+  #       io_system.write(output_handle, structure[:header].to_binary_s)
+  #     end
+  #   end
+  class BaseCompressor
+    attr_reader :io_system, :algorithm_factory, :file_manager
+
+    # Initialize compressor with I/O and algorithm dependencies
+    #
+    # @param io_system [System::IOSystem, nil] I/O system or nil for default
+    # @param algorithm_factory [AlgorithmFactory, nil] Algorithm factory or nil
+    def initialize(io_system = nil, algorithm_factory = nil)
+      @io_system = io_system || System::IOSystem.new
+      @algorithm_factory = algorithm_factory || Cabriolet.algorithm_factory
+      @file_manager = FileManager.new
+    end
+
+    # Add file from disk to archive
+    #
+    # @param source_path [String] Path to source file
+    # @param archive_path [String, nil] Path in archive (nil = use basename)
+    # @param options [Hash] Format-specific options
+    # @return [FileEntry] Added entry
+    # @raise [ArgumentError] if file doesn't exist
+    def add_file(source_path, archive_path = nil, **options)
+      @file_manager.add_file(source_path, archive_path, **options)
+    end
+
+    # Add file from memory to archive
+    #
+    # @param data [String] File data
+    # @param archive_path [String] Path in archive
+    # @param options [Hash] Format-specific options
+    # @return [FileEntry] Added entry
+    def add_data(data, archive_path, **options)
+      @file_manager.add_data(data, archive_path, **options)
+    end
+
+    # Generate archive (Template Method)
+    #
+    # This method defines the compression workflow:
+    # 1. Validate prerequisites
+    # 2. Build format-specific structure
+    # 3. Write to output file
+    # 4. Post-generation hook
+    # 5. Return bytes written
+    #
+    # Subclasses customize via hook methods, not by overriding this method.
+    #
+    # @param output_file [String] Path to output file
+    # @param options [Hash] Format-specific options
+    # @return [Integer] Bytes written to output file
+    # @raise [ArgumentError] if validation fails
+    def generate(output_file, **options)
+      validate_generation_prerequisites!(options)
+
+      structure = build_structure(options)
+
+      bytes_written = write_to_file(output_file, structure)
+
+      post_generation_hook(output_file, structure, bytes_written)
+
+      bytes_written
+    end
+
+    protected
+
+    # Hook: Build format-specific structure
+    #
+    # Subclasses MUST implement this method to create the archive structure
+    # ready for writing. The structure should contain all necessary metadata,
+    # compressed data, headers, and calculated offsets.
+    #
+    # @param options [Hash] Generation options from generate() call
+    # @return [Hash] Format structure ready for writing
+    # @raise [NotImplementedError] if not implemented by subclass
+    def build_structure(options)
+      raise NotImplementedError,
+            "#{self.class.name} must implement build_structure(options)"
+    end
+
+    # Hook: Write format to output handle
+    #
+    # Subclasses MUST implement this method to write the format-specific
+    # binary data to the output handle. Should write headers, directory,
+    # and file data according to format specification.
+    #
+    # @param output_handle [System::FileHandle] Open output handle
+    # @param structure [Hash] Format structure from build_structure()
+    # @return [Integer] Bytes written
+    # @raise [NotImplementedError] if not implemented by subclass
+    def write_format(output_handle, structure)
+      raise NotImplementedError,
+            "#{self.class.name} must implement write_format(output_handle, structure)"
+    end
+
+    # Hook: Validate pre-generation requirements
+    #
+    # Subclasses CAN override this for format-specific validation.
+    # Default implementation checks that files have been added.
+    #
+    # @param options [Hash] Generation options
+    # @raise [ArgumentError] if validation fails
+    def validate_generation_prerequisites!(_options)
+      raise ArgumentError, "No files added to archive" if @file_manager.empty?
+    end
+
+    # Hook: Post-generation callback
+    #
+    # Subclasses CAN override this for cleanup, logging, or additional
+    # processing after successful generation.
+    #
+    # @param output_file [String] Path to generated file
+    # @param structure [Hash] Generated structure
+    # @param bytes_written [Integer] Bytes written to file
+    # @return [void]
+    def post_generation_hook(_output_file, _structure, _bytes_written)
+      # Default: no-op
+      nil
+    end
+
+    # Helper: Compress data using specified algorithm
+    #
+    # Provides unified interface for compression across all formats.
+    # Uses algorithm factory for extensibility.
+    #
+    # @param data [String] Data to compress
+    # @param algorithm [Symbol] Algorithm type (:lzss, :mszip, :lzx, :quantum)
+    # @param options [Hash] Compression options
+    # @option options [Integer] :window_bits Window size in bits
+    # @option options [Integer] :mode Algorithm mode
+    # @return [String] Compressed data
+    def compress_data(data, algorithm:, **options)
+      input = System::MemoryHandle.new(data)
+      output = System::MemoryHandle.new("", Constants::MODE_WRITE)
+
+      compressor = @algorithm_factory.create(
+        algorithm,
+        :compressor,
+        @io_system,
+        input,
+        output,
+        data.bytesize,
+        **options,
+      )
+
+      compressor.compress
+      output.data
+    end
+
+    private
+
+    # Write structure to file
+    #
+    # Handles file opening/closing and delegates to write_format hook
+    #
+    # @param output_file [String] Path to output file
+    # @param structure [Hash] Format structure
+    # @return [Integer] Bytes written
+    def write_to_file(output_file, structure)
+      output_handle = @io_system.open(output_file, Constants::MODE_WRITE)
+
+      begin
+        bytes = write_format(output_handle, structure)
+        bytes
+      ensure
+        @io_system.close(output_handle) if output_handle
+      end
+    end
+  end
+end

data/lib/cabriolet/binary/bitstream.rb

@@ -4,22 +4,31 @@ module Cabriolet
   module Binary
     # Bitstream provides bit-level I/O operations for reading compressed data
     class Bitstream
-      attr_reader :io_system, :handle, :buffer_size
+      attr_reader :io_system, :handle, :buffer_size, :bit_order
 
       # Initialize a new bitstream
       #
       # @param io_system [System::IOSystem] I/O system for reading data
       # @param handle [System::FileHandle, System::MemoryHandle] Handle to read from
       # @param buffer_size [Integer] Size of the input buffer
+      # @param bit_order [Symbol] Bit order (:lsb or :msb)
+      # @param salvage [Boolean] Salvage mode - return 0 on EOF instead of raising
       def initialize(io_system, handle,
-buffer_size = Cabriolet.default_buffer_size)
+buffer_size = Cabriolet.default_buffer_size, bit_order: :lsb, salvage: false)
         @io_system = io_system
         @handle = handle
         @buffer_size = buffer_size
+        @bit_order = bit_order
+        @salvage = salvage
         @buffer = ""
         @buffer_pos = 0
         @bit_buffer = 0
         @bits_left = 0
+        @input_end = false # Track EOF state (matches libmspack's input_end flag)
+
+        # For MSB mode, we need to know the bit width of the buffer
+        # Ruby integers are arbitrary precision, so we use 32 bits as standard
+        @bitbuf_width = 32
       end
 
       # Read specified number of bits from the stream
@@ -33,31 +42,128 @@ buffer_size = Cabriolet.default_buffer_size)
                 "Can only read 1-32 bits at a time"
         end
 
+        if @bit_order == :msb
+          read_bits_msb(num_bits)
+        else
+          read_bits_lsb(num_bits)
+        end
+      end
+
+      private
+
+      # Read bits in LSB-first order
+      #
+      # Per libmspack: EOF handling allows padding to avoid bitstream overrun.
+      # First EOF: pad with zeros (2 bytes worth). Second EOF: raise error.
+      def read_bits_lsb(num_bits)
         # Ensure we have enough bits in the buffer
         while @bits_left < num_bits
           byte = read_byte
-          return 0 if byte.nil? # EOF
+          # First EOF: pad with zeros (matches libmspack read_input behavior)
+          # On second EOF, read_byte will raise DecompressionError
+          # In salvage mode, pad indefinitely; otherwise pad on first EOF
+          byte = 0 if byte.nil?
+
+          # DEBUG
+          if ENV["DEBUG_BITSTREAM"]
+            warn "DEBUG LSB read_byte: buffer_pos=#{@buffer_pos} byte=#{byte} (#{byte.to_s(2).rjust(
+              8, '0'
+            )}) bits_left=#{@bits_left}"
+          end
 
+          # INJECT_BITS (LSB): append to the right
           @bit_buffer |= (byte << @bits_left)
           @bits_left += 8
         end
 
-        # Extract the requested bits
+        # PEEK_BITS (LSB): extract from the right
         result = @bit_buffer & ((1 << num_bits) - 1)
+        # REMOVE_BITS (LSB): shift right
         @bit_buffer >>= num_bits
         @bits_left -= num_bits
 
+        # DEBUG
+        warn "DEBUG LSB read_bits(#{num_bits}): result=#{result} buffer=#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+
+        result
+      end
+
+      # Read bits in MSB-first order (libmspack LZX/Quantum style)
+      #
+      # Per libmspack readbits.h: Reads 2 bytes at a time (little-endian 16-bit word).
+      # EOF handling: First EOF pads with zeros, second EOF raises error.
+      def read_bits_msb(num_bits)
+        # Ensure we have enough bits in the buffer
+        while @bits_left < num_bits
+          # Read 2 bytes at a time (little-endian), like libmspack
+          byte0 = read_byte
+          if byte0.nil? && (@salvage || @input_end)
+            # First EOF: pad with zeros
+            # Second EOF: read_byte will raise DecompressionError
+            byte0 = 0
+          end
+
+          byte1 = read_byte
+          if byte1.nil?
+            # Pad with 0 if only 1 byte left (or EOF)
+            byte1 = 0
+          end
+
+          # Combine as little-endian 16-bit value
+          word = byte0 | (byte1 << 8)
+
+          # DEBUG
+          warn "DEBUG MSB read_bytes: byte0=0x#{byte0.to_s(16)} byte1=0x#{byte1.to_s(16)} word=0x#{word.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+
+          # INJECT_BITS (MSB): inject at the left side
+          # bit_buffer |= word << (BITBUF_WIDTH -16 - bits_left)
+          @bit_buffer |= (word << (@bitbuf_width - 16 - @bits_left))
+          @bits_left += 16
+        end
+
+        # PEEK_BITS (MSB): extract from the left
+        # result = bit_buffer >> (BITBUF_WIDTH - num_bits)
+        result = @bit_buffer >> (@bitbuf_width - num_bits)
+
+        # REMOVE_BITS (MSB): shift left
+        @bit_buffer = (@bit_buffer << num_bits) & ((1 << @bitbuf_width) - 1)
+        @bits_left -= num_bits
+
+        # DEBUG
+        warn "DEBUG MSB read_bits(#{num_bits}) result=#{result} (0x#{result.to_s(16)}) buffer=0x#{@bit_buffer.to_s(16)} bits_left=#{@bits_left}" if ENV["DEBUG_BITSTREAM"]
+
         result
       end
 
+      public
+
       # Read a single byte from the input
       #
-      # @return [Integer, nil] Byte value or nil at EOF
+      # Per libmspack readbits.h: On first EOF, we pad with zeros.
+      # On second EOF, we raise an error (unless salvage mode).
+      #
+      # @return [Integer, nil] Byte value or nil to signal EOF padding needed
+      # @raise [DecompressionError] on second EOF attempt (unless salvage mode)
       def read_byte
         if @buffer_pos >= @buffer.bytesize
           @buffer = @io_system.read(@handle, @buffer_size)
           @buffer_pos = 0
-          return nil if @buffer.empty?
+
+          if @buffer.empty?
+            # Hit EOF - check if this is first or second EOF
+            if @input_end
+              # Second EOF: raise error unless salvage mode
+              unless @salvage
+                raise DecompressionError, "Unexpected end of input stream"
+              end
+
+              # In salvage mode, keep returning nil
+            else
+              # First EOF: signal to pad with zeros (return nil)
+              @input_end = true
+            end
+            return nil
+          end
         end
 
         byte = @buffer.getbyte(@buffer_pos)
@@ -84,16 +190,50 @@ buffer_size = Cabriolet.default_buffer_size)
                 "Can only peek 1-32 bits at a time"
         end
 
-        # Ensure we have enough bits
-        while @bits_left < num_bits
-          byte = read_byte
-          return 0 if byte.nil?
+        if @bit_order == :msb
+          # Ensure we have enough bits
+          while @bits_left < num_bits
+            # Read 2 bytes at a time (little-endian), like libmspack
+            byte0 = read_byte
+            if byte0.nil?
+              # At EOF: break and work with remaining bits
+              break
+            end
 
-          @bit_buffer |= (byte << @bits_left)
-          @bits_left += 8
-        end
+            byte1 = read_byte
+            byte1 = 0 if byte1.nil?
+
+            # Combine as little-endian 16-bit value
+            word = byte0 | (byte1 << 8)
 
-        @bit_buffer & ((1 << num_bits) - 1)
+            # INJECT_BITS (MSB): inject at the left side
+            @bit_buffer |= (word << (@bitbuf_width - 16 - @bits_left))
+            @bits_left += 16
+          end
+
+          # PEEK_BITS (MSB): extract from the left
+          # If we have fewer than num_bits available, result may be incorrect
+          # but this matches EOF handling behavior
+          @bit_buffer >> (@bitbuf_width - num_bits)
+        else
+          # Ensure we have enough bits (LSB mode)
+          while @bits_left < num_bits
+            byte = read_byte
+            if byte.nil?
+              # At EOF: pad remaining bits with zeros and continue
+              # This matches libmspack behavior where peek can use partial bits
+              # The missing high bits are implicitly 0
+              break
+            end
+
+            @bit_buffer |= (byte << @bits_left)
+            @bits_left += 8
+          end
+
+          # Extract num_bits from bit_buffer
+          # If we have fewer than num_bits, the high bits will be 0
+          @bit_buffer & ((1 << num_bits) - 1)
+        end
       end
 
       # Skip specified number of bits