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

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

Instance Method Summary

#build(attrs = {}, &block) ⇒ Document (also: #new)

Build a document given the selector and return it.
#create(attrs = {}, &block) ⇒ Document

Create a document in the database given the selector and return it.
#create!(attrs = {}, &block) ⇒ Document

Create a document in the database given the selector and return it.
#create_with(attrs = {}) ⇒ Mongoid::Criteria

Define attributes with which new documents will be created.
#find_or_create_by(attrs = {}, &block) ⇒ Document

Find the first Document given the conditions, or creates a new document with the conditions that were supplied.
#find_or_create_by!(attrs = {}, &block) ⇒ Document

Find the first Document given the conditions, or creates a new document with the conditions that were supplied.
#find_or_initialize_by(attrs = {}, &block) ⇒ Document

Find the first Document given the conditions, or initializes a new document with the conditions that were supplied.
#first_or_create(attrs = nil, &block) ⇒ Document

Find the first Document, or creates a new document with the conditions that were supplied plus attributes.
#first_or_create!(attrs = nil, &block) ⇒ Document

Find the first Document, or creates a new document with the conditions that were supplied plus attributes and will raise an error if validation fails.
#first_or_initialize(attrs = nil, &block) ⇒ Document

Find the first Document, or initializes a new document with the conditions that were supplied plus attributes.
#new(attrs = {}, &block)

Alias for #build.
#create_document(method, attrs = nil, &block) ⇒ Document private Internal use only Internal use only

Create a document given the provided method and attributes from the existing selector.
#find_or(method, attrs = {}, &block) ⇒ Document private Internal use only Internal use only

Find the first object or create/initialize it.
#first_or(method, attrs = {}, &block) ⇒ Document private Internal use only Internal use only

Find the first document or create/initialize it.
#invalid_embedded_doc?(value) ⇒ Boolean private
#invalid_key?(hash, key) ⇒ Boolean private

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:

(Errors::Validations) —

on a validation error.

[ 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:

(Mongoid::Criteria) —

A criteria.

[ 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 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 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:

(Errors::Validations) —

on validation error.

[ 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 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 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 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 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