ruby_archive

Seamless access to Ruby source and other files inside zip archives

Works with all rubies I have tested it with… ruby-1.8.7, rubinius, jruby, and ruby-head.

Includes a modified version of rubyzip. Readme and license for rubyzip are available in README.rubyzip. Note that ruby_archive may fail if the program uses a different version of rubyzip.

A Ruby Summer of Code 2010 Project.

Usage

Using ruby_archive in your project is easy! It allows you to use zip or jar archives much the same way you already use normal operating system directories.

To use it, simply require 'ruby_archive' in your project. After this, you can:

open files for reading or writing within an archive using Kernel#open or File.open
load or require Ruby source files from within an archive
glob files within an archive directory
much more…

The format for accessing files within an archive is: “(archive_file)!/(file_within_archive)” So to open information.txt inside archive.jar, you might:

f = File.open('./archive.jar!/information.txt','r')

Or to load source.rb inside program.zip, you might:

require './program.zip!/source'

You can also add archive directories to the load path:

$LOAD_PATH << 'program.zip!/' ; require 'source'

Note that if the specified path (including the exclamation point) exists as a file on the filesystem (i.e. not an archive), it will load the file instead of the archive. So, if you have an archive named archive.zip and a directory name archive.zip! with a file named text.txt inside, a request for 'archive.zip!/text.txt' will load the file rather than look for text.txt inside archive.zip.

Launcher

There is also a simple launcher for programs packaged as archive files in the bin folder. If you include a file named start.rb in your archive, this launcher will run this file. The launcher always adds the base path of the archive to the load path.

The launcher can be used from the shell as follows:

rba_launch program.zip

You can also specify a specific file to load with the launcher, though often on some shells you may need to escape the ‘!’ or single-quote the filename:

rba_launch 'program.zip!/alternate_start.rb'

rba_launch program.zip\!/alternate_start.rb

To-do

A lot of work has gone into making this work great, but there are still many features that we should be able to implement.

autoload - initially I thought it would not be possible to make it work without patches to the Ruby interpreter, but some research on the topic has led me to believe it is indeed possible.
launcher - the included launcher is extremely basic. We would like one that can do things like read jar manifests and load configuration options from the archive.
File.*** and Dir.*** - while most common methods work, there are a couple that may come up from time to time that are currently marked as forward_method_unsupported (meaning they will fail if called on an archive location)
More archive handlers - zip_handler.rb works great for zip and jar files, but I’d like to add more supported formats. A handler for gem files, for example, would be great.
Various fixes to zip_handler/rubyzip - for example, currently you can only load files within a zip archive with string modes (‘r’,‘w’,etc). Trying to use a constant mode (File::RDONLY, etc) will raise an exception.

Bugs?

Please put bug reports on the issue tracker. Include any error messages, exceptions, and (if applicable) source code that is causing the problem.

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

Thanks

Ruby Summer of Code and all those involved in it, for being awesome - rubysoc.org
Evan Phoenix for being my mentor on this project
Authors of rubyzip for making a really great way to work with zip files in Ruby