* lib/tempfile.rb: Embed Rdoc style comments.

* lib/tempfile.rb: Add length as an alias for size.


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

1 files changed, 56 insertions, 41 deletions

diff --git a/lib/tempfile.rb b/lib/tempfile.rb
index 0fc1e81fd3..289fea324a 100644
--- a/lib/tempfile.rb
+++ b/lib/tempfile.rb
@@ -1,48 +1,26 @@
 #
-# $Id$
+# tempfile - manipulates temporary files
 #
-# This is a class for managing temporary files.
+# $Id$
 #
-#  o Tempfile::new("basename") creates a temporary file whose name is
-#    "basename.pid.n" and opens with mode "w+".
-#  o A Tempfile object can be treated as an IO object.
-#  o The temporary directory is determined by ENV['TMPDIR'],
-#    ENV['TMP'], and ENV['TEMP'] in the order named, and if none of
-#    them is available, it is set to /tmp.
-#  o When $SAFE > 0, you should specify a directory via the second argument
-#    of Tempfile::new(), or it will end up finding an ENV value tainted and
-#    pick /tmp.  In case you don't have it, an exception will be raised.
-#  o Tempfile#close! gets the temporary file removed immediately.
-#  o Otherwise, the removal is delayed until the object is finalized.
-#  o With Tempfile#open, you can reopen the temporary file.
-#  o The file mode for the temporary files is 0600.
-#  o This library is (considered to be) thread safe.
 
 require 'delegate'
 
+# A class for managing temporary files.  This library is written to be
+# thread safe.
 class Tempfile < SimpleDelegator
   MAX_TRY = 10
   @@cleanlist = []
 
-  def Tempfile.callback(data)
-    pid = $$
-    lambda{
-      if pid == $$ 
-	path, tmpfile, cleanlist = *data
-
-	print "removing ", path, "..." if $DEBUG
-
-	tmpfile.close if tmpfile
-
-	# keep this order for thread safeness
-	File.unlink(path) if File.exist?(path)
-	cleanlist.delete(path) if cleanlist
-
-	print "done\n" if $DEBUG
-      end
-    }
-  end
-
+  # Creates a temporary file of mode 0600 in the temporary directory
+  # whose name is basename.pid.n and opens with mode "w+".  A Tempfile
+  # object works just like a File object.
+  #
+  # If tmpdir is omitted, the temporary directory is determined by
+  # ENV['TMPDIR'], ENV['TMP'] and and ENV['TEMP'] in the order named.
+  # If none of them is available, or when $SAFE > 0 and the given
+  # tmpdir is tainted, it uses /tmp. (Note that ENV values are
+  # tainted by default)
   def initialize(basename, tmpdir=ENV['TMPDIR']||ENV['TMP']||ENV['TEMP']||'/tmp')
     if $SAFE > 0 and tmpdir.tainted?
       tmpdir = '/tmp'
@@ -88,10 +66,7 @@ class Tempfile < SimpleDelegator
     Dir.rmdir(lock)
   end
 
-  def Tempfile.open(*args)
-    Tempfile.new(*args)
-  end
-
+  # Opens or reopens the file with mode "r+".
   def open
     @tmpfile.close if @tmpfile
     @tmpfile = File.open(@tmpname, 'r+')
@@ -99,13 +74,18 @@ class Tempfile < SimpleDelegator
     __setobj__(@tmpfile)
   end
 
-  def _close
+  def _close	# :nodoc:
     @tmpfile.close if @tmpfile
     @data[1] = @tmpfile = nil
   end    
   protected :_close
 
-  def close(real=false)
+  # Closes the file.  If the optional flag is true, unlinks the file
+  # after closing.
+  #
+  # If you don't explicitly unlink the temporary file, the removal
+  # will be delayed until the object is finalized.
+  def close(unlink=false)
     if real
       close!
     else
@@ -113,12 +93,17 @@ class Tempfile < SimpleDelegator
     end
   end
 
+  # Closes and unlinks the file.
   def close!
     _close
     @clean_proc.call
     ObjectSpace.undefine_finalizer(self)
   end
 
+  # Unlinks the file.  On UNIX-like systems, it is often a good idea
+  # to unlink a temporary file immediately after creating and opening
+  # it, because it leaves other programs zero chance to access the
+  # file.
   def unlink
     # keep this order for thread safeness
     File.unlink(@tmpname) if File.exist?(@tmpname)
@@ -126,10 +111,13 @@ class Tempfile < SimpleDelegator
   end
   alias delete unlink
 
+  # Returns the full path name of the temporary file.
   def path
     @tmpname
   end
 
+  # Returns the size of the temporary file.  As a side effect, the IO
+  # buffer is flushed before determining the size.
   def size
     if @tmpfile
       @tmpfile.flush
@@ -138,6 +126,33 @@ class Tempfile < SimpleDelegator
       0
     end
   end
+  alias length size
+
+  class << self
+    def callback(data)	# :nodoc:
+      pid = $$
+      lambda{
+	if pid == $$ 
+	  path, tmpfile, cleanlist = *data
+
+	  print "removing ", path, "..." if $DEBUG
+
+	  tmpfile.close if tmpfile
+
+	  # keep this order for thread safeness
+	  File.unlink(path) if File.exist?(path)
+	  cleanlist.delete(path) if cleanlist
+
+	  print "done\n" if $DEBUG
+	end
+      }
+    end
+
+    # Equivalent to new().
+    def open(*args)
+      new(*args)
+    end
+  end
 end
 
 if __FILE__ == $0