randomperson 1.2.0 → 1.3.0

data/.gitignore

@@ -21,3 +21,4 @@ vendor/
 bin/
 docs/
 .yardoc/
+.rbx/

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+v1.3.0 Tuesday the 11th of September 2012
+
+* Quicker to get data out if you're not bothered about the demographic make up.
+* Better error handling.
+* Much easier to find out which name classes have been loaded.
+
+----
+
 v1.2.0 Wednesday the 22nd of August 2012
 
 * Removed the evil evals.

data/README.markdown

@@ -14,7 +14,7 @@ Development branch:
 
 ## QUICK NOTE!
 
-This was the first Ruby library I wrote. I'm adding specs and improving the code now I've half an idea of what I should be doing, but I'd really, *really* appreciate it that if you do see something is wrong or doesn't work for you or you've an idea for improvement **let me know**. Wow, Github makes this so easy, just go for it! I'll be happy to help and happy for the help.
+I'd really, *really* appreciate it that if you see something is wrong or doesn't work for you or you've an idea for improvement **let me know**. Wow, Github makes this so easy, just go for it! I'll be happy to help and happy for the help. Bonus points for a topic branch too!
 
 
 ## Why did I write this?
@@ -29,8 +29,21 @@ It also has unicode characters, so it'll give your database a real test. At leas
 ## Installation:
 
 		gem install randomperson
+		
+## Super quick start! ##
 
-## USAGE:
+For those with a short attention span:
+
+		require 'randomperson'
+
+		r = RandomPerson() # don't forget the brackets!
+		r.generate  # => each time this will generate a new person.
+		
+The demographics will be randomly selected.
+
+## USAGE: ##
+
+For those with more willpower:
 
 The original API (if you can call it that) was very clunky so I've endeavoured to improve it by adding a nice facade over the top. I'll start off using that but as the examples move along I might do some things "the old fashioned way" by using some of the classes underlying everything directly, just so you know what's going on under there. If you see several ways of doing the same thing don't freak out! You're probably best using the stuff just below here.
 
@@ -49,7 +62,7 @@ So, to generate 1000 random people with Spanish names, between the ages of 16 an
 
 Output:  
 
-  Bartolomé Andrés de Elixaeberna age: 20 born: 28-Apr-1990  
+>  Bartolomé Andrés de Elixaeberna age: 20 born: 28-Apr-1990  
   Fabiana Cordero Balmaceda age: 21 born: 14-Jun-1989  
   Jorge Alas Albarracin age: 29 born: 16-Apr-1981  
   Eufemia Berlanga de Sergi age: 33 born: 25-Jan-1977  
@@ -69,7 +82,7 @@ Here's an example using the Thai Romanised data:
 
 Output:  
  
-  Yongchaiyuth Sripituksakul Puntasrima age: 39 born: 29-Mar-1971  
+>  Yongchaiyuth Sripituksakul Puntasrima age: 39 born: 29-Mar-1971  
   Sri-Patana Wattanasin age: 77 born: 04-Feb-1933  
   Wattana Rojjanasukchai age: 7 born: 27-Jun-2003  
   Ban Sukbunsung age: 85 born: 07-Sep-1925  
@@ -219,7 +232,8 @@ etc etc
 or you can do things the old fashioned way (but why? anyway...)
 
 		require 'namefiles/spanish-female-first'   
-		#obviously you need to use the path from where you are or where the script will run from
+		# obviously you need to use the path from where you are 
+		# or where the script will run from
   
 		r.demographic["My fancy demo"].femalefirst = RandomPerson::Names::SpanishFemaleFirst.new
 
@@ -246,24 +260,21 @@ English males:
     r.demographic.add_English_Male
 
 
-If you need to check what's loaded, have a look in the instance variables of the demographic:
+If you need to check what's loaded, use `loaded_classes`
 
-		r.demographics["Mix n match"].malefirst.class.name  
-> => "RandomPerson::Names::SpanishMaleFirst"
+		r.demographics["French"].loaded_classes
 
-    r.demographics["Mix n match"].femalefirst.class.name  
-> => "RandomPerson::Names::SpanishFemaleFirst"
+> # => {:femalefirst=>"French_Female_First", :last=>"French_Last", :malefirst=>"French_Male_First"}
 
-    r.demographics["Mix n match"].last.class.name  
-> => "RandomPerson::Names::SpanishLast"
+Or, see all the demographics' loaded classes:
 
-    r.demographics["Mix n match"].prefix.class.name  
-> => "RandomPerson::Names::SpanishPrefix"
+    r.demographics.loaded_classes
     
-    r.demographics["Mix n match"].suffix.class.name  
-> => "NilClass"
-    
-  
+And (because I'm really lazy and like convenience), this does the same:
+
+    r.loaded_classes
+
+
 ## NEGATIONS
 
 Sometimes you'll want to load something but not another, you can do this by prepending _not_ to the things you don't want. For example, to get the Thai names that are in Thai script and not romanised:
@@ -357,62 +368,91 @@ If you do make your own name file then fork this project and send me a pull requ
 
 These are current name files in the library:
 
-AmericanFemaleFirst  
-AmericanLast  
-AmericanMaleFirst  
-AmericanPrefix  
-AmericanSuffix  
-AncientGreekFemaleFirst  
-AncientGreekLast  
-AncientGreekMaleFirst  
-AnyLast  
-BasqueFemaleFirst  
-BasqueLast  
-BasqueMaleFirst  
-BritishPrefix  
-BritishSuffix  
-EnglishFemaleFirst  
-EnglishLast  
-EnglishMaleFirst  
-EnglishPrefix  
-FinnishFemaleFirst  
-FinnishLast  
-FinnishMaleFirst  
-FinnishPrefix  
-FrenchFemaleFirst  
-FrenchLast  
-FrenchMaleFirst  
-GermanFemaleFirst  
-GermanLast  
-GermanMaleFirst  
-ScottishFemaleFirst  
-ScottishLast  
-ScottishMaleFirst  
-ScottishPrefix  
-SpanishFemaleFirst  
-SpanishLast  
-SpanishMaleFirst  
-SpanishPrefix  
-SwedishFemaleFirst  
-SwedishLast  
-SwedishMaleFirst  
-ThaiFemaleFirst  
-ThaiFirst  
-ThaiLast  
-ThaiMaleFirst  
-ThaiRomanisedFemaleFirst  
-ThaiRomanisedLast  
-ThaiRomanisedMaleFirst  
-WelshFemaleFirst  
-WelshLast  
-WelshMaleFirst  
-WelshPrefix  
+American\_Female\_First  
+American\_Last  
+American\_Male\_First  
+American\_Prefix  
+American\_Suffix  
+Ancient\_Greek\_Female\_First  
+Ancient\_Greek\_Last  
+Ancient\_Greek\_Male\_First  
+Any\_Last  
+Basque\_Female\_First  
+Basque\_Last  
+Basque\_Male\_First  
+British\_Prefix  
+British\_Suffix  
+English\_Female\_First  
+English\_Last  
+English\_Male\_First  
+English\_Prefix  
+Finnish\_Female\_First  
+Finnish\_Last  
+Finnish\_Male\_First  
+Finnish\_Prefix  
+French\_Female\_First  
+French\_Last  
+French\_Male\_First  
+German\_Female\_First  
+German\_Last  
+German\_Male\_First  
+Scottish\_Female\_First  
+Scottish\_Last  
+Scottish\_Male\_First  
+Scottish\_Prefix  
+Spanish\_Female\_First  
+Spanish\_Last  
+Spanish\_Male\_First  
+Spanish\_Prefix  
+Swedish\_Female\_First  
+Swedish\_Last  
+Swedish\_Male\_First  
+Thai\_Female\_First  
+Thai\_First  
+Thai\_Last  
+Thai\_Male\_First  
+Thai\_Romanised\_Female\_First  
+Thai\_Romanised\_Last  
+Thai\_Romanised\_Male\_First  
+Welsh\_Female\_First  
+Welsh\_Last  
+Welsh\_Male\_First  
+Welsh\_Prefix  
 
 
 ## ACCURACY OF NAMES AND RATIOS
 
 I've taken bits and pieces from wherever I could get them, so if you see something is wrong then either let me know or produce a patch, just have a look at the help links on Github for how to do it. I'll also add you name to this readme, and worldly fame will be yours.
 
+## PASS A BLOCK TO HANDLE ERRORS ##
+
+If you try calling a demographic that doesn't exist yet, an error will be raised. There is a default handler for this, and it will output a warning, and the result returned will be nil. If you wish, you may supply a block to handle the error.
+
+e.g.
+
+    r.person # => this will produce a person, with a randomised demographic
+    r.demographic("French").add_French 
+    r.person # => this will produce a person too, with a French demographic
+    r.person "French" # => French again
+    
+    # This raises an error, caught by the default block
+    # which prints a warning to stdout
+    r.person "British" # => That demographic does not exist!
+    
+    r.person "British" do |error|
+      warn "There are no British people here, this is Scotland!"
+    end
+    # => "There are no British people here, this is Scotland!"
+    
+The default block can be set via:
+
+    RandomPerson::Facade.default_error_block= #... put your block here, e.g
+    RandomPerson::Facade.default_error_block= ->(error){ warn "-> #{error}" }
+
+Or if you're lazy like me and have an instance floating around:
+
+    r.class.default_error_block= ->(error){ warn "-> #{error}" }
+
 ## TODO:
 
 There's lots to do. Lot of repetition and ugly bits here and there, but it works so I'll get round to it when I can.
@@ -421,7 +461,7 @@ There's lots to do. Lot of repetition and ugly bits here and there, but it works
 
 Peter Hickman for writing the original library in Perl that inspired this on in Ruby.
 
-My good friends:
+My good friends:  
 Johan Bergsten for helping me out with the Swedish names.  
 HALLOJULIA (hayl yeah!) for helping me with the German names.  
 Aino Rissanen for helping me with the Finnish names.  

data/lib/randomperson.rb

@@ -5,6 +5,9 @@ module RandomPerson
 
   #require all the scaffolding
   
+  require 'set'
+  require 'date'
+  
   require_relative './randomperson/version.rb'
   require_relative './randomperson/ext/array.rb'
   require_relative './randomperson/ext/date.rb'
@@ -19,11 +22,37 @@ module RandomPerson
   require_relative './randomperson/person.rb'
   #require_relative './randomperson/ratio.rb'
 
+  class DemoHash < Hash
+    def loaded_classes
+      if @loaded_classes.nil?
+        @loaded_classes = Hash.new
+        self.each do |key,demographic|
+          @loaded_classes[key] = demographic.loaded_classes
+        end
+      end
+      @loaded_classes
+    end
+
+    alias :old_store :store
+    alias :"[]=" :store
+
+    def store( key, value )
+      @loaded_classes ||= Hash.new
+      @loaded_classes[key] = value
+      old_store key, value
+    end
+  end
 
   class Facade
 
+    # @return [Hash{String => RandomPerson::Demographic}]
     def demographics
-      @demos ||= {}
+      @demos ||= DemoHash.new
+    end
+
+    # @return [Hash]
+    def loaded_classes
+      demographics.loaded_classes
     end
 
     #class instance variable to keep track of generators
@@ -32,7 +61,10 @@ module RandomPerson
     end
 
 
-    # little factory
+    # A little factory
+    # @param [String,Symbol,Integer] name The key for retrieving the demographic.
+    # @param [Hash] opts Option hash to pass to Demographic.new
+    # @see Demographic#initialize
     def demographic( name=nil, opts={} )
       if name.kind_of? Hash
         opts = name
@@ -60,40 +92,28 @@ module RandomPerson
 
     # The last person generated.
     # If a demographic name is given that is different to the last then a new person is generated. If no name is given then the last is used.
-    # @param [String] demo_name The key of the demographic to use, e.g "American Ladies".
-    def person( demo_name=nil )
+    # @param [String,Symbol,Integer] name The key for retrieving the demographic.
+    # @param [#call] block Error handler for when a key is given that does not exist.
+    # @return [RandomPerson::Person]
+    def person( demo_name=nil, &block )
       person, last_demo_name = 
         if demo_name.nil? 
-
           if @person.nil?
-
             # either generate a new one
-            gen_new( demo_name ) # gen a new person and get back demo name
-          else 
-
+            gen_new( demo_name, &block ) # gen a new person and get back demo name
+          else
             #  get last one
             [@person, @last_demo_name]
           end
         else # demo name given
-
           if demographics.has_key? demo_name
-
             if demo_name == @last_demo_name
-
               [@person, @last_demo_name]
             else
-
-              gen_new( demo_name )
-            end
-          else 
-
-            if demographics.nil? || demographics.empty?
-
-              raise "No demographics have been selected yet! Try something like r.demographic.add_Spanish..." 
-            else # that demo name doesn't exist...
-
-              [nil, @last_demo_name] # so preserve the last good demo name
+              gen_new( demo_name, &block )
             end
+          else
+            gen_new( demo_name, &block )
           end
         end
         return nil if person.nil?
@@ -103,37 +123,68 @@ module RandomPerson
     end
 
     
-    # generate a new person
-    # either with the last demographic loaded, or a specific one by passing the name.
-    def generate( demo_name=nil )
-      ds = gen_new( demo_name )
+
+    def generate( demo_name=nil, &block )
+      ds = gen_new( demo_name, &block )
       ds.nil? ? nil : ds.first
     end
 
 
-    # If not given a demographic's name then the *last demographic defined* will be used.
-    def gen_new( demo_name=nil )
-      if demographics.nil? || demographics.empty?
-        raise "No demographics have been selected yet! Try something like r.demographic.add_Spanish..." 
-      end
+    # For when a demo isn't given but you still need one.
+    # @return [String, RandomPerson::Demographic]
+    def generate_demo
+      Demographic.load
+      yesses = %w{prefix suffix female -male last}.map {|word|
+        Demographic.available_name_files.classify_true(word).to_a.sample
+      }
+      demo = self.demographic
+      demo.require_and_add yesses
+      [demo.name, demo]
+    end
+
+    DEFAULT_gen_new_BLOCK = ->(error) {
+      warn error.message
+    }
+
+
+    def self.default_error_block
+      @default_gen_new_error_block ||= DEFAULT_gen_new_BLOCK
+    end
+
+    def self.default_error_block=( block )
+      @default_gen_new_error_block = block
+    end
+
+
+    # If not given a demographic's name then the *last demographic defined* will be used. If there is no demographic already defined a new one will be created. If a key is given but does not exist then the supplied block will be called. If no block is given an exception will be raised.
+    # @param [String,Symbol,Integer] name The key for retrieving the demographic.
+    # @param [#call] block Default for when a key is given that does not exist.
+    def gen_new( demo_name=nil, &block )
+      block = self.class.default_error_block if block.nil?
       demo_name, demo = if demo_name.nil?
-        demographics.to_a.last # this produces a 2 dimensional array
-      else
-        demographics.assoc(demo_name)
-      end
-      
-      if demo_name
-        @last_demo_name = demo_name
-        unless generators.has_key? demo.name
-          generators[demo.name] = Generator.make_generator( demo )
+        if demographics.nil? || demographics.empty?
+          generate_demo
+        else
+          demographics.to_a.last # this produces a 2 dimensional array
         end
-  
-        @person = generators[@last_demo_name].call 
-          
-        [@person, @last_demo_name]
       else
-        nil
+        if ds = demographics.assoc(demo_name)
+          ds
+        else
+          fail "That demographic does not exist!" 
+        end
+      end
+
+      @last_demo_name = demo_name
+      unless generators.has_key? demo_name
+        generators[demo_name] = Generator.make_generator( demo )
       end
+
+      @person = generators[demo_name].call 
+        
+      [@person, demo_name]
+    rescue => error
+      block.call(error)
     end
 
   end # class

data/lib/randomperson/demographic.rb

@@ -28,12 +28,24 @@ module RandomPerson
     # the name of this demographic
     attr_accessor :name
 
+
+    def loaded_classes
+      @loaded_classes ||= {}
+    end
+
+
     attr_accessor :malefirst, :femalefirst, :last, :gender_ratio, :age_lower, :age_upper, :prefix, :suffix #,:age_ratio
-    
+
+
+    alias :lastname :last
+    alias :male_first :malefirst
+    alias :female_first :femalefirst
+
+
     def self.available_name_files
       @available_name_files ||= Set.new
     end
-    
+
 
     # Initialize the class with the parameters for the population you want.
     # @example 
@@ -47,9 +59,14 @@ module RandomPerson
       @gender_ratio = opts[:gender_ratio] || [1,1] #default
       @age_lower = opts[:age_lower] || 0
       @age_upper = opts[:age_upper] || 115
-      
+      @loaded_classes ||= {}
+
+      self.class.load
+    end
 
-      Demographic.available_name_files.merge Demographic.load_names
+    # puts the demo files into the class instance var
+    def self.load
+      self.available_name_files.merge self.load_names if self.available_name_files.empty?
     end
 
 

data/lib/randomperson/loader.rb

@@ -44,6 +44,7 @@ module RandomPerson
         patterns.each do |ps|
           if ps.all?{|p| klass =~ /#{p}/ }
             instance_variable_set( "@#{ps.join.downcase}", klass.to_constant.new)
+            instance_variable_get( :@loaded_classes ).store ps.join.downcase.to_sym, klass.to_s.split("::").last.scan( /([A-Z][a-z]+)/ ).flatten.join("_")
           end # if
         end
         klass

data/lib/randomperson/names/american-suffix.rb

@@ -24,7 +24,8 @@ module RandomPerson
 
           @possibles.each_pair{|k,v| break v if k === r }
         end #
-        
+
+        super
       end # initialize
       
     end # class

data/lib/randomperson/names/british-prefix.rb

@@ -14,8 +14,8 @@ module RandomPerson
         @names = Names
         @formats_ratiod = [ 0..47, 48..49, 50..70, 71..87, 88..99]
         @possibles = Hash[ @formats_ratiod.zip @names ]
-
         @on_execute = for_prefixes( 'Miss', 'Mr' )
+        super
       end
       
     end

data/lib/randomperson/names/english-prefix.rb

@@ -15,7 +15,7 @@ module RandomPerson
         @formats_ratiod = [ 0..47, 48..49, 50..70, 71..87, 88..99]
         @possibles = Hash[ @formats_ratiod.zip @names ]
         @on_execute = for_prefixes( 'Miss', 'Mr' )
-        
+        super
       end
       
     end

data/lib/randomperson/names/finnish-prefix.rb

@@ -17,7 +17,7 @@ module RandomPerson
         @possibles = Hash[ @formats_ratiod.zip @names ]
         
         @on_execute = for_prefixes( @names[3], @names.first )
-        
+        super
       end # initialize
       
 

data/lib/randomperson/version.rb

@@ -1,3 +1,3 @@
 module RandomPerson
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/spec/randomperson_spec.rb

@@ -63,9 +63,6 @@ shared_examples "clear or reset" do
   specify { r.should be_a_kind_of RandomPerson::Facade }
   specify { r.generators.should be_empty }
   specify { r.demographics.should be_empty }
-  specify { expect { r.person }.to raise_error }
-  specify { expect { r.generate }.to raise_error }
-  specify { expect { r.gen_new }.to raise_error }
 end
 
 
@@ -148,21 +145,32 @@ describe RandomPerson do
         end
       end
     end
+
     context "With no demographic" do
       context "Already loaded" do
+        before { r.demographics.clear }
         subject { r.person }
-        specify { expect { subject }.to raise_error }
-        context "and given a demo name" do
+        it { should be_a_kind_of RandomPerson::Person }
+        context "and given a demo name (that does not exist)" do
           subject { r.person "Not loaded" }
-          specify { expect { subject }.to raise_error }
+          it { should be_nil }
         end
       end
       context "Because they've been cleared" do
+        before { r.demographics.clear }
         subject { r.person }
-        specify { expect { subject }.to raise_error }
-        context "and given a demo name" do
+        it { should be_a_kind_of RandomPerson::Person }
+        context "and given a demo name (that does not exist)" do
           subject { r.person "Been cleared" }
-          specify { expect { subject }.to raise_error }
+          it { should be_nil }
+          context "and given a block with a raise" do
+            subject { 
+              r.person "Does not exist" do
+                fail "This demo name does not exist!"
+              end
+            }
+            specify { expect { subject }.to raise_error }
+          end
         end
       end
     end
@@ -205,7 +213,8 @@ describe RandomPerson do
     let(:r) { RandomPerson() }
     context "Before a demographic has been loaded" do
       subject { r.generate }
-      specify { expect { subject }.to raise_error }
+      it { should_not be_nil }
+      it { should be_a_kind_of RandomPerson::Person }
     end
     context "When there is a demographic loaded" do
       before(:all) {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: randomperson
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-22 00:00:00.000000000 Z
+date: 2012-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: wirble