cabriolet 0.1.0

data/lib/cabriolet/szdd/compressor.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module SZDD
+    # Compressor creates SZDD compressed files
+    #
+    # SZDD files wrap LZSS-compressed data with a header containing metadata
+    # about the original file. The compressor supports both NORMAL (used by
+    # MS-DOS EXPAND.EXE) and QBASIC formats.
+    class Compressor
+      attr_reader :io_system
+
+      # Initialize a new SZDD compressor
+      #
+      # @param io_system [System::IOSystem, nil] Custom I/O system or nil for
+      #   default
+      def initialize(io_system = nil)
+        @io_system = io_system || System::IOSystem.new
+      end
+
+      # Compress a file to SZDD format
+      #
+      # @param input_file [String] Path to input file
+      # @param output_file [String] Path to output SZDD file
+      # @param options [Hash] Compression options
+      # @option options [String] :missing_char Last character of original
+      #   filename for reconstruction
+      # @option options [Symbol] :format Format to use (:normal or :qbasic,
+      #   default: :normal)
+      # @return [Integer] Bytes written to output file
+      # @raise [Errors::CompressionError] if compression fails
+      def compress(input_file, output_file, **options)
+        format = options.fetch(:format, :normal)
+        missing_char = options[:missing_char]
+
+        validate_format(format)
+        validate_missing_char(missing_char) if missing_char
+
+        input_handle = @io_system.open(input_file, Constants::MODE_READ)
+        output_handle = @io_system.open(output_file, Constants::MODE_WRITE)
+
+        begin
+          # Get input size
+          input_size = @io_system.seek(input_handle, 0, Constants::SEEK_END)
+          @io_system.seek(input_handle, 0, Constants::SEEK_START)
+
+          # Write header
+          header_bytes = write_header(
+            output_handle,
+            format,
+            input_size,
+            missing_char,
+          )
+
+          # Compress data using LZSS
+          lzss_mode = if format == :normal
+                        Compressors::LZSS::MODE_EXPAND
+                      else
+                        Compressors::LZSS::MODE_QBASIC
+                      end
+
+          compressor = Compressors::LZSS.new(
+            @io_system,
+            input_handle,
+            output_handle,
+            2048,
+            lzss_mode,
+          )
+
+          compressed_bytes = compressor.compress
+
+          header_bytes + compressed_bytes
+        ensure
+          @io_system.close(input_handle) if input_handle
+          @io_system.close(output_handle) if output_handle
+        end
+      end
+
+      # Compress data from memory to SZDD format
+      #
+      # @param data [String] Input data to compress
+      # @param output_file [String] Path to output SZDD file
+      # @param options [Hash] Compression options
+      # @option options [String] :missing_char Last character of original
+      #   filename
+      # @option options [Symbol] :format Format to use (:normal or :qbasic,
+      #   default: :normal)
+      # @return [Integer] Bytes written to output file
+      # @raise [Errors::CompressionError] if compression fails
+      def compress_data(data, output_file, **options)
+        format = options.fetch(:format, :normal)
+        missing_char = options[:missing_char]
+
+        validate_format(format)
+        validate_missing_char(missing_char) if missing_char
+
+        input_handle = System::MemoryHandle.new(data)
+        output_handle = @io_system.open(output_file, Constants::MODE_WRITE)
+
+        begin
+          # Write header
+          header_bytes = write_header(
+            output_handle,
+            format,
+            data.bytesize,
+            missing_char,
+          )
+
+          # Compress data using LZSS
+          lzss_mode = if format == :normal
+                        Compressors::LZSS::MODE_EXPAND
+                      else
+                        Compressors::LZSS::MODE_QBASIC
+                      end
+
+          compressor = Compressors::LZSS.new(
+            @io_system,
+            input_handle,
+            output_handle,
+            2048,
+            lzss_mode,
+          )
+
+          compressed_bytes = compressor.compress
+
+          header_bytes + compressed_bytes
+        ensure
+          @io_system.close(output_handle) if output_handle
+        end
+      end
+
+      private
+
+      # Write SZDD header to output
+      #
+      # @param output_handle [System::FileHandle] Output file handle
+      # @param format [Symbol] Format to use (:normal or :qbasic)
+      # @param uncompressed_size [Integer] Size of uncompressed data
+      # @param missing_char [String, nil] Missing character or nil
+      # @return [Integer] Number of bytes written
+      def write_header(output_handle, format, uncompressed_size, missing_char)
+        if format == :normal
+          write_normal_header(output_handle, uncompressed_size, missing_char)
+        else
+          write_qbasic_header(output_handle, uncompressed_size)
+        end
+      end
+
+      # Write NORMAL format header
+      #
+      # @param output_handle [System::FileHandle] Output file handle
+      # @param uncompressed_size [Integer] Size of uncompressed data
+      # @param missing_char [String, nil] Missing character or nil
+      # @return [Integer] Number of bytes written (14 bytes)
+      def write_normal_header(output_handle, uncompressed_size, missing_char)
+        header = Binary::SZDDStructures::NormalHeader.new
+        header.signature = Binary::SZDDStructures::SIGNATURE_NORMAL
+        header.compression_mode = 0x41 # 'A'
+        header.missing_char = missing_char ? missing_char.ord : 0x00
+        header.uncompressed_size = uncompressed_size
+
+        header_data = header.to_binary_s
+        written = @io_system.write(output_handle, header_data)
+
+        unless written == header_data.bytesize
+          raise Errors::CompressionError,
+                "Failed to write SZDD header"
+        end
+
+        written
+      end
+
+      # Write QBASIC format header
+      #
+      # @param output_handle [System::FileHandle] Output file handle
+      # @param uncompressed_size [Integer] Size of uncompressed data
+      # @return [Integer] Number of bytes written (12 bytes)
+      def write_qbasic_header(output_handle, uncompressed_size)
+        header = Binary::SZDDStructures::QBasicHeader.new
+        header.signature = Binary::SZDDStructures::SIGNATURE_QBASIC
+        header.uncompressed_size = uncompressed_size
+
+        header_data = header.to_binary_s
+        written = @io_system.write(output_handle, header_data)
+
+        unless written == header_data.bytesize
+          raise Errors::CompressionError,
+                "Failed to write SZDD header"
+        end
+
+        written
+      end
+
+      # Validate format parameter
+      #
+      # @param format [Symbol] Format to validate
+      # @raise [ArgumentError] if format is invalid
+      def validate_format(format)
+        return if %i[normal qbasic].include?(format)
+
+        raise ArgumentError,
+              "Format must be :normal or :qbasic, got #{format.inspect}"
+      end
+
+      # Validate missing character parameter
+      #
+      # @param missing_char [String] Missing character to validate
+      # @raise [ArgumentError] if missing_char is invalid
+      def validate_missing_char(missing_char)
+        return if missing_char.is_a?(String) && missing_char.length == 1
+
+        raise ArgumentError,
+              "Missing character must be a single character string, got #{missing_char.inspect}"
+      end
+    end
+  end
+end

data/lib/cabriolet/szdd/decompressor.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module SZDD
+    # Decompressor is the main interface for SZDD file operations
+    #
+    # SZDD files use LZSS compression and are decompressed using the
+    # Decompressors::LZSS class with appropriate mode settings.
+    class Decompressor
+      attr_reader :io_system, :parser
+      attr_accessor :buffer_size
+
+      # Input buffer size for decompression
+      DEFAULT_BUFFER_SIZE = 2048
+
+      # Initialize a new SZDD decompressor
+      #
+      # @param io_system [System::IOSystem, nil] Custom I/O system or nil for
+      #   default
+      def initialize(io_system = nil)
+        @io_system = io_system || System::IOSystem.new
+        @parser = Parser.new(@io_system)
+        @buffer_size = DEFAULT_BUFFER_SIZE
+      end
+
+      # Open and parse an SZDD file
+      #
+      # @param filename [String] Path to the SZDD file
+      # @return [Models::SZDDHeader] Parsed header with file handle
+      # @raise [Errors::ParseError] if the file is not a valid SZDD
+      def open(filename)
+        header = @parser.parse(filename)
+        header.filename = filename
+        header
+      end
+
+      # Close an SZDD file (no-op for compatibility)
+      #
+      # @param _header [Models::SZDDHeader] Header to close
+      # @return [void]
+      def close(_header)
+        # No resources to free in the header itself
+        # File handles are managed separately during extraction
+        nil
+      end
+
+      # Extract an SZDD file to output
+      #
+      # @param header [Models::SZDDHeader] SZDD header from open()
+      # @param output_path [String] Where to write the decompressed file
+      # @return [Integer] Number of bytes written
+      # @raise [Errors::DecompressionError] if decompression fails
+      def extract(header, output_path)
+        raise ArgumentError, "Header must not be nil" unless header
+        raise ArgumentError, "Output path must not be nil" unless output_path
+
+        input_handle = @io_system.open(header.filename, Constants::MODE_READ)
+        output_handle = @io_system.open(output_path, Constants::MODE_WRITE)
+
+        begin
+          # Seek to compressed data start
+          data_offset = @parser.data_offset(header.format)
+          @io_system.seek(input_handle, data_offset, Constants::SEEK_START)
+
+          # Determine LZSS mode based on format
+          lzss_mode = if header.normal_format?
+                        Decompressors::LZSS::MODE_EXPAND
+                      else
+                        Decompressors::LZSS::MODE_QBASIC
+                      end
+
+          # Create LZSS decompressor
+          decompressor = Decompressors::LZSS.new(
+            @io_system,
+            input_handle,
+            output_handle,
+            @buffer_size,
+            lzss_mode,
+          )
+
+          # Decompress
+          bytes_written = decompressor.decompress(header.length)
+
+          # Verify decompressed size matches expected
+          if bytes_written != header.length && Cabriolet.verbose && Cabriolet.verbose
+            warn "[Cabriolet] WARNING; decompressed #{bytes_written} bytes, " \
+                 "expected #{header.length} bytes"
+          end
+
+          bytes_written
+        ensure
+          @io_system.close(input_handle) if input_handle
+          @io_system.close(output_handle) if output_handle
+        end
+      end
+
+      # Extract SZDD file to memory
+      #
+      # @param header [Models::SZDDHeader] SZDD header from open()
+      # @return [String] Decompressed data
+      # @raise [Errors::DecompressionError] if decompression fails
+      def extract_to_memory(header)
+        raise ArgumentError, "Header must not be nil" unless header
+
+        input_handle = @io_system.open(header.filename, Constants::MODE_READ)
+        output_handle = System::MemoryHandle.new("", Constants::MODE_WRITE)
+
+        begin
+          # Seek to compressed data start
+          data_offset = @parser.data_offset(header.format)
+          @io_system.seek(input_handle, data_offset, Constants::SEEK_START)
+
+          # Determine LZSS mode based on format
+          lzss_mode = if header.normal_format?
+                        Decompressors::LZSS::MODE_EXPAND
+                      else
+                        Decompressors::LZSS::MODE_QBASIC
+                      end
+
+          # Create LZSS decompressor
+          decompressor = Decompressors::LZSS.new(
+            @io_system,
+            input_handle,
+            output_handle,
+            @buffer_size,
+            lzss_mode,
+          )
+
+          # Decompress
+          decompressor.decompress(header.length)
+
+          # Return the decompressed data
+          output_handle.data
+        ensure
+          @io_system.close(input_handle) if input_handle
+        end
+      end
+
+      # One-shot decompression from input file to output file
+      #
+      # This method combines open(), extract(), and close() for convenience.
+      # Similar to MS-DOS EXPAND.EXE behavior.
+      #
+      # @param input_path [String] Path to compressed SZDD file
+      # @param output_path [String, nil] Path to output file, or nil to
+      #   auto-detect
+      # @return [Integer] Number of bytes written
+      # @raise [Errors::ParseError] if input is not valid SZDD
+      # @raise [Errors::DecompressionError] if decompression fails
+      def decompress(input_path, output_path = nil)
+        # Parse header
+        header = self.open(input_path)
+
+        # Auto-detect output filename if not provided
+        output_path ||= auto_output_filename(input_path, header)
+
+        # Extract
+        bytes_written = extract(header, output_path)
+
+        # Close (no-op but kept for API consistency)
+        close(header)
+
+        bytes_written
+      end
+
+      # Generate output filename from input filename and header
+      #
+      # @param input_path [String] Input file path
+      # @param header [Models::SZDDHeader] SZDD header
+      # @return [String] Suggested output filename
+      def auto_output_filename(input_path, header)
+        # Get base filename without directory
+        base = ::File.basename(input_path)
+
+        # Use header's suggested filename method
+        suggested = header.suggested_filename(base)
+
+        # Combine with original directory
+        dir = ::File.dirname(input_path)
+        ::File.join(dir, suggested)
+      end
+    end
+  end
+end

data/lib/cabriolet/szdd/parser.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module SZDD
+    # Parser reads and parses SZDD file headers
+    #
+    # SZDD files are single-file compressed archives using LZSS compression.
+    # There are two format variants:
+    # - NORMAL: Used by MS-DOS EXPAND.EXE (signature: SZDD\x88\xF0\x27\x33)
+    # - QBASIC: Used by QBasic (signature: SZDD \x88\xF0\x27\x33\xD1)
+    class Parser
+      attr_reader :io_system
+
+      # Expected compression mode for NORMAL format
+      COMPRESSION_MODE_NORMAL = 0x41
+
+      # Initialize a new parser
+      #
+      # @param io_system [System::IOSystem] I/O system for reading
+      def initialize(io_system)
+        @io_system = io_system
+      end
+
+      # Parse an SZDD file and return header information
+      #
+      # @param filename [String] Path to the SZDD file
+      # @return [Models::SZDDHeader] Parsed header
+      # @raise [Errors::ParseError] if the file is not a valid SZDD
+      def parse(filename)
+        handle = @io_system.open(filename, Constants::MODE_READ)
+        header = parse_handle(handle, filename)
+        @io_system.close(handle)
+        header
+      end
+
+      # Parse SZDD header from an already-open handle
+      #
+      # @param handle [System::FileHandle, System::MemoryHandle] Open handle
+      # @param filename [String] Filename for reference
+      # @return [Models::SZDDHeader] Parsed header
+      # @raise [Errors::ParseError] if not a valid SZDD
+      def parse_handle(handle, filename = nil)
+        # Read signature (8 bytes)
+        signature = @io_system.read(handle, 8)
+        raise ParseError, "Cannot read SZDD signature" if
+          signature.bytesize < 8
+
+        # Determine format based on signature
+        if signature == Binary::SZDDStructures::SIGNATURE_NORMAL
+          parse_normal_header(handle, filename)
+        elsif signature == Binary::SZDDStructures::SIGNATURE_QBASIC
+          parse_qbasic_header(handle, filename)
+        else
+          raise ParseError, "Invalid SZDD signature"
+        end
+      end
+
+      # Get the data offset for the compressed data
+      #
+      # @param format [Symbol] Format type (:normal or :qbasic)
+      # @return [Integer] Offset in bytes where compressed data starts
+      def data_offset(format)
+        format == Models::SZDDHeader::FORMAT_NORMAL ? 14 : 12
+      end
+
+      private
+
+      # Parse NORMAL format SZDD header (EXPAND.EXE)
+      #
+      # @param handle [System::FileHandle, System::MemoryHandle] Open handle
+      # @param filename [String, nil] Filename for reference
+      # @return [Models::SZDDHeader] Parsed header
+      # @raise [Errors::ParseError] if header is invalid
+      def parse_normal_header(handle, filename)
+        # Read remaining header fields (6 bytes)
+        # - 1 byte: compression mode (should be 0x41)
+        # - 1 byte: missing character
+        # - 4 bytes: uncompressed size (little-endian)
+        header_data = @io_system.read(handle, 6)
+        raise ParseError, "Cannot read SZDD header" if
+          header_data.bytesize < 6
+
+        compression_mode = header_data[0].ord
+        missing_char = header_data[1].chr
+        uncompressed_size = header_data[2..5].unpack1("V") # Little-endian uint32
+
+        # Validate compression mode
+        unless compression_mode == COMPRESSION_MODE_NORMAL
+          raise ParseError,
+                "Invalid compression mode: #{compression_mode}"
+        end
+
+        # Create header model
+        Models::SZDDHeader.new(
+          format: Models::SZDDHeader::FORMAT_NORMAL,
+          length: uncompressed_size,
+          missing_char: missing_char,
+          filename: filename,
+        )
+      end
+
+      # Parse QBASIC format SZDD header
+      #
+      # @param handle [System::FileHandle, System::MemoryHandle] Open handle
+      # @param filename [String, nil] Filename for reference
+      # @return [Models::SZDDHeader] Parsed header
+      # @raise [Errors::ParseError] if header is invalid
+      def parse_qbasic_header(handle, filename)
+        # Read remaining header fields (4 bytes)
+        # - 4 bytes: uncompressed size (little-endian)
+        header_data = @io_system.read(handle, 4)
+        raise ParseError, "Cannot read SZDD header" if
+          header_data.bytesize < 4
+
+        uncompressed_size = header_data.unpack1("V") # Little-endian uint32
+
+        # Create header model (no missing character in QBASIC format)
+        Models::SZDDHeader.new(
+          format: Models::SZDDHeader::FORMAT_QBASIC,
+          length: uncompressed_size,
+          missing_char: nil,
+          filename: filename,
+        )
+      end
+    end
+  end
+end