Module: Omnizip::Formats::Xar

Defined in:
lib/omnizip/formats/xar.rb,
lib/omnizip/formats/xar/toc.rb,
lib/omnizip/formats/xar/entry.rb,
lib/omnizip/formats/xar/header.rb,
lib/omnizip/formats/xar/reader.rb,
lib/omnizip/formats/xar/writer.rb,
lib/omnizip/formats/xar/constants.rb

Overview

XAR archive format support

XAR (eXtensible ARchive) format is primarily used on macOS for:

  • Software packages (.pkg files)
  • OS installers
  • Software distribution

Features:

  • GZIP-compressed XML Table of Contents (TOC)
  • Multiple compression algorithms (gzip, bzip2, lzma, xz, none)
  • Checksum verification (MD5, SHA1, SHA256, etc.)
  • Extended attributes (xattrs)
  • Hardlinks and symlinks
  • Device nodes and FIFOs

Examples:

Create XAR archive

Omnizip::Formats::Xar.create('archive.xar') do |xar|
  xar.add_file('document.pdf')
  xar.add_directory('resources/')
end

Extract XAR archive

Omnizip::Formats::Xar.extract('archive.xar', 'output/')

List XAR contents

entries = Omnizip::Formats::Xar.list('archive.xar')
entries.each { |e| puts "#{e.name} (#{e.size} bytes)" }

Defined Under Namespace

Modules: Constants Classes: Entry, Header, Reader, Toc, Writer

Constant Summary collapse

CKSUM_NONE =

Re-export constants for external access

Constants::CKSUM_NONE
CKSUM_SHA1 = 
Constants::CKSUM_SHA1
CKSUM_MD5 = 
Constants::CKSUM_MD5
CKSUM_OTHER = 
Constants::CKSUM_OTHER

Class Method Summary collapse

Class Method Details

.create(path, options = {}) {|writer| ... } ⇒ String

Create XAR archive

Examples:

Create archive with gzip compression

Omnizip::Formats::Xar.create('archive.xar', compression: 'gzip') do |xar|
  xar.add_file('config.yml')
  xar.add_directory('config.d/')
end

Create archive with bzip2 and SHA256 checksums

Omnizip::Formats::Xar.create('archive.xar',
  compression: 'bzip2',
  toc_checksum: 'sha256',
  file_checksum: 'sha256'
) do |xar|
  xar.add_file('data.bin')
end

Parameters:

  • path (String) —

    Output XAR file path

  • options (Hash) (defaults to: {}) —

    Archive options

Options Hash (options):

  • :compression (String) —

    Compression algorithm (gzip, bzip2, lzma, xz, none)

  • :compression_level (Integer) —

    Compression level (1-9)

  • :toc_checksum (String) —

    TOC checksum algorithm (sha1, md5, sha256)

  • :file_checksum (String) —

    File checksum algorithm (sha1, md5, sha256)

Yields:

  • (writer) —

    Block for adding files/directories

Yield Parameters:

  • writer (Writer) —

    XAR writer

Returns:

  • (String) —

    Path to created archive



74
75
76
77
78
 
# File 'lib/omnizip/formats/xar.rb', line 74

def create(path, options = {})
  Writer.create(path, options) do |writer|
    yield writer if block_given?
  end
end

.extract(xar_path, output_dir) ⇒ Object

Extract XAR archive

Examples:

Extract archive

Omnizip::Formats::Xar.extract('archive.xar', 'output/')

Parameters:

  • xar_path (String) —

    Path to XAR file

  • output_dir (String) —

    Output directory



124
125
126
127
128
 
# File 'lib/omnizip/formats/xar.rb', line 124

def extract(xar_path, output_dir)
  open(xar_path) do |xar| # rubocop:disable Security/Open
    xar.extract_all(output_dir)
  end
end

.info(path) ⇒ Hash

Get archive information

Examples:

Get archive info

info = Omnizip::Formats::Xar.info('archive.xar')
puts "Format: XAR version #{info[:header][:version]}"
puts "Files: #{info[:file_count]}"

Parameters:

  • path (String) —

    Path to XAR file

Returns:

  • (Hash) —

    Archive information



139
140
141
 
# File 'lib/omnizip/formats/xar.rb', line 139

def info(path)
  open(path, &:info) # rubocop:disable Security/Open
end

.list(path) ⇒ Array<Entry>

List XAR archive contents

Examples:

List archive contents

entries = Omnizip::Formats::Xar.list('archive.xar')
entries.each { |e| puts "#{e.name} (#{e.size} bytes)" }

Parameters:

  • path (String) —

    Path to XAR file

Returns:

  • (Array<Entry>) —

    Archive entries



113
114
115
 
# File 'lib/omnizip/formats/xar.rb', line 113

def list(path)
  open(path, &:entries) # rubocop:disable Security/Open
end

.open(path) {|reader| ... } ⇒ Reader

Open XAR archive for reading

Examples:

Read XAR archive

Omnizip::Formats::Xar.open('archive.xar') do |xar|
  xar.entries.each { |entry| puts entry.name }
end

Parameters:

  • path (String) —

    Path to XAR file

Yields:

  • (reader) —

    Block for reading archive

Yield Parameters:

  • reader (Reader) —

    XAR reader

Returns:



91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/omnizip/formats/xar.rb', line 91

def open(path)
  reader = Reader.open(path)

  if block_given?
    begin
      yield reader
    ensure
      reader.close
    end
  else
    reader
  end
end

.register! ⇒ Object

Auto-register XAR format when loaded



144
145
146
 
# File 'lib/omnizip/formats/xar.rb', line 144

def register!
  FormatRegistry.register(".xar", Reader)
end