key_struct 0.1.2 → 0.2.0

data/README.rdoc

@@ -74,13 +74,33 @@ The struct initializer checks for invalid arguments:
 
   name = Name.new(:this_is_a_typo => "Xavier")  # --> raises ArgumentError
 
-== Equaltiy
+== Comparison
 
 KeyStruct classes define the == operator, which returns true iff all corresponding struct members are equal (likewise via ==)
 
     Name.new(:first => "John", :last => "Doe") == Name.new(:first => "John", :last => "Doe")    # --> true
     Name.new(:first => "John", :last => "Doe") == Name.new(:first => "Jane", :last => "Doe")    # --> false
 
+As a convenience when a well-defined ordering is needed, KeyStruct classes
+defines the <=> operator and includes the +Comparable+ module. The <=>
+operator applies <=> to the coresponding struct members sequentially,
+returning the first that is non-0. The comparison is performed in the order
+the keys were listed in the class definition, so the first key is the
+primary comparison key, and so on down the line.  Thus:
+
+    Name = KeyStruct[:first, :last]
+    Name.new(:first => "Abigail", :last => "Zither") <=> Name.new(:first => "Zenobia", :last => "Aardvark")           # --> -1
+
+    LastFirst = KeyStruct[:last, :first]
+    LastFirst.new(:first => "Abigail", :last => "Zither") <=> LastFirst.new(:first => "Zenobia", :last => "Aardvark") # --> +1
+
+== Converting to a hash
+
+KeyStruct classes define a +to_hash+ method that returns a hash containing
+all members and their values:
+
+        Name.new(:first => "Jack", :last => "Ripper").to_hash # --> {:first => "Jack", :last => "Ripper")
+
 == Installation
 
 Install via:
@@ -97,6 +117,12 @@ Requires ruby >= 1.9.2.  (Has been tested on MRI 1.9.2 and MRI 1.9.3)
 
 == History
 
+Release Notes:
+
+* 0.2.0 - Introduced <=> and to_hash
+* 0.1.0 - Introduced ==
+* 0.0.1 - Initial version
+
 Past: There was some discussion around this idea in this thread:
 http://www.ruby-forum.com/topic/138124 in 2008. 
 

data/lib/key_struct.rb

@@ -1,38 +1,2 @@
 require "key_struct/version"
-
-module KeyStruct
-
-  def self.reader(*keys)
-    define_key_struct(:attr_reader, keys)
-  end
-
-  def self.accessor(*keys)
-    define_key_struct(:attr_accessor, keys)
-  end
-
-  instance_eval do
-    alias :[] :accessor
-  end
-
-  private
-
-  def self.define_key_struct(access, keys) 
-    Class.new.class_eval do
-      keyvalues = Hash[*keys.map{|key| (Hash === key) ? key.to_a : [key, nil]}.flatten(2)]
-      keys = keyvalues.keys
-      send access, *keys
-      define_method(:initialize) do |args={}|
-        args = keyvalues.merge(args)
-        keys.each do |key|
-          instance_variable_set("@#{key}".to_sym, args.delete(key))
-        end
-        raise ArgumentError, "Invalid argument(s): #{args.keys.map(&:inspect).join(' ')}; KeyStruct accepts #{keys.map(&:inspect).join(' ')}" if args.any?
-      end
-      define_method(:==) do |other|
-        keys.all?{|key| self.send(key) == other.send(key)}
-      end
-      self
-    end
-  end
-
-end
+require "key_struct/key_struct"

data/lib/key_struct/key_struct.rb

@@ -0,0 +1,48 @@
+module KeyStruct
+
+  def self.reader(*keys)
+    define_key_struct(:attr_reader, keys)
+  end
+
+  def self.accessor(*keys)
+    define_key_struct(:attr_accessor, keys)
+  end
+
+  instance_eval do
+    alias :[] :accessor
+  end
+
+  private
+
+  def self.define_key_struct(access, keys) 
+    Class.new.class_eval do
+      include Comparable
+      keyvalues = Hash[*keys.map{|key| (Hash === key) ? key.to_a : [key, nil]}.flatten(2)]
+      keys = keyvalues.keys
+      send access, *keys
+      define_method(:initialize) do |args={}|
+        args = keyvalues.merge(args)
+        keys.each do |key|
+          instance_variable_set("@#{key}".to_sym, args.delete(key))
+        end
+        raise ArgumentError, "Invalid argument(s): #{args.keys.map(&:inspect).join(' ')}; KeyStruct accepts #{keys.map(&:inspect).join(' ')}" if args.any?
+      end
+      define_method(:==) do |other|
+        keys.all?{|key| self.send(key) == other.send(key)}
+      end
+      define_method(:<=>) do |other|
+        keys.each do |key|
+          cmp = (self.send(key) <=> other.send(key))
+          return cmp unless cmp == 0
+        end
+        0
+      end
+      define_method(:to_hash) do
+        Hash[*keys.map{ |key| [key, self.send(key)]}.flatten(2)]
+      end
+      self
+    end
+  end
+
+end
+

data/lib/key_struct/version.rb

@@ -1,3 +1,3 @@
 module KeyStruct
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/spec/key_struct_spec.rb

@@ -113,15 +113,36 @@ describe "KeyStruct" do
     end
   end
 
-  context "==" do
+  context "comparison" do
     before(:all) do 
-      @klass = KeyStruct.accessor(:a, :b)
+      @klass = KeyStruct.accessor(:a, :b, :c)
     end
 
     it "returns true iff all members are ==" do
       @klass.new(:a => 1, :b => 2).should == @klass.new(:a => 1, :b => 2)
       @klass.new(:a => 1, :b => 2).should_not == @klass.new(:a => 1, :b => 3)
     end
+
+    it "compares based on primary key" do
+      @klass.new(:a => 1, :b => 2).should < @klass.new(:a => 2, :b => 2)
+    end
+
+    it "compares based on second key if first is equal" do
+      @klass.new(:a => 1, :b => 2).should > @klass.new(:a => 1, :b => 1)
+    end
+
+    it "compares based on third key if first two are equal" do
+      @klass.new(:a => 1, :b => 2, :c => 3).should > @klass.new(:a => 1, :b => 2, :c => 1)
+    end
+
+    it "returns zero for <=> if all are equal" do
+      (@klass.new(:a => 1, :b => 2) <=> @klass.new(:a => 1, :b => 2)).should == 0
+    end
+
+  end
+
+  it "returns hash using to_hash" do
+    KeyStruct.accessor(:a => 3, :b => 4).new.to_hash.should == {:a => 3, :b => 4}
   end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: key_struct
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-29 00:00:00.000000000 Z
+date: 2011-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70161596448140 !ruby/object:Gem::Requirement
+  requirement: &70350516522720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70161596448140
+  version_requirements: *70350516522720
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70161596447560 !ruby/object:Gem::Requirement
+  requirement: &70350516521800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70161596447560
+  version_requirements: *70350516521800
 - !ruby/object:Gem::Dependency
   name: simplecov-gem-adapter
-  requirement: &70161596438560 !ruby/object:Gem::Requirement
+  requirement: &70350516536920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70161596438560
+  version_requirements: *70350516536920
 description: Defines KeyStruct analogous to Struct, but constructor takes keyword
   arguments
 email:
@@ -61,6 +61,7 @@ files:
 - Rakefile
 - key_struct.gemspec
 - lib/key_struct.rb
+- lib/key_struct/key_struct.rb
 - lib/key_struct/version.rb
 - spec/key_struct_spec.rb
 - spec/spec_helper.rb