talent_scout 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d013c77ffd08bf7bb7d36d4f30c10bc763a4ea79c437d80604985de86fadd74
-  data.tar.gz: a4a996e5b44c64af45806849f3744f06bf7f192d346416943739f172abf45180
+  metadata.gz: d5fd5304fedac4c3a0cddd986f91cbc7a6bbe03e31948a1abdbdeaf58b7e16bf
+  data.tar.gz: 55e50c5eb694771e367f9741d79ae5510adcf48c05fdd62252895a31157730d2
 SHA512:
-  metadata.gz: 24e7c840762d376d5dd9353e3f9b4f167424914e1320573fbcc5cf6dcb691ab5a78f4465261fd2ca029784dd5fac25192c8def19b1f2280401dd3a1452baed7a
-  data.tar.gz: b6be4607619b5dcae29c012fb5194b640e5a5bf5ad9de94f1cd80532cf9cfdb12d8d61f615297da0531b8fe2fa9504a589d7f3816da2192f3e6b7f603231cb58
+  metadata.gz: b4ce41f71c08cc80a4acaf3ed9b4b382b3132966f8656ee7b817751e71abdfcc5571234bc66b93f07e022545be4e939f0317b227b9d662732f5f8916a7a2a967
+  data.tar.gz: dcc4a74c840c6cb423865794008496788af7bbcdfa5fc8d4a3096bf85448efcba553af1c4e1045d62866a38b4a4ec63f8791a25f4e68c5879b43054893b68274

data/README.md

@@ -42,10 +42,16 @@ end
 ```html+erb
 <!-- app/views/posts/index.html.erb -->
 
-<%= form_with model: @search, method: :get do |form| %>
+<%= form_with model: @search, local: true, method: :get do |form| %>
+  <%= form.label :title_includes %>
   <%= form.text_field :title_includes %>
+
+  <%= form.label :within %>
   <%= form.select :within, @search.each_choice(:within), include_blank: true %>
+
+  <%= form.label :only_published %>
   <%= form.check_box :only_published %>
+
   <%= form.submit %>
 <% end %>
 
@@ -77,13 +83,13 @@ In the above example:
 
 * The `PostSearch` class handles the responsibility of searching for
   `Post` models.  It can apply any combination of its defined criteria,
-  automatically ignoring missing or blank input values.  It can also
-  order the results by one of its defined orders, in either ascending or
-  descending direction.
+  automatically ignoring missing, blank, or invalid input values.  It
+  can also order the results by one of its defined orders, in either
+  ascending or descending direction.
 * `PostsController#index` uses the `model_search` helper to construct a
-  `PostSearch`, and assigns it to the `@search` variable for later use
-  in the view.  The search results are also assigned to a variable for
-  use in the view.
+  `PostSearch` instance, and assigns it to the `@search` variable for
+  later use in the view.  The search results are also assigned to a
+  variable for use in the view.
 * The view uses Rails' stock form builder to build a search form with
   the `@search` variable.  The `link_to_search` helper is used to create
   links in the table header which sort the results.  Note that the
@@ -91,13 +97,13 @@ In the above example:
   `@search` unmodified.
 
 For a detailed explanation of the methods used in this example, see
-the [API documentation](http://www.rubydoc.info/gems/talent_scout/).
+the [API documentation](https://www.rubydoc.info/gems/talent_scout/).
 
 
-## Search Objects
+## Search Classes
 
-You can use the `talent_scout:search` generator to generate search
-object class definitions.  For example,
+You can use the `talent_scout:search` generator to generate a model
+search class definition.  For example,
 
 ```bash
 $ rails generate talent_scout:search post
@@ -110,14 +116,14 @@ class PostSearch < TalentScout::ModelSearch
 end
 ```
 
-Search objects inherit from `TalentScout::ModelSearch`.  Their target
-model class is inferred from the search object's class name.  For
-example, `PostSearch` will search for `Post` models by default.  To
-override this behavior, use `ModelSearch::model_class=`:
+Search classes inherit from `TalentScout::ModelSearch`.  Their target
+model class is inferred from the search class name.  For example,
+`PostSearch` will search for `Post` models by default.  To override this
+inference, use `ModelSearch::model_class=`:
 
 ```ruby
 class EmployeeSearch < TalentScout::ModelSearch
-  self.model_class = Person # will search for Person models instead of `Employee`
+  self.model_class = Person # search for Person models instead of `Employee`
 end
 ```
 
@@ -147,7 +153,8 @@ end
 ```
 
 Note that explicit query blocks are evaluated in the context of the
-model's `ActiveRecord::Relation`, just as model scopes are.
+model's `ActiveRecord::Relation`, just like Active Record `scope` blocks
+are.
 
 
 #### Criteria Type
@@ -180,7 +187,7 @@ Available criteria types are the same as for Active Model attributes:
 `:integer`, `:string`, `:time`, plus any custom types you define.
 
 An additional convenience type is also available: `:void`.  The `:void`
-type is just like `:boolean`, except that the criteria will not be
+type typecasts like `:boolean`, but prevents the criteria from being
 applied when the typecasted value is falsey.  For example:
 
 ```ruby
@@ -331,8 +338,8 @@ PostSearch.new(order: :title)
 PostSearch.new(order: :category)
 ```
 
-Only one order can be applied at a time, but an order can be defined
-over multiple columns:
+Only one order can be applied at a time, but an order can comprise
+multiple columns:
 
 ```ruby
 class PostSearch < TalentScout::ModelSearch
@@ -385,7 +392,7 @@ end
 PostSearch.new(order: :category).toggle_order(:category)
 ```
 
-To circumvent this behavior, and instead fix a column in a static
+To circumvent this behavior and instead fix a column in a static
 direction, append `" ASC"` or `" DESC"` to the column name:
 
 ```ruby
@@ -459,7 +466,7 @@ PostSearch.new(order: :title)
 ```
 
 Note that the default order direction can be either ascending or
-descending, by specifing `default: :asc` or `default: :desc`,
+descending by specifying `default: :asc` or `default: :desc`,
 respectively.  Also, just as only one order can be applied at a time,
 only one order can be designated default.
 
@@ -507,10 +514,9 @@ class EmployeesController < ApplicationController
 end
 ```
 
-In these examples, the search object is stored in a variable for use in
-the view, as are the search results.  The search results will be an
-`ActiveRecord::Relation`, so any additional scoping, such as pagination,
-can be applied to `@search.results`.
+In these examples, the search object is stored in `@search` for use in
+the view.  Note that `@search.results` returns an `ActiveRecord::Relation`,
+so any additional scoping, such as pagination, can be applied.
 
 
 ## Search Forms
@@ -519,15 +525,21 @@ Search forms can be rendered using Rails' form builder and a search
 object:
 
 ```html+erb
-<%= form_with model: @search, method: :get do |form| %>
+<%= form_with model: @search, local: true, method: :get do |form| %>
+  <%= form.label :title_includes %>
   <%= form.text_field :title_includes %>
+
+  <%= form.label :created_on %>
   <%= form.date_field :created_on %>
+
+  <%= form.label :only_published %>
   <%= form.check_box :only_published %>
+
   <%= form.submit %>
 <% end %>
 ```
 
-Notice the `method: :get` argument to `form_with`; this is **required**.
+**Notice the `method: :get` argument to `form_with`.  This is required.**
 
 Form fields will be populated with the criteria input (or default)
 values of the same name from `@search`.  Type-appropriate form fields
@@ -550,7 +562,7 @@ method:
 <%= link_to_search "Sort by title", @search.toggle_order(:title, :asc) %>
 ```
 
-The link will automatically point to current controller and current
+The link will automatically point to the current controller and current
 action, with query parameters from the given search object.  To link to
 a different controller or action, pass an options Hash in place of the
 search object:
@@ -585,9 +597,9 @@ rendering the view.
 One such method is `ModelSearch#toggle_order`, which was shown in
 [previous examples](#order-direction).  Remember that `toggle_order` is
 a builder-style method that does not modify the search object.  Instead,
-it duplicates the search object, and sets the order on the new search
-object.  Such behavior is suitable to generating links to multiple
-variants of a search, such as sort links in table column headers.
+it duplicates the search object, and sets the order on the new object.
+Such behavior is suitable to generating links to multiple variants of a
+search, such as sort links in table column headers.
 
 
 ### `ModelSearch#with` and `ModelSearch#without`
@@ -629,8 +641,7 @@ PostSearch.new(title: "Maaaaath!", published: false).without(:published)
 
 Another helpful method is `ModelSearch#each_choice`, which will iterate
 over the defined choices for a given criteria.  This can be used to
-generate links to variants of a search, or to generate options for a
-select box:
+generate links to variants of a search:
 
 ```ruby
 class PostSearch < TalentScout::ModelSearch
@@ -645,17 +656,19 @@ end
 <% end %>
 ```
 
+Notice that if the block passed to `each_choice` accepts two arguments,
+the 2nd argument will indicate if the choice is currently chosen.
+
+If no block is passed to `each_choice`, it will return an `Enumerator`.
+This can be used to generate options for a select box:
+
 ```html+erb
-<%= form_with model: @search, method: :get do |form| %>
+<%= form_with model: @search, local: true, method: :get do |form| %>
   <%= form.select :category, @search.each_choice(:category) %>
   <%= form.submit %>
 <% end %>
 ```
 
-If the block passed to `each_choice` accepts two arguments, the 2nd
-argument will indicate if the choice is currently chosen.  If no block
-is passed to `each_choice`, it will return an `Enumerator`.
-
 The `each_choice` method can also be invoked with `:order`.  Doing so
 will iterate over each direction of each defined order, yielding the
 appropriate labels including direction suffix:
@@ -668,7 +681,7 @@ end
 ```
 
 ```html+erb
-<%= form_with model: @search, method: :get do |form| %>
+<%= form_with model: @search, local: true, method: :get do |form| %>
   <%= form.select :order, @search.each_choice(:order) %>
   <%= form.submit %>
 <% end %>
@@ -707,24 +720,17 @@ end
 
 Remember that only one order can be applied at a time, so only one value
 in the Hash, at most, will be non-`nil`.
->>>>>>> b0d201c... Update README
 
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem "talent_scout"
-```
-
-Then execute:
+Add the gem to your Gemfile:
 
 ```bash
-$ bundle install
+$ bundle add talent_scout
 ```
 
-And finally, run the installation generator:
+And run the installation generator:
 
 ```bash
 $ rails generate talent_scout:install
@@ -733,9 +739,9 @@ $ rails generate talent_scout:install
 
 ## Contributing
 
-Run `rake test` to run the tests.
+Run `bin/test` to run the tests.
 
 
 ## License
 
-[MIT License](https://opensource.org/licenses/MIT)
+[MIT License](MIT-LICENSE)

data/Rakefile

@@ -1,22 +1,3 @@
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
-
-require 'yard'
-
-YARD::Rake::YardocTask.new(:doc) do |t|
-end
+require 'bundler/setup'
 
 require 'bundler/gem_tasks'
-
-require 'rake/testtask'
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.test_files = FileList['test/**/*_test.rb'].exclude('test/tmp/**/*')
-  t.verbose = false
-end
-
-task default: :test

data/lib/talent_scout/controller.rb

@@ -4,10 +4,10 @@ module TalentScout
 
     module ClassMethods
       # Returns the controller model search class.  Defaults to a class
-      # corresponding to the singular-form of the controller name.  The
-      # model search class can also be set with {model_search_class=}.
-      # If the model search class has not been set, and the default
-      # class does not exist, a +NameError+ will be raised.
+      # corresponding to the singular form of the controller name.  The
+      # class can be set with {model_search_class=}.  If the class has
+      # not been set and the default class does not exist, a +NameError+
+      # will be raised.
       #
       # @example
       #   class PostsController < ApplicationController
@@ -17,8 +17,7 @@ module TalentScout
       #
       # @return [Class<TalentScout::ModelSearch>]
       # @raise [NameError]
-      #   if the model search class has not been set and the default
-      #   class does not exist
+      #   if the model search class does not exist
       def model_search_class
         @model_search_class ||= "#{controller_path.classify}Search".constantize
       end
@@ -26,14 +25,13 @@ module TalentScout
       # Sets the controller model search class.  See {model_search_class}.
       #
       # @param klass [Class<TalentScout::ModelSearch>]
-      # @return [Class<TalentScout::ModelSearch>]
+      # @return [klass]
       def model_search_class=(klass)
         @model_search_class = klass
       end
 
       # Similar to {model_search_class}, but returns nil instead of
-      # raising an error when the value has not been set (via
-      # {model_search_class=}) and the default class does not exist.
+      # raising an error when the model search class does not exist.
       #
       # @return [Class<TalentScout::ModelSearch>, nil]
       def model_search_class?
@@ -46,9 +44,9 @@ module TalentScout
       end
     end
 
-    # Instantiates {ClassMethods#model_search_class} using the current
-    # request's query params.  If that class does not exist, a
-    # +NameError+ will be raised.
+    # Instantiates {ClassMethods#model_search_class ::model_search_class}
+    # using the current request's query params.  If that class does not
+    # exist, a +NameError+ will be raised.
     #
     # @return [TalentScout::ModelSearch]
     # @raise [NameError]

data/lib/talent_scout/criteria.rb

@@ -1,6 +1,7 @@
 module TalentScout
   # @!visibility private
   class Criteria
+    SYMBOL_TO_PROC_ARITY = :to_s.to_proc.arity
 
     attr_reader :names, :allow_nil, :block
 
@@ -14,7 +15,7 @@ module TalentScout
       if applicable?(attribute_set)
         if block
           block_args = names.map{|name| attribute_set[name].value }
-          if block.arity == -1 # block from Symbol#to_proc
+          if block.arity == SYMBOL_TO_PROC_ARITY # assume block is from Symbol#to_proc
             scope.instance_exec(scope, *block_args, &block)
           else
             scope.instance_exec(*block_args, &block)

data/lib/talent_scout/model_search.rb

@@ -7,10 +7,10 @@ module TalentScout
     extend ActiveModel::Translation
 
     # Returns the model class that the search targets.  Defaults to a
-    # class with same name name as the search class, minus the "Search"
-    # suffix.  The model class can also be set with {model_class=}.
-    # If the model class has not been set, and the default class does
-    # not exist, a +NameError+ will be raised.
+    # class with same name as the search class, minus the "Search"
+    # suffix.  The class can be set with {model_class=}.  If the class
+    # has not been set and the default class does not exist, a
+    # +NameError+ will be raised.
     #
     # @example Default behavior
     #   class PostSearch < TalentScout::ModelSearch
@@ -27,8 +27,7 @@ module TalentScout
     #
     # @return [Class]
     # @raise [NameError]
-    #   if the model class has not been set and the default class does
-    #   not exist
+    #   if the model class does not exist
     def self.model_class
       @model_class ||= self.superclass == ModelSearch ?
         self.name.chomp("Search").constantize : self.superclass.model_class
@@ -37,7 +36,7 @@ module TalentScout
     # Sets the model class that the search targets.  See {model_class}.
     #
     # @param model_class [Class]
-    # @return [Class]
+    # @return [model_class]
     def self.model_class=(model_class)
       @model_class = model_class
     end
@@ -47,11 +46,11 @@ module TalentScout
       @model_name ||= ModelName.new(self)
     end
 
-    # Sets the default scope of the search.  Like ActiveRecord's
+    # Sets the default scope of the search.  Like Active Record's
     # +default_scope+, the scope here is specified as a block which is
     # evaluated in the context of the {model_class}.  Also like
-    # ActiveRecord, multiple calls to this method will be merged
-    # together.
+    # Active Record, multiple calls of this method will append to the
+    # default scope.
     #
     # @example
     #   class PostSearch < TalentScout::ModelSearch
@@ -66,7 +65,7 @@ module TalentScout
     #   end
     #
     #   class PostSearch < TalentScout::ModelSearch
-    #     default_scope(&:published)
+    #     default_scope &:published
     #   end
     #
     #   PostSearch.new.results  # == Post.published
@@ -78,36 +77,36 @@ module TalentScout
       criteria_list.insert(i, Criteria.new([], true, &block))
     end
 
-    # Defines criteria to incorporate into the search.  Each criteria
-    # corresponds to an attribute on the search object that can be used
-    # when building a search form.
-    #
-    # Each attribute has a type, just as Active Model attributes do, and
-    # values passed into the search object are typecasted before
-    # criteria are evaluated.  Supported types are the same as Active
-    # Model (e.g. +:string+, +:boolean+, +:integer+, etc), with the
-    # addition of a +:void+ type.  A +:void+ type is just like a
-    # +:boolean+ type, except that the criteria is not evaluated when
-    # the type-casted value is falsey.
-    #
-    # Alternatively, instead of a type, an array or hash of +choices+
-    # can be specified, and the criteria will be evaluated only if the
-    # passed-in value matches one of the choices.
-    #
-    # Active Model +attribute_options+ can also be specified, most
-    # notably +:default+ to provide the criteria a default value to
-    # operate on.
-    #
-    # Each criteria can specify a block which recieves the corresponding
-    # type-casted value as an argument.  If the corresponding value is
-    # not set on the search object (and no default value is defined),
-    # the criteria will not be evaluated.  Like an Active Record
-    # +scope+ block, a criteria block is evaluated in the context of an
-    # +ActiveRecord::Relation+ and should return an
-    # +ActiveRecord::Relation+.  A criteria block may also return nil,
-    # in which case the criteria will be skipped.  If no criteria block
-    # is specified, the criteria will be evaluated as a +where+ clause
-    # using the criteria name and type-casted value.
+    # Defines criteria that can be incorporated into a search.  The
+    # criteria will have a corresponding attribute on the search object
+    # that can be used when building a search form.  The type of the
+    # attribute can be specified, just as with Active Model attributes,
+    # and the attribute value will be typecasted before the criteria is
+    # incorporated.  Supported types are the same as Active Model (e.g.
+    # +:string+, +:boolean+, +:integer+, etc).  The default type is
+    # +:string+.  An additional +:void+ type is also supported, which
+    # typecasts like the +:boolean+ type, but prevents the criteria
+    # from being incorporated if the typecasted value is falsey.
+    #
+    # Alternatively, instead of a type, an Array or Hash of +choices+
+    # can be specified, and the criteria will be incorporated only if
+    # the attribute value matches one of the choices.
+    #
+    # Active Model +attribute_options+ can also be specified.  Most
+    # notably, the +:default+ option can specify a default value for the
+    # criteria to operate on.  If a default value is not specified, the
+    # criteria will be incorporated only if the attribute value is set.
+    #
+    # If no block is given, the criteria will be incorporated as a
+    # +where+ clause using the criteria name and typecasted attribute
+    # value.
+    #
+    # If a block is given, it will be passed the typecasted attribute
+    # value, and it will be evaluated in the context of an
+    # +ActiveRecord::Relation+, like Active Record +scope+ blocks are.
+    # The block should return an +ActiveRecord::Relation+.  The block
+    # may also return nil, in which case the criteria will not be
+    # incorporated.
     #
     # As a convenient shorthand, Active Record scopes which have been
     # defined on the {model_class} can be used directly as criteria
@@ -115,7 +114,7 @@ module TalentScout
     # the criteria block.
     #
     #
-    # @example Implicit block
+    # @example Without a block
     #   class PostSearch < TalentScout::ModelSearch
     #     criteria :title
     #   end
@@ -123,7 +122,7 @@ module TalentScout
     #   PostSearch.new(title: "FOO").results  # == Post.where(title: "FOO")
     #
     #
-    # @example Explicit block
+    # @example With a block
     #   class PostSearch < TalentScout::ModelSearch
     #     criteria :title do |string|
     #       where("title LIKE ?", "%#{string}%")
@@ -171,7 +170,7 @@ module TalentScout
     #   PostSearch.new(only_edited: "1").results    # == Post.where("modified_at > created_at")
     #
     #
-    # @example Specifying choices (array)
+    # @example Specifying choices (Array)
     #   class PostSearch < TalentScout::ModelSearch
     #     criteria :category, choices: %w[science tech engineering math]
     #   end
@@ -180,7 +179,7 @@ module TalentScout
     #   PostSearch.new(category: "BLAH").results  # == Post.all
     #
     #
-    # @example Specifying choices (hash)
+    # @example Specifying choices (Hash)
     #   class PostSearch < TalentScout::ModelSearch
     #     criteria :within, choices: {
     #       "Last 24 hours" => 24.hours,
@@ -209,15 +208,38 @@ module TalentScout
     #   PostSearch.new(within_days: 2).results  # == Post.where("created_at >= ?", 2.days.ago)
     #
     #
-    # @param names [String, Symbol, Array<String>, Array<Symbol>]
-    # @param type [Symbol, ActiveModel::Type]
-    # @param choices [Array<String>, Array<Symbol>, Hash<String, Object>, Hash<Symbol, Object>]
-    # @param attribute_options [Hash]
-    # @option attribute_options :default [Object]
-    # @yieldreturn [ActiveRecord::Relation, nil]
+    # @overload criteria(name, type = :string, **attribute_options)
+    #   @param name [String, Symbol]
+    #   @param type [Symbol, ActiveModel::Type]
+    #   @param attribute_options [Hash]
+    #   @option attribute_options :default [Object]
+    #
+    # @overload criteria(name, type = :string, **attribute_options, &block)
+    #   @param name [String, Symbol]
+    #   @param type [Symbol, ActiveModel::Type]
+    #   @param attribute_options [Hash]
+    #   @option attribute_options :default [Object]
+    #   @yieldparam value [Object]
+    #   @yieldreturn [ActiveRecord::Relation, nil]
+    #
+    # @overload criteria(name, choices:, **attribute_options)
+    #   @param name [String, Symbol]
+    #   @param choices [Array<String>, Array<Symbol>, Hash{String => Object}, Hash{Symbol => Object}]
+    #   @param attribute_options [Hash]
+    #   @option attribute_options :default [Object]
+    #   @yieldreturn [ActiveRecord::Relation, nil]
+    #
+    # @overload criteria(name, choices:, **attribute_options, &block)
+    #   @param name [String, Symbol]
+    #   @param choices [Array<String>, Array<Symbol>, Hash{String => Object}, Hash{Symbol => Object}]
+    #   @param attribute_options [Hash]
+    #   @option attribute_options :default [Object]
+    #   @yieldparam value [Object]
+    #   @yieldreturn [ActiveRecord::Relation, nil]
+    #
     # @return [void]
     # @raise [ArgumentError]
-    #   if +choices+ are specified and +type+ is other than +:string+
+    #   if +choices+ is specified and +type+ is not +:string+
     def self.criteria(names, type = :string, choices: nil, **attribute_options, &block)
       if choices
         if type != :string
@@ -237,7 +259,7 @@ module TalentScout
       criteria_list << crit
 
       crit.names.each do |name|
-        attribute name, type, attribute_options
+        attribute name, type, **attribute_options
 
         # HACK FormBuilder#select uses normal attribute readers instead
         # of `*_before_type_cast` attribute readers.  This breaks value
@@ -250,26 +272,26 @@ module TalentScout
       end
     end
 
-    # Defines an order that the search can apply to its results.  Only
-    # one order can be applied at a time, but an order can be defined
-    # over multiple columns.  If no columns are specified, the order's
-    # +name+ is taken as its column.
-    #
-    # Each order can be applied in an ascending or descending direction
-    # by appending a corresponding suffix to the order value.  By
-    # default, these suffixes are +".asc"+ and +".desc"+, but they can
-    # be overridden in the order definition using the +:asc_suffix+ and
-    # +:desc_suffix+ options, respectively.
-    #
-    # Order direction affects all columns of an order defintion, unless
+    # Defines a result order that can be incorporated into a search.
+    # Only one order can be incorporated at a time, but an order can
+    # comprise multiple columns.  If no columns are specified, the
+    # order's +name+ is taken as its column.
+    #
+    # An order can be incorporated in either ascending or descending
+    # direction by appending an appropriate suffix to the order value.
+    # By default, these suffixes are +".asc"+ and +".desc"+, but they
+    # can be overridden in the order definition using the +:asc_suffix+
+    # and +:desc_suffix+ options, respectively.
+    #
+    # The order direction will affect all columns of the order, unless
     # a column explicitly specifies +"ASC"+ or +"DESC"+, in which case
     # that column will stay fixed in its specified direction.
     #
-    # To apply an order to the search results by default, use the
-    # +:default+ option in the order definition.  (Note that only one
-    # order can be designated as the default order.)
+    # To designate the order as the default result order, use the
+    # +:default+ option.  (Note that only one order can be designated as
+    # the default order.)
     #
-    # See also {toggle_order}.
+    # @see toggle_order
     #
     #
     # @example Single-column order
@@ -327,44 +349,50 @@ module TalentScout
     #   PostSearch.new(order: :title).results            # == Post.order("title")
     #
     #
-    # @param name [String, Symbol]
-    # @param columns [Array<String>, Array<Symbol>, nil]
-    # @param options [Hash]
-    # @option options :default [Boolean, :asc, :desc] (false)
-    # @option options :asc_suffix [String] (".asc")
-    # @option options :desc_suffix [String] (".desc")
-    # @return [void]
+    # @overload order(name, columns = [name], **options)
+    #   @param name [String, Symbol]
+    #   @param columns [Array<String>, Array<Symbol>]
+    #   @param options [Hash]
+    #   @option options :default [Boolean, :asc, :desc] (false)
+    #   @option options :asc_suffix [String] (".asc")
+    #   @option options :desc_suffix [String] (".desc")
+    #   @return [void]
     def self.order(name, columns = nil, default: false, **options)
-      definition = OrderDefinition.new(name, columns, options)
+      definition = OrderDefinition.new(name, columns, **options)
 
       if !attribute_types.fetch("order", nil).equal?(order_type) || default
         criteria_options = default ? { default: definition.choice_for_direction(default) } : {}
         criteria_list.reject!{|crit| crit.names == ["order"] }
-        criteria "order", order_type, criteria_options, &:order
+        criteria "order", order_type, **criteria_options, &:order
       end
 
       order_type.add_definition(definition)
     end
 
-    # Initializes a +ModelSearch+ instance.  Assigns values in +params+
-    # to appropriate criteria attributes.
+    # Initializes a +ModelSearch+ instance.  Assigns values from
+    # +params+ to corresponding criteria attributes.
     #
     # If +params+ is a +ActionController::Parameters+, blank values are
     # ignored.  This behavior prevents empty search form fields from
     # affecting search results.
     #
-    # @param params [Hash<String, Object>, Hash<Symbol, Object>, ActionController::Parameters]
+    # @param params [Hash{String => Object}, Hash{Symbol => Object}, ActionController::Parameters]
+    # @raise [ActiveModel::UnknownAttributeError]
+    #   if +params+ is a Hash, and it contains an unrecognized key
     def initialize(params = {})
+      # HACK initialize ActiveRecord state required by ActiveRecord::AttributeMethods::BeforeTypeCast
+      @transaction_state ||= nil
+
       if params.is_a?(ActionController::Parameters)
         params = params.permit(self.class.attribute_types.keys).reject!{|key, value| value.blank? }
       end
       super(params)
     end
 
-    # Applies search {criteria} with set or default attribute values,
-    # and the set or default {order} on top of the {default_scope}.
-    # Returns an +ActiveRecord::Relation+, allowing further scopes, such
-    # as pagination, to be applied post-hoc.
+    # Applies the {default_scope}, search {criteria} with set or default
+    # attribute values, and the set or default {order} to the
+    # {model_class}.  Returns an +ActiveRecord::Relation+, allowing
+    # further scopes, such as pagination, to be applied post-hoc.
     #
     # @example
     #   class PostSearch < TalentScout::ModelSearch
@@ -383,14 +411,15 @@ module TalentScout
     #
     # @return [ActiveRecord::Relation]
     def results
-      self.class.criteria_list.reduce(self.class.model_class) do |scope, crit|
+      self.class.criteria_list.reduce(self.class.model_class.all) do |scope, crit|
         crit.apply(scope, attribute_set)
       end
     end
 
-    # Builds a new model search object with +criteria_values+ merged on
-    # top of the subject search object's criteria values.  Does not
-    # modify the subject search object.
+    # Builds a new search object with +criteria_values+ merged on top of
+    # the subject search object's criteria values.
+    #
+    # Does not modify the subject search object.
     #
     # @example
     #   class PostSearch < TalentScout::ModelSearch
@@ -404,7 +433,7 @@ module TalentScout
     #   search.with(category: "tech").results  # == Post.where(category: "tech")
     #   search.results                         # == Post.where(category: "math")
     #
-    # @param criteria_values [Hash<String, Object>, Hash<Symbol, Object>]
+    # @param criteria_values [Hash{String => Object}, Hash{Symbol => Object}]
     # @return [TalentScout::ModelSearch]
     # @raise [ActiveModel::UnknownAttributeError]
     #   if one or more +criteria_values+ keys are invalid
@@ -412,10 +441,11 @@ module TalentScout
       self.class.new(attributes.merge!(criteria_values.stringify_keys))
     end
 
-    # Builds a new model search object with the subject search object's
+    # Builds a new search object with the subject search object's
     # criteria values, excluding values specified by +criteria_names+.
-    # Default criteria values will still be applied.  Does not modify
-    # the subject search object.
+    # Default criteria values will still be applied.
+    #
+    # Does not modify the subject search object.
     #
     # @example
     #   class PostSearch < TalentScout::ModelSearch
@@ -441,12 +471,12 @@ module TalentScout
       self.class.new(attributes.except!(*criteria_names))
     end
 
-    # Builds a new model search object with the specified order applied
-    # on top of the subject search object's criteria values.  If the
-    # subject search object already has the specified order applied, the
-    # order's direction will be toggled from +:asc+ to +:desc+ or from
-    # +:desc+ to +:asc+.  Otherwise, the specified order will be applied
-    # with an +:asc+ direction, overriding any previously applied order.
+    # Builds a new search object with the specified order applied on top
+    # of the subject search object's criteria values.  If the subject
+    # search object already has the specified order applied, the order's
+    # direction will be toggled from +:asc+ to +:desc+ or from +:desc+
+    # to +:asc+.  Otherwise, the specified order will be applied with an
+    # +:asc+ direction, overriding any previously applied order.
     #
     # If +direction+ is explicitly specified, that direction will be
     # applied regardless of previously applied direction.
@@ -479,10 +509,10 @@ module TalentScout
 
     # Iterates over a specified {criteria}'s defined choices.  If the
     # given block accepts a 2nd argument, a boolean will be passed
-    # indicating whether that choice is currently used by the subject
-    # search object.  If no block is given, an +Enumerator+ will be
-    # returned.
+    # indicating whether that choice is currently assigned to the
+    # specified criteria attribute.
     #
+    # If no block is given, an Enumerator is returned instead.
     #
     # @example With block
     #   class PostSearch < TalentScout::ModelSearch
@@ -547,9 +577,9 @@ module TalentScout
 
     # Returns a +HashWithIndifferentAccess+ with a key for each defined
     # {order}.  Each key's associated value indicates that order's
-    # currently applied direction -- +:asc+, +:desc+, or +nil+ if the
+    # currently applied direction -- +:asc+, +:desc+, or nil if the
     # order is not applied.  Note that only one order can be applied at
-    # a time, so only one value in the Hash, at most, will be non-+nil+.
+    # a time, so, at most, one value in the Hash will be non-nil.
     #
     # @example
     #   class PostSearch < TalentScout::ModelSearch

data/lib/talent_scout/version.rb

@@ -1,3 +1,3 @@
 module TalentScout
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: talent_scout
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jonathan Hefner
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,79 +15,16 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.2'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: capybara
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.15'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '2.15'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-- !ruby/object:Gem::Dependency
-  name: simple_form
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.0'
-description: 
+        version: '8.1'
 email:
-- jonathan.hefner@gmail.com
+- jonathan@hefner.pro
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -117,8 +53,9 @@ files:
 homepage: https://github.com/jonathanhefner/talent_scout
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  source_code_uri: https://github.com/jonathanhefner/talent_scout
+  changelog_uri: https://github.com/jonathanhefner/talent_scout/blob/master/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -126,15 +63,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
-signing_key: 
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Model-backed searches in Rails
 test_files: []