rubysl-tempfile 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0ef0738dac62e35b9f6360922f94efc28d20fd39
-  data.tar.gz: fce5f3e54ef1085c072f867ae45bf51884d13061
+  metadata.gz: 0f82c47d38159bb53a71a207db4db87b6d0ace1d
+  data.tar.gz: 026e066a5774dbfb057f861cc78a9ae7717be308
 SHA512:
-  metadata.gz: e1ad962fc20d677dcb0b0179803065ef8f7ec8042808549b80e6b8dc12fea148327f19ee919974a3addcbd305474ee9917d58164715190fce6ec39ad033c51c1
-  data.tar.gz: 7b28bfb3515238570324440c5752d69d6b9def6feaa70847889e678b58bc88f0934853fa78a29f9ea665d70aa328f648a4a2dd5c458ca897b20a7ee40756db48
+  metadata.gz: daa1c9f4243df03b5f6266f0c451b6cba2fd1c499eab3e814575953a6c0124b3dbbe4d792c4c3e0ef11b852b41e88d24e8835ee7cb4c284027f573ee4f419b02
+  data.tar.gz: c6485ac719d85e2fd2ace909a61a52cccc0883752de27ab15e1ba53022745ced1d5d3388465a99366669ff4d255435577493226a7b49e7d050fb20a55e33b52e

data/.travis.yml

@@ -3,5 +3,5 @@ env:
   - RUBYLIB=lib
 script: bundle exec mspec
 rvm:
-  - 1.8.7
-  - rbx-nightly-18mode
+  - 1.9.3
+  - rbx-nightly-19mode

data/lib/rubysl/tempfile/tempfile.rb

@@ -1,94 +1,166 @@
 #
 # tempfile - manipulates temporary files
 #
-# $Id: tempfile.rb 16127 2008-04-21 09:43:44Z knu $
+# $Id: tempfile.rb 31768 2011-05-28 23:31:24Z yugui $
 #
 
 require 'delegate'
 require 'tmpdir'
+require 'thread'
 
-# A class for managing temporary files.  This library is written to be
-# thread safe.
+# A utility class for managing temporary files. When you create a Tempfile
+# object, it will create a temporary file with a unique filename. A Tempfile
+# objects behaves just like a File object, and you can perform all the usual
+# file operations on it: reading data, writing data, changing its permissions,
+# etc. So although this class does not explicitly document all instance methods
+# supported by File, you can in fact call any File instance method on a
+# Tempfile object.
+#
+# == Synopsis
+#
+#   require 'tempfile'
+#
+#   file = Tempfile.new('foo')
+#   file.path      # => A unique filename in the OS's temp directory,
+#                  #    e.g.: "/tmp/foo.24722.0"
+#                  #    This filename contains 'foo' in its basename.
+#   file.write("hello world")
+#   file.rewind
+#   file.read      # => "hello world"
+#   file.close
+#   file.unlink    # deletes the temp file
+#
+# == Good practices
+#
+# === Explicit close
+#
+# When a Tempfile object is garbage collected, or when the Ruby interpreter
+# exits, its associated temporary file is automatically deleted. This means
+# that's it's unnecessary to explicitly delete a Tempfile after use, though
+# it's good practice to do so: not explicitly deleting unused Tempfiles can
+# potentially leave behind large amounts of tempfiles on the filesystem
+# until they're garbage collected. The existance of these temp files can make
+# it harder to determine a new Tempfile filename.
+#
+# Therefore, one should always call #unlink or close in an ensure block, like
+# this:
+#
+#   file = Tempfile.new('foo')
+#   begin
+#      ...do something with file...
+#   ensure
+#      file.close
+#      file.unlink   # deletes the temp file
+#   end
+#
+# === Unlink after creation
+#
+# On POSIX systems, it's possible to unlink a file right after creating it,
+# and before closing it. This removes the filesystem entry without closing
+# the file handle, so it ensures that only the processes that already had
+# the file handle open can access the file's contents. It's strongly
+# recommended that you do this if you do not want any other processes to
+# be able to read from or write to the Tempfile, and you do not need to
+# know the Tempfile's filename either.
+#
+# For example, a practical use case for unlink-after-creation would be this:
+# you need a large byte buffer that's too large to comfortably fit in RAM,
+# e.g. when you're writing a web server and you want to buffer the client's
+# file upload data.
+#
+# Please refer to #unlink for more information and a code example.
+#
+# == Minor notes
+#
+# Tempfile's filename picking method is both thread-safe and inter-process-safe:
+# it guarantees that no other threads or processes will pick the same filename.
+#
+# Tempfile itself however may not be entirely thread-safe. If you access the
+# same Tempfile object from multiple threads then you should protect it with a
+# mutex.
 class Tempfile < DelegateClass(File)
-  MAX_TRY = 10
-  @@cleanlist = []
-
-  # Creates a temporary file of mode 0600 in the temporary directory,
-  # opens it with mode "w+", and returns a Tempfile object which
-  # represents the created temporary file.  A Tempfile object can be
-  # treated just like a normal File object.
-  #
-  # The basename parameter is used to determine the name of a
-  # temporary file.  If an Array is given, the first element is used
-  # as prefix string and the second as suffix string, respectively.
-  # Otherwise it is treated as prefix string.
-  #
-  # If tmpdir is omitted, the temporary directory is determined by
-  # Dir::tmpdir provided by 'tmpdir.rb'.
-  # When $SAFE > 0 and the given tmpdir is tainted, it uses
-  # /tmp. (Note that ENV values are tainted by default)
-  def initialize(basename, tmpdir=Dir::tmpdir)
-    if $SAFE > 0 and tmpdir.tainted?
-      tmpdir = '/tmp'
-    end
-
-    lock = nil
-    n = failure = 0
+  MAX_TRY = 10  # :nodoc:
+  include Dir::Tmpname
 
-    begin
-      Thread.critical = true
+  # call-seq:
+  #    new(basename, [tmpdir = Dir.tmpdir], [options])
+  #
+  # Creates a temporary file with permissions 0600 (= only readable and
+  # writable by the owner) and opens it with mode "w+".
+  #
+  # The +basename+ parameter is used to determine the name of the
+  # temporary file. You can either pass a String or an Array with
+  # 2 String elements. In the former form, the temporary file's base
+  # name will begin with the given string. In the latter form,
+  # the temporary file's base name will begin with the array's first
+  # element, and end with the second element. For example:
+  #
+  #   file = Tempfile.new('hello')
+  #   file.path  # => something like: "/tmp/hello2843-8392-92849382--0"
+  #
+  #   # Use the Array form to enforce an extension in the filename:
+  #   file = Tempfile.new(['hello', '.jpg'])
+  #   file.path  # => something like: "/tmp/hello2843-8392-92849382--0.jpg"
+  #
+  # The temporary file will be placed in the directory as specified
+  # by the +tmpdir+ parameter. By default, this is +Dir.tmpdir+.
+  # When $SAFE > 0 and the given +tmpdir+ is tainted, it uses
+  # '/tmp' as the temporary directory. Please note that ENV values
+  # are tainted by default, and +Dir.tmpdir+'s return value might
+  # come from environment variables (e.g. <tt>$TMPDIR</tt>).
+  #
+  #   file = Tempfile.new('hello', '/home/aisaka')
+  #   file.path  # => something like: "/home/aisaka/hello2843-8392-92849382--0"
+  #
+  # You can also pass an options hash. Under the hood, Tempfile creates
+  # the temporary file using +File.open+. These options will be passed to
+  # +File.open+. This is mostly useful for specifying encoding
+  # options, e.g.:
+  #
+  #   Tempfile.new('hello', '/home/aisaka', :encoding => 'ascii-8bit')
+  #
+  #   # You can also omit the 'tmpdir' parameter:
+  #   Tempfile.new('hello', :encoding => 'ascii-8bit')
+  #
+  # === Exceptions
+  #
+  # If Tempfile.new cannot find a unique filename within a limited
+  # number of tries, then it will raise an exception.
+  def initialize(basename, *rest)
+    @data = []
+    @clean_proc = Remover.new(@data)
+    ObjectSpace.define_finalizer(self, @clean_proc)
 
+    create(basename, *rest) do |tmpname, n, opts|
+      lock = tmpname + '.lock'
+      mode = File::RDWR|File::CREAT|File::EXCL
+      perm = 0600
+      if opts
+        mode |= opts.delete(:mode) || 0
+        opts[:perm] = perm
+        perm = nil
+      else
+        opts = perm
+      end
+      self.class.mkdir(lock)
       begin
-        tmpname = File.join(tmpdir, make_tmpname(basename, n))
-        lock = tmpname + '.lock'
-        n += 1
-      end while @@cleanlist.include?(tmpname) or
-                File.exist?(lock) or File.exist?(tmpname)
-
-      Dir.mkdir(lock)
-    rescue
-      failure += 1
-      retry if failure < MAX_TRY
-      raise "cannot generate tempfile `%s'" % tmpname
-    ensure
-      Thread.critical = false
+        @data[1] = @tmpfile = File.open(tmpname, mode, opts)
+        @data[0] = @tmpname = tmpname
+      ensure
+        self.class.rmdir(lock)
+      end
+      @mode = mode & ~(File::CREAT|File::EXCL)
+      perm or opts.freeze
+      @opts = opts
     end
 
-    @data = [tmpname]
-    @clean_proc = Tempfile.callback(@data)
-    ObjectSpace.define_finalizer(self, @clean_proc)
-
-    @tmpfile = File.open(tmpname, File::RDWR|File::CREAT|File::EXCL, 0600)
-    @tmpname = tmpname
-    @@cleanlist << @tmpname
-    @data[1] = @tmpfile
-    @data[2] = @@cleanlist
-
     super(@tmpfile)
-
-    # Now we have all the File/IO methods defined, you must not
-    # carelessly put bare puts(), etc. after this.
-
-    Dir.rmdir(lock)
   end
 
-  def make_tmpname(basename, n)
-    case basename
-    when Array
-      prefix, suffix = *basename
-    else
-      prefix, suffix = basename, ''
-    end
-
-    t = Time.now.strftime("%Y%m%d")
-    path = "#{prefix}#{t}-#{$$}-#{rand(0x100000000).to_s(36)}-#{n}#{suffix}"
-  end
-  private :make_tmpname
-
   # Opens or reopens the file with mode "r+".
   def open
     @tmpfile.close if @tmpfile
-    @tmpfile = File.open(@tmpname, 'r+')
+    @tmpfile = File.open(@tmpname, @mode, @opts)
     @data[1] = @tmpfile
     __setobj__(@tmpfile)
   end
@@ -100,8 +172,9 @@ class Tempfile < DelegateClass(File)
   end
   protected :_close
 
-  # Closes the file.  If the optional flag is true, unlinks the file
-  # after closing.
+  # Closes the file. If +unlink_now+ is true, then the file will be unlinked
+  # (deleted) after closing. Of course, you can choose to later call #unlink
+  # if you do not unlink it now.
   #
   # If you don't explicitly unlink the temporary file, the removal
   # will be delayed until the object is finalized.
@@ -113,25 +186,57 @@ class Tempfile < DelegateClass(File)
     end
   end
 
-  # Closes and unlinks the file.
+  # Closes and unlinks (deletes) the file. Has the same effect as called
+  # <tt>close(true)</tt>.
   def close!
     _close
-    @clean_proc.call
+    unlink
     ObjectSpace.undefine_finalizer(self)
-    @data = @tmpname = nil
   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.
+  # Unlinks (deletes) the file from the filesystem. One should always unlink
+  # the file after using it, as is explained in the "Explicit close" good
+  # practice section in the Tempfile overview:
+  #
+  #   file = Tempfile.new('foo')
+  #   begin
+  #      ...do something with file...
+  #   ensure
+  #      file.close
+  #      file.unlink   # deletes the temp file
+  #   end
+  #
+  # === Unlink-before-close
+  #
+  # On POSIX systems it's possible to unlink a file before closing it. This
+  # practice is explained in detail in the Tempfile overview (section
+  # "Unlink after creation"); please refer there for more information.
+  #
+  # However, unlink-before-close may not be supported on non-POSIX operating
+  # systems. Microsoft Windows is the most notable case: unlinking a non-closed
+  # file will result in an error, which this method will silently ignore. If
+  # you want to practice unlink-before-close whenever possible, then you should
+  # write code like this:
+  #
+  #   file = Tempfile.new('foo')
+  #   file.unlink   # On Windows this silently fails.
+  #   begin
+  #      ... do something with file ...
+  #   ensure
+  #      file.close!   # Closes the file handle. If the file wasn't unlinked
+  #                    # because #unlink failed, then this method will attempt
+  #                    # to do so again.
+  #   end
   def unlink
     # keep this order for thread safeness
+    return unless @tmpname
     begin
-      File.unlink(@tmpname) if File.exist?(@tmpname)
-      @@cleanlist.delete(@tmpname)
-      @data = @tmpname = nil
-      ObjectSpace.undefine_finalizer(self)
+      if File.exist?(@tmpname)
+        File.unlink(@tmpname)
+      end
+      # remove tmpname from remover
+      @data[0] = @data[2] = nil
+      @tmpname = nil
     rescue Errno::EACCES
       # may not be able to unlink on Windows; just ignore
     end
@@ -139,6 +244,7 @@ class Tempfile < DelegateClass(File)
   alias delete unlink
 
   # Returns the full path name of the temporary file.
+  # This will be nil if #unlink has been called.
   def path
     @tmpname
   end
@@ -149,52 +255,83 @@ class Tempfile < DelegateClass(File)
     if @tmpfile
       @tmpfile.flush
       @tmpfile.stat.size
+    elsif @tmpname
+      File.size(@tmpname)
     else
       0
     end
   end
   alias length size
 
-  class << self
-    def callback(data)	# :nodoc:
-      pid = $$
-      lambda {
-        if pid == $$
-          path, tmpfile, cleanlist = *data
+  # :stopdoc:
+  class Remover
+    def initialize(data)
+      @pid = $$
+      @data = data
+    end
 
-          print "removing ", path, "..." if $DEBUG
+    def call(*args)
+      if @pid == $$
+        path, tmpfile = *@data
 
-          tmpfile.close if tmpfile
+        STDERR.print "removing ", path, "..." if $DEBUG
 
-          # keep this order for thread safeness
-          File.unlink(path) if File.exist?(path)
-          cleanlist.delete(path) if cleanlist
+        tmpfile.close if tmpfile
 
-          print "done\n" if $DEBUG
+        # keep this order for thread safeness
+        if path
+          File.unlink(path) if File.exist?(path)
         end
-      }
+
+        STDERR.print "done\n" if $DEBUG
+      end
     end
+  end
+  # :startdoc:
 
-    # If no block is given, this is a synonym for new().
+  class << self
+    # Creates a new Tempfile.
+    #
+    # If no block is given, this is a synonym for Tempfile.new.
     #
-    # If a block is given, it will be passed tempfile as an argument,
-    # and the tempfile will automatically be closed when the block
-    # terminates.  In this case, open() returns nil.
+    # If a block is given, then a Tempfile object will be constructed,
+    # and the block is run with said object as argument. The Tempfile
+    # oject will be automatically closed after the block terminates.
+    # The call returns the value of the block.
+    #
+    # In any case, all arguments (+*args+) will be passed to Tempfile.new.
+    #
+    #   Tempfile.open('foo', '/home/temp') do |f|
+    #      ... do something with f ...
+    #   end
+    #
+    #   # Equivalent:
+    #   f = Tempfile.open('foo', '/home/temp')
+    #   begin
+    #      ... do something with f ...
+    #   ensure
+    #      f.close
+    #   end
     def open(*args)
       tempfile = new(*args)
 
       if block_given?
-        begin
-          yield(tempfile)
-        ensure
-          tempfile.close
-        end
-
-        nil
+	begin
+	  yield(tempfile)
+	ensure
+	  tempfile.close
+	end
       else
-        tempfile
+	tempfile
       end
     end
+
+    def mkdir(*args)
+      Dir.mkdir(*args)
+    end
+    def rmdir(*args)
+      Dir.rmdir(*args)
+    end
   end
 end
 

data/lib/rubysl/tempfile/version.rb

@@ -1,5 +1,5 @@
 module RubySL
   module Tempfile
-    VERSION = "1.0.0"
+    VERSION = "2.0.0"
   end
 end

data/rubysl-tempfile.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = "~> 1.8.7"
+  spec.required_ruby_version = "~> 2.0"
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubysl-tempfile
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Brian Shirai
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-27 00:00:00.000000000 Z
+date: 2013-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -95,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ~>
     - !ruby/object:Gem::Version
-      version: 1.8.7
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='