cabriolet 0.1.2 → 0.2.1

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Writes QuickHelp files to disk
+      class FileWriter
+        # Initialize file writer
+        #
+        # @param io_system [System::IOSystem] I/O system for writing
+        def initialize(io_system)
+          @io_system = io_system
+        end
+
+        # Write complete QuickHelp file
+        #
+        # @param output_handle [System::FileHandle] Output file handle
+        # @param structure [Hash] QuickHelp structure
+        # @return [Integer] Bytes written
+        def write_quickhelp_file(output_handle, structure)
+          bytes_written = 0
+
+          # Write file header
+          bytes_written += write_file_header(output_handle, structure[:header])
+
+          # Write topic index
+          bytes_written += write_topic_index(output_handle,
+                                             structure[:header][:offsets])
+
+          # Write context strings
+          bytes_written += write_context_strings(output_handle,
+                                                 structure[:contexts])
+
+          # Write context map
+          bytes_written += write_context_map(output_handle,
+                                             structure[:context_map])
+
+          # Write topic texts
+          bytes_written += write_topic_texts(output_handle, structure[:topics])
+
+          bytes_written
+        end
+
+        # Write file header
+        #
+        # @param output_handle [System::FileHandle] Output file handle
+        # @param header_info [Hash] Header information
+        # @return [Integer] Bytes written
+        def write_file_header(output_handle, header_info)
+          header = Binary::HLPStructures::FileHeader.new
+          header.signature = Binary::HLPStructures::SIGNATURE
+          header.version = header_info[:version]
+          header.attributes = header_info[:attributes]
+          header.control_character = header_info[:control_character]
+          header.padding1 = 0
+          header.topic_count = header_info[:topic_count]
+          header.context_count = header_info[:context_count]
+          header.display_width = header_info[:display_width]
+          header.padding2 = 0
+          header.predefined_ctx_count = header_info[:predefined_ctx_count]
+          header.database_name = header_info[:database_name]
+          header.reserved1 = 0
+          header.topic_index_offset = header_info[:offsets][:topic_index]
+          header.context_strings_offset = header_info[:offsets][:context_strings]
+          header.context_map_offset = header_info[:offsets][:context_map]
+          header.keywords_offset = header_info[:offsets][:keywords]
+          header.huffman_tree_offset = header_info[:offsets][:huffman_tree]
+          header.topic_text_offset = header_info[:offsets][:topic_text]
+          header.reserved2 = 0
+          header.reserved3 = 0
+          header.database_size = header_info[:offsets][:database_size]
+
+          header_data = header.to_binary_s
+          @io_system.write(output_handle, header_data)
+        end
+
+        # Write topic index
+        #
+        # @param output_handle [System::FileHandle] Output file handle
+        # @param offsets [Hash] Offset information
+        # @return [Integer] Bytes written
+        def write_topic_index(output_handle, offsets)
+          # Write all topic offsets including end marker
+          index_data = offsets[:topic_offsets].pack("V*")
+          @io_system.write(output_handle, index_data)
+        end
+
+        # Write context strings
+        #
+        # @param output_handle [System::FileHandle] Output file handle
+        # @param contexts [Array<String>] Context strings
+        # @return [Integer] Bytes written
+        def write_context_strings(output_handle, contexts)
+          data = contexts.map { |ctx| "#{ctx}\u0000" }.join
+          @io_system.write(output_handle, data)
+        end
+
+        # Write context map
+        #
+        # @param output_handle [System::FileHandle] Output file handle
+        # @param context_map [Array<Integer>] Topic indices
+        # @return [Integer] Bytes written
+        def write_context_map(output_handle, context_map)
+          map_data = context_map.pack("v*")
+          @io_system.write(output_handle, map_data)
+        end
+
+        # Write topic texts
+        #
+        # @param output_handle [System::FileHandle] Output file handle
+        # @param topics [Array<Hash>] Compressed topics
+        # @return [Integer] Bytes written
+        def write_topic_texts(output_handle, topics)
+          total_bytes = 0
+
+          topics.each do |topic|
+            total_bytes += @io_system.write(output_handle, topic[:compressed])
+          end
+
+          total_bytes
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../../binary/bitstream"
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Huffman stream decoder for QuickHelp topics
+      #
+      # Wraps a bitstream and uses a Huffman tree to decode symbols.
+      # Reads bits from MSB to LSB within each byte.
+      class HuffmanStream
+        # Initialize Huffman stream decoder
+        #
+        # @param input [String, IO] Input data (Huffman-encoded bitstream)
+        # @param huffman_tree [HuffmanTree] Huffman tree for decoding
+        def initialize(input, huffman_tree)
+          @input = input.is_a?(String) ? StringIO.new(input) : input
+          @huffman_tree = huffman_tree
+          # QuickHelp uses MSB-first bit order
+          @bitstream = Binary::Bitstream.new(@input, true) # MSB first
+        end
+
+        # Read and decode bytes from the Huffman stream
+        #
+        # @param length [Integer] Number of decoded bytes to read
+        # @return [String] Decoded data
+        def read(length)
+          result = String.new(encoding: Encoding::BINARY)
+
+          length.times do
+            byte = read_byte
+            break if byte.nil?
+
+            result << byte.chr
+          end
+
+          result
+        end
+
+        # Read and decode a single byte
+        #
+        # @return [Integer, nil] Decoded byte value or nil on EOF
+        def read_byte
+          return nil if @huffman_tree.empty?
+
+          # Handle singular tree (single symbol, no bits needed)
+          if @huffman_tree.singular?
+            return @huffman_tree.root.symbol
+          end
+
+          # Decode using tree
+          decoder = @huffman_tree.create_decoder
+
+          until decoder.has_value?
+            bit = @bitstream.read_bits(1)
+            return nil if bit.nil? # EOF
+
+            decoder.push(bit != 0)
+          end
+
+          decoder.value
+        end
+
+        # Check if at end of stream
+        #
+        # @return [Boolean] true if EOF
+        def eof?
+          @input.eof?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Huffman tree for QuickHelp topic compression
+      #
+      # Represents a Huffman tree that encodes symbols 0-255.
+      # Based on the QuickHelp binary format specification.
+      class HuffmanTree
+        attr_reader :root, :symbol_count
+
+        # Node in the Huffman tree
+        class Node
+          attr_accessor :symbol, :left_child, :right_child
+
+          def initialize
+            @symbol = nil
+            @left_child = nil
+            @right_child = nil
+          end
+
+          def leaf?
+            @left_child.nil? && @right_child.nil?
+          end
+        end
+
+        # Initialize empty tree
+        def initialize
+          @root = nil
+          @symbol_count = 0
+        end
+
+        # Check if tree is empty
+        #
+        # @return [Boolean] true if empty
+        def empty?
+          @root.nil?
+        end
+
+        # Check if tree has single node
+        #
+        # @return [Boolean] true if singular
+        def singular?
+          !@root.nil? && @root.leaf?
+        end
+
+        # Deserialize Huffman tree from node values
+        #
+        # @param node_values [Array<Integer>] Array of 16-bit node values
+        # @return [HuffmanTree] Deserialized tree
+        # @raise [Cabriolet::ParseError] if tree is invalid
+        def self.deserialize(node_values)
+          tree = new
+          return tree if node_values.empty?
+
+          n = node_values.length
+          if n.even?
+            raise Cabriolet::ParseError,
+                  "Invalid Huffman tree: expected odd number of nodes"
+          end
+
+          nodes = Array.new(n) { Node.new }
+          symbol_exists = Array.new(256, false)
+
+          n.times do |i|
+            node = nodes[i]
+            node_value = node_values[i]
+
+            if node_value.negative? # Leaf node (bit 15 set)
+              symbol = node_value & 0xFF
+              if symbol_exists[symbol]
+                raise Cabriolet::ParseError,
+                      "Invalid Huffman tree: symbol #{symbol} already encoded"
+              end
+
+              node.symbol = symbol
+              symbol_exists[symbol] = true
+            else # Internal node
+              child0 = node_value / 2
+              child1 = i + 1
+
+              # Validate child indices are within bounds
+              unless child0 < n && child1 < n
+                raise Cabriolet::ParseError,
+                      "Invalid Huffman tree: invalid child node location (child0=#{child0}, child1=#{child1}, n=#{n})"
+              end
+
+              # Check for cycles by verifying left child hasn't been assigned yet
+              if !nodes[child0].nil? && nodes[child0].left_child
+                raise Cabriolet::ParseError,
+                      "Invalid Huffman tree: cycle detected"
+              end
+
+              node.left_child = nodes[child0]
+              node.right_child = nodes[child1]
+            end
+          end
+
+          tree.instance_variable_set(:@root, nodes[0])
+          tree.instance_variable_set(:@symbol_count, (n / 2) + 1)
+          tree
+        end
+
+        # Create a decoder for this tree
+        #
+        # @return [HuffmanDecoder] New decoder
+        def create_decoder
+          HuffmanDecoder.new(self)
+        end
+      end
+
+      # Decoder for Huffman-encoded data
+      #
+      # Usage:
+      #   decoder = tree.create_decoder
+      #   while !decoder.has_value?
+      #     decoder.push(bitstream.read_bit)
+      #   end
+      #   symbol = decoder.value
+      class HuffmanDecoder
+        attr_reader :current_node
+
+        # Initialize decoder
+        #
+        # @param tree [HuffmanTree] Huffman tree to use
+        def initialize(tree)
+          @tree = tree
+          @current_node = tree.root
+        end
+
+        # Check if decoder has decoded a complete symbol
+        #
+        # @return [Boolean] true if value is ready
+        def has_value?
+          !@current_node.nil? && @current_node.leaf?
+        end
+
+        # Get decoded symbol value
+        #
+        # @return [Integer] Symbol value (0-255)
+        # @raise [RuntimeError] if no value is ready
+        def value
+          raise "Decoder does not have a value" unless has_value?
+
+          @current_node.symbol
+        end
+
+        # Push a bit into the decoder
+        #
+        # @param bit [Boolean, Integer] Bit value (true/1 for right, false/0 for left)
+        # @raise [RuntimeError] if tree is empty or at leaf
+        def push(bit)
+          raise "Cannot walk an empty tree" if @current_node.nil?
+          raise "Cannot walk further from a leaf" if @current_node.leaf?
+
+          @current_node = bit ? @current_node.right_child : @current_node.left_child
+        end
+
+        # Reset decoder to tree root
+        def reset
+          @current_node = @tree.root
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Calculates file offsets for QuickHelp structure
+      class OffsetCalculator
+        # Calculate all offsets in the file
+        #
+        # @param topics [Array<Hash>] Compressed topics
+        # @param contexts [Array<String>] Context strings
+        # @param context_map [Array<Integer>] Context topic indices
+        # @return [Hash] Calculated offsets
+        def self.calculate(topics:, contexts:, context_map:)
+          offsets = {}
+
+          # Start after file header (70 bytes = 2 signature + 68 header)
+          current_offset = 70
+
+          # Topic index: (topic_count + 1) * 4 bytes
+          offsets[:topic_index] = current_offset
+          topic_count = topics.size
+          current_offset += (topic_count + 1) * 4
+
+          # Context strings: sum of string lengths + null terminators
+          offsets[:context_strings] = current_offset
+          contexts.each do |ctx|
+            current_offset += ctx.bytesize + 1 # +1 for null terminator
+          end
+
+          # Context map: context_count * 2 bytes
+          offsets[:context_map] = current_offset
+          current_offset += context_map.size * 2
+
+          # Keywords: not implemented yet, set to 0
+          offsets[:keywords] = 0
+
+          # Huffman tree: not implemented yet, set to 0
+          offsets[:huffman_tree] = 0
+
+          # Topic text: starts after context map
+          offsets[:topic_text] = current_offset
+
+          # Calculate topic text offsets
+          offsets[:topic_offsets] = []
+          topics.each do |topic|
+            offsets[:topic_offsets] << (current_offset - offsets[:topic_text])
+            current_offset += topic[:compressed_length]
+          end
+          # Add end marker
+          offsets[:topic_offsets] << (current_offset - offsets[:topic_text])
+
+          # Total database size
+          offsets[:database_size] = current_offset
+
+          offsets
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require_relative "../../system/io_system"
+require_relative "../../constants"
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Parser for QuickHelp (.HLP) files
+      #
+      # Parses the QuickHelp binary format as specified in the DosHelp project.
+      # Structure:
+      # - Signature (2 bytes)
+      # - File Header (68 bytes)
+      # - Topic Index (variable)
+      # - Context Strings (variable)
+      # - Context Map (variable)
+      # - Keywords (optional)
+      # - Huffman Tree (optional)
+      # - Topic Texts (compressed)
+      class Parser
+        attr_reader :io_system
+
+        # Initialize parser
+        #
+        # @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
+
+        # Parse a QuickHelp file
+        #
+        # @param filename [String] Path to HLP file
+        # @return [Models::HLPHeader] Parsed header with metadata
+        # @raise [Cabriolet::ParseError] if file is not valid QuickHelp
+        def parse(filename)
+          handle = @io_system.open(filename, Constants::MODE_READ)
+
+          begin
+            header = parse_file(handle)
+            header.filename = filename
+            header
+          ensure
+            @io_system.close(handle)
+          end
+        end
+
+        private
+
+        # Parse complete QuickHelp file structure
+        #
+        # @param handle [System::FileHandle] Open file handle
+        # @return [Models::HLPHeader] Parsed header
+        # @raise [Cabriolet::ParseError] if parsing fails
+        def parse_file(handle)
+          # Check signature first
+          check_signature(handle)
+
+          # Parse file header
+          header = parse_header(handle)
+
+          # Parse topic index
+          topic_offsets = parse_topic_index(handle, header)
+
+          # Parse context strings and map
+          parse_contexts(handle, header)
+
+          # Parse keywords if present
+          parse_keywords(handle, header) if header.keywords_offset.positive?
+
+          # Parse Huffman tree if present
+          if header.huffman_tree_offset.positive?
+            parse_huffman_tree(handle,
+                               header)
+          end
+
+          # Calculate topic sizes from offsets
+          populate_topics(header, topic_offsets)
+
+          header
+        end
+
+        # Check file signature
+        #
+        # @param handle [System::FileHandle] Open file handle
+        # @raise [Cabriolet::ParseError] if signature is invalid
+        def check_signature(handle)
+          sig_data = @io_system.read(handle, 2)
+
+          unless sig_data == Binary::HLPStructures::SIGNATURE
+            raise Cabriolet::ParseError,
+                  "Invalid QuickHelp signature: expected 'LN' (0x4C 0x4E), " \
+                  "got #{sig_data.bytes.map do |b|
+                    format('0x%02X', b)
+                  end.join(' ')}"
+          end
+        end
+
+        # Parse file header
+        #
+        # @param handle [System::FileHandle] Open file handle positioned after signature
+        # @return [Models::HLPHeader] Parsed header
+        # @raise [Cabriolet::ParseError] if header is invalid
+        def parse_header(handle)
+          header_data = @io_system.read(handle, 68)
+          if header_data.bytesize < 68
+            raise Cabriolet::ParseError,
+                  "File too small for QuickHelp header"
+          end
+
+          binary_header = Binary::HLPStructures::FileHeader.read(
+            Binary::HLPStructures::SIGNATURE + header_data,
+          )
+
+          # Validate version
+          unless binary_header.version == 2
+            raise Cabriolet::ParseError,
+                  "Unsupported QuickHelp version: #{binary_header.version}"
+          end
+
+          # Create header model
+          Models::HLPHeader.new(
+            magic: binary_header.signature,
+            version: binary_header.version,
+            attributes: binary_header.attributes,
+            control_character: binary_header.control_character,
+            topic_count: binary_header.topic_count,
+            context_count: binary_header.context_count,
+            display_width: binary_header.display_width,
+            predefined_ctx_count: binary_header.predefined_ctx_count,
+            database_name: binary_header.database_name,
+            topic_index_offset: binary_header.topic_index_offset,
+            context_strings_offset: binary_header.context_strings_offset,
+            context_map_offset: binary_header.context_map_offset,
+            keywords_offset: binary_header.keywords_offset,
+            huffman_tree_offset: binary_header.huffman_tree_offset,
+            topic_text_offset: binary_header.topic_text_offset,
+            database_size: binary_header.database_size,
+          )
+        end
+
+        # Parse topic index section
+        #
+        # @param handle [System::FileHandle] Open file handle
+        # @param header [Models::HLPHeader] Header with offset information
+        # @return [Array<Integer>] Topic offsets (including end marker)
+        # @raise [Cabriolet::ParseError] if topic index is invalid
+        def parse_topic_index(handle, header)
+          # Seek to topic index
+          @io_system.seek(handle, header.topic_index_offset, Constants::SEEK_START)
+
+          # Read (topic_count + 1) DWORDs
+          count = header.topic_count + 1
+          index_data = @io_system.read(handle, count * 4)
+
+          if index_data.bytesize < count * 4
+            raise Cabriolet::ParseError, "Cannot read complete topic index"
+          end
+
+          # Unpack as array of little-endian 32-bit integers
+          index_data.unpack("V#{count}")
+        end
+
+        # Parse context strings and context map
+        #
+        # @param handle [System::FileHandle] Open file handle
+        # @param header [Models::HLPHeader] Header with offset information
+        # @raise [Cabriolet::ParseError] if context data is invalid
+        def parse_contexts(handle, header)
+          return if header.context_count.zero?
+
+          # Read context strings
+          @io_system.seek(handle, header.context_strings_offset, Constants::SEEK_START)
+          strings_size = header.context_map_offset - header.context_strings_offset
+          strings_data = @io_system.read(handle, strings_size)
+
+          # Split by null terminators
+          header.contexts = strings_data.force_encoding(Encoding::ASCII).split("\x00")
+
+          # Read context map
+          @io_system.seek(handle, header.context_map_offset, Constants::SEEK_START)
+          map_data = @io_system.read(handle, header.context_count * 2)
+
+          if map_data.bytesize < header.context_count * 2
+            raise Cabriolet::ParseError, "Cannot read complete context map"
+          end
+
+          # Unpack as array of little-endian 16-bit integers
+          header.context_map = map_data.unpack("v#{header.context_count}")
+        end
+
+        # Parse keywords dictionary
+        #
+        # @param handle [System::FileHandle] Open file handle
+        # @param header [Models::HLPHeader] Header with offset information
+        # @raise [Cabriolet::ParseError] if keywords section is invalid
+        def parse_keywords(handle, header)
+          @io_system.seek(handle, header.keywords_offset, Constants::SEEK_START)
+
+          # Calculate section size
+          next_offset = header.huffman_tree_offset.positive? ? header.huffman_tree_offset : header.topic_text_offset
+          section_size = next_offset - header.keywords_offset
+
+          return if section_size <= 0
+
+          section_data = @io_system.read(handle, section_size)
+
+          # Parse length-prefixed strings
+          header.keywords = []
+          pos = 0
+
+          while pos < section_data.bytesize
+            length = section_data.getbyte(pos)
+            break if length.nil? || length.zero?
+
+            pos += 1
+            break if pos + length > section_data.bytesize
+
+            keyword = section_data[pos, length]
+            header.keywords << keyword
+            pos += length
+          end
+        end
+
+        # Parse Huffman tree
+        #
+        # @param handle [System::FileHandle] Open file handle
+        # @param header [Models::HLPHeader] Header with offset information
+        # @raise [Cabriolet::ParseError] if Huffman tree is invalid
+        def parse_huffman_tree(handle, header)
+          @io_system.seek(handle, header.huffman_tree_offset, Constants::SEEK_START)
+
+          # Read nodes until we hit terminating 0x0000
+          nodes = []
+          loop do
+            node_data = @io_system.read(handle, 2)
+            break if node_data.bytesize < 2
+
+            node_value = node_data.unpack1("v")
+            break if node_value.zero? # Terminating null
+
+            nodes << node_value
+          end
+
+          # Validate node count (must be odd, representing a proper binary tree)
+          if nodes.length.even? && !nodes.empty?
+            raise Cabriolet::ParseError,
+                  "Invalid Huffman tree: expected odd number of nodes"
+          end
+
+          # Store raw node values (will be decoded during decompression)
+          header.huffman_tree = nodes
+        end
+
+        # Populate topic metadata from offset array
+        #
+        # @param header [Models::HLPHeader] Header to populate
+        # @param offsets [Array<Integer>] Topic offsets
+        def populate_topics(header, offsets)
+          header.topics = []
+
+          header.topic_count.times do |i|
+            topic = Models::HLPTopic.new(
+              index: i,
+              offset: offsets[i],
+              size: offsets[i + 1] - offsets[i],
+            )
+            header.topics << topic
+          end
+        end
+      end
+    end
+  end
+end