lib/zip/zipfilesystem.rb in bigtinker-0.97 vs lib/zip/zipfilesystem.rb in bigtinker-0.98

@@ -1,26 +1,71 @@
-require 'zip/zip'
+require 'lib/zip/zip'
 
 module Zip
+
+  # The ZipFileSystem API provides an API for accessing entries in 
+  # a zip archive that is similar to ruby's builtin File and Dir 
+  # classes.
+  #
+  # Requiring 'zip/zipfilesystem' includes this module in ZipFile
+  # making the methods in this module available on ZipFile objects.
+  #
+  # Using this API the following example creates a new zip file 
+  # <code>my.zip</code> containing a normal entry with the name
+  # <code>first.txt</code>, a directory entry named <code>mydir</code>
+  # and finally another normal entry named <code>second.txt</code>
+  #
+  #   require 'zip/zipfilesystem'
+  #   
+  #   Zip::ZipFile.open("my.zip", Zip::ZipFile::CREATE) {
+  #     |zipfile|
+  #     zipfile.file.open("first.txt", "w") { |f| f.puts "Hello world" }
+  #     zipfile.dir.mkdir("mydir")
+  #     zipfile.file.open("mydir/second.txt", "w") { |f| f.puts "Hello again" }
+  #   }
+  #
+  # Reading is as easy as writing, as the following example shows. The 
+  # example writes the contents of <code>first.txt</code> from zip archive
+  # <code>my.zip</code> to standard out.
+  #
+  #   require 'zip/zipfilesystem'
+  #   
+  #   Zip::ZipFile.open("my.zip") {
+  #     |zipfile|
+  #     puts zipfile.file.read("first.txt")
+  #   }
+
   module ZipFileSystem
 
-    def initialize
+    def initialize # :nodoc:
       mappedZip = ZipFileNameMapper.new(self)
       @zipFsDir  = ZipFsDir.new(mappedZip)
       @zipFsFile = ZipFsFile.new(mappedZip)
       @zipFsDir.file = @zipFsFile
       @zipFsFile.dir = @zipFsDir
     end
 
+    # Returns a ZipFsDir which is much like ruby's builtin Dir (class)
+    # object, except it works on the ZipFile on which this method is
+    # invoked
     def dir
       @zipFsDir
     end
     
+    # Returns a ZipFsFile which is much like ruby's builtin File (class)
+    # object, except it works on the ZipFile on which this method is
+    # invoked
     def file
       @zipFsFile
     end
-    
+
+    # Instances of this class are normally accessed via the accessor
+    # ZipFile::file. An instance of ZipFsFile behaves like ruby's
+    # builtin File (class) object, except it works on ZipFile entries.
+    #
+    # The individual methods are not documented due to their
+    # similarity with the methods in File
     class ZipFsFile
 
       attr_writer :dir
 #      protected :dir
 
@@ -196,11 +241,11 @@
       
       def size(fileName)
 	@mappedZip.get_entry(fileName).size
       end
       
-      # nil for not found and nil for directories
+      # Returns nil for not found and nil for directories
       def size?(fileName)
 	entry = @mappedZip.find_entry(fileName)
 	return (entry == nil || entry.directory?) ? nil : entry.size
       end
       
@@ -365,10 +410,16 @@
       def expand_path(aPath)
         @mappedZip.expand_path(aPath)
       end
     end
 
+    # Instances of this class are normally accessed via the accessor
+    # ZipFile::dir. An instance of ZipFsDir behaves like ruby's
+    # builtin Dir (class) object, except it works on ZipFile entries.
+    #
+    # The individual methods are not documented due to their
+    # similarity with the methods in Dir
     class ZipFsDir
       
       def initialize(mappedZip)
         @mappedZip = mappedZip
       end
@@ -429,21 +480,21 @@
         @mappedZip.remove(entryName)
       end
       alias rmdir  delete
       alias unlink delete
       
-      def mkdir(entryName, permissionInt = 0)
+      def mkdir(entryName, permissionInt = 0755)
         @mappedZip.mkdir(entryName, permissionInt)
       end
       
       def chroot(*args)
       	raise NotImplementedError, "The chroot() function is not implemented"
       end
 
     end
 
-    class ZipFsDirIterator
+    class ZipFsDirIterator # :nodoc:all
       include Enumerable
 
       def initialize(arrayOfFileNames)
         @fileNames = arrayOfFileNames
         @index = 0
@@ -479,11 +530,11 @@
       end
     end
 
     # All access to ZipFile from ZipFsFile and ZipFsDir goes through a
     # ZipFileNameMapper, which has one responsibility: ensure
-    class ZipFileNameMapper
+    class ZipFileNameMapper # :nodoc:all
       include Enumerable
 
       def initialize(zipFile)
         @zipFile = zipFile
         @pwd = "/"
@@ -518,10 +569,10 @@
       def rename(fileName, newName, &continueOnExistsProc)
         @zipFile.rename(expand_to_entry(fileName), expand_to_entry(newName), 
                         &continueOnExistsProc)
       end
 
-      def mkdir(fileName, permissionInt = 0)
+      def mkdir(fileName, permissionInt = 0755)
         @zipFile.mkdir(expand_to_entry(fileName), permissionInt)
       end
 
       # Turns entries into strings and adds leading /
       # and removes trailing slash on directories