facets 2.8.4 → 2.9.0.pre.1

data/lib/more/facets/tuple.rb

@@ -1,3 +1,5 @@
+require 'facets/multiton'
+
 # = Tuple
 #
 # Tuple is essentially an Array, but Comaparable and Immutable.
@@ -11,69 +13,25 @@
 #   t1 = Tuple[1,2,3]
 #   t2 = Tuple[2,3,4]
 #
-#   t1 < t2   #=> true
-#   t1 > t2   #=> false
+#   (t1 < t2)   #=> true
+#   (t1 > t2)   #=> false
 #
 #   t1 = '1.2.3'.to_t
 #   t2 = '1-2-3'.to_t
 #
-#   puts t1  #=> 1.2.3
-#   puts t2  #=> 1-2-3
+#   t1.to_s  #=> "1.2.3"
+#   t2.to_s  #=> "1.2.3"
 #
-#   t1 == t2  #=> true
+#   (t1 == t2)  #=> true
 #
 # Keep in mind that Tuple[1,2,3] is not the same as Tuple['1','2','3'].
 #
-# == Todo
-#
-# * The #hash method needs a touch-up.
-#
-# * There are a few more methods yet to borrow from Array.
-#   Consider how #+, #-, etc. ought to work.
-#
-# == Author
-#
-# * Thomas Sawyer
-#
-# == Copying
-#
-# Copyright (c) 2005 Thomas Sawyer
-#
-# 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 'facets/multiton'
-
-# = Tuple
+#--
+# TODO: The #hash method needs a touch-up.
 #
-# A tuple can be made using #new or #[] just as one builds an array,
-# or using the #to_t method on a string or array. With a string tuple
-# remembers the first non-alphanumeric character as the tuple divider.
-#
-# == Usage
-#
-#   t1 = Tuple[1,2,3]
-#   t2 = Tuple[2,3,4]
-#
-#   t1 < t2   #=> true
-#   t1 > t2   #=> false
-#
-#   t1 = '1.2.3'.to_t
-#   t2 = '1-2-3'.to_t
-#
-#   puts t1  #=> 1.2.3
-#   puts t2  #=> 1-2-3
-#
-#   t1 == t2  #=> true
-#
-# Keep in mind that Tuple[1,2,3] is not the same as Tuple['1','2','3'].
-
+# TODO: There are a few more methods yet to borrow from Array.
+# Consider how #+, #-, etc. ought to work.
+#++
 class Tuple
 
   include ::Multiton
@@ -102,16 +60,16 @@ class Tuple
       @values = arg.to_ary
     end
     @default = default
-    @divider = '.'
+    ##@divider = '.'
   end
 
   attr_accessor :default
 
-  def divider( set=nil )
-    return @divider unless set
-    @divider = set
-    self
-  end
+  ##def divider( set=nil )
+  ##  return @divider unless set
+  ##  @divider = set
+  ##  self
+  ##end
 
 protected
 
@@ -119,6 +77,8 @@ protected
 
 public
 
+  SEGMENT_SEPARATOR = '.'
+
   def inspect() to_a.inspect end
 
   def to_t()     self end
@@ -127,8 +87,8 @@ public
   def to_a()   Array(@values) end
   def to_ary() Array(@values) end
 
-  def to_s( divider=nil )
-    @values.join(divider||@divider)
+  def to_s(divider=nil)
+    @values.join(divider || SEGMENT_SEPARATOR)
   end
 
   def size()   @values.size end
@@ -184,9 +144,10 @@ public
   # very same tuple.
   def eql?( other )
     return true if object_id == other.object_id
-    #return true if values.eql? other.values
+    ##return true if values.eql? other.values
   end
 
+  #
   def <=>( other )
     other = other.to_t
     [size, other.size].max.times do |i|
@@ -214,8 +175,8 @@ public
 
   # Unique hash value.
   def hash
-    # TODO This needs to take into account the default
-    #      and maybe the divider too.
+    # TODO: This needs to take into account the default
+    # and maybe the divider too.
     to_a.hash
   end
 
@@ -223,6 +184,7 @@ public
 
   class << self
 
+    #
     def []( *args )
       instance( args )
     end
@@ -240,7 +202,6 @@ public
     #   Tuple.cast_from_string('1.2.3a'){ |v| v.upcase }  #=> ["1","2","3A"]
     #
     # This method is called by String#to_t.
-
     def cast_from_string( str, &yld )
       args = str.to_s.split(/\W+/)
       div = /\W+/.match( str.to_s )[0]
@@ -249,22 +210,21 @@ public
       else
         args = args.collect { |i| /^[0-9]+$/ =~ i ? i.to_i : i }
       end
-      self.instance( args ).divider( div )
+      self.instance(args) #.divider( div )
     end
 
     #
-
     def cast_from_array( arr )
       self.instance( arr )
     end
 
     # Parses a constraint returning the operation as a lambda.
-
     def constraint_to_lambda( constraint, &yld )
       op, val = *parse_constraint( constraint, &yld )
       lambda { |t| t.send(op, val) }
     end
 
+    #
     def parse_constraint( constraint, &yld )
       constraint = constraint.strip
       re = %r{^(=~|~>|<=|>=|==|=|<|>)?\s*(\d+(:?[-.]\d+)*)$}
@@ -288,8 +248,6 @@ public
 end
 
 
-# Conveniently turn a string into a tuple.
-
 class ::String
 
   # Translates a string in the form on a set of numerical and/or
@@ -305,7 +263,6 @@ class ::String
   #   '1.2.3a'.to_t { |v| v.upcase }  #=> ["1","2","3A"]
   #
   # This method calls Tuple.cast_from_string.
-
   def to_t( &yld )
     Tuple.cast_from_string( self, &yld )
   end
@@ -313,13 +270,13 @@ class ::String
 end
 
 
-# Convert and array into a tuple.
-
 class ::Array
 
+  # Convert an array into a tuple.
   def to_t
     Tuple.cast_from_array( self )
   end
 
 end
 
+# Copyright (c) 2005 Thomas Sawyer (Ruby License)

data/lib/more/facets/uri.rb

@@ -1,57 +1,33 @@
-# = URI Extensions
-#
-# Convenience extensions to URI module.
-#
-# == Authors
-#
-# * Thomas Sawyer (7rans)
-#
-# == Copyright
-#
-# Copyright (c) 2005 Thomas Sawyer
-#
-# 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 'uri'
 #require 'cgi'
-
-require 'facets/blank'
+require 'facets/kernel/blank'
 
 module URI
 
   module_function
 
   # Decode the uri components.
-
+  #
   def decode(uri)
-    # gmosx: hmm is this needed?
-    # guard against invalid filenames for example pictures with
-    # spaces uploaded by users
+    ## gmosx: hmm is this needed?
+    ## guard against invalid filenames for example pictures with
+    ## spaces uploaded by users
     escaped_uri = uri.gsub(/ /, "+")
 
     if md = URI::REGEXP::REL_URI.match(escaped_uri)
-
       path = "#{md[5]}#{md[6]}"
       type = File.extname(path)
       query_string = md[7]
 
-#      real_path = "#{$root_dir}/#{path}"
+      ## real_path = "#{$root_dir}/#{path}"
 
       parameters = URI.query_to_hash(query_string)
       path.gsub!(/\+/, " ")
 
       return [path, type, parameters, query_string]
+    end
 
-    end # match
-
-    # this is usefull for uncovering bugs!
+    ## this is usefull for uncovering bugs!
     raise ArgumentError.new("the parameter '#{uri}' is not a valid uri")
   end
 
@@ -59,25 +35,21 @@ module URI
   # converts single valued params (the most common case) to
   # objects instead of arrays
   #
-  # Input:
-  # the query string
+  # Returns hash of parameters, contains arrays for multivalued parameters
+  # (multiselect, checkboxes , etc).
   #
-  # Output:
-  # hash of parameters, contains arrays for multivalued parameters
-  # (multiselect, checkboxes , etc)
   # If no query string is provided (nil or "") returns an empty hash.
-
   def query_to_hash(query_string)
     return {} unless query_string
 
     query_parameters = cgi_parse(query_string)
 
     query_parameters.each { |key, val|
-      # replace the array with an object
+      ## replace the array with an object
       query_parameters[key] = val[0] if 1 == val.length
     }
 
-    # set default value to nil! cgi sets this to []
+    ## set default value to nil! cgi sets this to []
     query_parameters.default = nil
 
     return query_parameters
@@ -85,27 +57,29 @@ module URI
 
   alias_method :query_string_to_hash, :query_to_hash
 
+  #
+  KEY_VALUE_SEPARATOR = ";"  # "&"
+
   # Given a hash with parameter/value pairs construct a
   # standard query string.
   #
   #   URI.hash_to_query(:a => 1, :b => 2)
-  #   => "a=1&b=2"
-
+  #   #=> "a=1;b=2"
+  #
   def hash_to_query(parameters)
     return '' unless parameters
     pairs = []
     parameters.each do |param, value|
       pairs << "#{param}=#{cgi_escape(value.to_s)}"
     end
-    #return pairs.join('&')
-    return pairs.join(";")
+    return pairs.join(KEY_VALUE_SEPARATOR)
   end
 
   alias_method :hash_to_query_string, :hash_to_query
 
+  # CGI escape
   #
   # TODO: How does this compare to URI.escape?
-
   def cgi_escape(string)
     string.gsub(/([^ a-zA-Z0-9_.-]+)/n) do
       '%' + $1.unpack('H2' * $1.size).join('%').upcase
@@ -113,7 +87,6 @@ module URI
   end
 
   #
-
   def cgi_unescape(string)
     string.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n) do
       [$1.delete('%')].pack('H*')
@@ -121,7 +94,6 @@ module URI
   end
 
   #
-
   def cgi_parse(query)
     params = Hash.new([].freeze)
 
@@ -145,7 +117,6 @@ module URI
   # Output:
   # the query string.
   # returns nil if no query string
-
   def get_query_string(uri)
     return nil unless uri
     # gmosx: INVESTIGATE ruby's URI seems to differently handle
@@ -158,14 +129,9 @@ module URI
     return nil
   end
 
-  # Removes the query string from a uri
-  #
-  # Input:
-  # the uri
+  # Removes the query string from a +uri+.
   #
-  # Output:
-  # the chomped uri.
-
+  # Returns the chomped uri.
   def chomp_query_string(uri)
     return nil unless uri
     query_string = self.get_query_string(uri)
@@ -173,18 +139,14 @@ module URI
   end
 
   # Get a uri and a hash of parameters. Inject the hash values
-  # as parameters in the query sting path. Returns the full
-  # uri.
+  # as parameters in the query sting path. Returns the full uri.
   #
-  # Input:
-  # the uri to filter (String)
-  # hash of parameters to update
+  # uri       - the uri to filter (String)
+  # parameter - hash of parameters to update
   #
-  # Output:
-  # the full updated query string
+  # Returns the full updated query string.
   #
   # TODO: optimize
-
   def update_query_string(uri, parameters)
     query_string = self.get_query_string(uri)
     rest = uri.dup.gsub(/\?#{query_string}/, "")
@@ -200,21 +162,21 @@ module URI
     end
   end
 
-  # TODO: find a better name.
   # Gets the request uri, injects extra parameters in the query string
   # and returns a new uri. The request object is not modified.
   # There is always a qs string so an extra test is skipped.
-
+  #
+  # TODO: find a better name?
   def update_request_uri(request, parameters)
     hash = request.parameters.dup()
     hash.update(parameters)
 
-    # use this in hash_to_querystring.
+    ## use this in hash_to_querystring.
     query_string = hash.collect { |k, v|
       "#{k}=#{v}"
     }.join(";")
 
-    #return "#{request.translated_uri}?#{query_string}"
+    ## return "#{request.translated_uri}?#{query_string}"
     return "#{request.path}?#{query_string}"
   end
 

data/lib/more/facets/yaml.rb

@@ -1,52 +1,23 @@
-# = YAML Extensions
-#
-# YAML related extenstions.
-#
-# The Kernel method #yaml is a shortcut to YAML::load.
-#
-#   yaml %{
-#     a: 1
-#     b: 2
-#   }
-#
-# produes
-#
-#   {:a=>1, :b=>2}
-#
-# File.yaml? provides a way to check if a file is a YAML
-# formatted file.
-#
-#   File.yaml?('project.yaml')  #=> true
-#   File.yaml?('project.xml')   #=> false
-#
-# == Authors
-#
-# * Thomas Sawyer
-#
-# == Copyright
-#
-# Copyright (c) 2006 Thomas Sawyer
-#
-# 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 'yaml'
 
 module Kernel
-  # Convenience method for loading YAML.
+
+  # The Kernel method #yaml is a shortcut to YAML::load.
+  #
+  #   data = yaml %{
+  #     a: 1
+  #     b: 2
+  #   }  
+  #   data #=> {"a"=>1, "b"=>2}
   #
   def yaml(*args,&blk)
     YAML.load(*args,&blk)
   end
 
-  # As with #to_yaml but removes the header line (i.e. '---') to create a "YAML fragment".
+  # As with #to_yaml but removes the header line (i.e. '---') to create
+  # a "YAML fragment".
   #
+  # CREDT: Thomas Sawyer
   def to_yamlfrag
     y = to_yaml
     y.sub!(/---\ */, '')
@@ -55,13 +26,16 @@ module Kernel
 end
 
 class File
-  # Is a file a YAML file?
+  # File.yaml? provides a way to check if a file is a YAML
+  # formatted file:
+  #
+  #   File.yaml?('project.yaml')  #=> true
+  #   File.yaml?('project.xml')   #=> false
   #
   # Note this isn't perfect. At present it depends on the use
   # use of an initial document separator (eg. '---'). With
-  # YAML 1.1 the %YAML delaration will be manditory, so in the
-  # future this can be adapted to fit that standard.
-  #
+  # YAML 1.1 the %YAML delaration is supposed to be manditory,
+  # so in the future this can be adapted to fit that standard.
   def self.yaml?(file)
     File.open(file) do |f|
       until f.eof?
@@ -73,3 +47,13 @@ class File
   end
 end
 
+module YAML
+  # Shortcut for:
+  #
+  #   YAML.load(File.new(file))
+  #
+  def self.read(file)
+    load(File.new(file))
+  end
+end
+