archive-zip 0.1.0

data/HACKING

@@ -0,0 +1,122 @@
+= Guide to Hacking Archive::Zip
+
+== Licensing
+
+Contributed code must be licensed under the same license as this project.  See
+the included LICENSE file for details.  Special consideration MAY be made in
+some cases, but such cases will be rare.
+
+
+== Dependencies
+
+=== Runtime
+
+* Ruby 1.8.6 or greater
+
+
+=== Build
+
+* rubygems 0.9.0 or greater
+* rake 0.8.1 or greater
+* allison 2.0.3 (optional - used for documentation only, if available)
+* rsync (optional - used for publishing documentation)
+
+
+=== Install
+
+* rubygems 0.9.0 or greater
+
+
+== Versioning Policy
+
+Version numbers will be in <em>x.y.z</em> format, where <em>x</em>, <em>y</em>,
+and <em>z</em> are integers starting from 0.  The version increment rules are
+as follows:
+
+<b>x</b>:: Planned releases which implement significant changes and/or break API
+           compatibility.  An exception is to be made for the transition from
+           the <em>0.y.z</em> series to the <em>1.y.z</em> series since the
+           <em>0.y.z</em> series is expected to be unstable throughout
+           development.  When incremented, <em>y</em> and <em>z</em> are reset
+           to 0.
+<b>y</b>:: Planned releases which incorporate numerous bug fixes and/or new
+           features which do not break backward compatibility.  When
+           incremented, <em>z</em> is reset to 0.
+<b>z</b>:: Generally, unplanned releases which incorporate a single fix for a
+           critical defect.
+
+This is the {Rational Versioning Policy}[http://www.rubygems.org/read/chapter/7]
+as outlined in the {RubyGems User Guide}[http://www.rubygems.org/read/book/1].
+
+
+== Support Policy
+
+Due to limitations in resources (time/money/manpower), this project will focus
+primarily upon the development line of the current release at any given time.
+Fixes and new features should be applied first to that development line and then
+backported to earlier releases if necessary and feasible.  Long term maintenance
+of previous releases is not planned.  Users are generally expected to upgrade to
+the latest release in order to receive updates unless an explicit declaration of
+support for a previous release is made.
+
+
+== Coding Style
+
+The following points are not necessarily set in stone but should rather be used
+as a good guideline.  Consistency is the goal of coding style, and changes will
+be more easily accepted if they are consistent with the rest of the code.
+
+<b>File Encoding</b>::     UTF-8
+<b>Indentation</b>::       Two spaces; no tabs
+<b>Comments</b>::          Document classes, attributes, methods, and code
+<b>Boolean Operators</b>:: Use <tt>&&</tt> and <tt>||</tt> for boolean tests;
+                           avoid <tt>and</tt> and <tt>or</tt>
+<b>Method Calls</b>::      Use <tt>a_method(arg, arg, etc)</tt>; <b>not</b>
+                           <tt>a_method( arg, arg, etc )</tt>,
+                           <tt>a_method arg, arg, etc</tt>, or any other
+                           variation
+<b>Blocks</b>::            <tt>do end</tt> for multi-line blocks and
+                           <tt>{ }</tt> for single-line blocks
+<b>Line length</b>::       Limit lines to a maximum of 80 characters
+<b>General</b>::           Try to follow the flow and style of the rest of the
+                           code
+
+
+== Generating Patches
+
+Patches should usually be generated against the <em>HEAD</em> revision of the
+<em>master</em> branch.  When generating patches, please try to implement only
+a single feature or bug fix per patch.  Documentation describing a patch should
+be included along with the patch so that the maintainer can more easily
+determine whether or not a patch is acceptable.  Patches lacking the necessary
+documentation will be ignored.
+
+Patches will be much more readily accepted if test cases are provided which
+verify correct operation.  Such test cases should be provided within the patch
+rather than as a separate patch.  Proper documentation, especially for
+user-visible APIs, is highly prized; providing accurate and detailed
+documentation, often in the form of rubydocs, throughout new code contributions
+will also increase the desirability of a patch.
+
+If a series of patches is generated which cannot be applied individually, make
+sure to mention the dependency relationships in whatever medium is being used
+to distribute the patches.  For instance, if a bug is discovered while
+implementing a new feature, create a patch which fixes the bug followed by a
+separate patch adding the feature.  If the feature patch requires the bug fix
+patch in order to work, note that dependency in the comments for the feature
+patch by somehow referencing the bug fix patch.
+
+The patch generation process in general:
+  $ git clone git://rubyforge.org/archive-zip.git # Clone the repo and check out
+                                                  # the master branch.
+  $ cd archive-zip                                # Enter the workspace.
+  (make and test changes)
+  $ git add file1 file2 ..                        # Add new/modified files.
+  $ git commit                                    # Commit changes.
+  $ git format-patch -C HEAD^                     # Create a patch for the last
+                                                  # commit.
+
+Repeat as necessary until all patches are generated.  Then either attach them to
+1 or more email messages addressed to the maintainer or attach them to tickets
+in the issue tracker for the project.  Remember to include a brief description
+of the patch and its dependencies, if any.

data/LEGAL

@@ -0,0 +1,8 @@
+= Other Legalities
+
+== Files Licensed Differently
+
+The following file(s) are provided under a license or licenses separate from
+this project.
+
+  None at present

data/LICENSE

@@ -0,0 +1,57 @@
+LICENSE text follows:
+
+  Archive::Zip is copyrighted free software by Jeremy Bopp
+  <jeremy at bopp dot net>.  You can redistribute it and/or modify it under
+  either the terms of the GPL (see the included GPL file), or the conditions
+  below:
+
+    1. You may make and give away verbatim copies of the source form of the
+       software without restriction, provided that you duplicate all of the
+       original copyright notices and associated disclaimers.
+
+    2. You may modify your copy of the software in any way, provided that
+       you do at least ONE of the following:
+
+         a) place your modifications in the Public Domain or otherwise
+            make them Freely Available, such as by posting said
+            modifications to Usenet or an equivalent medium, or by allowing
+            the author to include your modifications in the software.
+
+         b) use the modified software only within your corporation or
+            organization.
+
+         c) rename any non-standard executables so the names do not conflict
+            with standard executables, which must also be provided.
+
+         d) make other distribution arrangements with the author.
+
+    3. You may distribute the software in object code or executable
+       form, provided that you do at least ONE of the following:
+
+         a) distribute the executables and library files of the software,
+            together with instructions (in the manual page or equivalent)
+            on where to get the original distribution.
+
+         b) accompany the distribution with the machine-readable source of
+            the software.
+
+         c) give non-standard executables non-standard names, with
+            instructions on where to get the original software distribution.
+
+         d) make other distribution arrangements with the author.
+
+    4. You may modify and include the covered part of the software into any
+       other software (possibly commercial).  But some files in the
+       distribution may not be written by the author, such that they are not
+       under these terms.  (See the file LEGAL for a listing and conditions)
+
+    5. The scripts and library files supplied as input to or produced as
+       output from the software do not automatically fall under the
+       copyright of the software, but belong to whomever generated them,
+       and may be sold commercially, and may be aggregated with this
+       software.
+
+    6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+       IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+       PURPOSE.

data/MANIFEST

@@ -0,0 +1,26 @@
+CONTRIBUTORS
+GPL
+HACKING
+LEGAL
+LICENSE
+MANIFEST
+NEWS
+README
+lib/archive/support/io-like.rb
+lib/archive/support/io.rb
+lib/archive/support/iowindow.rb
+lib/archive/support/stringio.rb
+lib/archive/support/time.rb
+lib/archive/support/zlib.rb
+lib/archive/zip.rb
+lib/archive/zip/codec.rb
+lib/archive/zip/codec/deflate.rb
+lib/archive/zip/codec/store.rb
+lib/archive/zip/entry.rb
+lib/archive/zip/datadescriptor.rb
+lib/archive/zip/extrafield.rb
+lib/archive/zip/extrafield/extendedtimestamp.rb
+lib/archive/zip/extrafield/raw.rb
+lib/archive/zip/extrafield/unix.rb
+lib/archive/zip/error.rb
+test/test_archive.rb

data/NEWS

@@ -0,0 +1,22 @@
+= News and Notifications by Version
+
+This file lists noteworthy changes which may affect users of this project.  More
+detailed information is available in the rest of the documentation.
+
+<b>NOTE:</b> Date stamps in the following entries are in YYYY/MM/DD format.
+
+
+== v0.1.0 (2008/07/10)
+
+* Initial release
+* Archive creation and extraction is supported with only a few lines of code
+  (See README)
+* Archives can be updated "in place" or dumped out to other files or pipes
+* Files, symlinks, and directories are supported within archives
+* Unix permission/mode bits are supported
+* Unix user and group ownerships are supported.
+* Unix last accessed and last modified times are supported.
+* Entry extension (AKA extra field) implementations can be added on the fly.
+* Unknown entry extension types are preserved during archive processing.
+* Deflate and Store compression codecs supported out of the box
+* More compression codecs can be added on the fly

data/README

@@ -0,0 +1,130 @@
+= Archive::Zip - ZIP Archival Made Easy
+
+The Archive::Zip library intends to provide a simple, yet complete and
+Ruby-esque, interface to working with ZIP archives.
+
+Basic archive creation and extraction can be handled using only a few methods.
+More complex operations involving the manipulation of existing archives in place
+(adding, removing, and modifying entries) are also possible with a little more
+work.  Even adding advanced features such as new compression codecs are
+supported with a moderate amount of effort.
+
+
+== License
+
+Copyright © 2008 Jeremy Bopp <jeremy at bopp dot net>
+
+Licensed under the same terms as Ruby -- See the included LICENSE file for
+details
+
+
+== Installation/Removal
+
+Download the GEM file and install it with:
+  % sudo gem install archive-zip-VERSION.gem
+
+or directly with:
+  % sudo gem install archive-zip
+
+Removal is the same in either case:
+  % sudo gem uninstall archive-zip
+
+
+== Example
+More examples can be found in the +examples+ directory of the source
+distribution.
+
+Create a few archives:
+  gem 'archive-zip'  # Use require_gem for rubygems versions older than 0.9.0.
+  require 'archive/zip'
+
+  # Add a_directory and its contents to example1.zip.
+  Archive::Zip.archive('example1.zip', 'a_directory')
+
+  # Add the contents of a_directory to example2.zip.
+  Archive::Zip.archive('example2.zip', 'a_directory/.')
+
+  # Add a_file and a_directory and its contents to example3.zip.
+  Archive::Zip.archive('example3.zip', ['a_directory', 'a_file'])
+
+  # Add only the files and symlinks contained in a_directory under the path
+  # a/b/c/a_directory in example4.zip.
+  Archive::Zip.archive(
+    'example4.zip',
+    'a_directory',
+    :directories => false,
+    :path_prefix => 'a/b/c'
+  )
+
+  # Create a new archive which will be written to a pipe.
+  # Assume $stdout is the write end a pipe.
+  # (ruby example.rb | cat >example.zip)
+  Archive::Zip.open(nil, $stdout) do |z|
+    z.archive('a_directory')
+  end
+
+Now extract those archives:
+  gem 'archive-zip'  # Use require_gem for rubygems versions older than 0.9.0.
+  require 'archive/zip'
+
+  # Extract example1.zip to a_destination.
+  Archive::Zip.extract('example1.zip', 'a_destination')
+
+  # Extract example2.zip to a_destination, skipping directory entries.
+  Archive::Zip.extract(
+    'example2.zip',
+    'a_destination',
+    :directories => false
+  )
+
+  # Extract example3.zip to a_destination, skipping symlinks.
+  Archive::Zip.extract(
+    'example3.zip',
+    'a_destination',
+    :symlinks => false
+  )
+
+  # Extract example4.zip to a_destination, skipping entries for which files
+  # already exist but are newer or for which files do not exist at all.
+  Archive::Zip.extract(
+    'example4.zip',
+    'a_destination',
+    :create => false,
+    :overwrite => :older
+  )
+
+
+== Features
+
+1.  100% native Ruby.  (Well, almost... depends on zlib.)
+2.  Archive creation and extraction is supported with only a few lines of code.
+3.  Archives can be updated "in place" or dumped out to other files or pipes.
+4.  Files, symlinks, and directories are supported within archives.
+5.  Unix permission/mode bits are supported.
+6.  Unix user and group ownerships are supported.
+7.  Unix last accessed and last modified times are supported.
+8.  Entry extension (AKA extra field) implementations can be added on the fly.
+9.  Unknown entry extension types are preserved during archive processing.
+10. The Deflate and Store compression codecs are supported out of the box.
+11. More compression codecs can be added on the fly.
+
+
+== Known Bugs/Limitations
+
+1.  More testcases are needed.
+2.  All file entries are archived and extracted in binary mode.  No attempt is
+    made to normalize text files to the line ending convention of any target
+    system.
+3.  Hard links and device files are not currently supported within archives.
+4.  Reading archives from non-seekable IO, such as pipes and sockets, is not
+    supported.
+5.  MSDOS permission attributes are not supported.
+6.  Encryption is not supported.
+7.  Zip64 is not supported.
+8.  Digital signatures are not supported.
+
+
+== Contributing
+
+Contributions for bug fixes, documentation, extensions, tests, etc. are
+encouraged.  Please read the file HACKING for details.

data/lib/archive/support/io-like.rb

@@ -0,0 +1,12 @@
+# Try to first load io-like from rubygems and then fall back to assuming a
+# standard installation.
+begin
+  require 'rubygems'
+  gem 'io-like', '>= 0.1.0'
+rescue LoadError
+  # Failed to load via rubygems.
+end
+
+# This will work for the gem and standard install assuming io-like is available
+# at all.
+require 'io/like'

data/lib/archive/support/io.rb

@@ -0,0 +1,14 @@
+require 'readbytes'
+
+class IO
+  # Returns +true+ if the seek method of this IO instance would succeed, +false+
+  # otherwise.
+  def seekable?
+    begin
+      pos
+      true
+    rescue SystemCallError
+      false
+    end
+  end
+end

data/lib/archive/support/iowindow.rb

@@ -0,0 +1,123 @@
+require 'archive/support/io-like'
+
+# IOWindow represents an IO object which wraps another one allowing read access
+# to a subset of the data within the stream.
+#
+# <b>NOTE:</b> This object is NOT thread safe.
+class IOWindow
+  include IO::Like
+
+  # Creates a new instance of this class using _io_ as the data source
+  # and where _window_position_ and _window_size_ define the location and size
+  # of data window respectively.
+  #
+  # _io_ must be opened for reading and must be seekable.  _window_position_
+  # must be an integer greater than or equal to 0.  _window_size_ must be an
+  # integer greater than or equal to 0.
+  def initialize(io, window_position, window_size)
+    raise ArgumentError, 'non-seekable IO object given' unless io.seekable?
+
+    @io = io
+    @unbuffered_pos = 0
+    self.window_position = window_position
+    self.window_size = window_size
+  end
+
+  # The file position at which this window begins.
+  attr_reader :window_position
+
+  # Set the file position at which this window begins.
+  # _window_position_ must be an integer greater than or equal to 0.
+  def window_position=(window_position)
+    unless window_position.kind_of?(Fixnum) then
+      raise ArgumentError, 'non-integer window position given'
+    end
+    if window_position < 0 then
+      raise ArgumentError, 'non-positive window position given'
+    end
+
+    @window_position = window_position
+  end
+
+  # The size of the window.
+  attr_reader :window_size
+
+  # Set the size of the window.
+  # _window_size_ must be an integer greater than or equal to 0.
+  def window_size=(window_size)
+    unless window_size.kind_of?(Fixnum) then
+      raise ArgumentError, 'non-integer window size given'
+    end
+    raise ArgumentError, 'non-positive window size given' if window_size < 0
+
+    @window_size = window_size
+  end
+
+  private
+
+  def unbuffered_read(length)
+    restore_self
+
+    # Error out if the end of the window is reached.
+    raise EOFError, 'end of file reached' if @unbuffered_pos >= @window_size
+
+    # Limit the read operation to the window.
+    length = @window_size - @unbuffered_pos if @unbuffered_pos + length > @window_size
+
+    # Fill a buffer with the data from the delegate.
+    buffer = @io.read(length)
+    # Error out if the end of the delegate is reached.
+    raise EOFError, 'end of file reached' if buffer.nil?
+
+    # Update the position.
+    @unbuffered_pos += buffer.length
+
+    buffer
+  ensure
+    restore_delegate
+  end
+
+  def unbuffered_seek(offset, whence = IO::SEEK_SET)
+    # Convert the offset and whence into an absolute position.
+    case whence
+    when IO::SEEK_SET
+      new_pos = offset
+    when IO::SEEK_CUR
+      new_pos = @unbuffered_pos + offset
+    when IO::SEEK_END
+      new_pos = @window_size + offset
+    end
+
+    # Error out if the position is outside the window.
+    raise Errno::EINVAL, 'Invalid argument' if new_pos < 0 or new_pos > @window_size
+
+    # Set the new position.
+    @unbuffered_pos = new_pos
+  end
+
+  def unbuffered_write(string)
+    restore_self
+
+    # Ensure that the outputted string will not extend past the window.
+    string = string.slice(0, @window_size - @unbuffered_pos)
+    @io.write(string)
+  ensure
+    restore_delegate
+  end
+
+  # Restores the state of the delegate IO object to that saved by a prior call
+  # to #restore_self.
+  def restore_delegate
+    @io.pos = @delegate_pos
+    @io.lineno = @delegate_lineno
+  end
+
+  # Saves the state of the delegate IO object so that it can be restored later
+  # using #restore_delegate and then configures the delegate so as to restore
+  # the state of this object.
+  def restore_self
+    @delegate_pos = @io.pos
+    @delegate_lineno = @io.lineno
+    @io.pos = @window_position + @unbuffered_pos
+  end
+end