mack-data_factory 0.7.1 → 0.7.1.1

data/lib/mack-data_factory/content_generator.rb

@@ -4,7 +4,7 @@ module Mack
   module Data
     module Factory
 
-      class FieldContentGenerator
+      class FieldContentGenerator # :nodoc:
         class << self
           def alpha_generator
             @alpha_gen = Proc.new do |def_value, rules, index|

data/lib/mack-data_factory/core_extensions/kernel.rb

@@ -11,19 +11,19 @@ module Kernel
   # Convenient routine to create an execution chain of factories
   #
   # Example:
-  #     factories(:foo) do
-  #         UserFactory.create(1)
-  #         UserFactory.create(2, :diff_firstname)
-  #     end
+  #   factories(:foo) do
+  #     UserFactory.create(1)
+  #     UserFactory.create(2, :diff_firstname)
+  #   end
   #
   # Then to execute the chains, you'll need to call run_factories, and
   # pass in the name of the chain you want to execute.  
   #
-  # Example:
-  #     run_factories(:foo)
+  #   run_factories(:foo)
   #
-  # @tag -- the name of the factory chain
-  # @block -- the proc to be executed later
+  # <i>Parameters:</i>
+  #   tag: the name of the factory chain
+  #   block: the proc to be executed later
   #
   def factories(tag, &block)
     raise "factories: block needed" if !block_given?
@@ -31,19 +31,15 @@ module Kernel
   end
   
   #
-  # Run defined factory chain
+  # Run defined factory chain defined using factories method.
+  #
+  # <i>Parameters:</i>
+  #   tag: the name of the factory chain to be run
   #
-  # @see factories
-  # @tag -- the name of the factory chain to be run
-  # @return true if successful, false otherwise
   def run_factories(tag)
     runners = fact_registry.registered_items[tag]
     return false if runners == nil
-    
-    runners.each do |r|
-      r.call
-    end
-    
+    runners.each { |r| r.call }
     return true
   end
   

data/lib/mack-data_factory/data_factory.rb

@@ -1,4 +1,4 @@
-module Mack
+module Mack # :nodoc:
   module Data # :nodoc:
     #
     # Add factory capability to a class.
@@ -7,15 +7,26 @@ module Mack
     # define a scope for different situation, and set a custom content generator 
     # for field that doesn't want to use the default content generator.
     #
-    # For more information and usage, please read README file
+    # You must add this module when creating a factory class; and the name
+    # of the factory class should be following this format:
+    #   #{model_name_camelcase}Factory
+    # 
+    # <i>Example:</i>
+    #   If there's a model class named "Item", then its factory must be:
+    #
+    #   class ItemFactory
+    #     include Mack::Data::Factory
+    #     ...
+    #   end
+    #
+    # See Mack::Data::Factory::ClassMethods for the factory API and examples.
     #
-    # author: Darsono Sutedja
-    # July 2008
+    # Author:: Darsono Sutedja
+    # Date:: July 2008
     #
     module Factory      
       
-      # make sure the data factory API is available to the class that includes it
-      def self.included(base)
+      def self.included(base) # :nodoc:
         base.extend ClassMethods
       end
       
@@ -24,17 +35,42 @@ module Mack
         #
         # Run the factory to produce n number of objects.
         #
-        # Example:
-        # class CarFactory
-        #    include Mack::Data::Factory
-        #    field :name, :default => "honda" { |def_value, rules, index| "#{def_value} #{['civic', 'accord', 'pilot'].randomize[0]}"}
-        # end
+        # <i>Example:</i>
+        # 
+        #   class CarFactory
+        #     include Mack::Data::Factory
+        #     field(:name, :default => "honda") do |def_value, rules, index| 
+        #       "#{def_value} #{['civic', 'accord', 'pilot'].randomize[0]}"
+        #     end
+        #   end
+        # 
+        #   CarFactory.create(100) #=> will produce 100 cars whose name is "honda xxx" where xxx is a random item from ['civic', 'accord', 'pilot']
+        # 
+        # <i>Scoping:</i>
         #
-        # CarFactory.create(100) #=> will produce 100 cars whose name is "honda xxx" where xxx is a random item from ['civic', 'accord', 'pilot']
+        # In some instances, you may want different settings in the factory for different test scope.  
+        # You can achieve this by doing the following:
+        # 
+        #     class UserFactory
+        #         include Mack::Data::Factory
+        # 
+        #         field :username, :default => "planters", :length => 25, :content => :alpha
+        #         field :password, :default => "roastedPeanuts", :immutable => true
+        # 
+        #         scope_for(:long_username) do
+        #             field :username, :default => "planters", :length => 128, :content => :alpha
+        #         end
+        #     end
+        # 
+        # The above example defined a scoping for "long_username", which you can use by calling:
+        #   UserFactory.create(100, :long_username)
+        # 
+        # When a scope is defined and called, the field defined in the block will overwrite the default field listing 
+        # in that class.  Scopes in the factory is independent to each other, so one scope cannot affect the others.
         #
-        # params:
-        # * num - how many objects to produce
-        # * scope - run the factory in a named scope
+        # <i>Parameters:</i>
+        #   num:  how many objects to produce
+        #   scope:  run the factory in a named scope.  By default the factory will be run in _default_ scope
         #
         def create(num, scope = :default)
           factory_name = self.name.underscore
@@ -75,15 +111,85 @@ module Mack
         end
         
         #
-        # Define a field with its default value and rules and an optional content generator
-        # for this factory
+        # Define a field for the factory class, and set the name of the field,
+        # any options for the field, and optionally specify a block that serves as the custom 
+        # content generator.
+        #
+        # The options can be categorized into the following:
+        # * default value (e.g. :default_value => "foo")
+        # * whether it's immutable or not (e.g. :immutable => true, and by default it's false)
+        # * the field's content type (e.g. :content => :alpha)
+        # * and the rules on how to generate the content (rules are contextually dependent on the content type).
+        #
+        # <i>Example:</i>
+        #   class UserFactory
+        #     include Mack::Data::Factory
+        #     field :full_name, :content => :name
+        #     field :created_at, :content => :time, :start_time => 2.days.ago, :end_time => 1.day.from_now
+        #   end
+        #
+        # The following are all the supported content types and its rules:
+        # 
+        # <i>Strings and Numbers</i>
+        # * :alpha --> alphabets.  rules: [:length, :min_length, :max_length]
+        # * :alphanumeric --> alphabets and number.  rules: same as :alpha
+        # * :numeric --> numbers [optional, because if the field's default value is number, its content type will automatically set to numeric)
+        # <i>Time and Money</i>
+        # * :time --> generate random time object.  rules: [:start_time, :end_time].  It will generate random time between the given start and end time if available, otherwise it'll generate random time between 'now' and 1 day from 'now'
+        # * :money --> generate random amount of money. rules: [:min, :max].  It will generate random money amount (of BigDecimal type) between the given min and max amount.
+        # <i>Internet related content</i>
+        # * :email --> generate random email address
+        # * :username --> generate random username
+        # * :domain --> generate random domain name
+        # <i>Name related info</i>
+        # * :firstname --> generate first name
+        # * :lastname --> generate last name
+        # * :name --> generate full name
+        # <i>Address related info</i>
+        # * :city --> generate city name
+        # * :streetname --> generate street name
+        # * :state --> generate state.  rules: [:country --> :us or :uk, :abbr --> true if you want a abbreviated state name (us only)]
+        # * :zipcode --> generate zipcode. rules: [:country --> :us or :uk]
+        # * :phone --> generate phone number
+        # <i>Company info</i>
+        # * :company --> generate company name.  rules: [:include_bs --> include sales tag line]
+        #   example:  field, :content => :company, :include_bs => true
+        #   could generate something like:
+        #       Fadel-Larkin
+        #       monetize cross-media experiences
+        #
+        # <i>Parameters:</i>
+        #  model_attrib_sym: the name of the field
+        #  options: the options for the field.  
+        #  block: the optional custom content generator
         #
         def field(model_attrib_sym, options = {}, &block)
           field_manager.add(scope, model_attrib_sym, options, &block)
         end
         
         # 
-        # Define an association rule for this field
+        # Define an association rule for this field.
+        #
+        # <i>Example:</i>
+        #   class ItemFactory
+        #     include Mack::Data::Factory
+        #     ...
+        #     association :owner_id, {:user => 'id'}, :random
+        #   end
+        #   
+        # The above example states that for each item generated, its owner_id will
+        # come from user's id field. But which user?  since the association rule
+        # is set to random, then the generator will pick random user.
+        #
+        # <i>Supported association rules: </i>
+        #   :first:: If there are 10 users, then the item will get associated with user #0.
+        #   :last:: If there are 10 users, then the item will get associated with user #10.
+        #   :random:: If there are 10 users, then the item will get associated with user #rand(10)
+        #   :spread:: If there are 3 users, then the items' association will be spread out (i.e. 6 items will have id, sequentially, [0, 1, 2, 0, 1, 2])
+        #
+        # <i>Parameters:</i>
+        #   model_attrib_sym: the name of the field
+        #   assoc_map: the association map
         #
         def association(model_attrib_sym, assoc_map, assoc_rule = :spread)
           field(model_attrib_sym, {:default => {:df_assoc_map => assoc_map}, :assoc => assoc_rule})
@@ -91,8 +197,11 @@ module Mack
         
         # 
         # Define a scope in the factory.
-        # Any field defined in a scope will overwrite its cousin in the default scope.
+        # Any field defined in a scope will overwrite its sibling in the default scope.
         #
+        # <i>Parameters:</i>
+        #   tag: name of the scope
+        # 
         def scope_for(tag)
           set_scope(tag)
           yield

data/lib/mack-data_factory/field.rb

@@ -4,7 +4,7 @@ module Mack
     class RegistryMap < Mack::Utils::RegistryMap # :nodoc:
     end
     
-    class Field
+    class Field # :nodoc:
       attr_accessor :field_name
       attr_accessor :field_value
       attr_accessor :field_value_producer

data/lib/mack-data_factory/field_manager.rb

@@ -1,6 +1,6 @@
 module Mack
   module Data          
-    class FieldMgr
+    class FieldMgr # :nodoc:
       attr_reader :scopes
       
       def initialize

data/lib/mack-data_factory/orm_api_bridge/bridge.rb

@@ -1,9 +1,41 @@
 module Mack
   module Data
     
-    class OrmRegistry < Mack::Utils::RegistryList # :nodoc:
+    #
+    # Registry list (LIFO) for all valid handlers.
+    #
+    # <i>Example:</i>
+    # OrmRegistry.add(Mack::Data::OrmBridge::ActiveRecord.new)
+    #
+    class OrmRegistry < Mack::Utils::RegistryList
     end
     
+    #
+    # Different ORMs have different API at getting object from the store.
+    # The ORM bridge is an attempt to have a common API that the data_factory
+    # can use to get at the objects it needed.  
+    # 
+    # Currently there are 2 orm bridges implemented: DataMapper and ActiveRecord.
+    # But developers are free to develop another adapter.
+    #
+    # Although this feature is called an "ORM" bridge, the API that it's trying
+    # to bridge doesn't necessarily have to be of an ORM.  As long as the module
+    # you're bridging can respond to these API, you can use it as a valid adapter.
+    # 
+    # This feature is an advanced feature of the Data Factory, and it's very useful
+    # in a case where you have some legacy data sitting somewhere, or you may have
+    # a collection of data that is obtained through a very costly sql query (so doing
+    # it many times is obviously not acceptable).  So you may want to build a class
+    # that can preload all the data, then register itself to the OrmRegistry.
+    #
+    # The most important method that a "handler" must implement is the can_handle
+    # method.  When the DataFactory is handling a certain object, it will attempt
+    # to find the appropriate API module that can handle that object, so it will
+    # ask all the registered handlers of the OrmRegistry, and the first one to
+    # answer yes to the question will be the handler of the object.
+    # When a handler say yes to the question, it's expected that the handler
+    # implement all the methods defined in the Bridge class.
+    #
     class Bridge
       
       def initialize
@@ -11,22 +43,58 @@ module Mack
         OrmRegistry.add(Mack::Data::OrmBridge::DataMapper.new)
       end
       
+      # 
+      # Get a record from the given _obj_ model.
+      # In active record implementation: this will get translated to
+      # obj.find(*args)
+      #
+      # <i>Parameters:</i>
+      #   obj: the object model class
+      #   args: the list of arguments
+      #
       def get(obj, *args)
         handler(obj).get(obj, *args)
       end
       
+      #
+      # Get all records from the given _obj_ model
+      #
+      # <i>Parameters:</i>
+      #   obj: the object model class
+      #   args: the list of arguments
+      #
       def get_all(obj, *args)
         handler(obj).get_all(obj, *args)
       end
       
+      #
+      # Get the first record from the given _obj_ model
+      #
+      # <i>Parameters:</i>
+      #   obj: the object model class
+      #   args: the list of arguments
+      #
       def get_first(obj, *args)
         handler(obj).get_first(obj, *args)
       end
       
+      # Get the total number of records for the given _obj_ model
+      #
+      # <i>Parameters:</i>
+      #   obj: the object model class
+      #   args: the list of arguments
+      #
       def count(obj, *args)
         handler(obj).count(obj, *args)
       end
       
+      #
+      # Commit changes made to the _obj_ model
+      #
+      # <i>Parameters:</i>
+      #   obj: the object model class
+      #   args: the list of arguments
+      #
       def save(obj, *args)
         handler(obj).save(obj, *args)
       end

data/lib/mack-data_factory/orm_api_bridge/orm/active_record.rb

@@ -1,7 +1,7 @@
 module Mack
   module Data
-    module OrmBridge
-      class ActiveRecord
+    module OrmBridge # :nodoc:
+      class ActiveRecord # :nodoc:
         
         def can_handle(obj)
           return false if !Object.const_defined?('ActiveRecord')

data/lib/mack-data_factory/orm_api_bridge/orm/data_mapper.rb

@@ -1,7 +1,7 @@
 module Mack
   module Data
-    module OrmBridge
-      class DataMapper
+    module OrmBridge # :nodoc:
+      class DataMapper # :nodoc:
         
         def can_handle(obj)
           return false if !Object.const_defined?('DataMapper')

data/lib/mack-data_factory/orm_api_bridge/orm/default.rb

@@ -1,7 +1,7 @@
 module Mack
   module Data
     module OrmBridge # :nodoc:
-      class Default
+      class Default # :nodoc:
         
         def can_handle(obj)
           return true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mack-data_factory
 version: !ruby/object:Gem::Version 
-  version: 0.7.1
+  version: 0.7.1.1
 platform: ruby
 authors: 
 - Darsono Sutedja
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-08 00:00:00 -04:00
+date: 2008-09-14 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,34 +42,6 @@ files:
 - lib/mack-data_factory/orm_api_bridge/orm/default.rb
 - lib/mack-data_factory.rb
 - README
-- doc/classes/Kernel.html
-- doc/classes/Mack/Data/Bridge.html
-- doc/classes/Mack/Data/Factory/ClassMethods.html
-- doc/classes/Mack/Data/Factory/FieldContentGenerator.html
-- doc/classes/Mack/Data/Factory.html
-- doc/classes/Mack/Data/Field.html
-- doc/classes/Mack/Data/FieldMgr.html
-- doc/classes/Mack/Data/OrmBridge/ActiveRecord.html
-- doc/classes/Mack/Data/OrmBridge/DataMapper.html
-- doc/classes/Mack/Data/OrmBridge/Default.html
-- doc/classes/Mack.html
-- doc/created.rid
-- doc/files/lib/mack-data_factory/content_generator_rb.html
-- doc/files/lib/mack-data_factory/core_extensions/kernel_rb.html
-- doc/files/lib/mack-data_factory/data_factory_rb.html
-- doc/files/lib/mack-data_factory/field_manager_rb.html
-- doc/files/lib/mack-data_factory/field_rb.html
-- doc/files/lib/mack-data_factory/orm_api_bridge/bridge_rb.html
-- doc/files/lib/mack-data_factory/orm_api_bridge/orm/active_record_rb.html
-- doc/files/lib/mack-data_factory/orm_api_bridge/orm/data_mapper_rb.html
-- doc/files/lib/mack-data_factory/orm_api_bridge/orm/default_rb.html
-- doc/files/lib/mack-data_factory_rb.html
-- doc/files/README.html
-- doc/fr_class_index.html
-- doc/fr_file_index.html
-- doc/fr_method_index.html
-- doc/index.html
-- doc/rdoc-style.css
 has_rdoc: true
 homepage: http://www.mackframework.com
 post_install_message: