queryable_array 0.0.0 → 0.0.1

data/README.rdoc

@@ -2,7 +2,7 @@
 
 {<img src="https://secure.travis-ci.org/shuber/queryable_array.png"/>}[http://travis-ci.org/shuber/queryable_array]
 {<img src="https://gemnasium.com/shuber/queryable_array.png"/>}[https://gemnasium.com/shuber/queryable_array]
-{<img src="https://d25lcipzij17d.cloudfront.net/badge.png?v=0.0.0"/>}[http://rubygems.org/gems/queryable_array]
+{<img src="https://d25lcipzij17d.cloudfront.net/badge.png?v=0.0.1"/>}[http://rubygems.org/gems/queryable_array]
 {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/shuber/queryable_array]
 
 A +QueryableArray+ inherits from +Array+ and is intended to store a group of
@@ -12,6 +12,7 @@ for looking up objects by querying their attributes.
 
 View the full documentation over at rubydoc.info[http://rubydoc.info/github/shuber/queryable_array/frames].
 
+
 == Installation
 
   gem install queryable_array
@@ -25,7 +26,7 @@ Initialize the +QueryableArray+ with a collection of objects e.g. +Page+ objects
 
   pages = QueryableArray.new Page.all
 
-The +pages+ object can then be queried by passing a search hash to the +[]+ method
+The +pages+ object can then be queried by passing a search hash to the <tt>[]</tt> method
 
   pages[uri: '/']                    # => #<Page @uri='/' @name='Home'>
   pages[name: 'About']               # => #<Page @uri='/about' @name='About'>
@@ -121,4 +122,37 @@ e.g. <tt>pages.sitemap!</tt> which calls <tt>pages['sitemap']</tt>
 You may also query to see if a match exists by appending a <tt>?</tt> to your search
 
   pages.sitemap?  # => true
-  pages.missing?  # => false
+  pages.missing?  # => false
+
+
+=== Composable
+
+Functionality for +QueryableArray+ has been separated out into individual modules
+containing their own features which allows you to create your own objects and only
+include the features you care about
+
+* <tt>QueryableArray::DefaultFinder</tt> - Allows objects to be searched by +default_finders+ thru <tt>[]</tt>
+* <tt>QueryableArray::DotNotation</tt> - Allows objects to be searched using dot notation thru +method_missing+ which behaves like an alias to <tt>QueryableArray::DefaultFinder#[]</tt>
+* <tt>QueryableArray::DynamicFinder</tt> - Allows objects to be searched by dynamic finders thru +method_missing+ similar to the ActiveRecord dynamic attribute-based finders e.g. +find_by_email+ or +find_all_by_last_name+
+* <tt>QueryableArray::Queryable</tt> - Allows +find_by+ and +find_all+ to accept search hashes which are converted into +Proc+ searches and passed as the block arguments for +find+ and +find_all+ respectively
+* <tt>QueryableArray::Shorthand</tt> - Makes <tt>[search_hash]</tt> and <tt>[[search_hash]]</tt> behave as an alias for +find_by+ and +find_all+ respectively
+
+
+=== Real world example
+
+Try using it inside of your templates:
+
+  <div class="posts">
+    <%- posts[[published: true]].each do |post| -%>
+      <div class="post">
+        <h2><a href="<%= post.url -%>"><%= post.title -%></a></h2>
+        <div class="excerpt"><%= post.excerpt -%></div>
+        <a href="<%= post.url -%>#comments"><%= post.comments[[approved: true]].size -%> comments</a>
+      </div>
+    <%- end -%>
+  </div>
+
+
+== Testing
+
+  bundle exec rake

data/Rakefile

@@ -1,5 +1,9 @@
 require 'rake/testtask'
-require 'rdoc/task'
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rake/rdoctask'
+end
 
 desc 'Default: run unit tests.'
 task :default => :test

data/lib/queryable_array.rb

@@ -3,6 +3,7 @@ require 'queryable_array/dot_notation'
 require 'queryable_array/dynamic_finder'
 require 'queryable_array/queryable'
 require 'queryable_array/shorthand'
+require 'queryable_array/version'
 
 # A +QueryableArray+ inherits from +Array+ and is intended to store a group of
 # objects which share the same attributes allowing them to be searched. It

data/lib/queryable_array/default_finder.rb

@@ -1,4 +1,9 @@
 class QueryableArray < Array
+  # Allows objects to be searched by +default_finders+ thru <tt>[]</tt>. For example:
+  #
+  #   users = QueryableArray.new(User.all, :email)
+  #   users['test@example.com']    # => #<User @email='test@example.com'>
+  #   users['missing@domain.com']  # => nil
   module DefaultFinder
     attr_accessor :default_finders
 
@@ -11,19 +16,26 @@ class QueryableArray < Array
       self.default_finders = Array(default_finders)
     end
 
-    # If +default_finders+ has been set and +key+ is not a +Fixnum+ then it
-    # loops thru each +default_finders+ and returns the first matching result
-    # of +find_by(finder => key)+ or +find_all(finder => key.first)+ if +key+
-    # is an +Array+. If +key+ is already a +Hash+ or an +Array+ containing one
-    # then it acts like an alias for +find_by+ or +find_all+ respectively. It
-    # behaves exactly like its superclass +Array+ in all other cases.
+    # If +default_finders+ has been set and +key+ is not a +Fixnum+, +Range+,
+    # or anything else natively supported by +Array+ then it loops thru each
+    # +default_finders+ and returns the first matching result of +find_by(finder => key)+
+    # or +find_all(finder => key.first)+ if +key+ is an +Array+. If +key+ is already
+    # a +Hash+ or an +Array+ containing a +Hash+ then it acts like an alias for +find_by+
+    # or +find_all+ respectively. It also accepts a +Proc+ or any object that responds to
+    # +call+. It behaves exactly like its superclass +Array+ in all other cases.
     #
     #   pages = QueryableArray.new(Page.all, [:uri, :name])
     #
-    #   pages['/']        # => #<Page @uri='/'>
-    #   pages['Home']     # => #<Page @name='Home'>
-    #   pages[/home/i]    # => #<Page @name='Home'>
+    #   pages['/']        # => #<Page @uri='/' @name='Home'>
+    #   pages['Home']     # => #<Page @uri='/' @name='Home'>
+    #   pages[/home/i]    # => #<Page @uri='/' @name='Home'>
     #   pages['missing']  # => nil
+    #
+    #   pages[[/users/i]]    # => [#<Page @uri='/users/bob' @name='Bob'>, #<Page @uri='/users/steve' @name='Steve'>]
+    #   pages[[/missing/i]]  # => []
+    #
+    #   pages[proc { |page| page.uri == '/' }]         # => #<Page @uri='/' @name='Home'>
+    #   pages[[proc { |page| page.uri =~ /users/i }]]  # => [#<Page @uri='/users/bob' @name='Bob'>, #<Page @uri='/users/steve' @name='Steve'>]
     def [](key)
       super
     rescue TypeError => error
@@ -35,6 +47,10 @@ class QueryableArray < Array
       end
     end
 
+    # Converts a search into a +Proc+ object that can be passed to +find_by+ or
+    # +find_all+. If +search+ is a +Proc+ or an object that responds to +call+
+    # then it is wrapped in a +Proc+ and returned. Otherwise the returned +Proc+
+    # loops thru each +default_finders+ looking for a value that matches +search+.
     def query(search)
       Proc.new do |object|
         proc = search.respond_to?(:call) ? search : Proc.new do |object|

data/lib/queryable_array/dot_notation.rb

@@ -1,23 +1,32 @@
 require 'queryable_array/default_finder'
 
 class QueryableArray < Array
+  # Allows objects to be searched using dot notation thru +method_missing+
+  # which behaves like an alias to <tt>QueryableArray::DefaultFinder#[]</tt>
   module DotNotation
     def self.included(base)
       base.send :include, DefaultFinder
     end
 
-    # If +method_name+ does not have a <tt>!</tt> or <tt>?</tt> suffix then +self[/#{method_name}/i]+
+    # If +method_name+ does not have a <tt>!</tt> or <tt>?</tt> suffix then <tt>self[/#{method_name}/i]</tt>
     # is returned. If it returns +nil+ or raises +TypeError+ (no +default_finders+) then +super+ is returned.
     #
-    # If +method_name+ ends in a <tt>!</tt> then +self[method_name]+ (without the <tt>!</tt>) is returned. If +method_name+
+    # If +method_name+ ends in a <tt>!</tt> then <tt>self[method_name]</tt> (without the <tt>!</tt>) is returned. If +method_name+
     # ends with a <tt>?</tt> then a boolean is returned determining whether or not a match was found.
     #
     #   users = QueryableArray.new User.all, :username
     #
-    #   users.bob                             # => #<User @name='bob'>
-    #   users.BOB                             # => #<User @name='bob'>
-    #   users.missing                         # => NoMethodError
-    #   QueryableArray.new.missing            # => NoMethodError
+    #   users.bob                   # => #<User @username='bob'>
+    #   users.BOB                   # => #<User @username='bob'>
+    #   users.missing               # => NoMethodError
+    #   QueryableArray.new.missing  # => NoMethodError
+    #
+    #   users.bob!  # => #<User @username='bob'>
+    #   users.BOB!  # => NoMethodError
+    #
+    #   users.bob?      # => true
+    #   users.BOB?      # => true
+    #   users.missing?  # => false
     def method_missing(method_name, *arguments)
       if method_name.to_s =~ /^(.+?)([\!\?])?$/
         search = $2 == '!' ? $1 : /#{$1}/i
@@ -30,8 +39,10 @@ class QueryableArray < Array
       end
     end
 
+    # Checks if +method_name+ can be handled by +method_missing+ and
+    # and delegates the call to +super+ otherwise.
     def respond_to_missing?(method_name, include_super)
-      !!(method_name.to_s =~/\?$/ || super || send(method_name))
+      !!(method_name.to_s =~ /\?$/ || super || send(method_name))
     rescue NoMethodError
       false
     end

data/lib/queryable_array/dynamic_finder.rb

@@ -1,5 +1,8 @@
 class QueryableArray < Array
   module DynamicFinder
+    # Allows objects to be searched by dynamic finders thru +method_missing+ similar
+    # to the ActiveRecord dynamic attribute-based finders e.g. +find_by_email+ or
+    # +find_all_by_last_name+
     def self.included(base)
       base.send :alias_method, :find_all_by, :find_all
     end
@@ -35,7 +38,7 @@ class QueryableArray < Array
     def method_missing(method_name, *arguments)
       if query = finder?(method_name)
         search = Hash[query[:attributes].split('_and_').zip(arguments)]
-        send "find_#{query[:type]}", search
+        send "find_#{query[:type].downcase}", search
       else
         super
       end

data/lib/queryable_array/queryable.rb

@@ -1,16 +1,19 @@
 class QueryableArray < Array
+  # Allows +find_by+ and +find_all+ to accept search hashes which are
+  # converted into +Proc+ searches and passed as the block arguments for
+  # +find+ and +find_all+ respectively
   module Queryable
-    # Returns a QueryableArray of objects matching +search+ criteria. When a +block+
-    # is specified, it behaves exactly like +Enumerable#find_all+. Otherwise the
-    # +search+ hash is converted into a +finder+ proc and passed as the block 
-    # argument to +Enumerable#find_all+.
+    # Returns a dup'd +Queryable+ replaced with objects matching the +search+
+    # criteria. When a +block+ is specified, it behaves exactly like
+    # +Enumerable#find_all+. Otherwise the +search+ hash is converted into
+    # a +finder+ proc and passed as the block argument to +Enumerable#find_all+.
     #
     #   users.find_all(age: 30)                  # => [#<User @age=30>, #<User @age=30>, ...]
     #   users.find_all(name: 'missing')          # => []
     #   users.find_all { |user| user.age < 30 }  # => [#<User @age=22>, #<User @age=26>, ...]
     def find_all(search = {}, &block)
       block = finder search unless block_given?
-      self.class.new super(&block)
+      dup.replace super(&block)
     end
 
     # Behaves exactly like +find_all+ but only returns the first match. If no match
@@ -24,14 +27,24 @@ class QueryableArray < Array
     end
 
     # Accepts a +search+ hash and returns a +Proc+ which determines if all of an
-    # object's attributes match their expected search values. It can be used as
+    # object's searched attributes match their expected values. It can be used as
     # the block arguments for +find+, +find_by+ and +find_all+.
     #
-    #   query = finder name: 'bob'     # => proc { |user| user.name == 'bob' }
+    # Values are compared with expected values using <tt>==</tt> or <tt>===</tt>.
+    # If the expected value is a +Proc+ or anything that responds to +call+ then
+    # it is evaluated with the +value+ as an argument and checks for a response
+    # other than +nil+ or +false+.
+    #
+    # Searched attributes first check if the +object+ responds to the attribute
+    # so +NoMethodError+ is never thrown if an attribute doesn't exist.
+    #
+    #   query = finder(name: 'bob')    # => proc { |user| user.name == 'bob' } # pseudo code
     #   query User.new(name: 'steve')  # => false
     #   query User.new(name: 'bob')    # => true
     #
     #   users.find(&query)             # => #<User @name='bob'>
+    #
+    #   users.find &finder(missing: 'value')  # => nil
     def finder(search)
       Proc.new do |object|
         search.all? do |attribute, expected|

data/lib/queryable_array/shorthand.rb

@@ -1,8 +1,10 @@
 class QueryableArray < Array
+  # Makes <tt>[search_hash]</tt> and <tt>[[search_hash]]</tt> behave as an alias
+  # for +find_by+ and +find_all+ respectively
   module Shorthand
-    # If +key+ is a +Hash+ or an +Array+ containing one
+    # If +key+ is a +Hash+, +Proc+, or an +Array+ containing a +Hash+ or +Proc+
     # then it acts like an alias for +find_by+ or +find_all+ respectively. It
-    # behaves exactly like its superclass +Array+ in all other cases.
+    # delegates the call to +super+ in all other cases.
     #
     #   pages = QueryableArray.new Page.all
     #
@@ -12,9 +14,11 @@ class QueryableArray < Array
     #
     #   pages[[uri: '/']]                # => [#<Page @uri='/' @name='Home'>]
     #   pages[[uri: '/', name: 'Typo']]  # => []
+    #
+    #   pages[uri: proc { |uri| uri.count('/') > 1 }]  # => #<Page @uri='/users/bob' @name='Bob'>
     def [](key)
       # Try to handle numeric indexes, ranges, and anything else that is
-      # natively supported by Array first
+      # natively supported by +Array+ first
       super
     rescue TypeError => error
       method, key = key.is_a?(Array) ? [:find_all, key.first] : [:find_by, key]

data/lib/queryable_array/version.rb

@@ -2,7 +2,7 @@ class QueryableArray < Array
   module Version
     MAJOR = 0
     MINOR = 0
-    PATCH = 0
+    PATCH = 1
 
     def self.to_s
       [MAJOR, MINOR, PATCH].join('.')

data/test/queryable_array_test.rb

@@ -95,6 +95,11 @@ describe QueryableArray do
       collection.respond_to?(:find_all_by).must_equal true
       collection.find_all_by(:uri => 'page_1').must_equal collection.find_all(:uri => 'page_1')
     end
+
+    it 'should return a QueryableArray with the same default_finders' do
+      collection.find_all(:uri => 'page_1').default_finders.must_equal collection.default_finders
+      collection.default_finders.wont_be_nil
+    end
   end
 
   describe :finder? do
@@ -163,6 +168,11 @@ describe QueryableArray do
       collection.pAgE_1?.must_equal true
       collection.missing?.must_equal false
     end
+
+    it 'should be case insensitive' do
+      collection.fInD_By_name('PAGE_1').must_equal pages[0]
+      collection.fInD_ALL_By_name('PAGE_1').must_equal [pages[0]]
+    end
   end
 
   describe :respond_to_missing? do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: queryable_array
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-24 00:00:00.000000000 Z
+date: 2013-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: respond_to_missing