Class: Zipr::Archive

Inherits:
Object
  • Object
show all
Defined in:
lib/zipr/archive.rb

Direct Known Subclasses

SFX

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path, options: nil, checksums: nil, mode: nil, checksum_file: nil) ⇒ Archive

Description:

Initializes the Archive.

Parameters:

path: The path to the existing archive or where the archive will be created.
see comment of method 'open' for remaining parameter information.



97
98
99
100
101
102
103
 
# File 'lib/zipr/archive.rb', line 97

def initialize(path, options: nil, checksums: nil, mode: nil, checksum_file: nil)
  @path = path
  archive_checksum = ::File.exist?(path) ? ::Digest::SHA256.file(path).hexdigest : 'does_not_exist'
  @checksum_path = checksum_file || "#{@cache_path}/checksums/#{::File.basename(path)}-#{archive_checksum}.txt"
  _assign_common_accessors(options: options, checksums: checksums, mode: mode)
  @options[:archive_type] ||= (::File.exist?(@path) ? detect_archive_type : :zip)
end

Instance Attribute Details

#checksum_path ⇒ Object

Returns the value of attribute checksum_path.



4
5
6
 
# File 'lib/zipr/archive.rb', line 4

def checksum_path
  @checksum_path
end

#checksums ⇒ Object

Returns the value of attribute checksums.



4
5
6
 
# File 'lib/zipr/archive.rb', line 4

def checksums
  @checksums
end

#mode ⇒ Object

Returns the value of attribute mode.



4
5
6
 
# File 'lib/zipr/archive.rb', line 4

def mode
  @mode
end

#options ⇒ Object

Returns the value of attribute options.



4
5
6
 
# File 'lib/zipr/archive.rb', line 4

def options
  @options
end

Class Method Details

.add(path, source_folder, files_to_add: nil, options: {}, checksums: {}, mode: :idempotent, checksum_file: nil) ⇒ Object

Description:

Add files to an existing archive or create one if it does not exist in a single line. No additional IO handling necessary.

Returns:

Array of 2 objects: String path to the checksum file and the hash of known checksums for archive files.

Parameters:

path: The full path to the archive being added to/created.
see comment of method 'add' below for :source_folder and :files_to_add parameter information.
see comment of method 'open' above for remaining parameter information.



40
41
42
43
 
# File 'lib/zipr/archive.rb', line 40

def self.add(path, source_folder, files_to_add: nil, options: {}, checksums: {}, mode: :idempotent, checksum_file: nil)
  archive = new(path, options: options, checksums: checksums, mode: mode, checksum_file: checksum_file)
  archive.add(source_folder, files_to_add: files_to_add)
end

.determine_files_to_add(path, source_folder, files_to_check: nil, options: {}, checksums: {}, mode: :idempotent, checksum_file: nil) ⇒ Object

Description:

Determines what files should be added to an archive based on the options and mode provided in a single line.
Can be useful to perform actions on changing files before they are added or to determine idempotency state (like with Chef/Puppet)

Returns:

Array of 2 objects: an array of files to be added (or the :all symbol) and a hash of the known file checksums in the archive

Parameters:

path: The full path to the archive being created/examined.
see comment of method 'determine_files_to_add' for :source_folder and :files_to_check
see comment of method 'open' for remaining parameter information.



69
70
71
72
73
 
# File 'lib/zipr/archive.rb', line 69

def self.determine_files_to_add(path, source_folder, files_to_check: nil, options: {}, checksums: {}, mode: :idempotent, checksum_file: nil)
  archive = new(path, options: options, checksums: checksums, mode: mode, checksum_file: checksum_file)
  files_to_add = archive.determine_files_to_add(source_folder, files_to_check: files_to_check)
  [files_to_add, archive.checksums]
end

.determine_files_to_extract(path, destination_folder, files_to_check: nil, options: {}, checksums: {}, mode: :idempotent, checksum_file: nil) ⇒ Object

Description:

Determines what files should be extracted based on the options and mode provided.
Can be useful to perform actions on changing files before they are extracted or to determine idempotency state (like with Chef/Puppet).

Returns:

Array of 2 objects: an array of files to be extracted (or the :all symbol) and a hash of the known file checksums in the archive.

Parameters:

path: The full path to the archive being extracted/examined.
see comment of method 'determine_files_to_extract' for :destination_folder and :files_to_check parameter information.
see comment of method 'open' for remaining parameter information.



85
86
87
88
89
 
# File 'lib/zipr/archive.rb', line 85

def self.determine_files_to_extract(path, destination_folder, files_to_check: nil, options: {}, checksums: {}, mode: :idempotent, checksum_file: nil)
  archive = new(path, options: options, checksums: checksums, mode: mode, checksum_file: checksum_file)
  files_to_extract = archive.determine_files_to_extract(destination_folder, files_to_check: files_to_check)
  [files_to_extract, archive.checksums]
end

.extract(path, destination_folder, files_to_extract: nil, options: {}, checksums: nil, mode: :idempotent, checksum_file: nil) ⇒ Object

Description:

Extract files from an archive in a single line. No additional IO handling necessary.

Returns:

Array of 2 objects: String path to the checksum file and the hash of known checksums for archive files.

Parameters:

path: The full path to the archive being extracted.
see comment of method 'extract' for :destination_folder and :files_to_extract parameter information.
see comment of method 'self.open' for remaining parameter information.



54
55
56
57
 
# File 'lib/zipr/archive.rb', line 54

def self.extract(path, destination_folder, files_to_extract: nil, options: {}, checksums: nil, mode: :idempotent, checksum_file: nil)
  archive = new(path, options: options, checksums: checksums, mode: mode, checksum_file: checksum_file)
  archive.extract(destination_folder, files_to_extract: files_to_extract)
end

.open(path, options: {}, checksums: {}, mode: :idempotent, checksum_file: nil, &block) ⇒ Object

Description:

Create an instance of the class.
Allows usage of block form.

Returns:

When used without a block, returns the instance.

Parameters:

options:
  :archive_type - The type of archive - :seven_zip or :zip - Can be omitted if the archive exists or using default. Default: :zip
  :exclude_files - Array of files to be excluded from archiving/extracting - Can be relative or exact paths.
  :exclude_unless_missing - Array of files to be excluded from archiving/extracting only if they already exist - Can be relative or exact paths.
  :exclude_unless_archive_changed - Array of files to be excluded from extracting only if the archive hasn't changed and they already exist - Use relative paths.
  :password - the archive password - currently :seven_zip is the only supported archive_type for encrypted archives.
  :silent - [true/false] No info messages if flagged
checksums: A hash of checksums of the archived files. If you checked one of the determine_files methods for idempotency first, pass the result to this parameter to avoid duplicate processing.
mode:
  :idempotent - Does not add/extract files to/from the archive if they already exist and are the exact same file, verified by checksum.
  :overwrite - Adds/Extracts all eligible files to/from the archive even if the checksums match.
  :if_missing - never overwrites any files, only adds/extracts to/from the archive if the relative path does not exist.
checksum_file: (optional) The path to the initial checksum file. Usually only needed if the archive is not kept on the disk and we need to see if extracted files have changed.



26
27
28
29
 
# File 'lib/zipr/archive.rb', line 26

def self.open(path, options: {}, checksums: {}, mode: :idempotent, checksum_file: nil, &block)
  archive_instance = new(path, options: options, checksums: checksums, mode: mode, checksum_file: checksum_file)
  block.nil? ? archive_instance : yield(archive_instance)
end

Instance Method Details

#add(source_folder, files_to_add: nil) ⇒ Object

Description:

Add files to an existing archive or create one if it does not exist

Returns:

Array of 2 objects: String path to the checksum file and the hash of known checksums for archive files.

Parameters:

source_folder: The path from which relative archive paths will be derived.
files_to_add: An array of files to be added to the archive. Relative or full paths accepted. If omitted, takes all files and folders in the source_folder.



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/zipr/archive.rb', line 138

def add(source_folder, files_to_add: nil)
  files_to_add = determine_files_to_add(source_folder, files_to_check: files_to_add)
  FileUtils.mkdir_p(::File.dirname(@path)) unless ::File.directory?(::File.dirname(@path))

  case @options[:archive_type]
  when :zip
    _add_to_zip(source_folder, files_to_add)
  when :seven_zip
    _add_to_seven_zip(source_folder, files_to_add)
  else
    raise "':#{@options[:archive_type]}' is not a supported archive type!"
  end
  raise "Failed to create archive at #{@path}!" unless ::File.file?(@path)
  EasyIO.logger.info "Archiving to #{::File.basename(@path)} finished." unless @options[:silent]
  archive_checksums = @options[:sfx] ? @checksums : update_checksum_file # Don't update the checksum file yet if it's an SFX
  [@checksum_path, archive_checksums]
end

#archive_type ⇒ Object

Description:

More readably access the archive_type option.

Returns:

A symbol representing the archive type of the instance.



306
307
308
 
# File 'lib/zipr/archive.rb', line 306

def archive_type
  @options[:archive_type]
end

#detect_archive_type(archive_types = supported_archive_types) ⇒ Object

Description:

Detects what kind of archive the existing file is.

Returns:

The type of archive detected.

Parameters:

archive_types: (optional) The array of archive_types to try. Be default, tries all archive types.



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/zipr/archive.rb', line 274

def detect_archive_type(archive_types = supported_archive_types)
  try_archive_type = archive_types.shift
  case try_archive_type
  when :zip
    ::Zip::File.open(@path) { |_archive_file| } # Test if the file can be opened as a zip file
  when :seven_zip
    SevenZipRuby::Reader.open_file(@path) { |_archive_file| } # Test if the file can be opened as a 7z file
  else
    raise "Archive type for #{try_archive_type} not implemented! Add it to Zipr::Archive.detect_archive_type definition."
  end
  @archive_type = try_archive_type
rescue ::Zip::Error, StandardError
  remaining_message = archive_types.empty? ? 'No remaining types to attempt!' : "Attempting remaining types (#{archive_types.join(', ')})..."
  EasyIO.logger.debug "Archive does not appear to be a #{try_archive_type}. #{remaining_message}"
  return detect_archive_type(archive_types) unless archive_types.empty? # Try the remaining archive types unless none are left
  raise "Archive type for #{@path} could not be detected! Ensure it is in the list of supported types (#{supported_archive_types.join(', ')})."
end

#determine_files_to_add(source_folder, files_to_check: nil) ⇒ Object

Description:

Determines what files should be added to an archive based on the options and mode provided.

Returns:

An array of files to be added (or the :all symbol).

Parameters:

source_folder: The filesystem directory where files are being added from.
files_to_check: Array of files intended to be added to an archive. Can be exact names/paths or names/paths with wildcards (glob style) or a Regexp.
  default: All files and folders under the source_folder.



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/zipr/archive.rb', line 239

def determine_files_to_add(source_folder, files_to_check: nil)
  files_to_check ||= Dir.glob("#{source_folder}/**/*".tr('\\', '/')) if files_to_check.nil?
  files_to_add = []
  source_folder_glob = nil
  files_to_check.each do |target_search|
    files = if target_search.is_a?(Regexp)
              source_folder_glob ||= Dir.glob("#{source_folder.tr('\\', '/')}/**/*")
              source_folder_glob.select do |path|
                path =~ target_search
              end
              source_folder_glob.select { |path| path.to_s =~ target_search }
            else
              Dir.glob(Zipr.prepend_source_folder(source_folder, target_search))
            end
    files.each do |source_file|
      relative_path = Zipr.slice_source_folder(source_folder, source_file)
      exists_in_zip = !!@checksums[relative_path]
      next if @mode == :if_missing && exists_in_zip
      next if _excluded_file?(relative_path, exists_in_zip: exists_in_zip) || _excluded_file?(source_file, exists_in_zip: exists_in_zip)
      next if @mode == :idempotent && ::File.file?(source_file) && @checksums[relative_path] == Digest::SHA256.file(source_file).hexdigest
      next if ::File.directory?(source_file) && @checksums[relative_path] == 'directory'
      EasyIO.logger.debug "'#{relative_path}' would be added to archive..."
      files_to_add.push(source_file)
    end
  end
  files_to_add
end

#determine_files_to_extract(destination_folder, files_to_check: nil) ⇒ Object

Description:

Determines what files should be extracted based on the options and mode provided.

Returns:

An array of files to be extracted (or the :all symbol).

Parameters:

destination_folder: Where the files would be extracted to.
files_to_check: Array of files intended to be extracted from an archive. Should be relative names/paths with or without asterisk wildcards or a regular expression.
  default: All files and folders in the archive.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/zipr/archive.rb', line 207

def determine_files_to_extract(destination_folder, files_to_check: nil)
  files_to_check ||= :all # defaults to :all files

  unless ::File.exist?(@path)
    # If the archive doesn't exist but checksums were provided, check for files to extract based off of checksums
    return @checksums.select { |entry_name, checksum| _extract_file?(entry_name, checksum == 'directory', destination_folder, files_to_check) }.keys unless @checksums.nil? || @checksums.empty?
    # If the archive doesn't exist and no checksums were found, extract all files_to_check
    return files_to_check
  end

  files_to_extract = case @options[:archive_type]
                     when :zip
                       _determine_zip_files_to_extract(destination_folder, files_to_check)
                     when :seven_zip
                       _determine_seven_zip_files_to_extract(destination_folder, files_to_check)
                     else
                       raise "':#{@options[:archive_type]}' is not a supported archive type!"
                     end

  EasyIO.logger.debug "Files to extract: #{files_to_extract.empty? ? 'none' : JSON.pretty_generate(files_to_extract)}"
  files_to_extract
end

#extract(destination_folder, files_to_extract: nil) ⇒ Object

Description:

Extract files from an archive

Returns:

Array of 2 objects: String path to the checksum file and the hash of known checksums for archive files.

Parameters:

path: The full path to the archive being extracted.
destination_folder: The path where files will be extracted to.
files_to_extract: An array of files to be extracted from the archive. Relative paths should be used. If omitted, extracts all contents of the archive.



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/zipr/archive.rb', line 114

def extract(destination_folder, files_to_extract: nil)
  raise "Unable to extract #{@path}! The file does not exist!" unless ::File.file?(@path)
  @options[:overwrite] = @mode != :if_missing
  files_to_extract = determine_files_to_extract(destination_folder, files_to_check: files_to_extract)

  case @options[:archive_type]
  when :zip
    _extract_zip(destination_folder, files_to_extract)
  when :seven_zip
    _extract_seven_zip(destination_folder, files_to_extract)
  end

  EasyIO.logger.info "Extracting #{::File.basename(@path)} finished." unless @options[:silent]
  [@checksum_path, update_checksum_file]
end

#load_checksum_file ⇒ Object

Description:

Loads the known checksums for this archive from the checksum file.

Returns:

A hash of all known checksums for the archive.



175
176
177
178
179
180
181
182
 
# File 'lib/zipr/archive.rb', line 175

def load_checksum_file
  @checksums = if ::File.exist?(@checksum_path) # Read the checksums file if it hasn't been read yet
                 file_content = ::File.read(@checksum_path)
                 JSON.parse(file_content)
               else
                 {}
               end
end

#supported_archive_types ⇒ Object

Description:

Defines all supported archive types.

Returns:

Array of supported archive types.



297
298
299
 
# File 'lib/zipr/archive.rb', line 297

def supported_archive_types
  [:zip, :seven_zip]
end

#update_checksum_file ⇒ Object

Description:

Writes the archive's checksum file.

Returns:

A hash of all known checksums for the archive.



161
162
163
164
165
166
167
168
169
 
# File 'lib/zipr/archive.rb', line 161

def update_checksum_file
  archive_path = @options[:sfx] ? @sfx_path : @path
  archive_checksum = ::Digest::SHA256.file(archive_path).hexdigest
  @checksums['archive_checksum'] = archive_checksum
  @checksum_path = "#{@cache_path}/checksums/#{::File.basename(archive_path)}-#{archive_checksum}.txt"
  FileUtils.mkdir_p(::File.dirname(checksum_path)) unless ::File.directory?(::File.dirname(checksum_path))
  ::File.write(checksum_path, @checksums.to_json)
  @checksums
end

#view_file(relative_path) ⇒ Object

Description:

Read a file inside a zip file without extracting it to the filesystem.
Currently only supports :zip files

Returns:

A string containing the file contents.

Parameters:

relative_path: The path inside the archive for the file to view.



192
193
194
195
196
 
# File 'lib/zipr/archive.rb', line 192

def view_file(relative_path)
  raise 'Reading files inside a 7zip archive is not yet supported!' if @options[:archive_type] == :seven_zip
  EasyIO.logger.debug "Reading #{@path} // #{relative_path}..."
  ::Zip::File.open(@path).read(relative_path)
end