Class: Omnizip::Filter Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/omnizip/filter.rb

Overview

This class is abstract.

Subclasses must implement encode, decode, metadata

Abstract base class for all preprocessing filters

Filters are reversible transformations applied to data before compression to improve compression ratios. This class defines the interface that all filter implementations must follow.

The key innovation is format-aware ID resolution: different formats (7z, XZ) use different IDs for the same filter. This class provides the id_for_format(format) method to handle this mapping.

Examples:

Create a custom filter

class MyFilter < Filter
  def initialize(architecture:)
    super(architecture: architecture, name: "MyFilter")
  end

  def id_for_format(format)
    format == :xz ? 0x04 : 0x03
  end

  def encode(data, position = 0)
    # encoding logic
  end

  def decode(data, position = 0)
    # decoding logic
  end

  def self.metadata
    { name: "MyFilter", description: "..." }
  end
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(architecture: nil, name: "Unknown") ⇒ Filter

Initialize filter

Parameters:

  • architecture (Symbol, nil) (defaults to: nil) —

    Target architecture (optional; filters that don't vary by architecture leave this as nil)

  • name (String) (defaults to: "Unknown") —

    Human-readable name



72
73
74
75
 
# File 'lib/omnizip/filter.rb', line 72

def initialize(architecture: nil, name: "Unknown")
  @architecture = architecture
  @name = name
end

Instance Attribute Details

#architecture ⇒ Symbol? (readonly)

Returns Architecture identifier (:x86, :arm, :arm64, :powerpc, :ia64, :sparc) or nil for architecture-agnostic filters.

Returns:

  • (Symbol, nil) —

    Architecture identifier (:x86, :arm, :arm64, :powerpc, :ia64, :sparc) or nil for architecture-agnostic filters



62
63
64
 
# File 'lib/omnizip/filter.rb', line 62

def architecture
  @architecture
end

#name ⇒ String (readonly)

Returns Human-readable filter name.

Returns:

  • (String) —

    Human-readable filter name



65
66
67
 
# File 'lib/omnizip/filter.rb', line 65

def name
  @name
end

Class Method Details

.metadata ⇒ Hash

Get metadata about this filter

Examples:

Get BCJ filter metadata

Omnizip::Filters::BCJ.metadata
# => { name: "BCJ", description: "...", supported_archs: [:x86, :arm, ...] }

Parameters:

  • metadata (Hash) —

    a customizable set of options

Returns:

  • (Hash) —

    Filter metadata

Raises:

  • (NotImplementedError) —

    Subclass must implement



135
136
137
138
 
# File 'lib/omnizip/filter.rb', line 135

def metadata
  raise NotImplementedError,
        "#{self} must implement .metadata"
end

Instance Method Details

#decode(data, position = 0) ⇒ String

Decode (postprocess) data after decompression

Reverses the encoding transformation, restoring original data.

Parameters:

  • data (String) —

    Binary data to decode

  • position (Integer) (defaults to: 0) —

    Current stream position (default: 0)

Returns:

  • (String) —

    Decoded binary data

Raises:

  • (NotImplementedError) —

    Subclass must implement



118
119
120
121
 
# File 'lib/omnizip/filter.rb', line 118

def decode(data, position = 0)
  raise NotImplementedError,
        "#{self.class} must implement #decode(data, position)"
end

#encode(data, position = 0) ⇒ String

Encode (preprocess) data for compression

Transforms data to make it more compressible. The transformation must be reversible - decode(encode(data)) == data.

Parameters:

  • data (String) —

    Binary data to encode

  • position (Integer) (defaults to: 0) —

    Current stream position (default: 0)

Returns:

  • (String) —

    Encoded binary data

Raises:

  • (NotImplementedError) —

    Subclass must implement



105
106
107
108
 
# File 'lib/omnizip/filter.rb', line 105

def encode(data, position = 0)
  raise NotImplementedError,
        "#{self.class} must implement #encode(data, position)"
end

#id_for_format(format) ⇒ Integer

Get filter ID for specific format

This is the KEY METHOD that solves the filter ID mapping problem. Different formats (7z, XZ) use different IDs for the same filter.

Examples:

Get XZ format ID for BCJ filter

bcj.id_for_format(:xz)  # => 0x04

Get 7z format ID for BCJ filter

bcj.id_for_format(:seven_zip)  # => 0x03030103

Parameters:

  • format (Symbol) —

    Format identifier (:seven_zip, :xz)

Returns:

  • (Integer) —

    Format-specific filter ID

Raises:

  • (NotImplementedError) —

    Subclass must implement



91
92
93
94
 
# File 'lib/omnizip/filter.rb', line 91

def id_for_format(format)
  raise NotImplementedError,
        "#{self.class} must implement #id_for_format(format)"
end