Class: Cuprum::Rails::Commands::FindMatching

Inherits:
Cuprum::Rails::Command show all
Includes:
Collections::Commands::AbstractFindMatching
Defined in:
lib/cuprum/rails/commands/find_matching.rb

Overview

Command for querying filtered, ordered data from a Rails collection.

Instance Attribute Summary

Attributes inherited from Cuprum::Rails::Command

#collection_name, #member_name, #options, #record_class

Instance Method Summary collapse

Methods inherited from Cuprum::Rails::Command

#initialize, #primary_key_name, #primary_key_type, subclass

Constructor Details

This class inherits a constructor from Cuprum::Rails::Command

Instance Method Details

#call(limit: nil, offset: nil, order: nil, &block) ⇒ Cuprum::Result<Enumerator> #call(limit: nil, offset: nil, order: nil, &block) ⇒ Cuprum::Result<Hash{String, Array<ActiveRecord::Base>}>

Queries the collection for records matching the given conditions.

Examples:

Querying all records in the collection.

command = FindMatching.new(collection_name: 'books', data: books)
command.call
#=> an enumerable iterating all records in the collection

Querying all records matching some critera:

command.call { { author: 'Nnedi Okorafor' } }
#=> an enumerable iterating all records in the collection whose author
    is 'Nnedi Okorafor'

Ordering query results

command.call(order: :title) { { author: 'Nnedi Okorafor' } }
#=> an enumerable iterating all records in the collection whose author
#   is 'Nnedi Okorafor', sorted by :title in ascending order

Advanced filtering

command.call do
  {
    category: eq('Science Fiction and Fantasy'),
    author:   ne('J.R.R. Tolkien')
  }
end
#=> an enumerable iterating all records in the collection whose
#   category is 'Science Fiction and Fantasy', and whose author is not
#   'J.R.R. Tolkien'.

Advanced ordering

order = { author: :asc, genre: :desc }
command.call(order: order) { { author: 'Nnedi Okorafor' } }
#=> an enumerable iterating all records in the collection whose author
#   is 'Nnedi Okorafor', sorted first by :author in ascending order
#   and within the same author by genre in descending order

Filtering, ordering, and subsets

command.call(offset: 50, limit: 10, order: :author) do
  { category: 'Science Fiction and Fantasy' }
end
#=> an enumerable iterating the 51st through 60th records in the
#   collection whose category is 'Science Fiction and Fantasy', sorted
#   by :author in ascending order.

Wrapping the result in an envelope

command =
  Filter.new(collection_name: 'books', data: books)
command.call(envelope: true)
#=> {
  'books' => [] # an array containing the matching records
}

Overloads:

  • #call(limit: nil, offset: nil, order: nil, &block) ⇒ Cuprum::Result<Enumerator>

    When the :envelope option is false (default), the command returns an Enumerator which can be iterated to return the matching records.

    Returns:

    • (Cuprum::Result<Enumerator>) —

      the matching records in the specified order as an Enumerator.

  • #call(limit: nil, offset: nil, order: nil, &block) ⇒ Cuprum::Result<Hash{String, Array<ActiveRecord::Base>}>

    When the :envelope option is true, the command immediately evaluates the query and wraps the resulting array in a Hash, using the name of the collection as the key.

    Returns:

    • (Cuprum::Result<Hash{String, Array<ActiveRecord::Base>}>) —

      a hash with the collection name as key and the matching records as value.

Parameters:

  • envelope (Boolean) (defaults to: false) —

    If true, wraps the result value in a Hash.

  • limit (Integer) (defaults to: nil) —

    The maximum number of results to return.

  • offset (Integer) (defaults to: nil) —

    The initial ordered items to skip.

  • order (Array<String, Symbol>, Hash<{String, Symbol => Symbol}>) (defaults to: nil) —

    The sort order of the returned items. Should be either an array of attribute names or a hash of attribute names and directions.

  • scope (Cuprum::Collections::Basic::Query, nil) (defaults to: nil) —

    Optional scope for the query. Records must match the scope as well as the :where filters.

  • where (Object) (defaults to: nil) —

    Additional filters for selecting data. The command will only return data matching these filters.

Yields:

  • The given block is passed to a QueryBuilder, which converts the block to query criteria and generates a new query using those criteria.

Yield Returns:

  • (Hash) —

    The filters to apply to the query. The hash keys should be the names of attributes or columns, and the corresponding values should be either the literal value for that attribute or a method call for a valid operation defined for the query.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/cuprum/rails/commands/find_matching.rb', line 100

validate_parameters :call do
  keyword :envelope,
    Stannum::Constraints::Boolean.new,
    default: true
  keyword :limit, Integer, optional: true
  keyword :offset, Integer, optional: true
  keyword :order,
    Cuprum::Collections::Constraints::Ordering.new,
    optional: true
  keyword :scope,
    Cuprum::Rails::Query,
    optional: true
  keyword :where, Object, optional: true
end