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:

  • (defaults to: nil)

    Custom I/O system or nil for default

  • (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 to add

  • Path within QuickHelp archive

  • (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:

  • Path to source file

  • Path within QuickHelp archive

  • (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

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)

Raises:

  • if compression fails

Parameters:

  • Path to output HLP file

  • Compression options

Returns:

  • Bytes written to output file



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