cabriolet 0.1.2 → 0.2.0

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

data/lib/cabriolet/hlp/winhelp/compressor.rb

@@ -0,0 +1,400 @@
+# frozen_string_literal: true
+
+require_relative "zeck_lz77"
+require_relative "btree_builder"
+
+module Cabriolet
+  module HLP
+    module WinHelp
+      # Compressor creates Windows Help (.HLP) files
+      #
+      # Creates WinHelp 3.x and 4.x format files with Zeck LZ77 compression.
+      # Supports creating |SYSTEM, |TOPIC, and other internal files.
+      class Compressor
+        attr_reader :io_system
+
+        # Default block size for WinHelp files (4096 bytes)
+        BLOCK_SIZE = 4096
+
+        # Initialize compressor
+        #
+        # @param io_system [System::IOSystem, nil] Custom I/O system
+        def initialize(io_system = nil)
+          @io_system = io_system || System::IOSystem.new
+          @internal_files = {}
+          @version = :winhelp3
+        end
+
+        # Add an internal file to the WinHelp archive
+        #
+        # @param name [String] Internal filename (e.g., "|SYSTEM", "|TOPIC")
+        # @param data [String] File data
+        # @return [void]
+        def add_internal_file(name, data)
+          @internal_files[name] = data
+        end
+
+        # Add |SYSTEM file with metadata
+        #
+        # @param options [Hash] System file options
+        # @option options [String] :title Help file title
+        # @option options [String] :copyright Copyright text
+        # @option options [String] :contents Contents file path
+        # @return [void]
+        def add_system_file(**options)
+          system_data = build_system_file(options)
+          add_internal_file("|SYSTEM", system_data)
+        end
+
+        # Add |TOPIC file with compressed topics
+        #
+        # @param topics [Array<String>] Array of topic texts
+        # @param compress [Boolean] Whether to compress topics
+        # @return [void]
+        def add_topic_file(topics, compress: true)
+          topic_data = build_topic_file(topics, compress)
+          add_internal_file("|TOPIC", topic_data)
+        end
+
+        # Generate WinHelp file
+        #
+        # @param output_file [String] Path to output file
+        # @param options [Hash] Generation options
+        # @option options [Symbol] :version Format version (:winhelp3 or :winhelp4)
+        # @return [Integer] Bytes written
+        def generate(output_file, **options)
+          @version = options.fetch(:version, :winhelp3)
+
+          if @internal_files.empty?
+            raise ArgumentError,
+                  "No internal files added"
+          end
+          raise ArgumentError, "Invalid version" unless %i[winhelp3
+                                                           winhelp4].include?(@version)
+
+          # Build structure
+          structure = build_structure
+
+          # Write to file
+          output_handle = @io_system.open(output_file, Constants::MODE_WRITE)
+          begin
+            write_winhelp_file(output_handle, structure)
+          ensure
+            @io_system.close(output_handle)
+          end
+        end
+
+        private
+
+        # Build complete WinHelp structure
+        #
+        # @return [Hash] Complete structure
+        def build_structure
+          structure = {
+            version: @version,
+            internal_files: [],
+          }
+
+          # Prepare internal files with block numbers
+          block_number = 1 # Block 0 is reserved for header
+          @internal_files.each do |name, data|
+            # Calculate blocks needed (round up)
+            blocks_needed = (data.bytesize.to_f / BLOCK_SIZE).ceil
+
+            structure[:internal_files] << {
+              name: name,
+              data: data,
+              size: data.bytesize,
+              starting_block: block_number,
+            }
+
+            block_number += blocks_needed
+          end
+
+          # Calculate directory offset
+          header_size = @version == :winhelp3 ? 28 : 32
+          structure[:directory_offset] = header_size
+
+          # Calculate directory size
+          dir_size = calculate_directory_size(structure[:internal_files])
+          structure[:directory_size] = dir_size
+
+          # Calculate total file size
+          structure[:file_size] =
+            header_size + dir_size + (block_number * BLOCK_SIZE)
+
+          structure
+        end
+
+        # Calculate directory size
+        #
+        # @param files [Array<Hash>] Internal file list
+        # @return [Integer] Directory size in bytes
+        def calculate_directory_size(files)
+          size = 0
+          files.each do |file|
+            # 4 bytes size + 2 bytes block + filename + null + padding
+            size += 4 + 2 + file[:name].bytesize + 1
+            # Align to 2-byte boundary
+            size += 1 if size.odd?
+          end
+          # Add end marker (4 bytes of zeros)
+          size + 4
+        end
+
+        # Write complete WinHelp file
+        #
+        # @param output_handle [System::FileHandle] Output handle
+        # @param structure [Hash] File structure
+        # @return [Integer] Bytes written
+        def write_winhelp_file(output_handle, structure)
+          bytes_written = 0
+
+          # Write header
+          bytes_written += write_header(output_handle, structure)
+
+          # Write directory
+          bytes_written += write_directory(output_handle, structure)
+
+          # Pad to first block boundary
+          padding_needed = BLOCK_SIZE - (bytes_written % BLOCK_SIZE)
+          if padding_needed < BLOCK_SIZE
+            bytes_written += @io_system.write(output_handle,
+                                              "\x00" * padding_needed)
+          end
+
+          # Write file data at block boundaries
+          structure[:internal_files].each do |file|
+            # Seek to correct block
+            target_offset = file[:starting_block] * BLOCK_SIZE
+            current_offset = bytes_written
+
+            if target_offset > current_offset
+              padding = "\x00" * (target_offset - current_offset)
+              bytes_written += @io_system.write(output_handle, padding)
+            end
+
+            # Write file data
+            bytes_written += @io_system.write(output_handle, file[:data])
+
+            # Pad to block boundary
+            remainder = file[:data].bytesize % BLOCK_SIZE
+            if remainder.positive?
+              padding = "\x00" * (BLOCK_SIZE - remainder)
+              bytes_written += @io_system.write(output_handle, padding)
+            end
+          end
+
+          bytes_written
+        end
+
+        # Write file header
+        #
+        # @param output_handle [System::FileHandle] Output handle
+        # @param structure [Hash] File structure
+        # @return [Integer] Bytes written
+        def write_header(output_handle, structure)
+          if structure[:version] == :winhelp3
+            write_header_3x(output_handle, structure)
+          else
+            write_header_4x(output_handle, structure)
+          end
+        end
+
+        # Write WinHelp 3.x header
+        #
+        # @param output_handle [System::FileHandle] Output handle
+        # @param structure [Hash] File structure
+        # @return [Integer] Bytes written
+        def write_header_3x(output_handle, structure)
+          header = Binary::HLPStructures::WinHelp3Header.new
+          header.magic = 0x35F3
+          header.unknown = 0x0001
+          header.directory_offset = structure[:directory_offset]
+          header.free_list_offset = 0
+          header.file_size = structure[:file_size]
+          header.reserved = "\x00" * 12
+
+          header_data = header.to_binary_s
+          @io_system.write(output_handle, header_data)
+        end
+
+        # Write WinHelp 4.x header
+        #
+        # @param output_handle [System::FileHandle] Output handle
+        # @param structure [Hash] File structure
+        # @return [Integer] Bytes written
+        def write_header_4x(output_handle, structure)
+          header = Binary::HLPStructures::WinHelp4Header.new
+          header.magic = 0x00033F5F # Magic with low 16 bits = 0x3F5F
+          header.directory_offset = structure[:directory_offset]
+          header.free_list_offset = 0
+          header.file_size = structure[:file_size]
+          header.reserved = "\x00" * 16
+
+          header_data = header.to_binary_s
+          @io_system.write(output_handle, header_data)
+        end
+
+        # Write directory
+        #
+        # @param output_handle [System::FileHandle] Output handle
+        # @param structure [Hash] File structure
+        # @return [Integer] Bytes written
+        def write_directory(output_handle, structure)
+          if structure[:version] == :winhelp4
+            write_directory_btree(output_handle, structure)
+          else
+            write_directory_simple(output_handle, structure)
+          end
+        end
+
+        # Write simple directory (WinHelp 3.x format)
+        #
+        # @param output_handle [System::FileHandle] Output handle
+        # @param structure [Hash] File structure
+        # @return [Integer] Bytes written
+        def write_directory_simple(output_handle, structure)
+          bytes_written = 0
+
+          structure[:internal_files].each do |file|
+            # Write file size (4 bytes)
+            bytes_written += @io_system.write(output_handle,
+                                              [file[:size]].pack("V"))
+
+            # Write starting block (2 bytes)
+            bytes_written += @io_system.write(output_handle,
+                                              [file[:starting_block]].pack("v"))
+
+            # Write filename with null terminator
+            bytes_written += @io_system.write(output_handle,
+                                              "#{file[:name]}\u0000")
+
+            # Align to 2-byte boundary
+            if bytes_written.odd?
+              bytes_written += @io_system.write(output_handle, "\x00")
+            end
+          end
+
+          # Write end marker
+          bytes_written += @io_system.write(output_handle, [0].pack("V"))
+
+          bytes_written
+        end
+
+        # Write B+ tree directory (WinHelp 4.x format)
+        #
+        # @param output_handle [System::FileHandle] Output handle
+        # @param structure [Hash] File structure
+        # @return [Integer] Bytes written
+        def write_directory_btree(output_handle, structure)
+          bytes_written = 0
+
+          # Build B+ tree from internal files
+          btree = BTreeBuilder.new
+          structure[:internal_files].each do |file|
+            # Add entry with filename, starting block (offset), and size
+            btree.add_entry(file[:name], file[:starting_block] * BLOCK_SIZE,
+                            file[:size])
+          end
+
+          # Build the tree
+          tree = btree.build
+
+          # Write FILEHEADER (9 bytes) before BTREEHEADER
+          # FILEHEADER structure:
+          # - 4 bytes: reserved_space (reserved space in help file incl. FILEHEADER)
+          # - 4 bytes: used_space (used space in help file excl. FILEHEADER)
+          # - 1 byte: file_flags (normally 4)
+          # For directory, we set these to 0 for now
+          file_header = Binary::HLPStructures::WinHelpFileHeader.new
+          file_header.reserved_space = 0
+          file_header.used_space = 0
+          file_header.file_flags = 4
+          file_header_data = file_header.to_binary_s
+          bytes_written += @io_system.write(output_handle, file_header_data)
+
+          # Write BTREEHEADER (38 bytes)
+          header = tree[:header]
+          header_data = header.to_binary_s
+          bytes_written += @io_system.write(output_handle, header_data)
+
+          # Write pages (sorted by page_num)
+          sorted_pages = tree[:pages].sort_by { |p| p[:page_num] }
+          sorted_pages.each do |page|
+            # Write page data
+            bytes_written += @io_system.write(output_handle, page[:data])
+          end
+
+          bytes_written
+        end
+
+        # Build |SYSTEM file
+        #
+        # @param options [Hash] System file options
+        # @return [String] System file data
+        def build_system_file(options)
+          data = +""
+
+          # Write title if provided
+          if options[:title]
+            data << build_system_record(1, options[:title])
+          end
+
+          # Write copyright if provided
+          if options[:copyright]
+            data << build_system_record(2, options[:copyright])
+          end
+
+          # Write contents if provided
+          if options[:contents]
+            data << build_system_record(3, options[:contents])
+          end
+
+          data
+        end
+
+        # Build a system record
+        #
+        # @param type [Integer] Record type
+        # @param text [String] Record text
+        # @return [String] Record data
+        def build_system_record(type, text)
+          record = +""
+          record << [type].pack("v") # Record type (2 bytes)
+          record << [text.bytesize + 1].pack("v") # Length including null (2 bytes)
+          record << text
+          record << "\x00" # Null terminator
+          record
+        end
+
+        # Build |TOPIC file
+        #
+        # @param topics [Array<String>] Topic texts
+        # @param compress [Boolean] Whether to compress
+        # @return [String] Topic file data
+        def build_topic_file(topics, compress)
+          # Simplified: just concatenate topic data
+          # Full implementation would include topic headers and blocks
+          data = +""
+          zeck = ZeckLZ77.new
+
+          topics.each do |topic_text|
+            compressed_data = if compress
+                                # Compress using Zeck LZ77
+                                zeck.compress(topic_text)
+                              else
+                                topic_text
+                              end
+
+            # Write topic with 2-byte length header
+            data << [compressed_data.bytesize].pack("v")
+            data << compressed_data
+          end
+
+          data
+        end
+      end
+    end
+  end
+end