mongoid-sleeping_king_studios 0.5.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cc9bfc29b8eaf26a12fdf6e8779468794c67d352
-  data.tar.gz: a927885e26c3aa375696654acc8d412b96ecc5b6
+  metadata.gz: fdd1c69e257d2151ecdb439fc1f9ab974628c9ba
+  data.tar.gz: cf273c392e0fde12e79b244819c1c880de8e11dd
 SHA512:
-  metadata.gz: c2913f5069f689cbeedf2d8257096fb88a90755971ea45924771a1e8d3f09c1ed9af2acfd97e57a9e816bceb08b5a083245af455860f6888899d45f9f57b401d
-  data.tar.gz: a0216507421c39e39548b138cb9277a185a0fbd1db69594975e6ecf256fc3e78e4aab7655db2eb45b11584b260354f3e24b588743eb80470accb118ca044da8b
+  metadata.gz: 0e20060ad75456272818d391425dad43a7deca8babe64f104a586a946221db0aa0e57d227bb16acee3ac7a3921d272a12d8da2bde3a4d2794b85a6f8233965b8
+  data.tar.gz: 6ab47ee0aed555756fd7ab7dadabe617985abe5c32d61efc1e4374546427abc0afebcb60185c84dfe50b87e083f8ca8ec10038120cc8480cca4adfdf7a54c8bf

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.6.2
+
+* Update dependencies (no user-facing changes).
+
+## 0.6.1
+
+### New Features
+
+* Added #siblings scope to HasTree concern.

data/LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2013 Rob Smith
+Copyright (c) 2013-2014 Rob Smith
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -54,7 +54,25 @@ Stores the chain of ancestors in an :ancestor_ids array field, and adds the
       has_tree :cache_ancestry => true
     end # class
 
-**Warning:** using this option will make many write operations much, much
+**Options**
+
+You can customize the ancestry cache by passing in a hash of options as the
+:cache\_ancestry value in the ::has_tree method.
+
+    class PartGroup
+      include Mongoid::Document
+      include Mongoid::SleepingKingStudios::HasTree
+
+      # This creates the #assemblies method and #assembly_ids field.
+      has_tree :cache_ancestry => { :relation_name => :assemblies }
+    end # class
+
+- *foreign\_key*: The name of the field used to store the ancestor references.
+  Defaults to 'ancestor_ids'.
+- *relation\_name*: The name of the generated relation for the array of
+  parent objects. Defaults to 'ancestors'.
+
+**Warning:** Using this option will make many write operations much, much
 slower and more resource-intensive. Do not use this option outside of
 read-heavy applications with very specific requirements, e.g. a directory
 structure where you must access all parent directories on each page view.
@@ -83,11 +101,11 @@ short, url-friendly version.
 
     slugify :title, :lockable => true
 
-Allows the slug to be specified manually. Adds an additional slug_lock field
+Allows the slug to be specified manually. Adds an additional #slug_lock field
 that is automatically set to true when #slug= is called. To resume tracking the
 base attribute, set :slug_lock to false.
 
 ## License
 
-RSpec::SleepingKingStudios is released under the
+Mongoid::SleepingKingStudios is released under the
 [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/mongoid/sleeping_king_studios.rb

@@ -1,7 +1,17 @@
 # lib/mongoid/sleeping_king_studios.rb
 
 require 'mongoid'
+require 'sleeping_king_studios/ext/object/metaclass'
 
 module Mongoid
-  module SleepingKingStudios; end
+  # A collection of concerns and extensions to add functionality to Mongoid
+  # documents and collections.
+  module SleepingKingStudios
+    def self.root
+      Pathname.new File.join __dir__, 'sleeping_king_studios'
+    end # class method root
+  end # module
 end # module
+
+### Require Extensions ###
+Dir[File.join Mongoid::SleepingKingStudios.root, *%w(ext ** *.rb)].each { |f| require f }

data/lib/mongoid/sleeping_king_studios/concern.rb

@@ -0,0 +1,69 @@
+# lib/mongoid/sleeping_king_studios/concern.rb
+
+require 'mongoid/sleeping_king_studios'
+require 'mongoid/sleeping_king_studios/concern/metadata'
+
+module Mongoid::SleepingKingStudios
+  # Base class for concerns with shared behavior, such as creating metadata
+  # objects from an options hash and storing that metadata in the Document
+  # class's ::relations attribute.
+  # 
+  # @since 0.6.0
+  module Concern
+    # @overload characterize name, properties, type = Metadata
+    #   Creates a metadata instance for the relation.
+    # 
+    #   @param [Symbol] name The name of the relation. Must be unique for the
+    #     base type within the sleeping_king_studios namespace.
+    #   @param [Hash] options The options for the relation.
+    #   @param [Class] type The type of the generated metadata.
+    # 
+    #   @return [Metadata] The generated metadata.
+    def characterize name, options, type = nil
+      type ||= Mongoid::SleepingKingStudios::Concern::Metadata
+      type.new name, options
+    end # method characterize
+
+    # Stores the metadata in the class's relations object. To avoid automatic
+    # Mongoid behavior on relations, adds a #sleeping_king_studios accessor to
+    # the relations hash by mixing in the Relations module. Then, saves the
+    # metadata using the metadata#relation_key as the key.
+    # 
+    # @param [Class] base The base class into which the concern is mixed in.
+    # @param [Symbol] name The name of the relation. Must be unique for the
+    #   base type within the sleeping_king_studios namespace.
+    # @param [Metadata] metadata The metadata to be stored.
+    def relate base, name, metadata
+      base.relations_sleeping_king_studios.update metadata.relation_key => metadata
+    end # method relate
+
+    # Returns a list of options that are valid for this concern.
+    # 
+    # @return [Array<Symbol>] The list of valid options.
+    def valid_options
+      %i(
+
+      ) # end array
+    end # method valid_options
+
+    # Evaluates the provided options and raises an error if any of the options
+    # are invalid, based on the list from #valid_options.
+    # 
+    # @param [Symbol] name The name of the relation.
+    # @param [Hash] options The options for the relation.
+    # 
+    # @raise [Mongoid::Errors::InvalidOptions] If any of the options provided
+    #   are invalid.
+    def validate_options name, options
+      options.keys.each do |key|
+        if !valid_options.include?(key)
+          raise Mongoid::Errors::InvalidOptions.new(
+            name,
+            key,
+            valid_options
+          ) # end InvalidOptions
+        end # if
+      end # each
+    end # method validate_options
+  end # class
+end # module

data/lib/mongoid/sleeping_king_studios/concern/metadata.rb

@@ -0,0 +1,61 @@
+# lib/mongoid/sleeping_king_studios/concern/metadata.rb
+
+require 'mongoid/sleeping_king_studios'
+require 'mongoid/sleeping_king_studios/concern'
+
+module Mongoid::SleepingKingStudios
+  module Concern
+    # Stores information about a given concern or relation. By default, stored
+    # in the Document class's ::relations attribute. Concerns may subclass
+    # Metadata to add further keys and/or functionality.
+    # 
+    # @since 0.6.0
+    class Metadata < Hash
+      # @param [Symbol, String] name The name of the concern or relation.
+      # @param [Hash] properties The properties of the concern or relation.
+      def initialize name, properties = {}
+        @name       = name
+        @properties = properties.dup
+
+        merge! properties if Hash === properties
+      end # method initialize
+
+      # @return [Symbol] The name of the concern or relation.
+      attr_reader :name
+
+      # @return [Hash] The unmodified properties hash that was passed into the
+      #   constructor.
+      attr_reader :properties
+
+      # @overload characterize name, properties, type = Metadata
+      #   Creates a metadata instance for a subgroup of the metadata, such as a
+      #   generated relation or for an optional parameter.
+      # 
+      #   @param [Symbol] name The name of the relation. Must be unique for the
+      #     base type within the sleeping_king_studios namespace.
+      #   @param [Hash] properties The options for the relation.
+      #   @param [Class] type The type of the generated metadata.
+      # 
+      #   @return [Metadata] The generated metadata.
+      def characterize name, properties, type = nil
+        type ||= Mongoid::SleepingKingStudios::Concern::Metadata
+        type.new name, properties
+      end # method characterize
+
+      # The key used to store the metadata inside the class's ::relations
+      # attribute. By default, adds the prefix 'sleeping_king_studios::' to the
+      # name, but can be set via the properties hash.
+      # 
+      # @return [String] The key used to store the metadata.
+      def relation_key
+        self[:relation_key] || name.to_s
+      end # method relation_key
+
+      # @return [Boolean] True if a custom relation key is defined, otherwise
+      #   false.
+      def relation_key?
+        !!self[:relation_key]
+      end # method relation_key?
+    end # class
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/ext/mongoid/document.rb

@@ -0,0 +1,15 @@
+# lib/mongoid/sleeping_king_studios/ext/mongoid/document.rb
+
+require 'mongoid'
+
+module Mongoid
+  module Document
+    module ClassMethods
+      # Metadata for the relations and concerns on the document class in the
+      # Mongoid::SleepingKingStudios namespace.
+      def relations_sleeping_king_studios
+        @relations_sleeping_king_studios ||= {}
+      end # class method relations_sleeping_king_studios
+    end # module
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/has_tree.rb

@@ -1,6 +1,8 @@
 # lib/mongoid/sleeping_king_studios/tree.rb
 
 require 'mongoid/sleeping_king_studios'
+require 'mongoid/sleeping_king_studios/concern'
+require 'mongoid/sleeping_king_studios/has_tree/metadata'
 require 'mongoid/sleeping_king_studios/has_tree/cache_ancestry'
 
 module Mongoid::SleepingKingStudios
@@ -34,6 +36,98 @@ module Mongoid::SleepingKingStudios
   # @since 0.2.0
   module HasTree
     extend ActiveSupport::Concern
+    extend Mongoid::SleepingKingStudios::Concern
+
+    # @api private
+    # 
+    # Sets up the has_tree relation, creating fields, accessors and
+    # validations.
+    # 
+    # @param [Class] base The base class into which the concern is mixed in.
+    # @param [Hash] options The options for the relation.
+    # 
+    # @since 0.6.0
+    def self.apply base, options
+      options[:parent]   ||= {}
+      options[:children] ||= {}
+
+      options[:parent][:inverse_of]   = options[:children].fetch(:relation_name, :children)
+      options[:children][:inverse_of] = options[:parent].fetch(:relation_name,   :parent)
+
+      name = :has_tree
+      validate_options    name, options
+      meta = characterize name, options, Metadata
+
+      relate base, name, meta
+
+      define_relations base, meta
+      define_helpers   base, meta
+
+      if meta.cache_ancestry?
+        concern = Mongoid::SleepingKingStudios::HasTree::CacheAncestry
+        concern.send :apply, base, meta.cache_ancestry
+      end # if
+    end # class method apply
+
+    # @api private
+    # 
+    # Sets up the helper methods for the relations as follows.
+    # 
+    # Defines the following class methods:
+    # - ::roots
+    # 
+    # Defines the following instance methods:
+    # - #leaf?
+    # - #root
+    # - #root?
+    # 
+    # @param [Class] base The base class into which the concern is mixed in.
+    # @param [Metadata] metadata The metadata for the relation.
+    # 
+    # @since 0.6.0
+    def self.define_helpers base, metadata
+      base.metaclass.send :define_method, :roots do
+        where({ :"#{metadata.parent.relation_name}_id" => nil })
+      end # class method roots
+
+      base.send :define_method, :root do
+        parent = send(metadata.parent.relation_name)
+        parent ? parent.root : self
+      end # method root
+
+      base.send :define_method, :leaf? do
+        send(metadata.children.relation_name).blank?
+      end # method root?
+
+      base.send :define_method, :root? do
+        send(metadata.parent.relation_name).nil?
+      end # method root?
+
+      base.send :define_method, :siblings do
+        self.class.where(:id => { "$ne" => self.id }).where(metadata.foreign_key => self.send(metadata.foreign_key))
+      end # method siblings
+    end # class method define_helpers
+
+    # @api private
+    # 
+    # Sets up the parent and children relations.
+    # 
+    # @param [Class] base The base class into which the concern is mixed in.
+    # @param [Metadata] metadata The metadata for the relation.
+    # 
+    # @since 0.6.0
+    def self.define_relations base, metadata
+      parent_options = metadata.parent.properties.dup
+      parent_options.update :class_name => base.name
+      parent_options.delete :relation_name
+
+      children_options = metadata.children.properties.dup
+      children_options.update :class_name => base.name
+      children_options.delete :relation_name
+
+      base.belongs_to metadata.parent.relation_name,   parent_options
+      base.has_many   metadata.children.relation_name, children_options
+    end # class method define_relations
 
     # Get the valid options allowed with this concern.
     # 
@@ -77,93 +171,50 @@ module Mongoid::SleepingKingStudios
       #     ancestors in an :ancestor_ids array field. Adds the #ancestors and
       #     #descendents scopes.
       #
-      #     Warning: using this option will make many write operations much,
+      #     Warning: Using this option will make many write operations much,
       #     much slower and more resource-intensive. Do not use this option
       #     outside of read-heavy applications with very specific requirements,
       #     e.g. a directory structure where you must access all parent
       #     directories on each page view.
       # 
-      #   @see Mongoid::SleepingKingStudios::HasTree::CacheAncestry
+      #   @see Mongoid::SleepingKingStudios::HasTree::CacheAncestry::ClassMethods#cache_ancestry
       # 
       #   @raise [ Mongoid::Errors::InvalidOptions ] If the options are invalid.
       #
       # @since 0.4.0
       def has_tree **options
-        validate_options options
-
-        # Create Relations
-        p_opts  = { :relation_name => :parent,   :class_name => self.name }
-        c_opts  = { :relation_name => :children, :class_name => self.name }
-        
-        p_opts.update(options[:parent])   if Hash === options[:parent]
-        c_opts.update(options[:children]) if Hash === options[:children]
-
-        p_opts.update :inverse_of => c_opts[:relation_name]
-        c_opts.update :inverse_of => p_opts[:relation_name]
-        
-        belongs_to p_opts.delete(:relation_name), p_opts
-        has_many   c_opts.delete(:relation_name), c_opts
-
-        options[:parent]   = p_opts
-        options[:children] = c_opts
-
-        # Set Up Ancestry Cache
-        if options.has_key? :cache_ancestry
-          self.send :include, Mongoid::SleepingKingStudios::HasTree::CacheAncestry
-          self.send :cache_ancestry, **options
-        end # if
-
-        self
+        concern = Mongoid::SleepingKingStudios::HasTree
+        concern.apply self, options
       end # class method has_tree
 
-      # Returns a Criteria specifying all root objects, e.g. objects with no
-      # parent object.
+      # @!method roots
+      #   Returns a Criteria specifying all root objects, e.g. objects with no
+      #   parent object.
       # 
-      # @return [Mongoid::Criteria]
-      def roots
-        where({ :parent_id => nil })
-      end # scope routes
-
-      private
-
-      # Determine if the provided options are valid for the concern.
-      #
-      # @param [ Hash ] options The options to check.
-      #
-      # @raise [ Mongoid::Errors::InvalidOptions ] If the options are invalid.
-      def validate_options options
-        valid_options = Mongoid::SleepingKingStudios::HasTree.valid_options
-        options.keys.each do |key|
-          if !valid_options.include?(key)
-            raise Mongoid::Errors::InvalidOptions.new(
-              :has_tree,
-              key,
-              valid_options
-            ) # end InvalidOptions
-          end # if
-        end # each
-      end # class method validate_options
+      #   @return [Mongoid::Criteria]
     end # module
 
-    # Returns the root object of the current object's tree.
+    # @!method root
+    #   Returns the root object of the current object's tree.
     # 
-    # @return [Tree]
-    def root
-      parent ? parent.root : self
-    end # method root
+    #   @return [Tree]
 
-    # Returns true if the object is a leaf object, e.g. has no child objects.
+    # @!method leaf?
+    #   Returns true if the object is a leaf object, e.g. has no child objects.
     # 
-    # @return [Boolean] True if the object has no children; otherwise false.
-    def leaf?
-      children.empty?
-    end # method leaf?
+    #   @return [Boolean] True if the object has no children; otherwise false.
 
-    # Returns true if the object is a root object, e.g. has no parent object.
+    # @!method root?
+    #   Returns true if the object is a root object, e.g. has no parent object.
+    # 
+    #   @return [Boolean] True if the object has no parent; otherwise false.
+
+    # @!method siblings
+    #   Returns a Criteria specifying all persisted objects in the tree whose
+    #   parent is the current object's parent, excluding the current object.
+    # 
+    #   @return [Mongoid::Criteria]
     # 
-    # @return [Boolean] True if the object has no parent; otherwise false.
-    def root?
-      parent.nil?
-    end # method root?
+    #   @since 0.6.1
   end # module
 end # module