Class: Archive::Tar::External

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

Overview

This class encapsulates tar & zip operations.

Constant Summary collapse

VERSION =

The version of the archive-tar-external library.

'1.3.3'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(archive_name, file_pattern = nil, program = nil) ⇒ External

Returns an Archive::Tar::External object. The archive_name is the name of the tarball. While a .tar extension is recommended based on years of convention, it is not enforced.

Note that this does not actually create the archive unless you pass a value to file_pattern. This then becomes a shortcut for Archive::Tar::External.new + Archive::Tar::External#create_archive.

If program is provided, then it compresses the archive as well by calling Archive::Tar::External#compress_archive internally.



42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/archive/tar/external.rb', line 42

def initialize(archive_name, file_pattern=nil, program=nil)
  @archive_name            = archive_name.to_s
  @compressed_archive_name = nil
  @tar_program             = 'tar'

  if file_pattern
     create_archive(file_pattern)
  end

  if program
     compress_archive(program)
  end
end

Instance Attribute Details

#archive_name ⇒ Object

The name of the archive file to be used, e.g. “test.tar”



23
24
25
 
# File 'lib/archive/tar/external.rb', line 23

def archive_name
  @archive_name
end

#compressed_archive_name ⇒ Object

The name of the archive file after compression, e.g. “test.tar.gz”



29
30
31
 
# File 'lib/archive/tar/external.rb', line 29

def compressed_archive_name
  @compressed_archive_name
end

#tar_program ⇒ Object

The name of the tar program you wish to use. The default is “tar”.



26
27
28
 
# File 'lib/archive/tar/external.rb', line 26

def tar_program
  @tar_program
end

Class Method Details

.extract_archive(archive, *files) ⇒ Object Also known as: expand_archive, extract, expand

A class method that behaves identically to the equivalent instance method, except that you must specifiy that tarball as the first argument. Also, the tar program is hard coded to ‘tar xf’.



251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/archive/tar/external.rb', line 251

def self.extract_archive(archive, *files)
  cmd = "tar xf #{archive}"

  unless files.empty?
    cmd << " " << files.join(" ")
  end

  Open3.popen3(cmd){ |ain, aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  }

  self
end

.uncompress_archive(archive, program = 'gunzip') ⇒ Object Also known as: uncompress

Uncompress an existing archive, using program to uncompress it. The default decompression program is gunzip.



148
149
150
151
152
153
154
155
 
# File 'lib/archive/tar/external.rb', line 148

def self.uncompress_archive(archive, program='gunzip')
  cmd = "#{program} #{archive}"

  Open3.popen3(cmd){ |prog_in, prog_out, prog_err|
    err = prog_err.gets
    raise CompressError, err.chomp if err
  }
end

Instance Method Details

#add_to_archive(*files) ⇒ Object Also known as: add

Adds files to an already existing archive.



184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/archive/tar/external.rb', line 184

def add_to_archive(*files)
  if files.empty?
    raise Error, "there must be at least one file specified"
  end

  cmd = "#{@tar_program} rf #{@archive_name} #{files.join(" ")}"

  Open3.popen3(cmd){ |ain, aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  }
  self
end

#archive_info ⇒ Object Also known as: info

Returns an array of file names that are included within the tarball. This method does not extract the archive.



164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/archive/tar/external.rb', line 164

def archive_info
  result = []
  cmd = "#{@tar_program} tf #{@archive_name}"
  Open3.popen3(cmd){ |ain, aout, aerr|
    err = aerr.gets
    if err
      raise Error, err.chomp
    end

    while output = aout.gets
      result << output.chomp
    end
  }
  result
end

#compress_archive(program = 'gzip') ⇒ Object Also known as: compress

Compresses the archive with program, or gzip if no program is provided. If you want to pass arguments to program, merely include them as part of the program name, e.g. “gzip -f”.

Any errors that occur here will raise a Tar::CompressError.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/archive/tar/external.rb', line 100

def compress_archive(program='gzip')
  cmd = "#{program} #{@archive_name}"

  Open3.popen3(cmd){ |prog_in, prog_out, prog_err|
    err = prog_err.gets
    raise CompressError, err.chomp if err

    # Find the new file name with the extension.  There's probably a more
    # reliable way to do this, but this should work 99% of the time.
    name = Dir["#{@archive_name}.{gz,bz2,cpio,zip}"].first
    @compressed_archive_name = name
  }

  self
end

#create_archive(file_pattern, options = 'cf') ⇒ Object Also known as: create

Creates the archive using file_pattern using options or ‘cf’ (create file) by default.

Raises an Archive::Tar::Error if a failure occurs.



79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/archive/tar/external.rb', line 79

def create_archive(file_pattern, options = 'cf')
  cmd = "#{@tar_program} #{options} #{@archive_name} #{file_pattern}"

  Open3.popen3(cmd){ |tar_in, tar_out, tar_err|
    err = tar_err.gets
    if err
      raise Error, err.chomp
    end
  }

  self
end

#expand ⇒ Object

Expands the contents of the tarball. It does NOT delete the tarball. If files are provided, then only those files are extracted. Otherwise, all files are extracted.

Note that some tar programs, notably the tar program shipped by Sun, does not issue any sort of warning or error if you try to extract a file that does not exist in the archive.



245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/archive/tar/external.rb', line 245

def extract_archive(*files)
  cmd = "#{@tar_program} xf #{@archive_name}"

  unless files.empty?
    cmd << " " << files.join(" ")
  end

  Open3.popen3(cmd){ |ain, aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  }

  self
end

#expand_archive ⇒ Object

Expands the contents of the tarball. It does NOT delete the tarball. If files are provided, then only those files are extracted. Otherwise, all files are extracted.

Note that some tar programs, notably the tar program shipped by Sun, does not issue any sort of warning or error if you try to extract a file that does not exist in the archive.



243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/archive/tar/external.rb', line 243

def extract_archive(*files)
  cmd = "#{@tar_program} xf #{@archive_name}"

  unless files.empty?
    cmd << " " << files.join(" ")
  end

  Open3.popen3(cmd){ |ain, aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  }

  self
end

#extract ⇒ Object

Expands the contents of the tarball. It does NOT delete the tarball. If files are provided, then only those files are extracted. Otherwise, all files are extracted.

Note that some tar programs, notably the tar program shipped by Sun, does not issue any sort of warning or error if you try to extract a file that does not exist in the archive.



244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/archive/tar/external.rb', line 244

def extract_archive(*files)
  cmd = "#{@tar_program} xf #{@archive_name}"

  unless files.empty?
    cmd << " " << files.join(" ")
  end

  Open3.popen3(cmd){ |ain, aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  }

  self
end

#extract_archive(*files) ⇒ Object

Expands the contents of the tarball. It does NOT delete the tarball. If files are provided, then only those files are extracted. Otherwise, all files are extracted.

Note that some tar programs, notably the tar program shipped by Sun, does not issue any sort of warning or error if you try to extract a file that does not exist in the archive.



228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/archive/tar/external.rb', line 228

def extract_archive(*files)
  cmd = "#{@tar_program} xf #{@archive_name}"

  unless files.empty?
    cmd << " " << files.join(" ")
  end

  Open3.popen3(cmd){ |ain, aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  }

  self
end

#uncompress ⇒ Object

Uncompresses the tarball using the program you pass to this method. The default is “gunzip”. Just as for compress_archive, you can pass arguments along as part of the argument.

Note that this is only for use with archives that have been zipped up with gunzip, or whatever. If you want to extract the files from the tarball, use Tar::External#extract instead.

Any errors that occur here will raise a Tar::CompressError.



143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/archive/tar/external.rb', line 143

def uncompress_archive(program="gunzip")
  unless @compressed_archive_name
    raise CompressError, "no compressed file found"
  end

  cmd = "#{program} #{@compressed_archive_name}"

  Open3.popen3(cmd){ |prog_in, prog_out, prog_err|
    err = prog_err.gets
    raise CompressError, err.chomp if err
    @compressed_archive_name = nil
  }
  self
end

#uncompress_archive(program = "gunzip") ⇒ Object

Uncompresses the tarball using the program you pass to this method. The default is “gunzip”. Just as for compress_archive, you can pass arguments along as part of the argument.

Note that this is only for use with archives that have been zipped up with gunzip, or whatever. If you want to extract the files from the tarball, use Tar::External#extract instead.

Any errors that occur here will raise a Tar::CompressError.



128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/archive/tar/external.rb', line 128

def uncompress_archive(program="gunzip")
  unless @compressed_archive_name
    raise CompressError, "no compressed file found"
  end

  cmd = "#{program} #{@compressed_archive_name}"

  Open3.popen3(cmd){ |prog_in, prog_out, prog_err|
    err = prog_err.gets
    raise CompressError, err.chomp if err
    @compressed_archive_name = nil
  }
  self
end

#update_archive(*files) ⇒ Object Also known as: update

Updates the given files in the archive, i.e. they are added if they are not already in the archive or have been modified.



203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/archive/tar/external.rb', line 203

def update_archive(*files)
  if files.empty?
    raise Error, "there must be at least one file specified"
  end

  cmd = "#{@tar_program} uf #{@archive_name} #{files.join(" ")}"

  Open3.popen3(cmd){ |ain, aout, aerr|
    err = aerr.gets
    raise Error, err.chomp if err
  }

  self
end