mongo_populator 0.2.0 → 1.0.1

data/CHANGELOG.md

@@ -1,11 +1,29 @@
+# 1.0.1 (September 30th, 2011)
+
+* Fixed bug where using #items without an array in parameters caused error.
+
+# 1.0.0 (September 30th, 2011)
+
+* Embedded documents. There is a known issue that generated data (e.g. MongoPopulator.words()) is only generated once per set of embedded documents.
+
+* Static arrays.
+
+* Static dictionaries.
+
+* Backwards-compat breaking API change: to conform better to the mongo gem API, attributes set to `nil` will be set to NULL in the resulting document. To suppress an attribute from a document, use MongoPopulator#skip (see README).
+
+# 0.2.1 (September 14th, 2011)
+
+* MongoArrays are now guaranteed unique.
+
 # 0.2.0 (September 14th, 2011)
 
 * an attribute set to nil (directly or randomly via an array) will not appear in the resulting document.
 
 # 0.1.1 (September 14th, 2011)
 
-* remove required minimum RubyGems version
+* remove required minimum RubyGems version.
 
 # 0.1.0 (September 14th, 2011)
 
-* initial release based on fork of http://github.com/ryanb/populator
+* initial release based on fork of http://github.com/ryanb/populator.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mongo_populator (0.1.1)
+    mongo_populator (1.0.0)
       mongo (~> 1.3.1)
 
 GEM

data/README.md

@@ -1,6 +1,6 @@
 # MongoPopulator
 
-`mongo_populator` populates a MongoDB database with placeholder data. It is built upon [`populator`](https://github.com/ryanb/populator) by Ryan Bates, but it works with the `mongo` gem in standalone scripts, and is not tied to any particular framework.
+MongoPopulator populates a MongoDB database with placeholder data. It is built upon [Populator](https://github.com/ryanb/populator) by Ryan Bates, but it works with the `mongo` gem in standalone scripts, and therefore is not tied to any particular framework.
 
 ## Installation
 
@@ -8,7 +8,7 @@
 
 ## Usage
 
-This gem adds a "populate" method to a `Mongo::Collection`. Pass the number of documents you want to create along with a block. In the block you can set the field values for each document.
+This gem adds a `#populate` method to a `Mongo::Collection`. Pass the number of documents you want to create along with a block. In the block you can set the field values for each document.
 
     require 'rubygems'
     require 'mongo_populator'
@@ -65,31 +65,56 @@ If you need to generate fake data, there are a few methods to do this.
 
 For fancier data generation, try the [Faker gem](http://faker.rubyforge.org).
 
-### JSON-specific structures
+### Mongo-specific values
 
-To persist arrays in your documents, use either #items to save a certain number of items randomly selected from a set, or #array to save a specific array.
+Setting an attribute with the `#skip` method prevents that attribute being set. This is useful when you only want a field to appear in *some* documents
+
+    ...
+    address.state = MongoPopulator.skip if address.country != "United States"
+    ...
+
+So, to support conditional setting of an attribute, pass it an array with one or more MongoPopulator.skip as elements.
+
+    ...
+    user.creds = ['M.D.', 'J.D.', 'N.D.', MongoPopulator.skip, MongoPopulator.skip]  
+    ...
+
+~40% of users will not have the "cred" field.
+
+If you actually want a field in your document to be set to NULL, pass `nil` as the value.
+
+   ...
+   user.style = nil # 'style' key will not be in resulting document
+   ...
+
+To persist arrays in your documents, use either `#items` to save a certain number of items randomly selected from a set, or `#array` to save a specific array.
 
     MongoPopulator.items(1..5, %w(ape bear cat dog elephant firefox)) # populates array with provided terms
     MongoPopulator.items(10..20) # populates array with random words
     MongoPopulator.array('red', 'green', 'blue') # saves `['red', 'green', 'blue']` exactly
 
-Setting an attribute to nil prevents that attribute being set. 
+Note that you cannot pass `#skip` in `#items`, `#dictionary`, or `#array`. Doing so will result in an error.
 
-    ...
-    address.state = nil if address.country != "United States"
-    ...
+    user.fruit = MongoPopulator.items(3, ['apple', 'banana', 'kiwi', MongoPopulator.skip]) #=> Error
 
-So, to support conditional setting of an attribute, pass it an array with one or more nils as elements.
+To persist a static dictionary to your document, use `#dictionary`.
 
-    ...
-    user.creds = ['M.D.', 'J.D.', 'N.D.', nil, nil]  
-    ...
+    MongoPopulator.dictionary(:name => "Mongo", :type => "db")
+
+#### Embedded Documents
 
-~40% of users will not have credentials.
+To embed documents, use `#embed`. It takes a dictionary template, which accepts any of the Populator constructs. See note below in "Known Issues."
 
-## TODO
+    @collection.populate(1) do |parent|
+      parent.name = "Bunny Sr."
+      parent.kids = MongoPopulator.embed(10..20, {:name => ["Bunny Jr.","Fluffy","Other Fluffy"], :age => (1..20), :tattoos => ["butterfly", "banjo frog", MongoPopulator.skip]})
+    end
+
+The above code generates a record with 10 to 20 embedded documents, roughly one-third of which have a 'tattoo' field.
+
+## Known issues
 
-* Support singular and multiple embedded documents
+* Data generation methods like `#words` or Faker methods will not return varying data within a set when used in embedded document templates. Instead a random value will be picked the first time, and used for the entire set.
 
 ## Development
 
@@ -97,8 +122,4 @@ Problems or questions? Add an [issue on GitHub](https://github.com/bak/mongo_pop
 
 ## Special Thanks
 
-MongoPopulator is highly derivative of, and heavily reuses, the work of Ryan Bates [via Populator](https://github.com/ryanb/populator/). Thanks, Ryan.
-
-## Special Thanks for the original Populator
-
-Special thanks to Zach Dennis for his ar-extensions gem which some of this code is based on. Also many thanks to the [contributors](https://github.com/ryanb/populator/contributors). See the [CHANGELOG](https://github.com/ryanb/populator/blob/master/CHANGELOG.rdoc) for the full list.
+MongoPopulator is built upon the work of Ryan Bates [via Populator](https://github.com/ryanb/populator/). Thanks, Ryan.

data/TODO.md

@@ -0,0 +1,2 @@
+Write MongoDictionary
+Write support for singular and multiple embedded documents

data/lib/mongo_populator.rb

@@ -5,6 +5,8 @@ require 'mongo_populator/collection_additions'
 require 'mongo_populator/factory'
 require 'mongo_populator/record'
 require 'mongo_populator/mongo_array'
+require 'mongo_populator/mongo_dictionary'
+require 'mongo_populator/mongo_skip'
 require 'mongo_populator/random'
 
 # MongoPopulator is made up of several parts. To start, see MongoPopulator::ModelAdditions.

data/lib/mongo_populator/factory.rb

@@ -50,7 +50,7 @@ module MongoPopulator
         # index = last_id_in_database + @records.size + 1
         record = Record.new(@collection)
         block.call(record) if block
-        @records << record.attributes
+        @records << record.attributes.delete_if {|k,v| v.is_a?(MongoSkip) }
         save_records 
       end
     end

data/lib/mongo_populator/mongo_dictionary.rb

@@ -0,0 +1,5 @@
+module MongoPopulator
+
+  # MongoArrays can be passed directly to attributes and will be saved as arrays in mongo.
+  class MongoDictionary < Hash; end
+end

data/lib/mongo_populator/mongo_skip.rb

@@ -0,0 +1,4 @@
+module MongoPopulator
+
+  class MongoSkip; end
+end

data/lib/mongo_populator/random.rb

@@ -39,19 +39,68 @@ module MongoPopulator
         
     # Generate a given number of items, or for a range, generate a random number of
     # items within that range, using values in array, or random words. Returns MongoArray.
+    # Resulting items should be a unique set, therefore if minimum number requested exceeds 
+    # number of items available, provide fewer items.
     def items(total, arr=nil)
+      if arr && arr.map{|e| e.class}.include?(MongoSkip)
+        raise StandardError, "#skip method is not permitted in the #items array argument"
+      end
+
+      # limit returned size to arr size if arr is not large enough
+      min = total.is_a?(Range) ? total.first : total
+      if arr
+        total = (min <= arr.size) ? total : arr.size
+      end
+
       out = MongoArray.new
-      (1..interpret_value(total)).map do
+      target = interpret_value(total)
+      until out.size == target do
         out << (arr ? arr[rand(arr.size)] : words(1))
+        out.uniq!
       end
-      return out
+      out
     end
 
     # Simply pass the values back out as a MongoArray
     def array(*values)
+      if values.map {|e| e.class}.include?(MongoSkip)
+        raise StandardError, "#skip method is not a permitted argument to #array"
+      end
       MongoArray.new(values)
     end
 
+    # Simply pass the values back out as a MongoDictionary
+    def dictionary(dict)
+      if dict.values.map {|e| e.class}.include?(MongoSkip)
+        raise StandardError, "#skip method is not a permitted value in #dictionary"
+      end
+      md = MongoDictionary.new()
+      dict.each {|k,v| md[k]=v}
+      md
+    end
+
+    # Because the mongo gem sets NULL for a value of `nil` instead of skipping the field 
+    # altogether, we need a way to suppress a field from a doc so we don't surprise anyone.
+    # See #build_records in factory.rb for how this is done in parent documents, and 
+    # #embed in this file for how it is done in embedded documents.
+    def skip()
+      MongoSkip.new
+    end
+
+    # Create n embedded documents from a template hash
+    def embed(total, template)
+      out = MongoArray.new
+      (1..interpret_value(total)).map do
+        md = MongoDictionary.new
+        template.each_pair { |k,v|
+          iv = interpret_value(v)
+          md[k] = iv unless iv.is_a?(MongoSkip)
+        }
+        out << md
+      end
+      out
+    end
+    
     # If an array or range is passed, a random value will be selected to match.
     # All other values are simply returned.
     def interpret_value(value)

data/lib/mongo_populator/record.rb

@@ -11,7 +11,7 @@ module MongoPopulator
     def attributes=(values_hash)
       values_hash.each_pair do |key, value|
         value = value.call if value.is_a?(Proc)
-        self.send((key.to_s + "=").to_sym, value)
+        self.send((key.to_s + "=").to_sym, value) 
       end
     end
 
@@ -19,8 +19,9 @@ module MongoPopulator
 
     def method_missing(sym, *args, &block)
       name = sym.to_s
-      if name.include?('=') && args.first
-        @attributes[name.sub('=', '').to_sym] = MongoPopulator.interpret_value(args.first)
+      if name.include?('=')
+        rtn = MongoPopulator.interpret_value(args.first)
+        @attributes[name.sub('=', '').to_sym] = rtn
       else
         @attributes[sym]
       end

data/spec/mongo_populator/collection_additions_spec.rb

@@ -21,13 +21,48 @@ describe MongoPopulator::CollectionAdditions do
     @collection.distinct('name').last.should == "foo"
   end
 
-  it "should not set an attribute if passed nil" do
+  it "should not set an attribute if passed MongoPopulator.skip" do
     @collection.populate(1) do |record|
-      record.monkey = nil
+      record.monkey = MongoPopulator.skip
     end
     @collection.distinct('monkey').should be_empty
   end
 
+  it "should set a NULL value if passed nil" do
+    @collection.populate(1) do |record|
+      record.monkey = nil
+    end
+    @collection.distinct('monkey').should_not be_empty
+  end
+
+  # TODO: there is a chance that this will legitimately fail (if 1 is always picked).
+  it "should set an attribute only sometimes if MongoPopulator.skip is part of set" do
+    @collection.populate(10) do |record|
+      record.monkey = [1, MongoPopulator.skip]
+    end
+    count = 0; @collection.find().collect {|r| count += 1 if r.keys.include?('monkey')}
+    count.should <= 9
+  end
+
+  context "when generating embedded documents" do
+    before do
+      @collection.populate(1) do |parent|
+        parent.name = "Abraham"
+        parent.kids = MongoPopulator.embed(30, {:name => ["River","Willow","Swan"], :age => (1..20), :tattoos => ["butterfly", MongoPopulator.skip]})
+      end
+    end
+
+    it "should generate within the value provided" do
+      @collection.find_one()['kids'].should have(30).items
+    end
+
+    it "should not set a field when value is MongoPopulator.skip" do
+      # above, tattoos is set to MongoPopulator.skip approx 50% of the time
+      count = 0; @collection.find_one()['kids'].collect {|r| count += 1 if r.keys.include?('tattoos')}
+      count.should <= 29
+    end
+  end
+
   after(:each) do
     @collection.drop
   end

data/spec/mongo_populator/mongo_array_spec.rb

@@ -0,0 +1,9 @@
+require "spec_helper"
+
+describe MongoPopulator::MongoArray do
+  it 'should basically be an array' do
+    ma = MongoPopulator::MongoArray.new
+    ma.should be_a(Array)
+    MongoPopulator::MongoArray.methods.count.should equal Array.methods.count
+  end
+end

data/spec/mongo_populator/mongo_dictionary_spec.rb

@@ -0,0 +1,9 @@
+require "spec_helper"
+
+describe MongoPopulator::MongoDictionary do
+  it 'should basically be a hash' do
+    md = MongoPopulator::MongoDictionary.new
+    md.should be_a(Hash)
+    MongoPopulator::MongoDictionary.methods.count.should equal Hash.methods.count
+  end
+end

data/spec/mongo_populator/mongo_skip_spec.rb

@@ -0,0 +1,8 @@
+require "spec_helper"
+
+describe MongoPopulator::MongoSkip do
+  it 'should be instantiable' do
+    mn = MongoPopulator::MongoSkip.new
+    mn.should be_an_instance_of(MongoPopulator::MongoSkip)
+  end
+end

data/spec/mongo_populator/random_spec.rb

@@ -46,4 +46,39 @@ describe MongoPopulator::Random do
   it "should generate 3 random paragraphs" do
     MongoPopulator.paragraphs(3).split(/\n\n/).should have(3).records
   end
+
+  it "should generate an array of requested size from set" do
+    MongoPopulator.items(5..7, %w(a b c d e f g h i j k)).should have_at_least(5).records
+  end
+
+  it "should generate an array of requested size without a set" do
+    MongoPopulator.items(5..7).should have_at_least(5).records
+  end
+
+  it "should raise an error if trying to skip within #items" do
+    lambda { MongoPopulator.items(2, ['money','cash',MongoPopulator.skip]) }.should raise_error(StandardError)
+  end
+  
+  it "should generate a unique array" do 
+    res = [ ]
+    100.times do # we can be reasonably certain...
+      set = MongoPopulator.items(3, %w(a b c d)) 
+      res << (set == set.uniq)
+    end
+    res.should_not include(false)
+  end
+
+  context "when the set is not large enough to accomodate a uniq array of the size requested" do
+    before do
+      @set = MongoPopulator.items(4..5, %w(a b c))
+    end 
+    
+    it "should generate a smaller array than asked for" do
+      @set.size.should == 3
+    end
+    
+    it "should still be unique" do
+      @set.should include("a","b","c")
+    end
+  end
 end

data/spec/mongo_populator/record_spec.rb

@@ -31,6 +31,26 @@ describe MongoPopulator::Record do
     record.stock.should == 15
   end
 
+  it "should persist a dictionary as-is" do
+    record = MongoPopulator::Record.new(@collection)
+    record.info = MongoPopulator.dictionary(:name => "mongo", :type => "db")
+    record.info[:name].should == "mongo"
+  end
+
+  it "should raise an error if trying to skip within #dictionary" do
+    lambda { MongoPopulator.dictionary(:name => "mongo", :type => MongoPopulator.skip) }.should raise_error(StandardError)
+  end
+
+  it "should persist an array as-is" do
+    record = MongoPopulator::Record.new(@collection)
+    record.info = MongoPopulator.array("mongo", "db")
+    record.info.should == ["mongo","db"]
+  end
+
+  it "should raise an error if trying to skip within #array" do
+    lambda { MongoPopulator.array("mongo", MongoPopulator.skip) }.should raise_error(StandardError)
+  end
+
   after(:each) do
     @collection.drop
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongo_populator
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-15 00:00:00.000000000Z
+date: 2011-10-01 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mongo
-  requirement: &70136711178880 !ruby/object:Gem::Requirement
+  requirement: &70105499047780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 1.3.1
   type: :runtime
   prerelease: false
-  version_requirements: *70136711178880
+  version_requirements: *70105499047780
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70136711178220 !ruby/object:Gem::Requirement
+  requirement: &70105499047300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *70136711178220
+  version_requirements: *70105499047300
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70136711177400 !ruby/object:Gem::Requirement
+  requirement: &70105499046840 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,7 +43,7 @@ dependencies:
         version: 0.10.0
   type: :development
   prerelease: false
-  version_requirements: *70136711177400
+  version_requirements: *70105499046840
 description: Mass populate MongoDB.
 email: ben.kerney -> gmail.com
 executables: []
@@ -53,11 +53,16 @@ files:
 - lib/mongo_populator/collection_additions.rb
 - lib/mongo_populator/factory.rb
 - lib/mongo_populator/mongo_array.rb
+- lib/mongo_populator/mongo_dictionary.rb
+- lib/mongo_populator/mongo_skip.rb
 - lib/mongo_populator/random.rb
 - lib/mongo_populator/record.rb
 - lib/mongo_populator.rb
 - spec/mongo_populator/collection_additions_spec.rb
 - spec/mongo_populator/factory_spec.rb
+- spec/mongo_populator/mongo_array_spec.rb
+- spec/mongo_populator/mongo_dictionary_spec.rb
+- spec/mongo_populator/mongo_skip_spec.rb
 - spec/mongo_populator/random_spec.rb
 - spec/mongo_populator/record_spec.rb
 - spec/README.md
@@ -68,6 +73,7 @@ files:
 - LICENSE
 - Rakefile
 - README.md
+- TODO.md
 homepage: http://github.com/bak/mongo_populator
 licenses: []
 post_install_message: