facets 3.0.0 → 3.2.0

data/lib/standard/facets/cgi/escape_html.rb

@@ -2,26 +2,25 @@ require 'cgi'
 
 class CGI
 
-  # Extends `#escape_html` to support escape modes. By default all strings
-  # are escaped on `&`, `>` and `<`. Add the `:nonstandard` mode to omit
-  # this conversion.
+  # Extended HTML/XHTML escaping with mode support. Unlike Ruby's built-in
+  # `CGI.escape_html`, this supports additional escape modes.
   #
-  # If no mode is given then the `:default` mode is used.
-  #
-  # Available modes include:
+  # Available modes:
   # * `:quote`     - escapes single and double quotes
   # * `:newlines`  - escapes newline characters (\r and \n)
   # * `:ampersand` - escapes the ampersand sign
   # * `:brackets`  - escapes less-than and greater-than signs
   # * `:default`   - escapes double quotes
   #
+  # By default all strings are escaped on `&`, `>`, `<` and `"`.
+  #
   # @example
-  #   escape_html("<tag>")  #=> "&lt;tag&gt;"
-  #   escape_html("Example\nString", :newlines)  #=> "Example&#13;&#10;String"
-  #   escape_html("\"QUOTE\"", false)  #=> "\"QUOTE\""
+  #   CGI.escape_xhtml("<tag>")  #=> "&lt;tag&gt;"
+  #   CGI.escape_xhtml("Example\nString", :newlines)  #=> "Example&#13;&#10;String"
+  #   CGI.escape_xhtml("\"QUOTE\"", false)  #=> "\"QUOTE\""
   #
-  def self.escape_html(string, *modes)
-    modes << :defualt if modes.empty?
+  def self.escape_xhtml(string, *modes)
+    modes << :default if modes.empty?
 
     unless modes.include?(:nonstandard)
       string = string.gsub(/&/, '&amp;').gsub(/>/, '&gt;').gsub(/</, '&lt;')
@@ -32,7 +31,7 @@ class CGI
         case mode
         when :quote, :quotes
           string.gsub(%r|"|,'&quot;').gsub(%r|'|,'&#39;')
-        when :newlines, :newlines
+        when :newlines
           string.gsub(/[\r\n]+/,'&#13;&#10;')
         when :ampersand
           string.gsub(/&/, '&amp;')
@@ -41,23 +40,13 @@ class CGI
         when :default, true
           string.gsub(/\"/, '&quot;')
         when false
+          string
         else
-          raise ArgumentError, "unrecognized HTML escape mode -- #{node}"
+          raise ArgumentError, "unrecognized HTML escape mode -- #{mode}"
         end
     end
-  end
 
-  class << self
-    # @deprecated
-    alias :escapeHTML :escape_html
-  end
-
-  if RUBY_VERSION < '1.9'
-    class << self
-      alias :unescape_html :unescapeHTML
-      alias :escape_element :escapeElement
-      alias :unescape_element :unescapeElement
-    end
+    string
   end
 
 end

data/lib/standard/facets/cloneable.rb

@@ -1,67 +1,20 @@
-# Clonable provides a standard basis for adding deep cloneablity to a class
-# via the standard #dup and #clone methods.
-#
-# Cloneable was originally ported from Jim Weirich's Rake.
-# The current version is the work of Ken Bloom.
-#
-# DEPRECATED: A better approach is to provide a #deep_dup and and a #deep_clone,
-# then if a class needs these for #dup and #clone they can just alias them.
-#
-# CREDIT: Ken Bloom
+# @deprecated Use deep_dup/deep_clone instead, or define your own
+#   initialize_copy method.
+warn "facets/cloneable is deprecated. Use deep_dup/deep_clone instead.", uplevel: 1
 
 module Cloneable
 
   def initialize_copy(sibling)
-    # First duplicate my superclass' state. Note that if it's duplicating
-    # instance variables, this will be overwritten, but this is important
-    # because we could be dealing with a C extension with state hidden from
-    # the Ruby interpreter.
     super
-
-    # We want to know if we're being dup'ed or clone'd, because we want to
-    # preserve the state of our internals the same way our state is being
-    # preserved. (If we can't figure it out, we'll just use #dup.)
     operation = (
       copy_call  = caller.find{|x| x !~ /'initialize_copy'/}
       copy_match = copy_call.match(/`(dup|clone)'/)
       copy_match ? copy_match[1] : :dup
     )
-
     sibling.instance_variables.each do |ivar|
       value = sibling.instance_variable_get(ivar)
-
-      # Set my instance variable to be a #dup or #clone
-      # or my sibling, depending on what's happening to me right now.
       instance_variable_set(ivar, value.send(operation))
     end
   end
 
-  # TODO: Is there a more robust means of determining if clone or dup is used?
-  #def clone
-  #  @_copy_operation = :clone
-  #  super
-  #end
-  #
-  #def dup
-  #  @_copy_operation = :dup
-  #  super
-  #end
-
-end 
-
-
-
-# OLD VERSION
-
-#module Cloneable
-#  def clone
-#    sibling = self.class.new
-#    instance_variables.each do |ivar|
-#      value = self.instance_variable_get(ivar)
-#      sibling.instance_variable_set(ivar, value.dup) #rake_dup)
-#    end
-#    sibling
-#  end
-#  alias_method :dup, :clone
-#end
-
+end

data/lib/standard/facets/continuation.rb

@@ -1,56 +1,2 @@
-if defined?(Continuation)
-
-  # = Continuation Extension
-  #
-  # Creates a continuation in a way that is easier to use than callcc.
-  # On the initial call this will return the created Continuation and
-  # the arguments you gave to Continuation.create in an Array. If you
-  # then issue .call() on the Continuation execution will jump back to
-  # the point of time where you initially invoked Continuation.create,
-  # but this time it will return the Continuation and the arguments
-  # you supplied in an Array.
-  #
-  # You can supply a block instead of default arguments which will
-  # cause that block to be executed once and its result to be returned
-  # along side the created Continuation, but this form is confusing
-  # and does only rarely make sense.
-  #
-  #   # Count from 0 to 10
-  #   cc, counter = Continuation.create(0)
-  #   counter   #~> 0..10
-  #   cc.call(counter + 1) if counter < 10
-  #
-  #   # Implement something similar to Array#inject using Continuations.
-  #   # For simplicity's sake, this is not fully compatible with the real
-  #   # inject. Make sure that you understand Array#inject before you try
-  #   # to understand this.
-  #   class ::Array
-  #     def cc_inject(value = nil)
-  #       copy = self.clone
-  #       cc, result, item = Continuation.create(value, nil)
-  #       next_item = copy.shift
-  #       if result and item
-  #         # Aggregate the result using the block.
-  #         cc.call(yield(result, item), next_item)
-  #       elsif next_item
-  #         # item not yet set and Array is not empty:
-  #         # This means we did not get a value and thus need to use the
-  #         # first item from the Array before we can start using the
-  #         # block to aggregate the result.
-  #         cc.call(next_item, result)
-  #       end
-  #
-  #       return result
-  #    end
-  #  end
-  #  [1,2,3,4,5].cc_inject { |acc, n| acc + n } # => 15
-  #
-  def Continuation.create(*args, &block)
-    args = [args] if not args.nil? and not args.is_a? Array # 1.6.8 compatibility
-    cc = nil; result = callcc {|c| cc = c; block.call(cc) if block and args.empty?}
-    result ||= args
-    return *[cc, *result]
-  end
-
-end
-
+# @deprecated callcc is obsolete in Ruby. Use Fiber instead.
+warn "facets/continuation is deprecated. callcc is obsolete; use Fiber instead.", uplevel: 1

data/lib/standard/facets/crypt3.rb

@@ -0,0 +1,126 @@
+# Crypt3 is a pure Ruby version of crypt(3), a salted one-way hashing
+# of a password.
+#
+# Supported hashing algorithms are: md5, sha1, sha256, sha384, sha512, rmd160.
+#
+# Only the md5 hashing algorithm is standard and compatible with crypt(3),
+# the others are not standard.
+#
+# Originally written by Poul-Henning Kamp (Beer-Ware License).
+# Adapted by guillaume.pierronnet based on FreeBSD src/lib/libcrypt/crypt.c
+#
+# Copyright (c) 2002 Poul-Henning Kamp
+# License: BSD-2-Clause
+
+module Crypt3
+
+  VERSION = '1.2.0'
+
+  # Base 64 character set.
+  ITOA64 = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+  # A pure ruby version of crypt(3), a salted one-way hashing of a password.
+  #
+  # Automatically generates an 8-byte salt if none given.
+  #
+  #   Crypt3.crypt('password')           #=> "$1$xxxxxxxx$hash..."
+  #   Crypt3.crypt('password', :sha256)  #=> "$1$xxxxxxxx$hash..."
+  #
+  # password - The phrase to encrypt. [String]
+  # algo     - The algorithm to use. [Symbol]
+  # salt     - Cryptographic salt, random if nil. [String]
+  # magic    - The magic prefix. [String]
+  #
+  # Returns the cryptographic hash. [String]
+  def self.crypt(password, algo = :md5, salt = nil, magic = '$1$')
+    salt ||= generate_salt(8)
+
+    case algo
+    when :md5
+      require "digest/md5"
+    when :sha1
+      require "digest/sha1"
+    when :rmd160
+      require "digest/rmd160"
+    when :sha256, :sha384, :sha512
+      require "digest/sha2"
+    else
+      raise(ArgumentError, "unknown algorithm: #{algo}")
+    end
+
+    digest_class = Digest.const_get(algo.to_s.upcase)
+
+    m = digest_class.new
+    m.update(password + magic + salt)
+
+    mixin = digest_class.new.update(password + salt + password).digest
+    password.length.times do |i|
+      m.update(mixin[i % 16].chr)
+    end
+
+    i = password.length
+    while i != 0
+      if (i & 1) != 0
+        m.update("\x00")
+      else
+        m.update(password[0].chr)
+      end
+      i >>= 1
+    end
+
+    final = m.digest
+
+    1000.times do |i|
+      m2 = digest_class.new
+      m2.update((i & 1) != 0 ? password : final)
+      m2.update(salt) if (i % 3) != 0
+      m2.update(password) if (i % 7) != 0
+      m2.update((i & 1) != 0 ? final : password)
+      final = m2.digest
+    end
+
+    rearranged = ""
+    [[0, 6, 12], [1, 7, 13], [2, 8, 14], [3, 9, 15], [4, 10, 5]].each do |a, b, c|
+      v = final.getbyte(a) << 16 | final.getbyte(b) << 8 | final.getbyte(c)
+      4.times do
+        rearranged += ITOA64[v & 0x3f]
+        v >>= 6
+      end
+    end
+
+    v = final.getbyte(11)
+    2.times do
+      rearranged += ITOA64[v & 0x3f]
+      v >>= 6
+    end
+
+    magic + salt + '$' + rearranged
+  end
+
+  # Check the validity of a password against a hashed string.
+  #
+  #   Crypt3.check('password', '$1$xxxxxxxx$hash...')  #=> true
+  #
+  # password - The phrase that was encrypted. [String]
+  # hash     - The cryptographic hash. [String]
+  # algo     - The algorithm used. [Symbol]
+  #
+  # Returns true if valid. [Boolean]
+  def self.check(password, hash, algo = :md5)
+    magic, salt = hash.split('$')[1, 2]
+    magic = '$' + magic + '$'
+    self.crypt(password, algo, salt, magic) == hash
+  end
+
+  # Generate a random salt of the given size.
+  #
+  #   Crypt3.generate_salt(8)  #=> "xK3d9Wq2"
+  #
+  # size - The size of the salt. [Integer]
+  #
+  # Returns random salt. [String]
+  def self.generate_salt(size)
+    (1..size).map { ITOA64[rand(ITOA64.size)] }.join
+  end
+
+end

data/lib/standard/facets/date/cmp.rb

@@ -0,0 +1,32 @@
+
+require 'date'
+
+class Time
+	alias_method :old_compare, :<=>
+	private :old_compare
+	
+	# Allow for Date <=> DateTime <=> Time, to work as expected.
+	
+	def <=>(other)
+		if Date === other or DateTime === other
+			self.to_datetime <=> other
+		else
+			old_compare(other)
+		end
+	end
+end
+
+class Date
+	alias_method :old_compare, :<=>
+	private :old_compare
+	
+	# Allow for Date <=> DateTime <=> Time, to work as expected.
+	
+	def <=>(other)
+		if Time === other
+			self.to_datetime <=> other.to_datetime
+		else
+			old_compare(other)
+		end
+	end
+end

data/lib/standard/facets/date.rb

@@ -1,5 +1,6 @@
 require 'date'
 require 'facets/time/stamp'
+require 'facets/date/cmp'
 
 # = Date
 #

data/lib/standard/facets/digest.rb

@@ -1,2 +1 @@
-require 'facets/digest/base64digest'
 require 'facets/digest/salted_digest'

data/lib/standard/facets/enumargs.rb

@@ -51,6 +51,11 @@ module Enumerable
           end
         }
       else
+        # this branch is used when the method has a variable number of arguments
+        #   resulting in an arity of -1.  Right now this is bugged as it does
+        #   not pass the argument to the each, and always passes the argument
+        #   to the method.  This makes methods like .min amdn .max to act
+        #   in an unexpected manner.
         class_eval %{
           def #{m}( *args, &yld )
             enum_for(:each).#{m}( *args, &yld )

data/lib/standard/facets/fileutils/cp_rx.rb

@@ -14,7 +14,6 @@ module FileUtils
   # subdirectory is automatically skipped as well.
 
   def cp_rx(src, dest, options = {}, &filter)
-	  fu_check_options(options, OPT_TABLE['cp_r'])
     if options[:verbose]
 	    fu_output_message("cp -r#{options[:preserve] ? 'p' : ''}#{options[:remove_destination] ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}")
     end
@@ -41,4 +40,3 @@ module FileUtils
   end
 
 end
-

data/lib/standard/facets/fileutils/ln_r.rb

@@ -27,7 +27,6 @@ module FileUtils
     #
     # TODO: Why --remove-destination and not just --force?
     def ln_r(src, dest, options = {})
-      fu_check_options options, OPT_TABLE['ln_r']
       fu_output_message "ln -r#{options[:remove_destination] ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
       return if options[:noop]
       options = options.dup

data/lib/standard/facets/find/select.rb

@@ -1,5 +1,3 @@
-require 'facets/enumerator'
-
 module Find
   # Identical to find except select returns the matching files as an array.
   # (find returns nil, which is not very useful if you actually wanted an array.)

data/lib/standard/facets/getoptlong.rb

@@ -1,59 +1,3 @@
-require 'getoptlong'
-
-# = GetoptLong
-#
-# Ruby's standard GetoptLong class with an added DSL.
-#
-#   opts = GetoptLong.new do
-#     reqs '--expect', '-x'
-#     flag '--help', '-h'
-#   end
-#
-# See GetoptLong::DSL for details.
-
-class GetoptLong
-
-  alias :init :initialize
-
-  #
-  def initialize(*arguments, &block)
-    if block_given?
-      raise ArgumentError unless arguments.empty?
-      arguments = DSL.new(&block).arguments
-    end
-    init(*arguments)
-  end
-
-  # DSL-mode parser.
-  class DSL
-    attr :arguments
-
-    def initialize(&block)
-      @arguments = []
-      instance_eval(&block)
-    end
-
-    #
-    def flag(*opts)
-      @arguments << (opts << GetoptLong::NO_ARGUMENT)
-    end
-
-    #
-    def required(*opts)
-      @arguments << (opts <<  GetoptLong::REQUIRED_ARGUMENT)
-    end
-
-    #
-    alias :reqs :required
-
-    #
-    def optional(*opts)
-      @arguments << (opts << GetoptLong::OPTIONAL_ARGUMENT)
-    end
-
-    #
-    alias :opts :optional
-  end
-
-end
-
+# @deprecated GetoptLong is a bundled gem heading for removal.
+#   Consider using OptionParser or a modern CLI library instead.
+warn "facets/getoptlong is deprecated. Consider OptionParser instead.", uplevel: 1

data/lib/standard/facets/load_monitor.rb

@@ -1,26 +1,2 @@
-module ::Kernel
-  class << self
-    alias_method :require_without_monitor, :require
-    alias_method :load_without_monitor, :load
-  end
-
-  alias_method :require_without_monitor, :require
-  alias_method :load_without_monitor, :load
-
-  # Require script and print what is being require.
-  def require(file)
-    $stderr.puts "monitor require: #{file}\n#{caller.inspect}\n\n"
-    require_without_monitor(file)
-  end
-
-  module_function :require
-
-  # Load script and print what is being loaded.
-  def load(file, wrap=false)
-    $stderr.puts "monitor load: #{file}\n#{caller.inspect}\n\n"
-    load_without_monitor(file, wrap)
-  end
-
-  module_function :load
-end
-
+# @deprecated Monkey-patching require/load globally is dangerous.
+warn "facets/load_monitor is deprecated. It monkey-patches require/load globally.", uplevel: 1

data/lib/standard/facets/math/gini_coefficient.rb

@@ -1,4 +1,5 @@
 require 'facets/math/approx_equal'
+require 'facets/math/mean'
 
 module Math
 
@@ -13,11 +14,11 @@ module Math
   #   GC = \frac{\sum_{i=1}^N (2i-N-1)x_i}{N^2-\bar{x}}
   #
   def self.gini_coefficient(array)
-    return -1 if size <= 0 or any? { |x| x < 0 }
-    return 0 if size < 2 or all? { |x| approx_equal(x,0) }
+    return -1 if array.size <= 0 or array.any? { |x| x < 0 }
+    return 0 if array.size < 2 or array.all? { |x| approx_equal(x,0) }
     s = 0
-    sort.each_with_index { |li,i| s += (2*i+1-size)*li }
-    s.to_f/(size**2*mean).to_f
+    array.sort.each_with_index { |li,i| s += (2*i+1-array.size)*li }
+    s.to_f/(array.size**2*mean(array)).to_f
   end
 
   ## OLD WAY

data/lib/standard/facets/math/kldivergence.rb

@@ -1,19 +1,20 @@
 module Math
 
-  # The Kullback-Leibler divergence from this array to that of +q+.
+  # The Kullback-Leibler divergence from distribution +p+ to distribution +q+.
+  #
+  # Both arrays must be the same size and represent probability distributions
+  # (values should be positive).
   #
   # NB: You will possibly want to sort both P and Q before calling this
   # depending on what you're actually trying to measure.
   #
   # http://en.wikipedia.org/wiki/Kullback-Leibler_divergence
   #
-  def self.kldivergence(array, q)
-    fail "Buggy."
-    fail "Cannot compare differently sized arrays." unless size = q.size
-    kld = 0
-    each_with_index { |pi,i| kld += pi*Math::log(pi.to_f/q[i].to_f) }
+  def self.kldivergence(p, q)
+    raise ArgumentError, "Cannot compare differently sized arrays." unless p.size == q.size
+    kld = 0.0
+    p.each_with_index { |pi, i| kld += pi * Math.log(pi.to_f / q[i].to_f) }
     kld
   end
 
 end
-

data/lib/standard/facets/math/percentile.rb

@@ -5,7 +5,7 @@ module Math
   # +pcnt+ should be expressed as an integer, e.g. `percentile(90)` returns
   # the 90th percentile of the array.
   #
-  # Algorithm from NIST[http://www.itl.nist.gov/div898/handbook/prc/section2/prc252.htm]
+  # Algorithm from NIST[http://www.itl.nist.gov/div898/handbook/prc/section2/prc262.htm]
   #
   # NOTE: This is not a common core extension and is not
   # loaded automatically when using <code>require 'facets'</code>.
@@ -13,7 +13,7 @@ module Math
   # CREDIT: Ben Koski
   #
   # @non-core
-  #   require 'facets/array/precentile'
+  #   require 'facets/math/percentile'
   #
   def self.percentile(array, pcnt)
     sorted_array = array.sort

data/lib/standard/facets/multiton.rb

@@ -76,7 +76,7 @@
 #
 # Copyright (c) 2007 Christoph Rippel, Thomas Sawyer
 #
-# Ruby License
+# Ruby License / BSD-2 License
 #
 # This module is free software. You may use, modify, and/or redistribute this
 # software under the same terms as Ruby.

data/lib/standard/facets/net/http.rb

@@ -2,13 +2,17 @@ require 'net/http'
 
 module Net
 
+  # Returns a response object for the given URL or raises
+  # an exception with the appropriate error status code if unable to
+  # complete the request
+  #
+  #   Net.download('http://example.com/')
+  #   Net.download('http://example.com/', 2) # fail after 2 redirects
+  #
   # CREDIT: Daniel Huckstep
-  def self.download(url, limit=10)
-    raise ArgumentError, 'HTTP redirect too deep' if limit == 0
-    #url = URI.parse(url)
-    #req = Net::HTTP::Get.new(url.path)
-    #req['User-Agent'] = "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.0.7) Gecko/2009030422 Ubuntu/8.10 (intrepid) Firefox/3.0.7"
-    #resp = Net::HTTP.new(url.host, url.port).start { |http| http.request(req) }
+  def self.download(url, limit = nil)
+    limit ||= 10
+    raise ArgumentError, 'HTTP redirect too deep' if limit.zero?
     resp = Net::HTTP.get_response(URI.parse(url))
     case resp
     when Net::HTTPSuccess     then resp
@@ -17,16 +21,31 @@ module Net
     end
   end
 
+  # Downloads a given URL and saves it to disk at the specified path.
+  # If path is not provided or nil, then the last segment in the path of
+  # the URL is used as the file name.
+  #
+  # Takes a third parameters as a hash of options:
+  # * <tt>limit</tt> - passed to Net.download to limit number of redirects
+  # * <tt>mode</tt>, <tt>:open_args<tt>, etc - passed to File.write to save the file.
+  #   For details on those options, see File.write
+  #
+  #   # Saves robots.txt to PWD as robots.txt
+  #   Net.download_and_save('http://example.com/robots.txt')
+  #
+  #   # Saves robots.txt to PWD as example.txt
+  #   Net.download_and_save('http://example.com/robots.txt', 'example.txt')
+  #
+  #   # Saves robots.txt to PWD as robots.txt, and writes the result as binary
+  #   Net.download_and_save('http://example.com/robots.txt', nil, mode: 'wb')
+  #
   # CREDIT: Daniel Huckstep
-  def self.download_and_save(url, path=nil)
-    if path.nil?
-      path = File.expand_path(url.split('/').last)
-    else
-      path = File.expand_path(path)
-    end
+  def self.download_and_save(url, path = nil, options = {})
+    opts = options.dup
+    path = File.expand_path(path || url.split('/').last)
     raise ArgumentError.new('Save path is a directory') if File.directory?(path)
-    resp = download(url)
-    open(path,'w') { |file| file.write(resp.body) } if resp.is_a?(Net::HTTPSuccess)
+    resp = download(url, opts.delete(:limit))
+    File.write(path, resp.body, opts) if resp.is_a?(Net::HTTPSuccess)
   end
 end