= libarchive-ruby

This is libarchive-ruby, your preferred archiving toolkit in Ruby! libarchive-ruby is a Ruby binding to the famous {libarchive library}[http://code.google.com/p/libarchive/] 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}[http://www.gnu.org] 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}[https://github.com/Hanmac/libarchive-ruby]:

$ 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

== Further reading

Have a look at the documentation for the Archive and Archive::Entry classes for more information.

== 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.

Copyright © 2011 Hans Mackowiak

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.