libarchive-ruby

This is libarchive-ruby, your preferred archiving toolkit in Ruby! libarchive-ruby is a Ruby binding to the famous libarchive library and supports nearly all features the library exposes through it’s C++ interface.

librarchive-ruby focuses on a clean and ruby-like syntax that makes it trivial to create, read, write and extract archive files of various formats. Want to know more? Keep reading!

Prerequesites

In order to successfully install libarchive-ruby, you need the following:

Ruby >= 1.8.7
A C++ compiler (we use the GNU project’s g++)
libarchive (we tested with 2.8.4)

How to install?

RubyGems

This is the easiest and preferred way. Ensure you have a proper built environment for C++ code, and then do

# gem install libarchive-ruby

Building from source

If you want to be on the bleeding etch, clone the our git repository at GitHub:

$ git clone https://github.com/Hanmac/libarchive-ruby.git
$ cd libarchive-ruby

Then you can either choose to use the library from that directory by running

$ rake compile

or to make a gem and install that one.

$ rake gem
# gem install --local pkg/libarchive-ruby-x.x.x

How to use?

First, you have to require the library:

require "archive" #Note this is NOT "libarchive-ruby"

Then you can use the beautiful rubyish API:

Read an archive

Assuming, you have “myarchive.tar.bz2” in the current directory.

a = Archive.new("myarchive.tar.bz2")
puts "This archive contains:"
a.each{|entry| puts entry}

#Archive includes the Enumerable module, making available all that 
#nice enumerating functionality: 
puts All entries in uppercase are:
puts a.map{|entry| entry.path.upcase}.join("\n")

#Furthermore, you can even read from the files contained in the 
#archive without actually extracting it:
a.each{|entry, data| puts "Content of #{entry} is: #{data}"}

Extract an archive

Assuming you have “myarchive.tar.bz2” in the current directory.

a = Archive.new("myarchive.tar.bz2")

#Extract all files to the current directory
a.extract

#Extract a specific file
a.extract("mydir/myfile")

#Restrict what file attributes are extracted:
a.extract(:extract => Archive::EXTRACT_OWNER | Archive::EXTRACT_TIME)

#Extract only files whose path is longer than 5 characters
a.extract_if{|entry| entry.path.size > 5}

Create an archive

Assuming you have three files “a.rb”, “b.cpp” and “README.rdoc” in your current directory:

a = Archive.new("myarchive.tar.gz")
a << "a.rb" << "b.cpp" << "README.rdoc"

If you have more than one file to add you can use an Array:

a = Archive.new("myarchive.tar.gz")
a << ["a.rb", "b.cpp", "README.rdoc"]

You can manipulate the entry witch is added to the file:

a = Archive.new("myarchive.tar.gz")
a.add("a.rb") {|entry| entry.mtime = Time.now }

#Note how libarchive-ruby automatically picked up the archive format 
#you wanted by examining the file extension:
a = Archive.new("myarchive.tar.gz")
puts a.format_name #=> POSIX ustar format

Contributors

The following people have worked on libarchive-ruby beside me:

Quintus <sutniuq ÄT gmx DÖT net> contributed to the docs

License

libarchive-ruby is a Ruby binding for the C library libarchive.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Contact

You can read me via the email address hanmac ÄT gmx DÖT de.