123456789_123456789_123456789_123456789_123456789_

Module: Mongoid::Criteria::Modifiable

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In:
::Mongoid::Criteria
Defined in: lib/mongoid/criteria/modifiable.rb

Overview

Mixin module for ::Mongoid::Criteria which adds the ability to build or create new documents with attributes initialized to the conditions of the criteria.

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#create_attrs (readonly)

This method is for internal use only.
[ GitHub ] 

  


# File 'lib/mongoid/criteria/modifiable.rb', line 14



attr_reader :create_attrs


  








  

    #create_attrs Additional attributes to add to the Document upon creation.(Additional attributes to add to the Document upon creation.)   (readonly)
  

  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 14



attr_reader :create_attrs


  







Instance Method Details



  

    #build(attrs = {}, &block)  ⇒ Document 
    Also known as: #new
  



  

    

Build a document given the selector and return it. Complex criteria, such as $in and $or operations will get ignored.


  





    

    
Examples:

        


build the document.



      
Person.where(:title => "Sir").build

        


Build with selectors getting ignored.



      
Person.where(:age.gt => 5).build

  


Returns:


    
  
  • 
    (Document)
—    
    

    A non-persisted document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 26



def build(attrs = {}, &block)
  create_document(:new, attrs, &block)
end


  








  

    #create(attrs = {}, &block)  ⇒ Document 
  



  

    

Create a document in the database given the selector and return it. Complex criteria, such as $in and $or operations will get ignored.


  





    

    
Examples:

        


Create the document.



      
Person.where(:title => "Sir").create

        


Create with selectors getting ignored.



      
Person.where(:age.gt => 5).create

  


Returns:


    
  
  • 
    (Document)
—    
    

    A newly created document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 41



def create(attrs = {}, &block)
  create_document(:create, attrs, &block)
end


  








  

    #create!(attrs = {}, &block)  ⇒ Document 
  



  

    

Create a document in the database given the selector and return it. Complex criteria, such as $in and $or operations will get ignored. If validation fails, an error will be raised.


  





    

    
Examples:

        


Create the document.



      
Person.where(:title => "Sir").create

        


Create with selectors getting ignored.



      
Person.where(:age.gt => 5).create

  


Returns:


    
  
  • 
    (Document)
—    
    

    A newly created document.
    

    
  
    • 



Raises:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 58



def create!(attrs = {}, &block)
  create_document(:create!, attrs, &block)
end


  








  

    #create_document(method, attrs = nil, &block)  ⇒ Document  (private)
  

  

    This method is for internal use only.
  



  

    

Create a document given the provided method and attributes from the existing selector.


  





    

    
Examples:

        


Create a new document.



      
criteria.create_document(:new, {})

  


Parameters:


    
  
  • 
    method
    (Symbol)
—    
    

    Either :new or :create.
    

    
  
    • 
  
  • 
    attrs
    (Hash)
    (defaults to: nil)
—    
    

    Additional attributes to use.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    The new or saved document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 174



def create_document(method, attrs = nil, &block)
  attrs = (create_attrs || {}).merge(attrs || {})
  attributes = selector.reduce(attrs) do |hash, (key, value)|
    unless invalid_key?(hash, key) || invalid_embedded_doc?(value)
      hash[key] = value
    end
    hash
  end
  if embedded?
    attributes[:_parent] = parent_document
    attributes[:_association] = association
  end
  if polymorphic? && @criterion
    klass.__send__(method, attributes.merge(@criterion), &block)
  else
    klass.__send__(method, attributes, &block)
  end
end


  








  

    #create_with(attrs = {})  ⇒ Mongoid::Criteria 
  



  

    

Define attributes with which new documents will be created.



Note that if #find_or_create_by is called after this in a method chain, the attributes in the query will override those from this method.


  





    

    
Examples:

        


Define attributes to be used when a new document is created.



      
Person.create_with(job: 'Engineer').find_or_create_by(employer: 'MongoDB')

  


Returns:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 71



def create_with(attrs = {})
  tap do
    @create_attrs ||= {}
    @create_attrs.update(attrs)
  end
end


  








  

    #find_or(method, attrs = {}, &block)  ⇒ Document  (private)
  

  

    This method is for internal use only.
  



  

    

Find the first object or create/initialize it.


  





    

    
Examples:

        


Find or perform an action.



      
Person.find_or(:create, :name => "Dev")

  


Parameters:


    
  
  • 
    method
    (Symbol)
—    
    

    The method to invoke.
    

    
  
    • 
  
  • 
    attrs
    (Hash)
    (defaults to: {})
—    
    

    The attributes to query or set.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    The first or new document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 204



def find_or(method, attrs = {}, &block)
  where(attrs).first || send(method, attrs, &block)
end


  








  

    #find_or_create_by(attrs = {}, &block)  ⇒ Document 
  



  

    

Find the first ::Mongoid::Document given the conditions, or creates a new document with the conditions that were supplied.


  





    

    
Examples:

        


Find or create the document.



      
Person.find_or_create_by(:attribute => "value")

  


Parameters:


    
  
  • 
    attrs
    (Hash)
    (defaults to: {})
—    
    

    The attributes to check.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    A matching or newly created document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 87



def find_or_create_by(attrs = {}, &block)
  find_or(:create, attrs, &block)
end


  








  

    #find_or_create_by!(attrs = {}, &block)  ⇒ Document 
  



  

    

Find the first ::Mongoid::Document given the conditions, or creates a new document with the conditions that were supplied. If validation fails an exception will be raised.


  





    

    
Examples:

        


Find or create the document.



      
Person.find_or_create_by!(:attribute => "value")

  


Parameters:


    
  
  • 
    attrs
    (Hash)
    (defaults to: {})
—    
    

    The attributes to check.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    A matching or newly created document.
    

    
  
    • 



Raises:





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 103



def find_or_create_by!(attrs = {}, &block)
  find_or(:create!, attrs, &block)
end


  








  

    #find_or_initialize_by(attrs = {}, &block)  ⇒ Document 
  



  

    

Find the first ::Mongoid::Document given the conditions, or initializes a new document with the conditions that were supplied.


  





    

    
Examples:

        


Find or initialize the document.



      
Person.find_or_initialize_by(:attribute => "value")

  


Parameters:


    
  
  • 
    attrs
    (Hash)
    (defaults to: {})
—    
    

    The attributes to check.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    A matching or newly initialized document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 116



def find_or_initialize_by(attrs = {}, &block)
  find_or(:new, attrs, &block)
end


  








  

    #first_or(method, attrs = {}, &block)  ⇒ Document  (private)
  

  

    This method is for internal use only.
  



  

    

Find the first document or create/initialize it.


  





    

    
Examples:

        


First or perform an action.



      
Person.first_or(:create, :name => "Dev")

  


Parameters:


    
  
  • 
    method
    (Symbol)
—    
    

    The method to invoke.
    

    
  
    • 
  
  • 
    attrs
    (Hash)
    (defaults to: {})
—    
    

    The attributes to query or set.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    The first or new document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 219



def first_or(method, attrs = {}, &block)
  first || create_document(method, attrs, &block)
end


  








  

    #first_or_create(attrs = nil, &block)  ⇒ Document 
  



  

    

Find the first ::Mongoid::Document, or creates a new document with the conditions that were supplied plus attributes.


  





    

    
Examples:

        


First or create the document.



      
Person.where(name: "Jon").first_or_create(attribute: "value")

  


Parameters:


    
  
  • 
    attrs
    (Hash)
    (defaults to: nil)
—    
    

    The additional attributes to add.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    A matching or newly created document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 129



def first_or_create(attrs = nil, &block)
  first_or(:create, attrs, &block)
end


  








  

    #first_or_create!(attrs = nil, &block)  ⇒ Document 
  



  

    

Find the first ::Mongoid::Document, or creates a new document with the conditions that were supplied plus attributes and will raise an error if validation fails.


  





    

    
Examples:

        


First or create the document.



      
Person.where(name: "Jon").first_or_create!(attribute: "value")

  


Parameters:


    
  
  • 
    attrs
    (Hash)
    (defaults to: nil)
—    
    

    The additional attributes to add.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    A matching or newly created document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 143



def first_or_create!(attrs = nil, &block)
  first_or(:create!, attrs, &block)
end


  








  

    #first_or_initialize(attrs = nil, &block)  ⇒ Document 
  



  

    

Find the first ::Mongoid::Document, or initializes a new document with the conditions that were supplied plus attributes.


  





    

    
Examples:

        


First or initialize the document.



      
Person.where(name: "Jon").first_or_initialize(attribute: "value")

  


Parameters:


    
  
  • 
    attrs
    (Hash)
    (defaults to: nil)
—    
    

    The additional attributes to add.
    

    
  
    • 



Returns:


    
  
  • 
    (Document)
—    
    

    A matching or newly initialized document.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 156



def first_or_initialize(attrs = nil, &block)
  first_or(:new, attrs, &block)
end


  








  

    #invalid_embedded_doc?(value)  ⇒ Boolean  (private)
  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 231



def invalid_embedded_doc?(value)
  # @todo Change this to BSON::String::ILLEGAL_KEY when ruby driver 2.3.0 is
  # released and mongoid is updated to depend on driver >= 2.3.0
  value.is_a?(Hash) && value.any? do |key, v|
    key.to_s =~ Mongoid::Document::ILLEGAL_KEY || invalid_embedded_doc?(v)
  end
end


  








  

    #invalid_key?(hash, key)  ⇒ Boolean  (private)
  



  

    
  





  


  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 225



def invalid_key?(hash, key)
  # @todo Change this to BSON::String::ILLEGAL_KEY when ruby driver 2.3.0 is
  # released and mongoid is updated to depend on driver >= 2.3.0
  key.to_s =~ Mongoid::Document::ILLEGAL_KEY || hash.key?(key.to_sym) || hash.key?(key)
end


  








  

    #new(attrs = {}, &block)  
  



  

    

Alias for #build.


  



  [ GitHub ]


  

  


# File 'lib/mongoid/criteria/modifiable.rb', line 29



alias :new :build