ptools 1.2.2-universal-mingw32

data/lib/ptools.rb

@@ -0,0 +1,429 @@
+require 'rbconfig'
+require 'win32/file' if File::ALT_SEPARATOR
+
+class File
+  # The version of the ptools library.
+  PTOOLS_VERSION = '1.2.2'
+
+  # :stopdoc:
+
+  # The WIN32EXTS string is used as part of a Dir[] call in certain methods.
+  if File::ALT_SEPARATOR
+    MSWINDOWS = true
+    if ENV['PATHEXT']
+      WIN32EXTS = ('.{' + ENV['PATHEXT'].tr(';', ',').tr('.','') + '}').downcase
+    else
+      WIN32EXTS = '.{exe,com,bat}'
+    end
+  else
+    MSWINDOWS = false
+  end
+
+  IMAGE_EXT = %w[.bmp .gif .jpg .jpeg .png]
+
+  # :startdoc:
+
+  # Returns whether or not the file is an image. Only JPEG, PNG, BMP and
+  # GIF are checked against.
+  #
+  # This method does some simple read and extension checks. For a version
+  # that is more robust, but which depends on a 3rd party C library (and is
+  # difficult to build on MS Windows), see the 'filemagic' library, available
+  # on the RAA.
+  #
+  # Examples:
+  #
+  #    File.image?('somefile.jpg') # => true
+  #    File.image?('somefile.txt') # => true
+  #--
+  # The approach I used here is based on information found at
+  # http://en.wikipedia.org/wiki/Magic_number_(programming)
+  #
+  def self.image?(file)
+    bool = IMAGE_EXT.include?(File.extname(file).downcase)      # Match ext
+    bool = bmp?(file) || jpg?(file) || png?(file) || gif?(file) # Check data
+    bool
+  end
+
+  # Returns the name of the null device (aka bitbucket) on your platform.
+  #
+  # Examples:
+  #
+  #   # On Linux
+  #   File.null # => '/dev/null'
+  #
+  #   # On MS Windows
+  #   File.null # => 'NUL'
+  #--
+  # The values I used here are based on information from
+  # http://en.wikipedia.org/wiki//dev/null
+  #
+  def self.null
+    case RbConfig::CONFIG['host_os']
+      when /mswin|win32|msdos|cygwin|mingw|windows/i
+        'NUL'
+      when /amiga/i
+        'NIL:'
+      when /openvms/i
+        'NL:'
+      else
+        '/dev/null'
+    end
+  end
+
+  class << self
+    alias null_device null
+  end
+
+  # Returns whether or not +file+ is a binary file.  Note that this is
+  # not guaranteed to be 100% accurate.  It performs a "best guess" based
+  # on a simple test of the first +File.blksize+ characters.
+  #
+  # Example:
+  #
+  #   File.binary?('somefile.exe') # => true
+  #   File.binary?('somefile.txt') # => false
+  #--
+  # Based on code originally provided by Ryan Davis (which, in turn, is
+  # based on Perl's -B switch).
+  #
+  def self.binary?(file)
+    s = (File.read(file, File.stat(file).blksize) || "").split(//)
+    ((s.size - s.grep(" ".."~").size) / s.size.to_f) > 0.30
+  end
+
+  # Looks for the first occurrence of +program+ within +path+.
+  #
+  # On Windows, it looks for executables ending with the suffixes defined
+  # in your PATHEXT environment variable, or '.exe', '.bat' and '.com' if
+  # that isn't defined, which you may optionally include in +program+.
+  #
+  # Returns nil if not found.
+  #
+  # Examples:
+  #
+  #   File.which('ruby') # => '/usr/local/bin/ruby'
+  #   File.which('foo')  # => nil
+  #
+  def self.which(program, path=ENV['PATH'])
+    if path.nil? || path.empty?
+      raise ArgumentError, "path cannot be empty"
+    end
+
+    # Bail out early if an absolute path is provided.
+    if program =~ /^\/|^[a-z]:[\\\/]/i
+      program += WIN32EXTS if MSWINDOWS && File.extname(program).empty?
+      found = Dir[program].first
+      if found && File.executable?(found) && !File.directory?(found)
+        return found
+      else
+        return nil
+      end
+    end
+
+    # Iterate over each path glob the dir + program.
+    path.split(File::PATH_SEPARATOR).each{ |dir|
+      next unless File.exists?(dir) # In case of bogus second argument
+      file = File.join(dir, program)
+
+      # Dir[] doesn't handle backslashes properly, so convert them. Also, if
+      # the program name doesn't have an extension, try them all.
+      if MSWINDOWS
+        file = file.tr("\\", "/")
+        file += WIN32EXTS if File.extname(program).empty?
+      end
+
+      found = Dir[file].first
+
+      # Convert all forward slashes to backslashes if supported
+      if found && File.executable?(found) && !File.directory?(found)
+        found.tr!(File::SEPARATOR, File::ALT_SEPARATOR) if File::ALT_SEPARATOR
+        return found
+      end
+    }
+
+    nil
+  end
+
+  # Returns an array of each +program+ within +path+, or nil if it cannot
+  # be found.
+  #
+  # On Windows, it looks for executables ending with the suffixes defined
+  # in your PATHEXT environment variable, or '.exe', '.bat' and '.com' if
+  # that isn't defined, which you may optionally include in +program+.
+  #
+  # Examples:
+  #
+  #   File.whereis('ruby') # => ['/usr/bin/ruby', '/usr/local/bin/ruby']
+  #   File.whereis('foo')  # => nil
+  #
+  def self.whereis(program, path=ENV['PATH'])
+    if path.nil? || path.empty?
+      raise ArgumentError, "path cannot be empty"
+    end
+
+    paths = []
+
+    # Bail out early if an absolute path is provided.
+    if program =~ /^\/|^[a-z]:[\\\/]/i
+      program += WIN32EXTS if MSWINDOWS && File.extname(program).empty?
+      program = program.tr("\\", '/') if MSWINDOWS
+      found = Dir[program]
+      if found[0] && File.executable?(found[0]) && !File.directory?(found[0])
+        if File::ALT_SEPARATOR
+          return found.map{ |f| f.tr('/', "\\") }
+        else
+          return found
+        end
+      else
+        return nil
+      end
+    end
+
+    # Iterate over each path glob the dir + program.
+    path.split(File::PATH_SEPARATOR).each{ |dir|
+      next unless File.exists?(dir) # In case of bogus second argument
+      file = File.join(dir, program)
+
+      # Dir[] doesn't handle backslashes properly, so convert them. Also, if
+      # the program name doesn't have an extension, try them all.
+      if MSWINDOWS
+        file = file.tr("\\", "/")
+        file += WIN32EXTS if File.extname(program).empty?
+      end
+
+      found = Dir[file].first
+
+      # Convert all forward slashes to backslashes if supported
+      if found && File.executable?(found) && !File.directory?(found)
+        found.tr!(File::SEPARATOR, File::ALT_SEPARATOR) if File::ALT_SEPARATOR
+        paths << found
+      end
+    }
+
+    paths.empty? ? nil : paths.uniq
+  end
+
+  # In block form, yields the first +num_lines+ from +filename+.  In non-block
+  # form, returns an Array of +num_lines+
+  #
+  # Examples:
+  #
+  #  # Return an array
+  #  File.head('somefile.txt') # => ['This is line1', 'This is line2', ...]
+  #
+  #  # Use a block
+  #  File.head('somefile.txt'){ |line| puts line }
+  #
+  def self.head(filename, num_lines=10)
+    a = []
+
+    IO.foreach(filename){ |line|
+      break if num_lines <= 0
+      num_lines -= 1
+      if block_given?
+        yield line
+      else
+        a << line
+      end
+    }
+
+    return a.empty? ? nil : a # Return nil in block form
+  end
+
+  # In block form, yields line +from+ up to line +to+.  In non-block form
+  # returns an Array of lines from +from+ to +to+.
+  #
+  def self.middle(filename, from=10, to=20)
+    if block_given?
+      IO.readlines(filename)[from-1..to-1].each{ |line| yield line }
+    else
+      IO.readlines(filename)[from-1..to-1]
+    end
+  end
+
+  # In block form, yields the last +num_lines+ of file +filename+.
+  # In non-block form, it returns the lines as an array.
+  #
+  # Note that this method slurps the entire file, so I don't recommend it
+  # for very large files. Also note that 'tail -f' functionality is not
+  # present. See the 'file-tail' library for that.
+  #
+  # Example:
+  #
+  #   File.tail('somefile.txt') # => ['This is line7', 'This is line8', ...]
+  #
+  def self.tail(filename, num_lines=10)
+    if block_given?
+      IO.readlines(filename).reverse[0..num_lines-1].reverse.each{ |line|
+        yield line
+      }
+    else
+      IO.readlines(filename).reverse[0..num_lines-1].reverse
+    end
+  end
+
+  # Converts a text file from one OS platform format to another, ala
+  # 'dos2unix'. The possible values for +platform+ include:
+  #
+  # * MS Windows -> dos, windows, win32, mswin
+  # * Unix/BSD   -> unix, linux, bsd
+  # * Mac        -> mac, macintosh, apple, osx
+  #
+  # Note that this method is only valid for an ftype of "file".  Otherwise a
+  # TypeError will be raised.  If an invalid format value is received, an
+  # ArgumentError is raised.
+  #
+  def self.nl_convert(old_file, new_file = old_file, platform = 'dos')
+    unless File::Stat.new(old_file).file?
+      raise ArgumentError, 'Only valid for plain text files'
+    end
+
+    case platform
+      when /dos|windows|win32|mswin|cygwin|mingw/i
+        format = "\cM\cJ"
+      when /unix|linux|bsd/i
+        format = "\cJ"
+      when /mac|apple|macintosh|osx/i
+        format = "\cM"
+      else
+        raise ArgumentError, "Invalid platform string"
+    end
+
+    orig = $\ # AKA $OUTPUT_RECORD_SEPARATOR
+    $\ = format
+
+    if old_file == new_file
+      require 'fileutils'
+      require 'tempfile'
+
+      begin
+        temp_name = Time.new.strftime("%Y%m%d%H%M%S")
+        tf = Tempfile.new('ruby_temp_' + temp_name)
+        tf.open
+
+        IO.foreach(old_file){ |line|
+          line.chomp!
+          tf.print line
+        }
+      ensure
+        tf.close if tf && !tf.closed?
+      end
+
+      File.delete(old_file)
+      FileUtils.cp(tf.path, old_file)
+    else
+      begin
+        nf = File.new(new_file, 'w')
+        IO.foreach(old_file){ |line|
+          line.chomp!
+          nf.print line
+        }
+      ensure
+        nf.close if nf && !nf.closed?
+      end
+    end
+
+    $\ = orig
+    self
+  end
+
+  # Changes the access and modification time if present, or creates a 0
+  # byte file +filename+ if it doesn't already exist.
+  #
+  def self.touch(filename)
+    if File.exists?(filename)
+      time = Time.now
+      File.utime(time, time, filename)
+    else
+      File.open(filename, 'w'){}
+    end
+    self
+  end
+
+  # With no arguments, returns a four element array consisting of the number
+  # of bytes, characters, words and lines in filename, respectively.
+  #
+  # Valid options are 'bytes', 'characters' (or just 'chars'), 'words' and
+  # 'lines'.
+  #
+  def self.wc(filename, option='all')
+    option.downcase!
+    valid = %w/all bytes characters chars lines words/
+
+    unless valid.include?(option)
+      raise ArgumentError, "Invalid option: '#{option}'"
+    end
+
+    n = 0
+
+    if option == 'lines'
+      IO.foreach(filename){ n += 1 }
+      return n
+    elsif option == 'bytes'
+      File.open(filename){ |f|
+        f.each_byte{ n += 1 }
+      }
+      return n
+    elsif option == 'characters' || option == 'chars'
+      File.open(filename){ |f|
+        while f.getc
+          n += 1
+        end
+      }
+      return n
+    elsif option == 'words'
+      IO.foreach(filename){ |line|
+        n += line.split.length
+      }
+      return n
+    else
+      bytes,chars,lines,words = 0,0,0,0
+      IO.foreach(filename){ |line|
+        lines += 1
+        words += line.split.length
+        chars += line.split('').length
+      }
+      File.open(filename){ |f|
+        while f.getc
+          bytes += 1
+        end
+      }
+      return [bytes,chars,words,lines]
+    end
+  end
+
+  # Already provided by win32-file on MS Windows
+  unless respond_to?(:sparse?)
+    # Returns whether or not +file+ is a sparse file.
+    #
+    # A sparse file is a any file where its size is greater than the number
+    # of 512k blocks it consumes, i.e. its apparent and actual file size is
+    # not the same.
+    #
+    # See http://en.wikipedia.org/wiki/Sparse_file for more information.
+    #
+    def self.sparse?(file)
+      stats = File.stat(file)
+      stats.size > stats.blocks * 512
+    end
+  end
+
+  private
+
+  def self.bmp?(file)
+    IO.read(file, 3) == "BM6"
+  end
+
+  def self.jpg?(file)
+    IO.read(file, 10) == "\377\330\377\340\000\020JFIF"
+  end
+
+  def self.png?(file)
+    IO.read(file, 4) == "\211PNG"
+  end
+
+  def self.gif?(file)
+    ['GIF89a', 'GIF97a'].include?(IO.read(file, 6))
+  end
+end

data/ptools.gemspec

@@ -0,0 +1,30 @@
+require 'rubygems'
+require 'rbconfig'
+
+Gem::Specification.new do |gem|
+  gem.name       = 'ptools'
+  gem.version    = '1.2.2'
+  gem.license    = 'Artistic 2.0'
+  gem.author     = 'Daniel J. Berger'
+  gem.email      = 'djberg96@gmail.com'
+  gem.homepage   = 'http://www.rubyforge.org/projects/shards'
+  gem.summary    = 'Extra methods for the File class'
+  gem.test_files = Dir['test/test*']
+  gem.files      = Dir['**/*'] << '.gemtest'
+
+  gem.rubyforge_project = 'shards'
+  gem.extra_rdoc_files  = ['README', 'CHANGES', 'MANIFEST']
+
+  gem.description = <<-EOF
+    The ptools (power tools) library provides several handy methods to
+    Ruby's core File class, such as File.which for finding executables,
+    File.null to return the null device on your platform, and so on.
+  EOF
+
+  gem.add_development_dependency('test-unit', '>= 2.4.0')
+
+  if File::ALT_SEPARATOR
+    gem.platform = Gem::Platform.new(['universal', 'mingw32'])
+    gem.add_dependency('win32-file', '>= 0.5.4')
+  end
+end

data/test/test_binary.rb

@@ -0,0 +1,47 @@
+#####################################################################
+# test_binary.rb
+#
+# Test case for the File.binary? method. You should run this test
+# via the 'rake test_binary' task.
+#####################################################################
+require 'rubygems'
+require 'test-unit'
+require 'ptools'
+
+class TC_Ptools_Binary < Test::Unit::TestCase
+  def self.startup
+    @@txt_file = 'test_binary.txt'
+
+    if File::ALT_SEPARATOR
+      @@bin_file = File.join(ENV['windir'], 'notepad.exe')
+    else
+      @@bin_file = '/bin/ls'
+    end
+
+    Dir.chdir('test') if File.exists?('test')
+
+    File.open(@@txt_file, 'w'){ |fh| 10.times{ |n| fh.puts "line #{n}" } }
+  end
+
+  test "File.binary? basic functionality" do
+    assert_respond_to(File, :binary?)
+    assert_nothing_raised{ File.binary?(@@txt_file) }
+  end
+
+  test "File.binary? returns expected results" do
+    assert_false(File.binary?(@@txt_file))
+    assert_true(File.binary?(@@bin_file))
+  end
+
+  test "File.binary? raises an error if the file cannot be found" do
+    assert_raise_kind_of(SystemCallError){ File.binary?('bogus') }
+  end
+
+  test "File.binary? only accepts one argument" do
+    assert_raise_kind_of(ArgumentError){ File.binary?(@@txt_file, @@bin_file) }
+  end
+
+  def self.shutdown
+    File.delete(@@txt_file) if File.exists?(@@txt_file)
+  end
+end

data/test/test_constants.rb

@@ -0,0 +1,38 @@
+#####################################################################
+# test_constants.rb
+#
+# Tests the constants that have been defined for our package. This
+# test case should be run via the 'rake test_constants' task.
+#####################################################################
+require 'rubygems'
+require 'test-unit'
+require 'rbconfig'
+require 'ptools'
+
+class TC_Ptools_Constants < Test::Unit::TestCase
+  def self.startup
+    @@windows = File::ALT_SEPARATOR
+  end
+
+  test "PTOOLS_VERSION constant is set to expected value" do
+    assert_equal('1.2.2', File::PTOOLS_VERSION)
+  end
+
+  test "IMAGE_EXT constant is set to array of values" do
+    assert_equal(%w[.bmp .gif .jpeg .jpg .png], File::IMAGE_EXT.sort)
+  end
+
+  test "WINDOWS constant is defined on MS Windows" do
+    omit_unless(@@windows, "Skipping on Unix systems")
+    assert_not_nil(File::MSWINDOWS)
+  end
+
+  test "WIN32EXTS constant is defiend on MS Windows" do
+    omit_unless(@@windows, "Skipping on Unix systems")
+    assert_not_nil(File::WIN32EXTS)
+  end
+
+  def self.shutdown
+    @@windows = nil
+  end
+end

data/test/test_head.rb

@@ -0,0 +1,51 @@
+######################################################################
+# test_head.rb
+# 
+# Test case for the File.head method. This test should be run via
+# the 'rake test_head' task.
+######################################################################
+require 'rubygems'
+gem 'test-unit'
+
+require 'test/unit'
+require 'ptools'
+
+class TC_FileHead < Test::Unit::TestCase
+   def self.startup
+      Dir.chdir('test') if File.exists?('test')
+      File.open('test_file1.txt', 'w'){ |fh| 25.times{ |n| fh.puts "line#{n+1}" } }
+   end
+   
+   def setup
+      @test_file = 'test_file1.txt'
+      @expected_head1 = ["line1\n","line2\n","line3\n","line4\n","line5\n"]
+      @expected_head1.push("line6\n","line7\n","line8\n","line9\n","line10\n")
+      @expected_head2 = ["line1\n","line2\n","line3\n","line4\n","line5\n"]
+   end
+
+   def test_head_basic
+      assert_respond_to(File, :head)
+      assert_nothing_raised{ File.head(@test_file) }
+      assert_nothing_raised{ File.head(@test_file, 5) }
+      assert_nothing_raised{ File.head(@test_file){} }
+   end
+
+   def test_head_expected_results
+      assert_kind_of(Array, File.head(@test_file))
+      assert_equal(@expected_head1, File.head(@test_file))
+      assert_equal(@expected_head2, File.head(@test_file, 5))
+   end
+
+   def test_head_expected_errors
+      assert_raises(ArgumentError){ File.head(@test_file, 5, "foo") }
+      assert_raises(Errno::ENOENT){ File.head("bogus") }
+   end
+
+   def teardown
+      @test_file = nil
+   end
+
+   def self.shutdown
+      File.delete('test_file1.txt') if File.exists?('test_file1.txt')
+   end
+end

data/test/test_image.rb

@@ -0,0 +1,43 @@
+#####################################################################
+# test_image.rb
+# 
+# Test case for the File.image? method. You should run this test
+# via the 'rake test_image' task.
+#####################################################################
+require 'rubygems'
+gem 'test-unit'
+
+require 'test/unit'
+require 'ptools'
+
+class TC_Ptools_Image < Test::Unit::TestCase
+   def self.startup
+      Dir.chdir('test') if File.exists?('test')
+      File.open('test_file1.txt', 'w'){ |fh| 25.times{ |n| fh.puts "line#{n+1}" } }
+   end
+   
+   def setup   
+      @text_file = 'test_file1.txt'
+   end
+
+   def test_image_basic
+      assert_respond_to(File, :image?)
+      assert_nothing_raised{ File.image?(@text_file) }
+   end
+
+   def test_image_expected_results
+      assert_equal(false, File.image?(@text_file))
+   end
+
+   def test_image_expected_errors
+      assert_raises(Errno::ENOENT, ArgumentError){ File.image?('bogus') }
+   end
+
+   def teardown
+      @text_file = nil
+   end
+
+   def self.shutdown
+      File.delete('test_file1.txt') if File.exists?('test_file1.txt')
+   end
+end

data/test/test_is_sparse.rb

@@ -0,0 +1,52 @@
+#####################################################################
+# test_is_sparse.rb
+#
+# Test case for the File.sparse? method. You should run this test
+# via the 'rake test:is_sparse' task.
+#####################################################################
+require 'rubygems'
+gem 'test-unit'
+
+require 'test/unit'
+require 'ptools'
+
+class TC_IsSparse < Test::Unit::TestCase
+  def self.startup
+    Dir.chdir("test") if File.exists?("test")
+    @@win = RbConfig::CONFIG['host_os'] =~ /windows|mswin|dos|cygwin|mingw/i
+    @@osx = RbConfig::CONFIG['host_os'] =~ /darwin|osx/i
+    @@sun = RbConfig::CONFIG['host_os'] =~ /sunos|solaris/i
+  end
+
+  def setup
+    @sparse_file = @@sun ? '/var/adm/lastlog' : '/var/log/lastlog'
+    @non_sparse_file = File.expand_path(File.basename(__FILE__))
+  end
+
+  test "is_sparse basic functionality" do
+    omit_if(@@win, "File.sparse? tests skipped on MS Windows")
+    omit_if(@@osx, "File.sparse? tests skipped on OS X")
+
+    assert_respond_to(File, :sparse?)
+    assert_nothing_raised{ File.sparse?(@sparse_file) }
+    assert_boolean(File.sparse?(@sparse_file))
+  end
+
+  test "is_sparse returns the expected results" do
+    omit_if(@@win, "File.sparse? tests skipped on MS Windows")
+    omit_if(@@osx, "File.sparse? tests skipped on OS X")
+
+    assert_true(File.sparse?(@sparse_file))
+    assert_false(File.sparse?(@non_sparse_file))
+  end
+
+  test "is_sparse only accepts one argument" do
+    omit_if(@@win, "File.sparse? tests skipped on MS Windows")
+    assert_raise(ArgumentError){ File.sparse?(@sparse_file, @sparse_file) }
+  end
+
+  def teardown
+    @sparse_file = nil
+    @non_sparse_file = nil
+  end
+end