cabriolet 0.1.2 → 0.2.0

data/lib/cabriolet/hlp/parser.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "quickhelp/parser"
+require_relative "winhelp/parser"
+
 module Cabriolet
   module HLP
-    # Parser for HLP (Windows Help) files
+    # Main parser for HLP files
     #
-    # NOTE: This implementation is based on the knowledge that HLP files use
-    # LZSS compression with MODE_MSHELP, but cannot be fully validated due to
-    # lack of test fixtures and incomplete libmspack implementation.
+    # Detects the HLP format variant and delegates to the appropriate parser:
+    # - QuickHelp (DOS format with "LN" signature)
+    # - Windows Help (WinHelp 3.x/4.x format)
     class Parser
       attr_reader :io_system
 
       # Initialize parser
       #
-      # @param io_system [System::IOSystem, nil] Custom I/O system or nil for
-      #   default
+      # @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
@@ -21,111 +23,60 @@ module Cabriolet
       # Parse an HLP file
       #
       # @param filename [String] Path to HLP file
-      # @return [Models::HLPHeader] Parsed header
-      # @raise [Errors::ParseError] if file is not valid HLP
+      # @return [Models::HLPHeader, Models::WinHelpHeader] Parsed header with metadata
+      # @raise [Cabriolet::ParseError] if file is not a valid HLP format
       def parse(filename)
-        handle = @io_system.open(filename, Constants::MODE_READ)
-
-        begin
-          parse_header(handle)
-        ensure
-          @io_system.close(handle)
+        # Detect format
+        format = detect_format(filename)
+
+        # Dispatch to appropriate parser
+        case format
+        when :quickhelp
+          QuickHelp::Parser.new(@io_system).parse(filename)
+        when :winhelp
+          WinHelp::Parser.new(@io_system).parse(filename)
+        else
+          raise Cabriolet::ParseError,
+                "Unknown HLP format in file: #{filename}"
         end
       end
 
       private
 
-      # Parse HLP header from file handle
-      #
-      # @param handle [System::FileHandle] Open file handle
-      # @return [Models::HLPHeader] Parsed header with file list
-      # @raise [Errors::ParseError] if header is invalid
-      def parse_header(handle)
-        # Read header structure
-        header_data = @io_system.read(handle, 18)
-        raise Errors::ParseError, "File too small for HLP header" if
-          header_data.bytesize < 18
-
-        binary_header = Binary::HLPStructures::Header.read(header_data)
-
-        # Validate signature
-        unless valid_signature?(binary_header.signature)
-          raise Errors::ParseError,
-                "Invalid HLP signature: #{binary_header.signature.inspect}"
-        end
-
-        # Create header model
-        header = Models::HLPHeader.new(
-          magic: binary_header.signature,
-          version: binary_header.version,
-          length: 0,
-        )
-
-        # Parse file directory if present
-        if binary_header.file_count.positive? &&
-            binary_header.directory_offset.positive?
-          parse_directory(handle, header, binary_header)
-        end
-
-        header
-      end
-
-      # Parse file directory
+      # Detect HLP format variant
       #
-      # @param handle [System::FileHandle] Open file handle
-      # @param header [Models::HLPHeader] Header to populate
-      # @param binary_header [Binary::HLPStructures::Header] Binary header
-      # @return [void]
-      def parse_directory(handle, header, binary_header)
-        # Seek to directory
-        @io_system.seek(
-          handle,
-          binary_header.directory_offset,
-          Constants::SEEK_START,
-        )
-
-        # Read each file entry
-        binary_header.file_count.times do
-          # Read filename length
-          length_data = @io_system.read(handle, 4)
-          break if length_data.bytesize < 4
-
-          filename_length = length_data.unpack1("V")
-          next if filename_length.zero? || filename_length > 1024
-
-          # Read filename
-          filename = @io_system.read(handle, filename_length)
-          next if filename.bytesize != filename_length
-
-          # Read rest of entry (offset, sizes, compression flag)
-          metadata_data = @io_system.read(handle, 13)
-          next if metadata_data.bytesize < 13
-
-          offset, uncompressed_size, compressed_size, compression_flag =
-            metadata_data.unpack("V3C")
-
-          # Create file model
-          file = Models::HLPFile.new(
-            filename: filename.force_encoding("ASCII-8BIT"),
-            offset: offset,
-            length: uncompressed_size,
-            compressed_length: compressed_size,
-            compressed: compression_flag != 0,
-          )
+      # @param filename [String] Path to HLP file
+      # @return [Symbol] :quickhelp or :winhelp
+      # @raise [Cabriolet::ParseError] if format cannot be determined
+      def detect_format(filename)
+        handle = @io_system.open(filename, Constants::MODE_READ)
 
-          header.files << file
+        begin
+          # Read first 4 bytes to check signature
+          sig_data = @io_system.read(handle, 4)
+
+          # Check QuickHelp signature ("LN" at offset 0)
+          if sig_data[0..1] == Binary::HLPStructures::SIGNATURE
+            return :quickhelp
+          end
+
+          # Check WinHelp 3.x magic (0x35F3 at offset 0, 16-bit)
+          magic_word = sig_data[0..1].unpack1("v")
+          return :winhelp if magic_word == 0x35F3
+
+          # Check WinHelp 4.x magic (0x5F3F or 0x3F5F in lower 16 bits of 32-bit value)
+          magic_dword = sig_data.unpack1("V")
+          return :winhelp if (magic_dword & 0xFFFF) == 0x5F3F || (magic_dword & 0xFFFF) == 0x3F5F
+
+          # Unknown format
+          raise Cabriolet::ParseError,
+                "Unknown HLP signature: #{sig_data.bytes.map do |b|
+                  format('0x%02X', b)
+                end.join(' ')}"
+        ensure
+          @io_system.close(handle)
         end
       end
-
-      # Check if signature is valid HLP
-      #
-      # @param signature [String] Signature bytes
-      # @return [Boolean] true if valid
-      def valid_signature?(_signature)
-        # Accept the placeholder signature or other common HLP signatures
-        # For now, accept any signature since we're testing without real fixtures
-        true
-      end
     end
   end
 end

data/lib/cabriolet/hlp/quickhelp/compression_stream.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "../../binary/bitstream"
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Compression stream decoder for QuickHelp topics
+      #
+      # Handles dictionary substitution (keyword compression) and run-length
+      # encoding as specified in the QuickHelp format.
+      #
+      # Control bytes 0x10-0x1A have special meanings:
+      # - 0x10-0x17: Dictionary entry (with optional space append)
+      # - 0x18: Run of spaces
+      # - 0x19: Run of bytes
+      # - 0x1A: Escape byte
+      class CompressionStream
+        # Initialize compression stream decoder
+        #
+        # @param input [String, IO] Input data (compressed)
+        # @param keywords [Array<String>] Keyword dictionary
+        def initialize(input, keywords = [])
+          @input = input.is_a?(String) ? StringIO.new(input) : input
+          @keywords = keywords || []
+          @buffer = ""
+          @buffer_pos = 0
+        end
+
+        # Read bytes from the decompressed stream
+        #
+        # @param length [Integer] Number of bytes to read
+        # @return [String] Decompressed data
+        def read(length)
+          result = String.new(encoding: Encoding::BINARY)
+
+          while result.bytesize < length
+            # Fill buffer if needed
+            fill_buffer(length - result.bytesize) if @buffer_pos >= @buffer.bytesize
+
+            # Check for EOF
+            break if @buffer_pos >= @buffer.bytesize
+
+            # Copy from buffer
+            available = @buffer.bytesize - @buffer_pos
+            to_copy = [length - result.bytesize, available].min
+            result << @buffer[@buffer_pos, to_copy]
+            @buffer_pos += to_copy
+          end
+
+          result
+        end
+
+        # Check if at end of stream
+        #
+        # @return [Boolean] true if EOF
+        def eof?
+          @buffer_pos >= @buffer.bytesize && @input.eof?
+        end
+
+        private
+
+        # Fill internal buffer by decoding compressed data
+        #
+        # @param max_bytes [Integer] Maximum bytes to decode
+        def fill_buffer(max_bytes)
+          @buffer = String.new(encoding: Encoding::BINARY)
+          @buffer_pos = 0
+
+          # Decode until buffer has enough data or we hit EOF
+          while @buffer.bytesize <= 256 && @buffer.bytesize < max_bytes
+            byte = read_byte
+            break if byte.nil? # EOF
+
+            if byte < 0x10 || byte > 0x1A
+              # Regular value byte
+              @buffer << byte.chr
+            elsif byte == 0x1A
+              # Escape byte - next byte is literal
+              escaped = read_byte
+              if escaped.nil?
+                raise Cabriolet::DecompressionError,
+                      "Unexpected EOF after escape byte"
+              end
+
+              @buffer << escaped.chr
+            elsif byte == 0x19
+              # Run of bytes: REPEAT-BYTE, REPEAT-COUNT
+              repeat_byte = read_byte
+              repeat_count = read_byte
+              if repeat_byte.nil? || repeat_count.nil?
+                raise Cabriolet::DecompressionError,
+                      "Unexpected EOF in byte run"
+              end
+
+              @buffer << (repeat_byte.chr * repeat_count)
+            elsif byte == 0x18
+              # Run of spaces: SPACE-COUNT
+              space_count = read_byte
+              if space_count.nil?
+                raise Cabriolet::DecompressionError,
+                      "Unexpected EOF in space run"
+              end
+
+              @buffer << (" " * space_count)
+            else
+              # Dictionary entry (0x10-0x17)
+              dict_index_low = read_byte
+              if dict_index_low.nil?
+                raise Cabriolet::DecompressionError,
+                      "Unexpected EOF reading dictionary index"
+              end
+
+              # Extract append-space flag (bit 2) and index (bits 0-1 + next 8 bits)
+              append_space = byte.anybits?(0x04)
+              dict_index = ((byte & 0x03) << 8) | dict_index_low
+
+              if dict_index >= @keywords.length
+                raise Cabriolet::DecompressionError,
+                      "Dictionary index #{dict_index} out of range (max #{@keywords.length - 1})"
+              end
+
+              @buffer << @keywords[dict_index]
+              @buffer << " " if append_space
+            end
+          end
+        end
+
+        # Read a single byte from input
+        #
+        # @return [Integer, nil] Byte value or nil on EOF
+        def read_byte
+          @input.getbyte
+        end
+      end
+    end
+  end
+end