Class: Cabriolet::HLP::QuickHelp::Compressor

Inherits:
Object
  • Object
show all
Defined in:
lib/cabriolet/hlp/quickhelp/compressor.rb

Overview

Compressor creates QuickHelp (.HLP) compressed archives

QuickHelp files (DOS format) contain topics with Huffman encoding and optional keyword compression using LZSS MODE_MSHELP.

NOTE: This implementation is based on the DosHelp project specification for the QuickHelp format used in DOS-era development tools.

Constant Summary collapse

DEFAULT_BUFFER_SIZE =

Default buffer size for I/O operations

2048

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(io_system = nil, algorithm_factory = nil) ⇒ Compressor

Initialize a new QuickHelp compressor

Parameters:

  • io_system (System::IOSystem, nil) (defaults to: nil) —

    Custom I/O system or nil for default

  • algorithm_factory (AlgorithmFactory, nil) (defaults to: nil) —

    Custom algorithm factory or nil for default



28
29
30
31
32
 
# File 'lib/cabriolet/hlp/quickhelp/compressor.rb', line 28

def initialize(io_system = nil, algorithm_factory = nil)
  @io_system = io_system || System::IOSystem.new
  @algorithm_factory = algorithm_factory || Cabriolet.algorithm_factory
  @files = []
end

Instance Attribute Details

#io_system ⇒ Object (readonly)

Returns the value of attribute io_system.



19
20
21
 
# File 'lib/cabriolet/hlp/quickhelp/compressor.rb', line 19

def io_system
  @io_system
end

Instance Method Details

#add_data(data, hlp_path, compress: true) ⇒ void

This method returns an undefined value.

Add data from memory to the QuickHelp archive

Parameters:

  • data (String) —

    Data to add

  • hlp_path (String) —

    Path within QuickHelp archive

  • compress (Boolean) (defaults to: true) —

    Whether to compress the data



54
55
56
57
58
59
60
 
# File 'lib/cabriolet/hlp/quickhelp/compressor.rb', line 54

def add_data(data, hlp_path, compress: true)
  @files << {
    data: data,
    hlp_path: hlp_path,
    compress: compress,
  }
end

#add_file(source_path, hlp_path, compress: true) ⇒ void

This method returns an undefined value.

Add a file to the QuickHelp archive

Parameters:

  • source_path (String) —

    Path to source file

  • hlp_path (String) —

    Path within QuickHelp archive

  • compress (Boolean) (defaults to: true) —

    Whether to compress the file



40
41
42
43
44
45
46
 
# File 'lib/cabriolet/hlp/quickhelp/compressor.rb', line 40

def add_file(source_path, hlp_path, compress: true)
  @files << {
    source: source_path,
    hlp_path: hlp_path,
    compress: compress,
  }
end

#generate(output_file, **options) ⇒ Integer

Generate HLP archive

Parameters:

  • output_file (String) —

    Path to output HLP file

  • options (Hash) —

    Compression options

Options Hash (**options):

  • :version (Integer) —

    QuickHelp format version (default: 2)

  • :database_name (String) —

    Database name for external links (max 13 chars)

  • :control_character (Integer) —

    Control character (default: 0x3A ‘:’)

  • :case_sensitive (Boolean) —

    Case-sensitive contexts (default: false)

Returns:

  • (Integer) —

    Bytes written to output file

Raises:



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/cabriolet/hlp/quickhelp/compressor.rb', line 72

def generate(output_file, **options)
  version = options.fetch(:version, 2)
  database_name = options.fetch(:database_name, "")
  control_char = options.fetch(:control_character, 0x3A) # ':'
  case_sensitive = options.fetch(:case_sensitive, false)

  raise ArgumentError, "No files added to archive" if @files.empty?
  raise ArgumentError, "Version must be 2" unless version == 2

  if database_name.length > 13
    raise ArgumentError,
          "Database name too long (max 13 chars)"
  end

  # Prepare topics from files
  topics = prepare_topics

  # Build QuickHelp structure
  structure_builder = StructureBuilder.new(
    version: version,
    database_name: database_name,
    control_char: control_char,
    case_sensitive: case_sensitive,
  )
  qh_structure = structure_builder.build(topics)

  # Write to output file
  output_handle = @io_system.open(output_file, Constants::MODE_WRITE)
  begin
    file_writer = FileWriter.new(@io_system)
    bytes_written = file_writer.write_quickhelp_file(output_handle,
                                                     qh_structure)
    bytes_written
  ensure
    @io_system.close(output_handle)
  end
end