cabriolet 0.1.2 → 0.2.1

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/hlp/winhelp/btree_builder.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require_relative "../../binary/hlp_structures"
+require "stringio"
+
+module Cabriolet
+  module HLP
+    module WinHelp
+      # B+ tree builder for WinHelp 4.x directory format
+      #
+      # Builds B+ tree directory structure for WinHelp 4.x files.
+      # The directory maps filenames to file offsets using a B+ tree
+      # with fixed-size pages.
+      class BTreeBuilder
+        # Default page size for WinHelp 4.x directory (1KB for catalog/directory)
+        DEFAULT_PAGE_SIZE = 0x0400 # 1KB
+
+        # Page types
+        PAGE_TYPE_LEAF = 0
+        PAGE_TYPE_INDEX = 1
+
+        # B+ tree magic number
+        BTREE_MAGIC = 0x293B
+
+        # Flags for B+ tree header
+        # Bit 0x0002 is always 1
+        # Bit 0x0400 is 1 for catalog/directory
+        FLAGS_MAGIC_BIT = 0x0002
+        FLAGS_CATALOG_BIT = 0x0400
+
+        attr_reader :page_size, :structure
+
+        # Initialize B+ tree builder
+        #
+        # @param page_size [Integer] Page size in bytes (default: 1KB)
+        # @param structure [String] Structure string describing data format
+        def initialize(page_size: DEFAULT_PAGE_SIZE, structure: "FFz")
+          @page_size = page_size
+          @structure = structure
+          @entries = []
+        end
+
+        # Add a file entry to the B+ tree
+        #
+        # @param filename [String] Internal filename (e.g., "|SYSTEM")
+        # @param offset [Integer] File offset in help file
+        # @param size [Integer] File size in bytes
+        def add_entry(filename, offset, size)
+          @entries << { filename: filename, offset: offset, size: size }
+        end
+
+        # Build B+ tree structure
+        #
+        # @return [Hash] Hash containing :header, :pages
+        def build
+          return build_empty if @entries.empty?
+
+          # Sort entries by filename
+          sorted_entries = @entries.sort_by { |e| e[:filename] }
+
+          # Build leaf pages
+          leaf_pages = build_leaf_pages(sorted_entries)
+
+          # Build index pages if needed
+          if leaf_pages.size > 1
+            index_pages = build_index_pages(leaf_pages)
+            root_page = index_pages.first[:page_num]
+            n_levels = 2
+          else
+            index_pages = []
+            root_page = leaf_pages.first[:page_num]
+            n_levels = 1
+          end
+
+          # Build B+ tree header
+          header = build_header(
+            total_pages: leaf_pages.size + index_pages.size,
+            root_page: root_page,
+            n_levels: n_levels,
+            total_entries: @entries.size,
+          )
+
+          # Combine all pages
+          all_pages = index_pages + leaf_pages
+
+          { header: header, pages: all_pages }
+        end
+
+        private
+
+        # Build empty B+ tree (single empty leaf page)
+        #
+        # @return [Hash] Hash containing :header, :pages
+        def build_empty
+          # Create empty leaf page
+          leaf_page = {
+            page_num: 0,
+            data: build_empty_leaf_page,
+          }
+
+          header = build_header(
+            total_pages: 1,
+            root_page: 0,
+            n_levels: 1,
+            total_entries: 0,
+          )
+
+          { header: header, pages: [leaf_page] }
+        end
+
+        # Build B+ tree header
+        #
+        # @param total_pages [Integer] Total number of pages
+        # @param root_page [Integer] Root page number
+        # @param n_levels [Integer] Number of levels in tree
+        # @param total_entries [Integer] Total number of entries
+        # @return [Binary::HLPStructures::WinHelpBTreeHeader] B+ tree header
+        def build_header(total_pages:, root_page:, n_levels:, total_entries:)
+          Binary::HLPStructures::WinHelpBTreeHeader.new(
+            magic: BTREE_MAGIC,
+            flags: FLAGS_MAGIC_BIT | FLAGS_CATALOG_BIT,
+            page_size: @page_size,
+            structure: @structure.ljust(16, "\x00"),
+            must_be_zero: 0,
+            page_splits: 0,
+            root_page: root_page,
+            must_be_neg_one: 0xFFFF,
+            total_pages: total_pages,
+            n_levels: n_levels,
+            total_btree_entries: total_entries,
+          )
+        end
+
+        # Build leaf pages from entries
+        #
+        # @param entries [Array<Hash>] Sorted file entries
+        # @return [Array<Hash>] Array of page hashes with :page_num and :data
+        def build_leaf_pages(entries)
+          pages = []
+          current_page_data = StringIO.new
+          page_num = 0
+
+          entries.each do |entry|
+            # Check if this entry fits in current page
+            entry_size = entry[:filename].bytesize + 1 + 4 # filename + null + offset
+            header_size = 8 # leaf node header
+
+            # Check if we need a new page
+            if (current_page_data.size + entry_size + header_size) > @page_size
+              # Finish current page and start new one
+              pages << finish_leaf_page(current_page_data, page_num,
+                                        pages.empty?)
+              page_num += 1
+              current_page_data = StringIO.new
+            end
+
+            # Write entry to current page
+            current_page_data.write(entry[:filename])
+            current_page_data.write("\x00") # null terminator
+            current_page_data.write([entry[:offset]].pack("V")) # 4-byte offset
+          end
+
+          # Finish last page
+          if current_page_data.size.positive?
+            pages << finish_leaf_page(current_page_data, page_num, pages.empty?)
+          end
+
+          pages
+        end
+
+        # Finish a leaf page by adding header
+        #
+        # @param page_data [StringIO] Page data without header
+        # @param page_num [Integer] Page number
+        # @param is_first [Boolean] Whether this is the first page
+        # @return [Hash] Page hash with :page_num and :data
+        def finish_leaf_page(page_data, page_num, is_first)
+          data = page_data.string
+          n_entries = count_entries(data)
+
+          # Build leaf node header
+          # - 2 bytes: unused (we use 0)
+          # - 2 bytes: nEntries
+          # - 2 bytes: PreviousPage (0xFFFF for first)
+          # - 2 bytes: NextPage (0xFFFF for last, to be determined)
+          header = [
+            0, # unused
+            n_entries,
+            is_first ? 0xFFFF : page_num - 1, # previous page
+            0xFFFF, # next page (will update if more pages added)
+          ].pack("vvvv")
+
+          { page_num: page_num, data: header + data }
+        end
+
+        # Build empty leaf page
+        #
+        # @return [String] Empty leaf page data
+        def build_empty_leaf_page
+          # Empty leaf has header with nEntries = 0
+          [
+            0, # unused
+            0, # nEntries = 0
+            0xFFFF, # previous page
+            0xFFFF, # next page
+          ].pack("vvvv")
+        end
+
+        # Build index pages from leaf pages
+        #
+        # @param leaf_pages [Array<Hash>] Leaf page hashes
+        # @return [Array<Hash>] Array of index page hashes
+        def build_index_pages(leaf_pages)
+          # For simplicity, create single index page pointing to all leaf pages
+          # In a real implementation, this would recursively build index pages
+          index_data = StringIO.new
+
+          leaf_pages.each do |page|
+            # For index pages, entries are: (filename, page_number)
+            # We use the first filename from each leaf page as key
+            first_filename = extract_first_filename(page[:data])
+            index_data.write(first_filename)
+            index_data.write("\x00") # null terminator
+            index_data.write([page[:page_num]].pack("v")) # 2-byte page number
+          end
+
+          data = index_data.string
+          n_entries = leaf_pages.size
+
+          # Build index node header
+          # - 2 bytes: unused (we use 0)
+          # - 2 bytes: nEntries
+          # - 2 bytes: PreviousPage (0xFFFF - no previous)
+          header = [
+            0, # unused
+            n_entries,
+            0xFFFF, # previous page (none for root)
+          ].pack("vvv")
+
+          [{
+            page_num: leaf_pages.size, # Index pages come after leaf pages
+            data: header + data,
+          }]
+        end
+
+        # Extract first filename from page data
+        #
+        # @param page_data [String] Page data with header
+        # @return [String] First filename in page
+        def extract_first_filename(page_data)
+          # Skip 8-byte header
+          data_start = 8
+          data = page_data[data_start..]
+
+          # Filename is null-terminated
+          null_pos = data.index("\x00")
+          return "" if null_pos.nil?
+
+          data[0...null_pos]
+        end
+
+        # Count entries in page data
+        #
+        # @param data [String] Page data without header
+        # @return [Integer] Number of entries
+        def count_entries(data)
+          count = 0
+          pos = 0
+
+          while pos < data.bytesize
+            # Find null terminator
+            null_pos = data.index("\x00", pos)
+            break if null_pos.nil?
+
+            # Skip filename
+            pos = null_pos + 1
+
+            # Skip 4-byte offset
+            pos += 4
+
+            count += 1
+          end
+
+          count
+        end
+      end
+    end
+  end
+end