cabriolet 0.2.0 → 0.2.1

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/structure_builder.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "topic_compressor"
+require_relative "offset_calculator"
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Builds complete QuickHelp structure from file data
+      class StructureBuilder
+        attr_reader :version, :database_name, :control_char, :case_sensitive
+
+        # Initialize structure builder
+        #
+        # @param version [Integer] QuickHelp format version
+        # @param database_name [String] Database name for external links
+        # @param control_char [Integer] Control character
+        # @param case_sensitive [Boolean] Case-sensitive contexts
+        def initialize(version: 2, database_name: "", control_char: 0x3A,
+case_sensitive: false)
+          @version = version
+          @database_name = database_name
+          @control_char = control_char
+          @case_sensitive = case_sensitive
+        end
+
+        # Build complete QuickHelp structure from topics
+        #
+        # @param topics [Array<Hash>] Topic data with :text, :context, :compress keys
+        # @return [Hash] Complete QuickHelp structure
+        def build(topics)
+          structure = {}
+
+          # Compress topics
+          structure[:topics] = compress_topics(topics)
+
+          # Build context data
+          structure[:contexts] = topics.map { |t| t[:context] }
+          structure[:context_map] = topics.map.with_index { |_t, i| i }
+
+          # Calculate offsets
+          structure[:offsets] = OffsetCalculator.calculate(
+            topics: structure[:topics],
+            contexts: structure[:contexts],
+            context_map: structure[:context_map],
+          )
+
+          # Build header
+          structure[:header] = build_header(structure)
+
+          structure
+        end
+
+        private
+
+        # Compress all topics
+        #
+        # @param topics [Array<Hash>] Topic data
+        # @return [Array<Hash>] Compressed topics
+        def compress_topics(topics)
+          topics.map do |topic|
+            if topic[:compress]
+              TopicCompressor.compress_topic(topic[:text])
+            else
+              TopicCompressor.store_uncompressed(topic[:text])
+            end
+          end
+        end
+
+        # Build file header
+        #
+        # @param structure [Hash] QuickHelp structure
+        # @return [Hash] Header information
+        def build_header(structure)
+          attributes = 0
+          attributes |= Binary::HLPStructures::Attributes::CASE_SENSITIVE if @case_sensitive
+
+          {
+            version: @version,
+            attributes: attributes,
+            control_character: @control_char,
+            topic_count: structure[:topics].size,
+            context_count: structure[:contexts].size,
+            display_width: 80,
+            predefined_ctx_count: 0,
+            database_name: @database_name.ljust(14, "\x00")[0, 14],
+            offsets: structure[:offsets],
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Builds topic data in QuickHelp internal format
+      class TopicBuilder
+        # Build topic data in QuickHelp internal format
+        #
+        # Topic format as expected by decompressor:
+        # - Each line: [text_length][text][newline][attr_len][attrs][0xFF]
+        # - text_length = text + newline + 1 (for attr_len byte) = text_bytes + 2
+        # - Line structure: text_length byte + text + newline + attr_len byte + attr_data
+        #
+        # The decompressor reads:
+        # - text_length = data.getbyte(pos)
+        # - text_bytes = text_length - 2 (reads text, skips newline)
+        # - attr_length = data.getbyte(pos after text + newline)
+        #
+        # @param text [String] Raw topic text
+        # @return [String] Formatted topic data
+        def self.build_topic_data(text)
+          result = +""
+
+          # Split text into lines
+          lines = text.split("\n")
+
+          lines.each do |line|
+            text_bytes = line.b
+            newline = "\x0D" # Carriage return
+
+            # Attribute section: just 0xFF terminator (attr_len = 1)
+            attr_data = "\xFF"
+            attr_len = 1
+
+            # text_length = text + newline + 1 (for attr_len byte)
+            # This ensures text_bytes = text_length - 2 gives correct text length
+            text_length = text_bytes.bytesize + 2
+
+            result << text_length.chr
+            result << text_bytes
+            result << newline
+            result << attr_len.chr
+            result << attr_data
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module HLP
+    module QuickHelp
+      # Compresses topic text using QuickHelp keyword compression
+      class TopicCompressor
+        # Compress topic text using QuickHelp keyword compression
+        #
+        # QuickHelp format uses:
+        # - 0x00-0x0F: Literal bytes
+        # - 0x10-0x17: Dictionary entry references
+        # - 0x18: Run of spaces
+        # - 0x19: Run of bytes (repeat)
+        # - 0x1A: Escape byte (next byte is literal)
+        # - 0x1B-0xFF: Literal bytes
+        #
+        # Without a dictionary, we encode literals directly and escape
+        # control characters (0x10-0x1A) with 0x1A prefix.
+        #
+        # Topic text format:
+        # - Each line: [len][text][newline][attr_len][attrs][0xFF]
+        # - len includes itself, text, newline, attr_len
+        # - attr_len includes itself and attrs, minimum 1 (just 0xFF terminator)
+        #
+        # @param text [String] Topic text
+        # @return [Hash] Compressed topic with metadata
+        def self.compress_topic(text)
+          topic_data = TopicBuilder.build_topic_data(text)
+          encoded = encode_keyword_compression(topic_data)
+
+          # Prepend decompressed length (2 bytes)
+          length_header = [topic_data.bytesize].pack("v")
+
+          {
+            text: text,
+            compressed: length_header + encoded,
+            decompressed_length: topic_data.bytesize,
+            compressed_length: (length_header + encoded).bytesize,
+          }
+        end
+
+        # Store topic without compression
+        #
+        # @param text [String] Topic text
+        # @return [Hash] Uncompressed topic with metadata
+        def self.store_uncompressed(text)
+          topic_data = TopicBuilder.build_topic_data(text)
+
+          {
+            text: text,
+            compressed: topic_data,
+            decompressed_length: topic_data.bytesize,
+            compressed_length: topic_data.bytesize,
+          }
+        end
+
+        # Encode data using QuickHelp keyword compression format
+        #
+        # @param data [String] Data to encode
+        # @return [String] Encoded data
+        def self.encode_keyword_compression(data)
+          result = +""
+
+          data.bytes.each do |byte|
+            if byte < 0x10 || byte == 0x1B || byte > 0x1A
+              # Literal byte (except control range 0x10-0x1A)
+              result << byte.chr
+            elsif byte.between?(0x10, 0x1A)
+              # Control byte - escape it
+              result << 0x1A.chr << byte.chr
+            else
+              # 0x1B is also literal (above control range)
+              result << byte.chr
+            end
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/cabriolet/huffman/encoder.rb

@@ -53,20 +53,23 @@ module Cabriolet
       #
       # @return [Hash] Hash with :literal and :distance code tables
       def self.build_fixed_codes
-        # Fixed literal/length code lengths
-        literal_lengths = Array.new(288, 0)
-        (0...144).each { |i| literal_lengths[i] = 8 }
-        (144...256).each { |i| literal_lengths[i] = 9 }
-        (256...280).each { |i| literal_lengths[i] = 7 }
-        (280...288).each { |i| literal_lengths[i] = 8 }
+        # Memoize fixed codes since they never change
+        @build_fixed_codes ||= begin
+          # Fixed literal/length code lengths
+          literal_lengths = Array.new(288, 0)
+          (0...144).each { |i| literal_lengths[i] = 8 }
+          (144...256).each { |i| literal_lengths[i] = 9 }
+          (256...280).each { |i| literal_lengths[i] = 7 }
+          (280...288).each { |i| literal_lengths[i] = 8 }
 
-        # Fixed distance code lengths (all 5 bits)
-        distance_lengths = Array.new(32, 5)
+          # Fixed distance code lengths (all 5 bits)
+          distance_lengths = Array.new(32, 5)
 
-        {
-          literal: build_codes(literal_lengths, 288),
-          distance: build_codes(distance_lengths, 32),
-        }
+          {
+            literal: build_codes(literal_lengths, 288),
+            distance: build_codes(distance_lengths, 32),
+          }
+        end
       end
 
       # Encode a symbol using Huffman codes and write to bitstream