burp 0.0.1 → 0.1.1

data/README.rdoc

@@ -1,46 +1,159 @@
-= burp
+= Burp
+== Why Burp?
+Did you ever get a list of structured data (for example an array of hash data) and get a bit of indigestion when you realize that the unique attribute(s) of the data is(are) buried underneath the array? Well, if you're like me you're tired of having to do something like
 
+    structured_array = list_of_stuff.map{|struc_data| organize(struc_data)}
+    a_nice_hash = Hash.new[structured_array]
+
+Burp provides an easier way
+
+== Basic Burp
 Oh yum, look at this collection of hashes I have to manage. Each with a unique id to represent it:
   
-yummy = [
-          {:id => :a, :data => "A"},
-          {:id => :b, :data => "B"},
-          {:id => :c, :data => "C"}
-        ]
+    yummy  = [
+               {:id => :a, :data => "A", :other_stuff => "aaa"},
+               {:id => :b, :data => "B", :other_stuff => "bbb"},
+               {:id => :c, :data => "C", :other_stuff => "ccc"}
+             ]
 
-I feel like checking out :b today:
+I feel like referencing :b's data today:
 
 Yes, you could just select what you need the boring, ugly way
-b_data = yummy.select{|node| node[:id] == :b}.first
+
+    b_data = yummy.select{|node| node[:id] == :b}.first
+
 That's not hard, but rather than manually select it, let's just let out a hearty burp
 
-burped = Burp.new(yummy, :id)
+    burped = Burp.new(yummy, :id)
 
 and get good old fashioned hash in return
 
-#=> { :a => {:id => :a, :data => "A" },
-      :b => {:id => :b, :data => "B" },
-      :c => {:id => :c, :data => "C" }
+    #=> { :a => {:id => :a, :data => "A", :other_stuff => "aaa" },
+          :b => {:id => :b, :data => "B", :other_stuff => "bbb" },
+          :c => {:id => :c, :data => "C", :other_stuff => "ccc" }
 
 meaning that
-b_data = burped[:b]
+
+    b_data = burped[:b]
+      #=> {:id => :b, :data => "B", :other_stuff => "bbb" }
+
+
+Burp also allows you to filter the data if desired by providing a list of fields to keep
+
+    filtered_burp = Burp.new(yummy, :id, [:data])
+
+or if there's only one field of interest and you can't be bothered with array brackets, just
+
+    filtered_burp = Burp.new(yummy, :id, :data) 
+
+will work fine as well, and will return
+
+    #=> { :a => {:data => "A"},
+          :b => {:data => "B"},
+          :c => {:data => "C"}
 
 As a special side-dish, Burp can handle things that are a bit messier as well
 
-fly_in_my_soup = [
-                   {:id => :a, :data => "A"},
-                   {:id => :b, :data => "B"},
-                   {:id => :c, :data => "C"},
-                   {:fly => :d, :data => "D"}
-        ] 
+    fly_in_my_soup = [
+                       {:id => :a, :data => "A"},
+                       {:id => :b, :data => "B"},
+                       {:id => :c, :data => "C"},
+                       {:fly => :d, :data => "D"}
+                     ] 
+
+    yummy_soup = Burped.new(fly_in_my_soup, :id)
+      #=> { :a => {:id => :a, :data => "A" },
+            :b => {:id => :b, :data => "B" },
+            :c => {:id => :c, :data => "C" }
+
+    fly = yummy_soup.left_overs
+      #=> [{:fly => :d, :data => "D"}]
+
+== Advanced Burp
+Burp's not only good for lists of hashes, it can work for a list of any arbitrary data, and you can set any key you'd like to the underlying data.
+
+Examples Ahoy!
+
+Let's say our IronChef gem (don't go look for it, I just made that up) provides us a list of foods and some information about them, however the food information is encapsulated in its own class, something like:
+
+    class Food
+      attr_accessor :name, :tastiness, :prep_effort
+
+      def initialize(name, tastiness, prep_effort)
+        @name = name
+        @tastiness = tastiness
+        @prep_effort = prep_effort
+      end
+    end
+
+So when inspecting this array of food objects I see something like:
+
+    pp food_array
+      #=>
+         [#<Food:0xb41368 
+            @name="bacon",
+            @prep_effort="nuke it",
+            @tastiness="awesome">,
+          #<Food:0xb41308
+            @name="tofu",
+            @prep_effort="mix it in something",
+            @tastiness="meh">,
+          #<Food:0xb412a8
+            @name="beer",
+            @prep_effort="mooch from buddy",
+            @tastiness="essential to life">]
+
+Ok, so maybe I'm just interested in the preparation of said food items, we can use the name attribute for our key, and pull out the prep effort.
+
+To do this with Burp, we can create a custom id label with a proc:
+
+    food_name = lambda{ |item| item.name }
+
+just use it like this in Burp
+
+  food_data = Burp.new(food_array, food_name)
+    #=>
+      {"bacon"=>
+        #<Food:0x8a9c8bc
+         @name="bacon",
+         @prep_effort="nuke it",
+         @tastiness="awesome">,
+       "tofu"=>
+        #<Food:0x8a9c86c
+         @name="tofu",
+         @prep_effort="mix it in something",
+         @tastiness="meh">,
+       "beer"=>
+        #<Food:0x8a9c81c
+         @name="beer",
+         @prep_effort="mooch from buddy",
+         @tastiness="essential to life">}
+
+Ah, that's a little bit better, now I can get my desired food object (beer of course) just by
+
+    food_data["beer"]
+      #=>
+         #<Food:0x8a9c81c
+         @name="beer",
+         @prep_effort="mooch from buddy",
+         @tastiness="essential to life">}
+
+and to prepare I can just call prep_effort
+
+    food_data["beer"].prep_effort
+
+But, we can go a step further, and have burp provided us just the information we want
+
+    filter = lambda{|item| item.prep_effort}
+
+    food_prep = Burp.new(food_array, food_name, filter)
+      #=> {"bacon"=>"nuke it", "tofu"=>"mix it in something", "beer"=>"mooch from buddy"}
+
+    food_prep["beer"]
+      #=> "mooch from buddy"
 
-yummy_soup = Burped.new(fly_in_my_soup)
-#=> { :a => {:id => :a, :data => "A" },
-      :b => {:id => :b, :data => "B" },
-      :c => {:id => :c, :data => "C" }
 
-fly = yummy_soup.left_overs
-#=> [{:fly => :d, :data => "D"}]
+Now if you'll excuse me, I'm hungry and have to grab something to eat.
 
 == Contributing to burp
  

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.1

data/burp.gemspec

@@ -0,0 +1,65 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{burp}
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Dave M"]
+  s.date = %q{2011-04-13}
+  s.description = %q{Tell it which hash key in the array of hashes to use as the hash id, and voila a hash is made from your array}
+  s.email = %q{dmarti21@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "burp.gemspec",
+    "lib/burp.rb",
+    "spec/burp_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/forforf/burp}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Turns an array of hashes into a hash of hashes}
+  s.test_files = [
+    "spec/burp_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, ["~> 2.3.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+  end
+end
+

data/lib/burp.rb

@@ -1,31 +1,66 @@
 class Burp < Hash
   attr_reader :left_overs
-  #Converts an array of hashes into a hash
+  #Converts a list of data (i.e. an array) into a ruby hash structure
+  #
   #It takes as arguments,the array of hashes (each hash representing node data)
   #and a field in the hash (node data) to use as the key for the returned hash
-  def initialize(node_list, id)
+  def initialize(node_list, id_key, data_filter = nil)
     @left_overs = []
-    node_list.map do |node|
-      #better error information and eliminate nil keys
-      node = validate(node, id) 
-      #it's left over if the primary hash key doesn't exist in the node
-      add_leftovers(self, @left_overs, node) unless ( node[id] && node.keys.include?(id) )
+    node_list.map do |raw_node|
+      node_id = find_id(raw_node, id_key)
+      if node_ok?(raw_node, node_id)
+        node_burp(raw_node, node_id, data_filter)  #adds to self (i.e. this hash)
+      else
+        @left_overs << raw_node
+      end
     end
   end
+
+  def node_ok?(raw_node, node_id)
+    resp = true
+    resp = false if self.has_key?(node_id)
+    resp = false if raw_node && node_id.nil?
+    resp
+  end
   
+  def node_burp(raw_node, node_id, data_filter)
+    node_data = find_data(raw_node, data_filter)
+    self[node_id] = node_data
+  end
+
+
+  def find_id(node, id_key)
+    if id_key.is_a? Proc
+      id_key.call(node)
+    else
+      validate(node, id_key)
+    end
+  end
+  
+  def find_data(node, data_filter)
+    return node unless data_filter
+    if data_filter.is_a? Proc
+      node_data = data_filter.call(node)
+    else
+      #Done this way to allow any object that supports [], []= and has_key? methods
+      #I'm intentionally avoiding Hash#select/reject for this (selfish) reason
+      data_filter = [data_filter].flatten
+      new_data = {}
+      data_filter.each do |key|
+        if node.has_key?(key)
+          new_data[key] = validate(node, key)
+        end
+      end
+      new_data
+    end
+  end
+
   def validate(node, id)
     begin
-      self[node[id]] = node 
+      node[id]
     rescue TypeError  #replacing an unhelpful error with something more helpful
       raise ArgumentError, "Can't use #{id.inspect} as a valid key in #{node.inspect}. "\
-        "Maybe array elements are not hashes?" 
+        "Maybe you're trying a hash method on something other than a hash?"
     end
   end
-
-  def add_leftovers(main_hash, left_overs, node)
-    #remove nil hash from main_hash
-    main_hash.delete(nil)
-    #add data to left overs (excluding nil data)
-    left_overs << node if node
-  end
 end

data/spec/burp_spec.rb

@@ -1,26 +1,64 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
+module BurpSpecH
 
-describe "Burp" do
+  #Food Stuff for Advanced Burp
+  class Food
+    attr_accessor :name, :tastiness, :prep_effort
+    def initialize(name, tastiness, prep_effort)
+      @name = name
+      @tastiness = tastiness
+      @prep_effort = prep_effort
+    end
+  end
+
+  Foods = {'bacon' => {:taste =>  'awesome', :prep => 'nuke it'},
+           'tofu' => {:taste => 'meh', :prep => 'mix it in something'},
+           'beer' => {:taste => 'essential to life', :prep => 'mooch from buddy'}
+          }
+  FoodNames = Foods.keys
+
+  def self.make_food
+    #make us an array of Food objects
+    FoodNames.map do |food_name| Food.new(food_name, 
+                                        Foods[food_name][:taste],
+                                        Foods[food_name][:prep])
+    end
+  end
+
+  #Baseic stuff for Basic (and Advanced) Burp
+
+  NiceArray = [{:id => :a, :data => "A", :other_stuff => "aaa"},
+               {:id => :b, :data => "B", :other_stuff => "bbb"},
+               {:id => :c, :data => "C", :other_stuff => "ccc"}]
+ 
+  #notice the last id typo
+  DirtyArray = [{:id => :a, :data => "A", :other_stuff => "aaa"},
+                {:id => :b, :data => "B", :other_stuff => "bbb"},
+                {:id => :c, :data => "C", :other_stuff => "ccc"},
+                {:iidd => :d, :data => "D"}]
+end
+
+describe "Basic Burp" do
   before(:each) do
-    @nice_array = [{:id => :a, :data => "A"},
-                   {:id => :b, :data => "B"},
-                   {:id => :c, :data => "C"}]
-    @nice_burped = {:a => {:id => :a, :data => "A"},
-                    :b => {:id => :b, :data => "B"},
-                    :c => {:id => :c, :data => "C"}}
+    @nice_array = BurpSpecH::NiceArray
+
+    @nice_burped = {:a => {:id => :a, :data => "A", :other_stuff => "aaa"},
+                    :b => {:id => :b, :data => "B", :other_stuff => "bbb"},
+                    :c => {:id => :c, :data => "C", :other_stuff => "ccc"}}
 
     @not_an_array = @nice_burped #its a hash now
 
     #notice the last id typo
-    @dirty_array = [{:id => :a, :data => "A"},
-                   {:id => :b, :data => "B"},
-                   {:id => :c, :data => "C"},
-                   {:iidd => :d, :data => "D"}]
+    @dirty_array = BurpSpecH::DirtyArray
 
     @dirty_burped = @nice_burped
 
     @dirty_left_overs = [{:iidd => :d, :data => "D"}]
+
+    @filtered_burp =  {:a => {:data => "A"},
+                       :b => {:data => "B"},
+                       :c => {:data => "C"}}
   end
 
   it "makes a hash out of a nicely formed array" do
@@ -37,4 +75,67 @@ describe "Burp" do
     my_dirty_burp.should == @dirty_burped
     my_dirty_burp.left_overs.should == @dirty_left_overs
   end
+
+  it "filters data" do
+    filtered_burp = Burp.new(@dirty_array, :id, :data)
+    filtered_burp.should == @filtered_burp
+  end
+
+  
+end
+
+describe "Advanced Burp" do
+  include BurpSpecH
+
+  before(:each) do
+    @food_list = BurpSpecH.make_food
+    @id_block = lambda{|item| item.name}
+    @filtered_food_block = lambda{|item| item.prep_effort} 
+    @filtered_simple_block = lambda{|item| item[:data].downcase}                    
+    @nice_array = NiceArray
+    @nice_burped_proc = {:a => "a",
+                         :b => "b",
+                         :c => "c"}
+    @dirty_array = DirtyArray
+    @dirty_bupred_proc = @nice_burped_proc
+    @dirty_left_overs = [{:iidd => :d, :data => "D"}]
+    @filtered_burp = {'bacon' => 'nuke it',
+                      'tofu' => 'mix it in something',
+                      'beer' => 'mooch from buddy'}
+  end
+
+  it "is passed a food list" do
+    @food_list.should be_an Array
+  end
+
+  it "uses blocks for ids without vomiting" do
+    my_burp = Burp.new(@food_list, @id_block)
+    my_burp['bacon'].should be_a Food
+    my_burp['bacon'].tastiness.should == "awesome"
+    my_burp['bacon'].prep_effort.should == "nuke it"
+    
+    #comprehensive test
+    FoodNames.each do |food_name|
+      my_burp[food_name].should be_a Food
+      my_burp[food_name].tastiness.should == Foods[food_name][:taste]
+      my_burp[food_name].prep_effort.should == Foods[food_name][:prep]
+    end
+  end
+
+  it "uses blocks for nice data without vomiting" do
+    my_burp = Burp.new(@nice_array, :id, @filtered_simple_block)
+    my_burp.should == @nice_burped_proc
+  end
+
+  it "uses blocks for dirty data without vomiting" do
+    my_dirty_burp = Burp.new(@dirty_array, :id, @filtered_simple_block)
+    my_dirty_burp.should == @nice_burped_proc
+    my_dirty_burp.left_overs.should == @dirty_left_overs
+  end
+
+  it "uses blocks for both ids and data without vomiting" do
+    my_burp = Burp.new(@food_list, @id_block, @filtered_food_block)
+    my_burp.should == @filtered_burp
+  end
+
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 0
   - 1
-  version: 0.0.1
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Dave M
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-12 00:00:00 +00:00
+date: 2011-04-13 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -93,6 +93,7 @@ files:
 - README.rdoc
 - Rakefile
 - VERSION
+- burp.gemspec
 - lib/burp.rb
 - spec/burp_spec.rb
 - spec/spec_helper.rb
@@ -110,7 +111,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 771572209
+      hash: 997682877
       segments: 
       - 0
       version: "0"