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.
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
requireRuby source files from within an archive
globfiles within an archive directory
The format for accessing files within an archive is: “(archive_file)!/(file_within_archive)” So to open
archive.jar, you might:
f = File.open('./archive.jar!/information.txt','r')
Or to load
program.zip, you might:
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
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:
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:
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.
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.
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
Copyright © 2010 Jonathan Nielsen. Released under Ruby's license, including GPL option.