lib/hashery/dictionary.rb in hashery-2.0.1 vs lib/hashery/dictionary.rb in hashery-2.1.0

@@ -54,14 +54,18 @@
   class Dictionary
 
     include Enumerable
 
     class << self
-      #--
-      # TODO is this needed? Doesn't the super class do this?
-      #++
 
+      #
+      # Create a new Dictionary storing argument pairs as an initial mapping.
+      #
+      # TODO: Is this needed? Doesn't the super class do this?
+      #
+      # Returns Dictionary instance.
+      #
       def [](*args)
         hsh = new
         if Hash === args[0]
           hsh.replace(args[0])
         elsif (args.size % 2) != 0
@@ -73,33 +77,38 @@
         end
         hsh
       end
 
       #
-      # Like #new but the block sets the order.
+      # Like #new but the block sets the order instead of the default.
       #
+      #   Dictionary.new_by{ |k,v| k }
+      #
       def new_by(*args, &blk)
         new(*args).order_by(&blk)
       end
 
       #
-      # Alternate to #new which creates a dictionary sorted by key.
+      # Alternate to #new which creates a dictionary sorted by the key as a string.
       #
-      #   d = Dictionary.alpha
+      #   d = Dictionary.alphabetic
       #   d["z"] = 1
       #   d["y"] = 2
       #   d["x"] = 3
       #   d  #=> {"x"=>3,"y"=>2,"z"=>2}
       #
       # This is equivalent to:
       #
-      #   Dictionary.new.order_by { |key,value| key }
-
-      def alpha(*args, &block)
-        new(*args, &block).order_by_key
+      #   Dictionary.new.order_by { |key,value| key.to_s }
+      #
+      def alphabetic(*args, &block)
+        new(*args, &block).order_by { |key,value| key.to_s }
       end
 
+      # DEPRECATED: Use #alphabetic instead.
+      alias :alpha :alphabetic
+
       #
       # Alternate to #new which auto-creates sub-dictionaries as needed.
       #
       # Examples
       #
@@ -118,11 +127,11 @@
     #
     def initialize(*args, &blk)
       @order = []
       @order_by = nil
       if blk
-        dict = self                                  # This ensure autmatic key entry effect the
+        dict = self                                  # This ensures automatic key entry effect the
         oblk = lambda{ |hsh, key| blk[dict,key] }    # dictionary rather then just the interal hash.
         @hash = Hash.new(*args, &oblk)
       else
         @hash = Hash.new(*args)
       end
@@ -167,11 +176,15 @@
     # The initializer Dictionary#alpha also provides this.
     #
     # Returns +self+.
     #
     def order_by_key
-      @order_by = Proc.new{ |k,v| k }
+      if block_given?
+        @order_by = Proc.new{ |k,v| yield(k) }
+      else
+        @order_by = Proc.new{ |k,v| k }
+      end
       order
       self
     end
 
     #
@@ -186,10 +199,14 @@
     # This is equivalent to:
     #
     #   Dictionary.new.order_by { |key,value| value }
     #
     def order_by_value
-      @order_by = Proc.new{ |k,v| v }
+      if block_given?
+        @order_by = Proc.new{ |k,v| yield(v) }
+      else
+        @order_by = Proc.new{ |k,v| v }
+      end
       order
       self
     end
 
     #