@@ -113,7 +113,7 @@ begin YARD::Rake::YardocTask.new("yardoc") do |t| t.options << '--protected' - t.options << '-q' + # t.options << '-q' # t.files << '...anyglobshere...' end rescue Exception Rakefile @@ -1 +1 @@ -See: http://wiki.datamapper.org/doku.php?id=what_needs_to_be_done +See: http://github.com/sam/dm-core/wikis TODO @@ -37,6 +37,8 @@ module DataMapper module Resource @@extra_inclusions = [] + + ## # # Appends a module for inclusion into the model class after # DataMapper::Resource. @@ -44,11 +46,12 @@ module DataMapper # This is a useful way to extend DataMapper::Resource while still retaining # a self.included method. # - # @param inclusion<Module> the module that is to be appended to the module - # after DataMapper::Resource + # @param [Module] inclusion the module that is to be appended to the module + # after DataMapper::Resource # - # @return <TrueClass, FalseClass> whether or not the inclusions have been - # successfully appended to the list + # @return [TrueClass, FalseClass] whether or not the inclusions have been + # successfully appended to the list + # @return <TrueClass, FalseClass> #- # @api public def self.append_inclusions(*inclusions) @@ -60,18 +63,19 @@ module DataMapper module Model @@extra_extensions = [] - # + ## + # # Extends the model with this module after DataMapper::Resource has been # included. # # This is a useful way to extend DataMapper::Model while # still retaining a self.extended method. # - # @param extension<Module> the module that is to be extend the model after - # after DataMapper::Model + # @param [Module] extensions the module that is to be extend the model after + # after DataMapper::Model # - # @return <TrueClass, FalseClass> whether or not the inclusions have been - # successfully appended to the list + # @return [TrueClass, FalseClass] whether or not the inclusions have been + # successfully appended to the list #- # @api public # @@ -160,18 +164,19 @@ module DataMapper ## # Setups up a connection to a data-store - # - # @param name<Symbol> a name for the context, defaults to :default - # @param uri_or_options<Hash{Symbol => String}, Addressable::URI, String> + # + # @param Symbol name a name for the context, defaults to :default + # @param [Hash{Symbol => String}, Addressable::URI, String] uri_or_options # connection information - # - # @return <Repository> the resulting setup repository - # - # @raise <ArgumentError> "+name+ must be a Symbol, but was..." indicates that - # an invalid argument was passed for name<Symbol> - # @raise <ArgumentError> "+uri_or_options+ must be a Hash, URI or String, but was..." - # indicates that connection information could not be gleaned from the given - # uri_or_options<Hash, Addressable::URI, String> + # + # @return Repository the resulting setup repository + # + # @raise ArgumentError "+name+ must be a Symbol, but was..." indicates that + # an invalid argument was passed for name[Symbol] + # @raise [ArgumentError] "+uri_or_options+ must be a Hash, URI or String, + # but was..." indicates that connection information could not be gleaned + # from the given uri_or_options<Hash, Addressable::URI, String> + # # - # @api public def self.setup(name, uri_or_options) @@ -201,20 +206,17 @@ module DataMapper end ## - # - # @details [Block Syntax] + # Block Syntax # Pushes the named repository onto the context-stack, # yields a new session, and pops the context-stack. # - # results = DataMapper.repository(:second_database) do |current_context| - # ... - # end - # - # @details [Non-Block Syntax] + # Non-Block Syntax # Returns the current session, or if there is none, # a new Session. # - # current_repository = DataMapper.repository + # @param [Symbol] args the name of a repository to act within or return, :default is default + # @yield [Proc] (optional) block to execute within the context of the named repository + # @demo spec/integration/repository_spec.rb def self.repository(*args, &block) # :yields: current_context if args.size > 1 raise ArgumentError, "Can only pass in one optional argument, but passed in #{args.size} arguments", caller @@ -243,7 +245,7 @@ module DataMapper ## # destructively migrates the repository upwards to match model definitions # - # @param <Symbol> name repository to act on, :default is the default + # @param [Symbol] name repository to act on, :default is the default def self.migrate!(name = Repository.default_name) repository(name).migrate! end @@ -251,7 +253,7 @@ module DataMapper ## # drops and recreates the repository upwards to match model definitions # - # @param <Symbol> name repository to act on, :default is the default + # @param [Symbol] name repository to act on, :default is the default def self.auto_migrate!(name = Repository.default_name) repository(name).auto_migrate! end lib/dm-core.rb @@ -26,7 +26,7 @@ module DataMapper 1.0/0 end - # + ## # A shorthand, clear syntax for defining one-to-one, one-to-many and # many-to-many resource relationships. # @@ -44,23 +44,23 @@ module DataMapper # * has n, :friendships => :friends # # identical to above example # - # @param cardinality <Integer, Range, Infinity> + # @param cardinality [Integer, Range, Infinity] # cardinality that defines the association type and constraints # @param name <Symbol> the name that the association will be referenced by # @param opts <Hash> an options hash # - # @option :through<Symbol> A association that this join should go through to form + # @option :through[Symbol] A association that this join should go through to form # a many-to-many association - # @option :class_name<String> The name of the class to associate with, if omitted + # @option :class_name[String] The name of the class to associate with, if omitted # then the association name is assumed to match the class name - # @option :remote_name<Symbol> In the case of a :through option being present, the + # @option :remote_name[Symbol] In the case of a :through option being present, the # name of the relationship on the other end of the :through-relationship # to be linked to this relationship. # - # @return <DataMapper::Association::Relationship> the relationship that was + # @return [DataMapper::Association::Relationship] the relationship that was # created to reflect either a one-to-one, one-to-many or many-to-many # relationship - # @raise <ArgumentError> if the cardinality was not understood. Should be a + # @raise [ArgumentError] if the cardinality was not understood. Should be a # Integer, Range or Infinity(n) # # @api public @@ -103,18 +103,17 @@ module DataMapper relationship end - # + ## # A shorthand, clear syntax for defining many-to-one resource relationships. # # @example [Usage] # * belongs_to :user # many_to_one, :friend # * belongs_to :friend, :class_name => 'User' # many_to_one :friends # - # @param name<Symbol> The name that the association will be referenced by - # @param opts<Hash> An options hash (see below) + # @param name [Symbol] The name that the association will be referenced by # @see #has # - # @return <DataMapper::Association::ManyToOne> The association created + # @return [DataMapper::Association::ManyToOne] The association created # should not be accessed directly # # @api public @@ -170,9 +169,4 @@ module DataMapper Model.append_extensions DataMapper::Associations - # module Resource - # module ClassMethods - # include DataMapper::Associations - # end # module ClassMethods - # end # module Resource end # module DataMapper lib/dm-core/associations.rb @@ -6,7 +6,7 @@ module DataMapper # Setup many to many relationship between two models # - - # @private + # @api private def self.setup(name, model, options = {}) assert_kind_of 'name', name, Symbol assert_kind_of 'model', model, Model lib/dm-core/associations/many_to_many.rb @@ -5,7 +5,7 @@ module DataMapper # Setup many to one relationship between two models # - - # @private + # @api private def self.setup(name, model, options = {}) assert_kind_of 'name', name, Symbol assert_kind_of 'model', model, Model lib/dm-core/associations/many_to_one.rb @@ -7,7 +7,7 @@ module DataMapper # Setup one to many relationship between two models # - - # @private + # @api private def self.setup(name, model, options = {}) assert_kind_of 'name', name, Symbol assert_kind_of 'model', model, Model lib/dm-core/associations/one_to_many.rb @@ -5,7 +5,7 @@ module DataMapper # Setup one to one relationship between two models # - - # @private + # @api private def self.setup(name, model, options = {}) assert_kind_of 'name', name, Symbol assert_kind_of 'model', model, Model lib/dm-core/associations/one_to_one.rb @@ -47,7 +47,7 @@ module DataMapper Class === @child_model ? @child_model : find_const(@child_model) end - # @private + # @api private def get_children(parent, options = {}, finder = :all, *args) bind_values = parent_key.get(parent) return [] if bind_values.any? { |bind_value| bind_value.nil? } @@ -58,7 +58,7 @@ module DataMapper end end - # @private + # @api private def get_parent(child) bind_values = child_key.get(child) return nil if bind_values.any? { |bind_value| bind_value.nil? } @@ -69,7 +69,7 @@ module DataMapper end end - # @private + # @api private def attach_parent(child, parent) child_key.set(child, parent && parent_key.get(parent)) end lib/dm-core/associations/relationship.rb @@ -14,7 +14,7 @@ module DataMapper near_relationship.child_model end - # @private + # @api private def get_children(parent, options = {}, finder = :all, *args) query = @query.merge(options).merge(child_key.to_query(parent_key.get(parent))) lib/dm-core/associations/relationship_chain.rb @@ -2,12 +2,24 @@ module DataMapper class AutoMigrator + ## + # Destructively automigrates the data-store to match the model + # REPEAT: THIS IS DESTRUCTIVE + # + # @param Symbol repository_name the repository to be migrated + # @calls DataMapper::Resource#auto_migrate! def self.auto_migrate(repository_name = nil) DataMapper::Resource.descendants.each do |model| model.auto_migrate!(repository_name) end end + ## + # Safely migrates the data-store to match the model + # preserving data already in the data-store + # + # @param Symbol repository_name the repository to be migrated + # @calls DataMapper::Resource#auto_upgrade! def self.auto_upgrade(repository_name = nil) DataMapper::Resource.descendants.each do |model| model.auto_upgrade!(repository_name) @@ -16,6 +28,11 @@ module DataMapper end # class AutoMigrator module AutoMigrations + ## + # Destructively automigrates the data-store to match the model + # REPEAT: THIS IS DESTRUCTIVE + # + # @param Symbol repository_name the repository to be migrated def auto_migrate!(repository_name = nil) if self.superclass != Object self.superclass.auto_migrate!(repository_name) @@ -29,6 +46,11 @@ module DataMapper end end + ## + # Safely migrates the data-store to match the model + # preserving data already in the data-store + # + # @param Symbol repository_name the repository to be migrated def auto_upgrade!(repository_name = nil) repository_name ||= default_repository_name repository(repository_name) do |r| lib/dm-core/auto_migrations.rb @@ -4,20 +4,48 @@ module DataMapper attr_reader :query + ## + # @return [Repository] the repository the collection is + # associated with + # @api public def repository query.repository end + ## + # loads the entries for the collection. Used by the + # adapters to load the instances of the declared + # model for this collection's query. + # + # @api private def load(values) add(model.load(values, query)) end + ## + # reloads the entries associated with this collection + # + # @param [DataMapper::Query] query (optional) additional query + # to scope by. Use this if you want to query a collections result + # set + # + # @see DataMapper::Collection#all + # + # @api public def reload(query = {}) @query = scoped_query(query) @query.update(:fields => @query.fields | @key_properties) replace(all(:reload => true)) end + ## + # retrieves an entry out of the collection's entry by key + # + # @param [DataMapper::Types::*, ...] key keys which uniquely + # identify a resource in the collection + # @return [DataMapper::Resource, NilClass] the resource which + # has the supplied keys + # @api public def get(*key) if loaded? # loop over the collection to find the matching resource @@ -42,17 +70,51 @@ module DataMapper end end + ## + # retrieves an entry out of the collection's entry by key, + # raising an exception if the object cannot be found + # + # @param [DataMapper::Types::*, ...] key keys which uniquely + # identify a resource in the collection + # + # @calls DataMapper::Collection#get + # + # @raise [ObjectNotFoundError] "Could not find #{model.name} with key #{key.inspect} in collection" + # def get!(*key) get(*key) || raise(ObjectNotFoundError, "Could not find #{model.name} with key #{key.inspect} in collection") end + ## + # Further refines a collection's conditions. #all provides an + # interface which simulates a database view. + # + # @param [Hash[Symbol, Object], DataMapper::Query] query parameters for + # an query within the results of the original query. + # + # @return [DataMapper::Collection] a collection whose query is the result + # of a merge def all(query = {}) + # TODO: this shouldn't be a kicker if scoped_query() is called return self if query.kind_of?(Hash) ? query.empty? : query == self.query query = scoped_query(query) query.repository.read_many(query) end + ## + # Simulates Array#first by returning the first entry (when + # there are no arguments), or transforms the collection's query + # by applying :limit => n when you supply an Integer. If you + # provide a conditions hash, or a Query object, the internal + # query is scoped and a new collection is returned + # + # @param [Integer, Hash[Symbol, Object], Query] args + # + # @return [DataMapper::Resource, DataMapper::Collection] The + # first resource in the entries of this collection, or + # a new collection whose query has been merged def first(*args) + # TODO: this shouldn't be a kicker if scoped_query() is called if loaded? if args.empty? return super @@ -72,6 +134,16 @@ module DataMapper end end + ## + # Simulates Array#last by returning the last entry (when + # there are no arguments), or transforming the collection's + # query by reversing the declared order, and applying + # :limit => n when you supply an Integer. If you + # supply a conditions hash, or a Query object, the + # internal query is scoped and a new collection is returned + # + # @calls Collection#first + # def last(*args) return super if loaded? && args.empty? @@ -84,11 +156,40 @@ module DataMapper reversed.first(*args) end + ## + # Simulates Array#at and returns the entrie at that index. + # Also accepts negative indexes and appropriate reverses + # the order of the query + # + # @calls Collection#first + # @calls Collection#last + # + # @author adam def at(offset) return super if loaded? offset >= 0 ? first(:offset => offset) : last(:offset => offset.abs - 1) end + ## + # Simulates Array#slice and returns a new Collection + # whose query has a new offset or limit according to the + # arguments provided. + # + # If you provide a range, the min is used as the offset + # and the max minues the offset is used as the limit. + # + # @param [Integer, Array(Integer), Range] args the offset, + # offset and limit, or range indicating offsets and limits + # + # @return [DataMapper::Resource, DataMapper::Collection] + # The entry which resides at that offset and limit, + # or a new Collection object with the set limits and offset + # + # @raise [ArgumentError] "arguments may be 1 or 2 Integers, + # or 1 Range object, was: #{args.inspect}" + # + # @alias [] + # def slice(*args) return at(args.first) if args.size == 1 && args.first.kind_of?(Integer) @@ -108,22 +209,35 @@ module DataMapper alias [] slice + ## + # + # @return [DataMapper::Collection] a new collection whose + # query is sorted in the reverse + # + # @see Array#reverse, DataMapper#all, DataMapper::Query#reverse + # def reverse all(self.query.reverse) end + ## + # @see Array#<< def <<(resource) super relate_resource(resource) self end + ## + # @see Array#push def push(*resources) super resources.each { |resource| relate_resource(resource) } self end - + + ## + # @see Array#unshift def unshift(*resources) super resources.each { |resource| relate_resource(resource) } @@ -163,6 +277,11 @@ module DataMapper self end + ## + # creates a new array, saves it, and << it onto the collection + # + # @param Hash[Symbol => Object] attributes attributes which + # the new resource should have. def create(attributes = {}) repository.scope do resource = model.create(default_attributes.merge(attributes)) @@ -171,8 +290,18 @@ module DataMapper end end - # TODO: delegate to Model.update + ## + # batch updates the entries belongs to this collection. + # + # @example Reached the Age of Alchohol Consumption + # Person.all(:age.gte => 21).update(:allow_beer => true) + # + # @return [TrueClass, FalseClass] + # TrueClass indicates that all entries were affected + # FalseClass indicates that some entries were affected + # def update(attributes = {},preload=false) + # TODO: delegate to Model.update return true if attributes.empty? dirty_attributes, keys_to_reload = {}, {} @@ -199,8 +328,18 @@ module DataMapper return loaded? ? affected == size : affected > 0 end - # TODO: delegate to Model.destroy + ## + # batch destroy the entries belongs to this collection. + # + # @example The War On Terror (if only it were this easy) + # Person.all(:terrorist => true).destroy() # + # + # @return [TrueClass, FalseClass] + # TrueClass indicates that all entries were affected + # FalseClass indicates that some entries were affected + # def destroy + # TODO: delegate to Model.destroy if loaded? return false unless repository.delete(scoped_query) == size @@ -223,10 +362,17 @@ module DataMapper true end + ## + # @return [DataMapper::PropertySet] The set of properties this + # query will be retrieving + # def properties PropertySet.new(query.fields) end + ## + # @return [DataMapper::Relationship] The model's relationships + # def relationships model.relationships(repository.name) end lib/dm-core/collection.rb @@ -205,7 +205,7 @@ module DataMapper end end - # @private + # @api private # TODO: spec this def load(values, query) repository = query.repository lib/dm-core/model.rb @@ -437,7 +437,7 @@ module DataMapper # @return <TrueClass, String, Float, Integer, BigDecimal, DateTime, Date, Time # Class> the primitive data-type, defaults to TrueClass #- - # @private + # @api private def typecast(value) return value if value.kind_of?(type) || value.nil? lib/dm-core/property.rb @@ -16,7 +16,7 @@ module DataMapper # it gets all the methods # # - - # @private + # @api private def self.included(model) model.extend Model model.extend ClassMethods if defined?(ClassMethods) @@ -39,7 +39,7 @@ module DataMapper # DataMapper.Resource.decendents[1].type == Foo # # - - # @semipublic + # @api semipublic def self.descendants @descendants ||= Set.new end @@ -80,7 +80,7 @@ module DataMapper # end # # - - # @semipublic + # @api semipublic def attribute_get(name) properties[name].get(self) end @@ -121,7 +121,7 @@ module DataMapper # end # # - - # @semipublic + # @api semipublic def attribute_set(name, value) properties[name].set(self, value) end @@ -135,7 +135,7 @@ module DataMapper # <True>:: the outcome of the comparison as a boolean # # - - # @public + # @api public def eql?(other) return true if object_id == other.object_id return false unless other.kind_of?(model) @@ -161,7 +161,7 @@ module DataMapper # => #<Foo name=nil updated_at=nil created_at=nil id=nil> # # - - # @public + # @api public def inspect attrs = [] @@ -195,7 +195,7 @@ module DataMapper # ==== Returns # <Repository>:: the respository this resource belongs to in the context of a collection OR in the class's context # - # @public + # @api public def repository @repository || model.repository end @@ -208,7 +208,7 @@ module DataMapper # <Array[Key], Key> key or keys # # -- - # @public + # @api public def id key = self.key key.first if key.size == 1 @@ -263,7 +263,7 @@ module DataMapper # <True, False>:: results of the destruction # # -- - # @public + # @api public def destroy return false unless repository.delete(to_query) @@ -292,7 +292,7 @@ module DataMapper # Foo.new.attribute_loaded?(:description) # will return false # # -- - # @public + # @api public def attribute_loaded?(name) instance_variable_defined?(properties[name].instance_variable_name) end @@ -314,7 +314,7 @@ module DataMapper # Foo.new.loaded_attributes # returns [:name] # # -- - # @public + # @api public def loaded_attributes names = [] properties.each do |property| @@ -329,7 +329,7 @@ module DataMapper # Hash:: original values of properties # # -- - # @public + # @api public def original_values @original_values ||= {} end @@ -340,7 +340,7 @@ module DataMapper # Hash:: attributes that have been marked dirty # # -- - # @private + # @api private def dirty_attributes dirty_attributes = {} properties = self.properties @@ -375,7 +375,7 @@ module DataMapper # True:: returns if class is dirty # # -- - # @public + # @api public def dirty? dirty_attributes.any? end @@ -389,7 +389,7 @@ module DataMapper # True:: returns if attribute is dirty # # -- - # @public + # @api public def attribute_dirty?(name) dirty_attributes.has_key?(properties[name]) end @@ -406,7 +406,7 @@ module DataMapper # self:: returns the class itself # # -- - # @public + # @api public def reload reload_attributes(*loaded_attributes) (parent_associations + child_associations).each { |association| association.reload } @@ -422,7 +422,7 @@ module DataMapper # self:: returns the class itself # # -- - # @public + # @api public def reload_attributes(*attributes) collection.reload(:fields => attributes) self @@ -434,7 +434,7 @@ module DataMapper # True:: status if the model is new # # -- - # @public + # @api public def new_record? !defined?(@new_record) || @new_record end @@ -445,7 +445,7 @@ module DataMapper # Hash[<Symbol>]:: All the (non)-lazy attributes # # -- - # @public + # @api public def attributes pairs = {} @@ -463,7 +463,7 @@ module DataMapper # value_hash <Hash[<Symbol>]>:: # # -- - # @public + # @api public def attributes=(values_hash) values_hash.each_pair do |k,v| setter = "#{k.to_s.sub(/\?\z/, '')}=" @@ -556,13 +556,13 @@ module DataMapper end # TODO document - # @semipublic + # @api semipublic def attribute_get!(name) properties[name].get!(self) end # TODO document - # @semipublic + # @api semipublic def attribute_set!(name, value) properties[name].set!(self, value) end lib/dm-core/resource.rb @@ -238,6 +238,13 @@ if ADAPTER @unlimited = DataMapper::Collection.new(query) {} end + it "should not be a kicker" do + pending do + puts @collection.all.loaded? + @collection.all.should_not be_loaded + end + end + it 'has an offset equal to 10' do @collection.all.query.offset.should == 10 end spec/integration/collection_spec.rb 887befdd7c66c3bc0daed2cb44babed35b902fb9 Adam French adam@adam.wieck.com http://github.com/sam/dm-core/commit/c5ecb84ee1d1422ac23da3e1e69926d8b181bdea c5ecb84ee1d1422ac23da3e1e69926d8b181bdea 2008-06-19T16:02:19-07:00 2008-06-19T15:57:56-07:00 moving/rewriting docs in newest yard style 5e918e7168d1fc9945662827a82912c09f2b6d06 Adam French adam@adam.wieck.com