facets 2.9.1 → 2.9.2

data/src/standard/facets/pathname.rb

@@ -0,0 +1,240 @@
+# = Pathname
+#
+# Ruby's standard Pathname class with extensions.
+#
+# == Authors:
+#
+# * Daniel Burger
+# * Thomas Sawyer
+#
+# == Copying
+#
+# Copyright (c) 2006 Thomas Sawyer, Daniel Burger
+#
+# Ruby License
+#
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.
+
+require 'pathname'
+require 'facets/file/rootname'
+require 'facets/fileutils/outofdate'
+
+class Pathname
+
+  # Alias #to_s to #to_str when #to_str is not defined.
+  #
+  alias_method(:to_str, :to_s) unless method_defined?(:to_str)
+
+  # Alternate to Pathname#new.
+  #
+  #   Pathname['/usr/share']
+  #
+  def self.[](path)
+    new(path)
+  end
+
+  # Start a path. Another alias for #new.
+  #
+  #   Pathname / 'usr'
+  #
+  def self./(path)
+    new(path)
+  end
+
+  # Root constant for building paths from root directory onward.
+  def self.root
+    Pathname.new('/')
+  end
+
+  # Home constant for building paths from root directory onward.
+  #
+  # TODO: Pathname#home needs to be more robust.
+  #
+  def self.home
+    Pathname.new('~')
+  end
+
+  # Work constant for building paths from root directory onward.
+  #
+  def self.work
+    Pathname.new('.')
+  end
+
+  # Platform dependent null device.
+  #
+  # CREDIT Daniel Burger
+  def self.null
+    case RUBY_PLATFORM
+    when /mswin/i
+      'NUL'
+    when /amiga/i
+      'NIL:'
+    when /openvms/i
+      'NL:'
+    else
+      '/dev/null'
+    end
+  end
+
+  # Try to get this into standard Pathname class.
+  alias_method :/, :+
+
+  #
+  def rootname
+    self.class.new(File.rootname(to_s))
+  end
+
+  #
+  def split_root
+    head, tail = *::File.split_root(to_s)
+    [self.class.new(head), self.class.new(tail)]
+  end
+
+  # Glob pathnames.
+  def glob(match, *opts)
+    flags = glob_flags(opts)
+    Dir.glob(::File.join(self.to_s, match), flags).collect{ |m| self.class.new(m) }
+  end
+
+  # Return the first glob match.
+  #
+  # DEPRECATE: While slightly faster then glob().first, not really worth it
+  # unless this can be rewritten to shortcut on first match (using fnmatch?).
+  # In wich case, is there a better name for this method?
+  def glob_first(match, *opts)
+    flags = glob_flags(opts)
+    file = ::Dir.glob(::File.join(self.to_s, match), flags).first
+    file ? self.class.new(file) : nil
+  end
+
+  # Return globbed matches with pathnames relative to the current pathname.
+  def glob_relative(match, *opts)
+    flags = glob_flags(opts)
+    files = Dir.glob(::File.join(self.to_s, match), flags)
+    files = files.map{ |f| f.sub(self.to_s.chomp('/') + '/', '') }
+    files.collect{ |m| self.class.new(m) }
+  end
+
+  private
+
+  def glob_flags(opts)
+    flags = 0
+    opts.each do |opt|
+      case opt when Symbol, String
+        flags += ::File.const_get("FNM_#{opt}".upcase)
+      else
+        flags += opt
+      end
+    end
+    flags
+  end
+
+  public
+
+  #
+  def empty?
+    Dir.glob(::File.join(to_s, '*')).empty?
+  end
+
+  #
+  def uptodate?(*sources)
+    ::FileUtils.uptodate?(to_s, sources.flatten)
+  end
+
+  #
+  def outofdate?(*sources)
+    ::FileUtils.outofdate?(to_s, sources.flatten)
+  end
+
+  # Recursively visit a directory located by its path, yielding each resource
+  # as its full matching pathname object. If called on a file, yield the file.
+  #
+  # call-seq:
+  #   visit => yield each file
+  #   visit(all: true) => yield visited directories as well
+  #   visit(hidden: true) => yield hidden files and directories as well
+  #
+  # Example use case:
+  #
+  #   # Locate any file but *.haml within app/**/*
+  #   Pathname.new("app").visit do |f|
+  #     next unless f.to_s =~ /\.haml$/
+  #     f
+  #   end 
+  #
+  # TODO: Use #map instead of #each ?
+  # 
+  # CREDIT: Jean-Denis Vauguet
+  def visit(options = {:all => false, :hidden => false})
+    if self.directory?
+      children.each do |entry|
+        next if entry.basename.to_s[0] == "." && !options[:hidden]
+        yield(entry) unless entry.directory? && !options[:all]
+        ##entry.visit(:all => options[:all]) { |sub_entry| yield sub_entry } if entry.directory?
+        entry.visit(:all => options[:all], :hidden => options[:hidden]) do |sub_entry|
+          yield(sub_entry)
+        end if entry.directory?
+      end
+    else
+      yield self
+    end
+  end
+
+##   # Already included in 1.8.4+ version of Ruby (except for inclusion flag)
+##   if not instance_methods.include?(:ascend)
+##
+##     # Calls the _block_ for every successive parent directory of the
+##     # directory path until the root (absolute path) or +.+ (relative path)
+##     # is reached.
+##     def ascend(inclusive=false,&block) # :yield:
+##       cur_dir = self
+##       yield( cur_dir.cleanpath ) if inclusive
+##       until cur_dir.root? or cur_dir == Pathname.new(".")
+##         cur_dir = cur_dir.parent
+##         yield cur_dir
+##       end
+##     end
+##
+##   end
+##
+##   # Already included in 1.8.4+ version of Ruby
+##   if ! instance_methods.include?(:descend)
+##
+##     # Calls the _block_ for every successive subdirectory of the
+##     # directory path from the root (absolute path) until +.+
+##     # (relative path) is reached.
+##     def descend()
+##       @path.scan(%r{[^/]*/?})[0...-1].inject('') do |path, dir|
+##         yield Pathname.new(path << dir)
+##       path
+##       end
+##     end
+##
+##   end
+
+  # Does a directory contain a matching entry?
+  # Or if the pathname is a file, same as #fnmatch.
+  def include?(pattern,*opts)
+    if directory?
+      glob_first(pattern,*opts)
+    else
+      fnmatch(pattern,*opts)
+    end
+  end
+
+end
+
+class NilClass
+  # Provide platform dependent null path.
+  #
+  # CREDIT Daniel Burger
+  def to_path
+    Pathname.null
+  end
+end
+

data/src/standard/facets/random.rb

@@ -0,0 +1,446 @@
+require 'facets/hash/zip'
+require 'facets/string/shatter'
+require 'facets/kernel/maybe'
+
+# = Randomization Extensions
+#
+# This library extends Array, String, Hash and other classes with randomization
+# methods. Most of the methods are of one of two kinds. Either they "pick" a
+# random element from the reciever or they randomly "shuffle" the reciever.
+#
+# The most common example is Array#shuffle, which simply randmomizes the
+# order of an array's elements.
+#
+#   [1,2,3].shuffle  #~> [2,3,1]
+#
+# The other methods do similar things for their respective classes.
+#
+# The classes are all extended via mixins which have been created within
+# Ruby's Random class.
+#
+# Credit for this work is due to:
+#
+# * Ilmari Heikkinen
+# * Christian Neukirchen
+# * Thomas Sawyer
+#
+# NOTE: Inline QED tests are almost pointless here b/c... yea, it's random.
+# So indtead of the usual `#=>` we use `#~>` which means approx. equal and
+# prevens QED from making a hard assertion.
+
+class Random
+
+  class << self
+    # Alias for Kernel#rand.
+    alias_method :number, :rand
+
+    public :number
+  end
+
+  ##def self.number(*args)
+  ##  ::Kernel.rand(*args)
+  ##end
+
+  # Module method to generate a random letter.
+  #
+  #   Random.letter  #~> "q"
+  #   Random.letter  #~> "r"
+  #   Random.letter  #~> "a"
+  #
+  def self.letter
+    (Random.number(26) + (Random.number(2) == 0 ? 65 : 97) ).chr
+  end
+
+  #
+  module RangeExtensions
+    # Return a random element from the range.
+    #
+    #   (1..4).at_rand           #~> 2
+    #   (1..4).at_rand           #~> 4
+    #
+    #   (1.5..2.5).at_rand       #~> 2.06309842754533
+    #   (1.5..2.5).at_rand       #~> 1.74976944931541
+    #
+    #   ('a'..'z').at_rand       #~> 'q'
+    #   ('a'..'z').at_rand       #~> 'f'
+    #
+    # CREDIT: Lavir the Whiolet, Thomas Sawyer
+    def at_rand
+      first, last = first(), last()
+      if first.respond_to?(:random_delta)  # TODO: work on this!!!
+        begin
+          first.random_delta(last, exclude_end?)
+        rescue
+          to_a.at_rand
+        end
+      else
+        to_a.at_rand
+      end
+      ##elsif first.respond_to?(:succ)
+      ##  # optimized algorithm
+      ##  if (Fixnum === first || Bignum === first) &&
+      ##     (Fixnum === last  || Bignum === last)
+      ##    last -= 1 if exclude_end?
+      ##    return nil if last < first
+      ##    return Random.number(last - first + 1) + first
+      ##  end
+      ##  # standard algorithm
+      ##  return to_a.at_rand
+      ##elsif Numeric === first && Numeric === last
+      ##  return nil if last < first
+      ##  return nil if exclude_end? && last == first
+      ##  return (last - first) * Random.number + first
+      ##else
+      ##  return nil
+      ##end
+    end
+  end
+
+  #
+  module IntegerExtensions
+    #
+    def random_delta(last, exclude_end)
+      first = self
+      last -= 1 if exclude_end
+      return nil if last < first
+      return Random.number(last - first + 1) + first
+    end
+  end
+
+  #
+  module NumericExtensions
+    #
+    def random_delta(last, exclude_end)
+      first = self
+      return nil if last < first
+      return nil if exclude_end && last == first
+      return (last - first) * Random.number + first
+    end
+  end
+
+  #
+  module ArrayExtensions
+    # Return a random element from the array.
+    #
+    #   [1, 2, 3, 4].at_rand           #~> 2
+    #   [1, 2, 3, 4].at_rand           #~> 4
+    #
+    def at_rand
+      at(Random.number(size))
+    end
+
+    # Same as #at_rand, but acts in place removing a
+    # random element from the array.
+    #
+    #   a = [1,2,3,4]
+    #   a.at_rand!       #~> 2
+    #   a                #~> [1,3,4]
+    #
+    def at_rand!
+      return delete_at( Random.number( size ) )
+    end
+
+    # Similar to #at_rand, but will return an array of randomly
+    # picked exclusive elements if given a number.
+    def pick(n=nil)
+      if n
+        a = self.dup
+        a.pick!(n)
+      else
+        at(Random.number(size))
+      end
+    end
+
+    # Similar to #at_rand!, but given a number will return
+    # an array of exclusive elements.
+    def pick!(n=nil)
+      if n
+        if n > self.size
+          r = self.dup
+          self.replace([])
+          r
+        else
+          r = []
+          n.times { r << delete_at(Random.number(size)) }
+          r
+        end
+      else
+        delete_at(Random.number(size))
+      end
+    end
+
+    # Random index.
+    #
+    def rand_index
+      Random.number(size)
+    end
+
+    # Returns a random subset of an Array. If a _number_
+    # of elements is specified then returns that number of
+    # elements, otherwise returns a random number of elements
+    # upto the size of the Array.
+    #
+    # By defualt the returned values are exclusive of
+    # each other, but if _exclusive_ is set to <tt>false</tt>,
+    # the same values can be choosen more than once.
+    #
+    # When _exclusive_ is <tt>true</tt> (the default) and the
+    # _number_ given is greater than the size of the array,
+    # then all values are returned.
+    #
+    #   [1, 2, 3, 4].rand_subset(1)        #~> [2]
+    #   [1, 2, 3, 4].rand_subset(4)        #~> [2, 1, 3, 4]
+    #   [1, 2, 3, 4].rand_subset           #~> [1, 3, 4]
+    #   [1, 2, 3, 4].rand_subset           #~> [2, 3]
+    #
+    def rand_subset( number=nil, exclusive=true )
+      number = Random.number(size) unless number
+      number = number.to_int
+      #return self.dup if (number >= size and exlusive)
+      return sort_by{rand}.slice(0,number) if exclusive
+      ri =[]; number.times { |n| ri << Random.number(size) }
+      return values_at(*ri)
+    end
+
+    # Randomize the order of an array.
+    #
+    #   [1,2,3,4].shuffle  #~> [2,4,1,3]
+    #
+    def shuffle
+      dup.shuffle!
+      #sort_by{Random.number}
+    end
+
+    # As with #shuffle but modifies the array in place.
+    # The algorithm used here is known as a Fisher-Yates shuffle.
+    #
+    #   a = [1,2,3,4]
+    #   a.shuffle!
+    #
+    #   a  #~> [2,4,1,3]
+    #
+    # CREDIT Niel Spring
+    def shuffle!
+      s = size
+      each_index do |j|
+        i = Random.number(s-j)
+        #self[j], self[j+i] = self[j+i], self[j]
+        tmp = self[j]
+        self[j] = self[j+i]
+        self[j+i] = tmp
+      end
+      self
+    end
+
+  end
+
+  #
+  module HashExtensions
+    # Returns a random key.
+    #
+    #   {:one => 1, :two => 2, :three => 3}.pick_key  #~> :three
+    #
+    def rand_key
+      keys.at(Random.number(keys.size))
+    end
+
+    # Delete a random key-value pair, returning the key.
+    #
+    #   a = {:one => 1, :two => 2, :three => 3}
+    #   a.rand_key!  #~> :two
+    #   a            #~> {:one => 1, :three => 3}
+    #
+    def rand_key!
+      k,v = rand_pair
+      delete(k)
+      return k
+    end
+
+    alias_method( :pick_key, :rand_key! )
+
+    # Returns a random key-value pair.
+    #
+    #   {:one => 1, :two => 2, :three => 3}.pick  #~> [:one, 1]
+    #
+    def rand_pair
+      k = rand_key
+      return k, fetch(k)
+    end
+
+    # Deletes a random key-value pair and returns that pair.
+    #
+    #   a = {:one => 1, :two => 2, :three => 3}
+    #   a.rand_pair!  #~> [:two, 2]
+    #   a             #~> {:one => 1, :three => 3}
+    #
+    def rand_pair!
+      k,v = rand_pair
+      delete( k )
+      return k,v
+    end
+
+    alias_method( :pick_pair, :rand_pair! )
+
+    # Returns a random hash value.
+    #
+    #   {:one => 1, :two => 2, :three => 3}.rand_value  #~> 2
+    #   {:one => 1, :two => 2, :three => 3}.rand_value  #~> 1
+    #
+    def rand_value
+      fetch(rand_key)
+    end
+
+    # Deletes a random key-value pair and returns the value.
+    #
+    #   a = {:one => 1, :two => 2, :three => 3}
+    #   a.at_rand!  #~> 2
+    #   a           #~> {:one => 1, :three => 3}
+    #
+    def rand_value!
+      k,v = rand_pair
+      delete( k )
+      return v
+    end
+
+    alias_method( :pick, :rand_value! )
+
+    alias_method( :at_rand, :rand_value )
+    alias_method( :at_rand!, :rand_value! )
+
+    # Returns a copy of the hash with _values_ arranged
+    # in new random order.
+    #
+    #   h = {:a=>1, :b=>2, :c=>3}
+    #   h.shuffle  #~> {:b=>2, :c=>1, :a>3}
+    #
+    def shuffle
+      ::Hash.zip( keys.sort_by{Random.number}, values.sort_by{Random.number} )
+    end
+
+    # Destructive shuffle_hash. Arrange the values in
+    # a new random order.
+    #
+    #   h = {:a => 1, :b => 2, :c => 3}
+    #   h.shuffle!
+    #   h  #~> {:b=>2, :c=>1, :a=>3}
+    #
+    def shuffle!
+      self.replace(shuffle)
+    end
+
+  end
+
+  #
+  module StringExtensions
+
+    #
+    def self.included(base)
+      base.extend(Self)
+    end
+
+    # Class-level methods.
+    module Self
+      # Returns a randomly generated string. One possible use is
+      # password initialization. Takes a max legnth of characters
+      # (default 8) and an optional valid char Regexp (default /\w\d/).
+      #
+      #   String.random    #~> 'dd4qed4r'
+      #
+      # CREDIT George Moschovitis
+      #--
+      # TODO: This is not very efficient. Better way?
+      #++
+      def random(max_length = 8, char_re = /[\w\d]/)
+        raise ArgumentError.new('char_re must be a regular expression!') unless char_re.is_a?(Regexp)
+        string = ""
+        while string.length < max_length
+            ch = Random.number(255).chr
+            string << ch if ch =~ char_re
+        end
+        return string
+      end
+    end
+
+    # Return a random separation of the string.
+    # Default separation is by charaacter.
+    #
+    #   "Ruby rules".at_rand(' ')  #~> ["Ruby"]
+    #
+    def at_rand( separator=// )
+      #separator = self.class.patterns( separator )
+      self.split(separator,-1).at_rand
+    end
+
+    # Return a random separation while removing it
+    # from the string. Default separation is by character.
+    #
+    #   s = "Ruby rules"
+    #   s.at_rand!(' ')    #~> "Ruby"
+    #   s                  #~> "rules"
+    #
+    def at_rand!( separator=// )
+      #separator = self.class.patterns( separator )
+      a = self.shatter( separator )
+      w = []; a.each_with_index { |s,i| i % 2 == 0 ? w << s : w.last << s }
+      i = Random.number(w.size)
+      r = w.delete_at( i )
+      self.replace( w.join('') )
+      return r
+    end
+
+    # Return a random byte of _self_.
+    #
+    #   "Ruby rules".rand_byte  #~> 121
+    #
+    def rand_byte
+      self[Random.number(size)]
+    end
+
+    # Destructive rand_byte. Delete a random byte of _self_ and return it.
+    #
+    #   s = "Ruby rules"
+    #   s.rand_byte!      #~> 121
+    #   s                 #~> "Rub rules"
+    #
+    def rand_byte!
+      i = Random.number(size)
+      rv = self[i,1]
+      self[i,1] = ''
+      rv
+    end
+
+    # Return a random string index.
+    #
+    #   "Ruby rules".rand_index  #~> 3
+    #
+    def rand_index
+      Random.number(size)
+    end
+
+    # Return the string with seperated sections arranged
+    # in a random order. The default seperation is by character.
+    #
+    #   "Ruby rules".shuffle  #~> "e lybRsuur"
+    #
+    def shuffle(separator=//)
+      split(separator).shuffle.join('')
+    end
+
+    # In place version of shuffle.
+    #
+    def shuffle!(separator=//)
+      self.replace( shuffle(separator) )
+    end
+
+  end
+
+end
+
+class Range   ; include Random::RangeExtensions   ; end
+class Array   ; include Random::ArrayExtensions   ; end
+class Hash    ; include Random::HashExtensions    ; end
+class String  ; include Random::StringExtensions  ; end
+class Integer ; include Random::IntegerExtensions ; end
+class Numeric ; include Random::NumericExtensions ; end
+
+# Copyright (c) 2005 Ilmari Heikkinen, Christian Neukirchen, Thomas Sawyer