ruby_archive 0.1.2

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,24 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## RUBINIUS
+*.rbc
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/README.rdoc

@@ -0,0 +1,106 @@
+= 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 <code>require 'ruby_archive'</code> in your project.  After this, you can:
+* open files for reading or writing within an archive using <code>Kernel#open</code> or
+  <code>File.open</code>
+* <code>load</code> or <code>require</code> Ruby source files from within an archive
+* <code>glob</code> files within an archive directory
+* much more...
+
+The format for accessing files within an archive is: "(archive_file)!/(file_within_archive)"
+So to open <code>information.txt</code> inside <code>archive.jar</code>, you might:
+
+<code>f = File.open('./archive.jar!/information.txt','r')</code>
+
+Or to load <code>source.rb</code> inside <code>program.zip</code>, you might:
+
+<code>require './program.zip!/source'</code>
+
+You can also add archive directories to the load path:
+
+<code>$LOAD_PATH << 'program.zip!/' ; require 'source'</code>
+
+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 <code>archive.zip</code> and a
+directory name <code>archive.zip!</code> with a file named <code>text.txt</code>
+inside, a request for <code>'archive.zip!/text.txt'</code> will load the file
+rather than look for text.txt inside <code>archive.zip</code>.
+
+== Launcher
+
+There is also a simple launcher for programs packaged as archive files in the
+bin folder.  If you include a file named <code>start.rb</code> 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:
+
+<code>rba_launch program.zip</code>
+
+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:
+
+<code>rba_launch 'program.zip!/alternate_start.rb'</code>
+
+<code>rba_launch program.zip\!/alternate_start.rb</code>
+
+== 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.
+
+* <b>autoload</b> - 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.
+* <b>launcher</b> - 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.
+* <b>File.*** and Dir.***</b> - 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)
+* <b>More archive handlers</b> - 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.
+* <b>Various fixes to zip_handler/rubyzip</b> - 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
+
+* <b>Ruby Summer of Code</b> and all those involved in it, for being awesome - http://rubysoc.org
+* <b>Evan Phoenix</b> for being my mentor on this project
+* <b>Authors of rubyzip</b> for making a really great way to work with zip files in Ruby
+
+== Copyright
+
+Copyright (c) 2010 Jonathan Nielsen.
+Released under Ruby's license, including GPL option.

data/README.rubyzip

@@ -0,0 +1,72 @@
+= rubyzip
+
+rubyzip is a ruby library for reading and writing zip files.
+
+= Install
+
+If you have rubygems you can install rubyzip directly from the gem
+repository
+
+  gem install rubyzip
+
+Otherwise obtain the source (see below) and run
+
+  ruby install.rb
+
+To run the unit tests you need to have test::unit installed
+
+  rake test
+
+
+= Documentation
+
+There is more than one way to access or create a zip archive with
+rubyzip. The basic API is modeled after the classes in
+java.util.zip from the Java SDK. This means there are classes such
+as Zip::ZipInputStream, Zip::ZipOutputStream and
+Zip::ZipFile. Zip::ZipInputStream provides a basic interface for
+iterating through the entries in a zip archive and reading from the
+entries in the same way as from a regular File or IO
+object. ZipOutputStream is the corresponding basic output
+facility. Zip::ZipFile provides a mean for accessing the archives
+central directory and provides means for accessing any entry without
+having to iterate through the archive. Unlike Java's
+java.util.zip.ZipFile rubyzip's Zip::ZipFile is mutable, which means
+it can be used to change zip files as well.
+
+Another way to access a zip archive with rubyzip is to use rubyzip's
+Zip::ZipFileSystem API. Using this API files can be read from and
+written to the archive in much the same manner as ruby's builtin
+classes allows files to be read from and written to the file system.
+
+rubyzip also features the
+zip/ziprequire.rb[link:files/lib/zip/ziprequire_rb.html] module which
+allows ruby to load ruby modules from zip archives.
+
+For details about the specific behaviour of classes and methods refer
+to the test suite. Finally you can generate the rdoc documentation or
+visit http://rubyzip.sourceforge.net.
+
+= License
+
+rubyzip is distributed under the same license as ruby. See
+http://www.ruby-lang.org/en/LICENSE.txt
+
+
+= Website and Project Home
+
+http://rubyzip.sourceforge.net
+
+http://sourceforge.net/projects/rubyzip
+
+== Download (tarballs and gems)
+
+http://sourceforge.net/project/showfiles.php?group_id=43107&package_id=35377
+
+= Authors
+
+Thomas Sondergaard (thomas at sondergaard.cc)
+
+Technorama Ltd. (oss-ruby-zip at technorama.net)
+
+extra-field support contributed by Tatsuki Sugiura (sugi at nemui.org)

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ruby_archive"
+    gem.summary = %Q{Seamless access to ruby source and other files inside zip archives}
+    gem.description = %Q{Allows loading applications, libraries, and data from easily distributable archive files}
+    gem.email = "jonathan@jmnet.us"
+    gem.homepage = "http://github.com/byuni/ruby_archive"
+    gem.authors = ["Jonathan Nielsen"]
+    gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rubyarchive-pure #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/bin/rba_launch

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+require 'optparse'
+
+# default options
+options = {
+  :entry_point => 'start.rb'
+}
+
+# overrides in archive
+options_archive = {}
+
+# overrides by command line
+options_cmdline = {}
+
+help_banner = nil
+opts = OptionParser.new do |opts|
+  opts.banner = 
+%{Usage: #{$0} [options] [archive] [arguments]
+To run a specific file within an archive, use archive.zip!/ruby_file.rb
+
+}
+
+  #opts.on("-v", "--[no-]verbose", "Verbose errors/warnings") do |v|
+  #  options[:verbose] = v
+  #end
+
+  opts.on("-e", "--entry-point=FILE", String, "Force a specific default file to load within the archive") do |l|
+    options_cmdline[:entry_point] = l
+  end
+
+  opts.on_tail("-h", "--help", "Print this message") do
+    puts opts
+    exit
+  end
+end
+
+opts.order! # parse up to archive name
+
+if ARGV.empty?  # no archive was specified, print banner and exit
+  puts opts
+  exit
+end
+
+require File.expand_path("../../lib/ruby_archive",__FILE__)
+
+archive_file = File.expand_path(ARGV.shift,Dir.getwd)
+file_to_load = nil
+
+location_info = File.in_archive?(archive_file)
+unless location_info == false
+  archive_file = location_info[0]
+  file_to_load = location_info[1]
+end
+
+options.merge!(options_archive)
+options.merge!(options_cmdline)
+# TODO: load archive specific options
+
+file_to_load = options[:entry_point] if file_to_load.nil?
+
+$LOAD_PATH << "#{archive_file}!/"
+load("#{archive_file}!#{file_to_load}",false)

data/lib/ruby_archive.rb

@@ -0,0 +1,79 @@
+require File.expand_path('../ruby_archive/patch.rb',__FILE__)
+
+module RubyArchive
+  class Handler
+    # ruby_archive/handler.rb
+    require File.expand_path('../ruby_archive/handler.rb',__FILE__)
+  end
+
+  module Handlers
+    # ruby_archive/handlers/*.rb
+    # loaded at end of file
+  end
+
+  @@archive_handlers ||= []
+  # Adds an archive handler to the list used.  Provided handler must be a
+  # subclass of +RubyArchive::Handler+
+  def add_handler_class handler_class
+    unless (handler_class.is_a? Class) && (handler_class <= RubyArchive::Handler)
+      raise TypeError, "#{handler_class} is not a RubyArchive::Handler"
+    end
+    @@archive_handlers << handler_class
+    true
+  end
+  module_function :add_handler_class
+
+  # Finds the appropriate +RubyArchive::Handler+ subclass for a given location.
+  # Returns nil if no supported handler found.
+  def find_handler_class location
+    @@archive_handlers.each do |h|
+      return h if h.handles?(location)
+    end
+    return nil
+  end
+  module_function :find_handler_class
+
+  @@loaded_archives ||= {}
+  # Retrieves an archive from the loaded_archives cache, or automatically
+  # loads the archive.  Returns the archive on success.  Returns nil if
+  # archive is not available and autoload is false.  Raises +LoadError+
+  # if autoload is attempted and fails.
+  def get location, autoload=true
+    @@archive_handlers.each do |h|
+      normalized = h.normalize_path(location)
+      return @@loaded_archives[normalized] if @@loaded_archives.has_key?(normalized)
+    end
+    return load(location) if autoload
+    nil
+  end
+  module_function :get
+
+  # Loads the specified archive location.  Returns the handler object on
+  # success.  Raises +LoadError+ if no handler can be found or it does not
+  # exist.  May also pass exceptions passed along by creating the handler.
+  def load location
+    handler_class = find_handler_class(location)
+    if handler_class.nil?
+      raise LoadError, "No handler found or does not exist for archive -- #{location}"
+    end
+    archive = handler_class.new(location)
+    @@loaded_archives[archive.name] = archive
+  end
+  module_function :load
+
+  def close_all_archives
+    @@loaded_archives.each_value do |archive|
+      archive.close
+    end
+    @@loaded_archives.clear
+    true
+  end
+  module_function :close_all_archives
+
+end
+
+# Set RubyArchive::close_all_archives to at_exit
+at_exit { RubyArchive::close_all_archives }
+
+# load builtin handlers
+require File.expand_path('../ruby_archive/handlers/zip_handler.rb',__FILE__)

data/lib/ruby_archive/handler.rb

@@ -0,0 +1,55 @@
+module RubyArchive
+  # RubyArchive::Handler
+  class Handler
+    # Should return true if the class can handle the given location as an
+    # archive.  Returns false otherwise.  The default implementation always
+    # returns false, this must be overridden in your subclasses.
+    #
+    # This method must NOT raise an exception.
+    def self.handles? location
+      false
+    end
+
+    # Should return a normalized version of the location specified.
+    # +File.expand_path+ works well in many cases, and is provided as the
+    # default.
+    def self.normalize_path location
+      File.expand_path(location)
+    end
+
+    # Initialize a handler object for the location given.  The default
+    # implementation raises a +NotImplementedError+.
+    #
+    # Your implementation needs to set +@name+ to identify the archive
+    def initialize location
+      raise NotImplementedError, "Cannot initialize a handler of class #{self.class}"
+    end
+
+    # Close the handler.  This will be executed when +RubyArchive::close_all_archives+
+    # is executed, or at_exit
+    #
+    # Should always return nil
+    def close
+      nil
+    end
+
+    # Should return a +File+-like object for the archive.  The default
+    # implementation raises a +NotImplentedError+, must be overridden.
+    def file
+      raise NotImplementedError, "Cannot retrieve a file object for class #{self.class}"
+    end
+
+    # Should return a +Dir+-like object for the archive (optional)
+    # Should return +nil+ if not supported.
+    def dir
+      nil
+    end
+
+    # reader for +@name+, which should be set in +initialize+
+    attr_reader :name
+
+    def inspect
+      "<#{self.class}:#{self.name}>"
+    end
+  end
+end