Update to RubyGems 1.3.4 r2223

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@23659 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

7 files changed, 158 insertions, 22 deletions

diff --git a/lib/rubygems/package/f_sync_dir.rb b/lib/rubygems/package/f_sync_dir.rb
index 3e2e4a59a8..1915ab3ecb 100644
--- a/lib/rubygems/package/f_sync_dir.rb
+++ b/lib/rubygems/package/f_sync_dir.rb
@@ -3,8 +3,6 @@
 # See LICENSE.txt for additional licensing information.
 #--
 
-require 'rubygems/package'
-
 module Gem::Package::FSyncDir
 
   private
diff --git a/lib/rubygems/package/tar_header.rb b/lib/rubygems/package/tar_header.rb
index fa78126a0d..44c6695cf9 100644
--- a/lib/rubygems/package/tar_header.rb
+++ b/lib/rubygems/package/tar_header.rb
@@ -3,8 +3,6 @@
 # See LICENSE.txt for additional licensing information.
 #--
 
-require 'rubygems/package'
-
 ##
 #--
 # struct tarfile_entry_posix {
@@ -26,9 +24,13 @@ require 'rubygems/package'
 #   char prefix[155];   # ASCII + (Z unless filled)
 # };
 #++
+# A header for a tar file
 
 class Gem::Package::TarHeader
 
+  ##
+  # Fields in the tar header
+
   FIELDS = [
     :checksum,
     :devmajor,
@@ -48,6 +50,9 @@ class Gem::Package::TarHeader
     :version,
   ]
 
+  ##
+  # Pack format for a tar header
+
   PACK_FORMAT = 'a100' + # name
                 'a8'   + # mode
                 'a8'   + # uid
@@ -65,6 +70,9 @@ class Gem::Package::TarHeader
                 'a8'   + # devminor
                 'a155'   # prefix
 
+  ##
+  # Unpack format for a tar header
+
   UNPACK_FORMAT = 'A100' + # name
                   'A8'   + # mode
                   'A8'   + # uid
@@ -84,6 +92,9 @@ class Gem::Package::TarHeader
 
   attr_reader(*FIELDS)
 
+  ##
+  # Creates a tar header from IO +stream+
+
   def self.from(stream)
     header = stream.read 512
     empty = (header == "\0" * 512)
@@ -147,6 +158,9 @@ class Gem::Package::TarHeader
     #    :empty => empty
   end
 
+  ##
+  # Creates a new TarHeader using +vals+
+
   def initialize(vals)
     unless vals[:name] && vals[:size] && vals[:prefix] && vals[:mode] then
       raise ArgumentError, ":name, :size, :prefix and :mode required"
@@ -171,11 +185,14 @@ class Gem::Package::TarHeader
     @empty = vals[:empty]
   end
 
+  ##
+  # Is the tar entry empty?
+
   def empty?
     @empty
   end
 
-  def ==(other)
+  def ==(other) # :nodoc:
     self.class === other and
     @checksum == other.checksum and
     @devmajor == other.devmajor and
@@ -195,11 +212,14 @@ class Gem::Package::TarHeader
     @version  == other.version
   end
 
-  def to_s
+  def to_s # :nodoc:
     update_checksum
     header
   end
 
+  ##
+  # Updates the TarHeader's checksum
+
   def update_checksum
     header = header " " * 8
     @checksum = oct calculate_checksum(header), 6
diff --git a/lib/rubygems/package/tar_input.rb b/lib/rubygems/package/tar_input.rb
index 2ed3d6b772..9f901023b8 100644
--- a/lib/rubygems/package/tar_input.rb
+++ b/lib/rubygems/package/tar_input.rb
@@ -3,8 +3,6 @@
 # See LICENSE.txt for additional licensing information.
 #--
 
-require 'rubygems/package'
-
 class Gem::Package::TarInput
 
   include Gem::Package::FSyncDir
@@ -72,9 +70,9 @@ class Gem::Package::TarInput
       # map trust policy from string to actual class (or a serialized YAML
       # file, if that exists)
       if String === security_policy then
-        if Gem::Security::Policy.key? security_policy then
+        if Gem::Security::Policies.key? security_policy then
           # load one of the pre-defined security policies
-          security_policy = Gem::Security::Policy[security_policy]
+          security_policy = Gem::Security::Policies[security_policy]
         elsif File.exist? security_policy then
           # FIXME: this doesn't work yet
           security_policy = YAML.load File.read(security_policy)
@@ -136,10 +134,10 @@ class Gem::Package::TarInput
 
   def extract_entry(destdir, entry, expected_md5sum = nil)
     if entry.directory? then
-      dest = File.join(destdir, entry.full_name)
+      dest = File.join destdir, entry.full_name
 
-      if File.dir? dest then
-        @fileops.chmod entry.header.mode, dest, :verbose=>false
+      if File.directory? dest then
+        @fileops.chmod entry.header.mode, dest, :verbose => false
       else
         @fileops.mkdir_p dest, :mode => entry.header.mode, :verbose => false
       end
diff --git a/lib/rubygems/package/tar_output.rb b/lib/rubygems/package/tar_output.rb
index b22f7dd86b..dfb74af9fc 100644
--- a/lib/rubygems/package/tar_output.rb
+++ b/lib/rubygems/package/tar_output.rb
@@ -3,8 +3,6 @@
 # See LICENSE.txt for additional licensing information.
 #--
 
-require 'rubygems/package'
-
 ##
 # TarOutput is a wrapper to TarWriter that builds gem-format tar file.
 #
@@ -66,8 +64,10 @@ class Gem::Package::TarOutput
       Zlib::GzipWriter.wrap(sio || inner) do |os|
 
         Gem::Package::TarWriter.new os do |data_tar_writer|
+          # :stopdoc:
           def data_tar_writer.metadata() @metadata end
           def data_tar_writer.metadata=(metadata) @metadata = metadata end
+          # :startdoc:
 
           yield data_tar_writer
 
diff --git a/lib/rubygems/package/tar_reader.rb b/lib/rubygems/package/tar_reader.rb
index 4aa9c26cc9..1a2fbaf678 100644
--- a/lib/rubygems/package/tar_reader.rb
+++ b/lib/rubygems/package/tar_reader.rb
@@ -3,14 +3,21 @@
 # See LICENSE.txt for additional licensing information.
 #--
 
-require 'rubygems/package'
+##
+# TarReader reads tar files and allows iteration over their items
 
 class Gem::Package::TarReader
 
   include Gem::Package
 
+  ##
+  # Raised if the tar IO is not seekable
+
   class UnexpectedEOF < StandardError; end
 
+  ##
+  # Creates a new TarReader on +io+ and yields it to the block, if given.
+
   def self.new(io)
     reader = super
 
@@ -25,14 +32,24 @@ class Gem::Package::TarReader
     nil
   end
 
+  ##
+  # Creates a new tar file reader on +io+ which needs to respond to #pos,
+  # #eof?, #read, #getc and #pos=
+
   def initialize(io)
     @io = io
     @init_pos = io.pos
   end
 
+  ##
+  # Close the tar file
+
   def close
   end
 
+  ##
+  # Iterates over files in the tarball yielding each entry
+
   def each
     loop do
       return if @io.eof?
@@ -84,3 +101,5 @@ class Gem::Package::TarReader
 
 end
 
+require 'rubygems/package/tar_reader/entry'
+
diff --git a/lib/rubygems/package/tar_reader/entry.rb b/lib/rubygems/package/tar_reader/entry.rb
index dcc66153d8..eeb70bf000 100644
--- a/lib/rubygems/package/tar_reader/entry.rb
+++ b/lib/rubygems/package/tar_reader/entry.rb
@@ -3,12 +3,19 @@
 # See LICENSE.txt for additional licensing information.
 #--
 
-require 'rubygems/package'
+##
+# Class for reading entries out of a tar file
 
 class Gem::Package::TarReader::Entry
 
+  ##
+  # Header for this tar entry
+
   attr_reader :header
 
+  ##
+  # Creates a new tar entry for +header+ that will be read from +io+
+
   def initialize(header, io)
     @closed = false
     @header = header
@@ -21,24 +28,39 @@ class Gem::Package::TarReader::Entry
     raise IOError, "closed #{self.class}" if closed?
   end
 
+  ##
+  # Number of bytes read out of the tar entry
+
   def bytes_read
     @read
   end
 
+  ##
+  # Closes the tar entry
+
   def close
     @closed = true
   end
 
+  ##
+  # Is the tar entry closed?
+
   def closed?
     @closed
   end
 
+  ##
+  # Are we at the end of the tar entry?
+
   def eof?
     check_closed
 
     @read >= @header.size
   end
 
+  ##
+  # Full name of the tar entry
+
   def full_name
     if @header.prefix != "" then
       File.join @header.prefix, @header.name
@@ -47,6 +69,9 @@ class Gem::Package::TarReader::Entry
     end
   end
 
+  ##
+  # Read one byte from the tar entry
+
   def getc
     check_closed
 
@@ -58,20 +83,33 @@ class Gem::Package::TarReader::Entry
     ret
   end
 
+  ##
+  # Is this tar entry a directory?
+
   def directory?
     @header.typeflag == "5"
   end
 
+  ##
+  # Is this tar entry a file?
+
   def file?
     @header.typeflag == "0"
   end
 
+  ##
+  # The position in the tar entry
+
   def pos
     check_closed
 
     bytes_read
   end
 
+  ##
+  # Reads +len+ bytes from the tar file entry, or the rest of the entry if
+  # nil
+
   def read(len = nil)
     check_closed
 
@@ -86,6 +124,9 @@ class Gem::Package::TarReader::Entry
     ret
   end
 
+  ##
+  # Rewinds to the beginning of the tar file entry
+
   def rewind
     check_closed
 
diff --git a/lib/rubygems/package/tar_writer.rb b/lib/rubygems/package/tar_writer.rb
index 04a15c7779..6f11529302 100644
--- a/lib/rubygems/package/tar_writer.rb
+++ b/lib/rubygems/package/tar_writer.rb
@@ -3,15 +3,30 @@
 # See LICENSE.txt for additional licensing information.
 #--
 
-require 'rubygems/package'
+##
+# Allows writing of tar files
 
 class Gem::Package::TarWriter
 
   class FileOverflow < StandardError; end
 
+  ##
+  # IO wrapper that allows writing a limited amount of data
+
   class BoundedStream
 
-    attr_reader :limit, :written
+    ##
+    # Maximum number of bytes that can be written
+
+    attr_reader :limit
+
+    ##
+    # Number of bytes written
+
+    attr_reader :written
+
+    ##
+    # Wraps +io+ and allows up to +limit+ bytes to be written
 
     def initialize(io, limit)
       @io = io
@@ -19,6 +34,10 @@ class Gem::Package::TarWriter
       @written = 0
     end
 
+    ##
+    # Writes +data+ onto the IO, raising a FileOverflow exception if the
+    # number of bytes will be more than #limit
+
     def write(data)
       if data.size + @written > @limit
         raise FileOverflow, "You tried to feed more data than fits in the file."
@@ -30,18 +49,30 @@ class Gem::Package::TarWriter
 
   end
 
+  ##
+  # IO wrapper that provides only #write
+
   class RestrictedStream
 
+    ##
+    # Creates a new RestrictedStream wrapping +io+
+
     def initialize(io)
       @io = io
     end
 
+    ##
+    # Writes +data+ onto the IO
+
     def write(data)
       @io.write data
     end
 
   end
 
+  ##
+  # Creates a new TarWriter, yielding it if a block is given
+
   def self.new(io)
     writer = super
 
@@ -56,12 +87,19 @@ class Gem::Package::TarWriter
     nil
   end
 
+  ##
+  # Creates a new TarWriter that will write to +io+
+
   def initialize(io)
     @io = io
     @closed = false
   end
 
-  def add_file(name, mode)
+  ##
+  # Adds file +name+ with permissions +mode+, and yields an IO for writing the
+  # file to
+
+  def add_file(name, mode) # :yields: io
     check_closed
 
     raise Gem::Package::NonSeekableIO unless @io.respond_to? :pos=
@@ -90,7 +128,11 @@ class Gem::Package::TarWriter
     self
   end
 
-  def add_file_simple(name, mode, size)
+  ##
+  # Add file +name+ with permissions +mode+ +size+ bytes long.  Yields an IO
+  # to write the file to.
+
+  def add_file_simple(name, mode, size) # :yields: io
     check_closed
 
     name, prefix = split_name name
@@ -112,10 +154,16 @@ class Gem::Package::TarWriter
     self
   end
 
+  ##
+  # Raises IOError if the TarWriter is closed
+
   def check_closed
     raise IOError, "closed #{self.class}" if closed?
   end
 
+  ##
+  # Closes the TarWriter
+
   def close
     check_closed
 
@@ -125,16 +173,25 @@ class Gem::Package::TarWriter
     @closed = true
   end
 
+  ##
+  # Is the TarWriter closed?
+
   def closed?
     @closed
   end
 
+  ##
+  # Flushes the TarWriter's IO
+
   def flush
     check_closed
 
     @io.flush if @io.respond_to? :flush
   end
 
+  ##
+  # Creates a new directory in the tar file +name+ with +mode+
+
   def mkdir(name, mode)
     check_closed
 
@@ -149,6 +206,9 @@ class Gem::Package::TarWriter
     self
   end
 
+  ##
+  # Splits +name+ into a name and prefix that can fit in the TarHeader
+
   def split_name(name) # :nodoc:
     raise Gem::Package::TooLongFileName if name.size > 256
 
@@ -169,7 +229,7 @@ class Gem::Package::TarWriter
       name = newname
 
       if name.size > 100 or prefix.size > 155 then
-        raise Gem::Package::TooLongFileName
+        raise Gem::Package::TooLongFileName 
       end
     end