Uniword provides comprehensive error handling with a clear exception hierarchy. All custom exceptions inherit from Uniword::Error.

1. Exception Hierarchy 

Uniword::Error
  |-- FileNotFoundError
  |-- CorruptedFileError
  |-- InvalidFormatError
  |-- ValidationError
  |-- ConversionError

2. Usage 

require 'uniword'

begin
  doc = Uniword::DocumentFactory.from_file('document.docx')
rescue Uniword::FileNotFoundError => e
  puts "File not found: #{e.path}"
rescue Uniword::CorruptedFileError => e
  puts "Corrupted file: #{e.reason}"
rescue Uniword::InvalidFormatError => e
  puts "Invalid format: #{e.message}"
rescue Uniword::Error => e
  puts "Error: #{e.message}"
end

3. Exception Details

FileNotFoundError

Raised when the specified file does not exist. Provides the path attribute with the file path.

CorruptedFileError

Raised when the file exists but cannot be parsed. Provides the reason attribute describing the corruption.

InvalidFormatError

Raised when the file format is not supported or unrecognized. Covers non-DOCX, non-MHTML files.

ValidationError

Raised when document validation fails. Used by the verification pipeline to report structural issues.

ConversionError

Raised when format conversion between DOCX and MHTML fails. Covers unsupported features or data loss scenarios.

4. Catching All Errors

For top-level error handling, catch Uniword::Error:

begin
  doc = Uniword.load(path)
  doc.save(output)
rescue Uniword::Error => e
  logger.error("Uniword error: #{e.message}")
end

5. Logging

Uniword uses Uniword::Logger for internal diagnostics. The default log level is WARN and output goes to $stdout.

# Use the default logger
Uniword::Logger.info("Processing document")
Uniword::Logger.warn("Unexpected format")
Uniword::Logger.error("Failed to process")

# Or provide your own logger
Uniword::Logger.logger = MyCustomLogger.new

Internal operations that encounter recoverable errors (e.g., image dimension detection, metadata parsing, font availability checks) log diagnostic messages at debug level. Config file load failures log at warn level. To see these messages, set the log level:

Uniword::Logger.logger.level = ::Logger::DEBUG