Module: Omnizip::Convenience

Included in:
Omnizip
Defined in:
lib/omnizip/convenience.rb

Overview

Convenience methods for common archive operations.

All public methods accept an optional format: keyword (default :zip) that selects the underlying archive handler via Omnizip::ArchiveHandler. New formats gain access to the convenience API by registering a handler; no edits to this file are needed.

Constant Summary collapse

DEFAULT_FORMAT = 
:zip

Instance Method Summary collapse

Instance Method Details

#add_to_archive(archive_path, entry_name, source_path, format: DEFAULT_FORMAT) ⇒ String

Add a file to an existing archive.

Parameters:

  • archive_path (String) —

    Path to archive

  • entry_name (String) —

    Entry name in archive

  • source_path (String) —

    Path to source file

  • format (Symbol) (defaults to: DEFAULT_FORMAT) —

    Archive format (default :zip)

Returns:

  • (String) —

    archive_path



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/omnizip/convenience.rb', line 118

def add_to_archive(archive_path, entry_name, source_path,
                   format: DEFAULT_FORMAT)
  require_archive!(archive_path)
  unless ::File.exist?(source_path)
    raise Errno::ENOENT, "Source file not found: #{source_path}"
  end

  handler = Omnizip::ArchiveHandler.for(format)
  if handler.respond_to?(:add_entry)
    handler.add_entry(archive_path, entry_name, source_path)
  else
    raise Omnizip::UnsupportedFormatError,
          "Format #{format.inspect} does not support adding entries"
  end

  archive_path
end

#compress_directory(input_dir, output_path, format: DEFAULT_FORMAT, recursive: true, **options) ⇒ String

Compress a directory into an archive.

Parameters:

  • input_dir (String) —

    Path to input directory

  • output_path (String) —

    Path to output archive

  • format (Symbol) (defaults to: DEFAULT_FORMAT) —

    Archive format (default :zip)

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

    Include subdirectories (default true)

  • options (Hash) —

    Compression / format-specific options

Returns:

  • (String) —

    output_path



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/omnizip/convenience.rb', line 49

def compress_directory(input_dir, output_path, format: DEFAULT_FORMAT,
                       recursive: true, **options)
  unless ::File.exist?(input_dir)
    raise Errno::ENOENT, "Input directory not found: #{input_dir}"
  end
  unless ::File.directory?(input_dir)
    raise ArgumentError, "Input is not a directory: #{input_dir}"
  end

  if options[:profile]
    first_file = find_first_file(input_dir)
    apply_profile(first_file, options)
  end

  Omnizip::ArchiveHandler.for(format).create(output_path) do |archive|
    add_directory_contents(archive, input_dir, "", recursive: recursive)
  end

  output_path
end

#compress_file(input_path, output_path, format: DEFAULT_FORMAT, **options) ⇒ String

Compress a single file into an archive.

Parameters:

  • input_path (String) —

    Path to input file

  • output_path (String) —

    Path to output archive

  • format (Symbol) (defaults to: DEFAULT_FORMAT) —

    Archive format (default :zip)

  • options (Hash) —

    Compression / format-specific options

Returns:

  • (String) —

    output_path



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/omnizip/convenience.rb', line 20

def compress_file(input_path, output_path, format: DEFAULT_FORMAT, **options)
  unless ::File.exist?(input_path)
    raise Errno::ENOENT, "Input file not found: #{input_path}"
  end
  if ::File.directory?(input_path)
    raise ArgumentError, "Input is a directory: #{input_path}"
  end

  options = apply_profile(input_path, options) if options[:profile]

  if options[:chunked]
    return Omnizip::Chunked.compress_file(input_path, output_path, **options)
  end

  Omnizip::ArchiveHandler.for(format).create(output_path) do |archive|
    archive.add(::File.basename(input_path), input_path)
  end

  output_path
end

#create_rar(archive_path, **options, &block) ⇒ Object

Create a RAR archive (requires RAR license — see NotLicensedError). rubocop:disable Naming/BlockForwarding, Style/ArgumentsForwarding -- Ruby 3.0 compatibility



156
157
158
159
 
# File 'lib/omnizip/convenience.rb', line 156

def create_rar(archive_path, **options, &block)
  options[:version] ||= 5
  Omnizip::Formats::Rar.create(archive_path, options, &block)
end

#extract_archive(archive_path, output_dir, format: DEFAULT_FORMAT, overwrite: false, **options) ⇒ Array<String>

Extract an archive to a directory.

Parameters:

  • archive_path (String) —

    Path to archive

  • output_dir (String) —

    Output directory

  • format (Symbol) (defaults to: DEFAULT_FORMAT) —

    Archive format (default :zip)

  • overwrite (Boolean) (defaults to: false) —

    Overwrite existing files (default false)

  • options (Hash) —

    Format-specific extraction options

Returns:

  • (Array<String>) —

    Extracted file paths



78
79
80
81
82
83
84
 
# File 'lib/omnizip/convenience.rb', line 78

def extract_archive(archive_path, output_dir, format: DEFAULT_FORMAT,
                    overwrite: false, **options)
  require_archive!(archive_path)
  Omnizip::ArchiveHandler.for(format)
    .extract_to(archive_path, output_dir,
                overwrite: overwrite, **options)
end

#list_archive(archive_path, format: DEFAULT_FORMAT, details: false, **options) ⇒ Array<String>, Array<Hash>

List contents of an archive.

Parameters:

  • archive_path (String) —

    Path to archive

  • format (Symbol) (defaults to: DEFAULT_FORMAT) —

    Archive format (default :zip)

  • details (Boolean) (defaults to: false) —

    Include detailed info (default false)

  • options (Hash) —

    Format-specific listing options

Returns:

  • (Array<String>, Array<Hash>) 


93
94
95
96
97
98
 
# File 'lib/omnizip/convenience.rb', line 93

def list_archive(archive_path, format: DEFAULT_FORMAT, details: false,
                 **options)
  require_archive!(archive_path)
  Omnizip::ArchiveHandler.for(format)
    .list(archive_path, details: details, **options)
end

#read_from_archive(archive_path, entry_name, format: DEFAULT_FORMAT) ⇒ String

Read a single entry from an archive.

Parameters:

  • archive_path (String) —

    Path to archive

  • entry_name (String) —

    Entry to read

  • format (Symbol) (defaults to: DEFAULT_FORMAT) —

    Archive format (default :zip)

Returns:

  • (String) —

    Entry contents



106
107
108
109
 
# File 'lib/omnizip/convenience.rb', line 106

def read_from_archive(archive_path, entry_name, format: DEFAULT_FORMAT)
  require_archive!(archive_path)
  Omnizip::ArchiveHandler.for(format).read_entry(archive_path, entry_name)
end

#remove_from_archive(archive_path, entry_name, format: DEFAULT_FORMAT) ⇒ String

Remove an entry from an existing archive.

Parameters:

  • archive_path (String) —

    Path to archive

  • entry_name (String) —

    Entry to remove

  • format (Symbol) (defaults to: DEFAULT_FORMAT) —

    Archive format (default :zip)

Returns:

  • (String) —

    archive_path



142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/omnizip/convenience.rb', line 142

def remove_from_archive(archive_path, entry_name, format: DEFAULT_FORMAT)
  require_archive!(archive_path)
  handler = Omnizip::ArchiveHandler.for(format)
  unless handler.respond_to?(:remove_entry)
    raise Omnizip::UnsupportedFormatError,
          "Format #{format.inspect} does not support removing entries"
  end

  handler.remove_entry(archive_path, entry_name)
  archive_path
end