module Sequel::Plugins::Finder::ClassMethods

Public Instance Methods

finder(meth=OPTS, opts=OPTS, &block) click to toggle source

Create an optimized finder method using a dataset placeholder literalizer. This pre-computes the SQL to use for the query, except for given arguments.

There are two ways to use this. The recommended way is to pass a symbol that represents a model class method that returns a dataset:

def Artist.by_name(name)
  where(name: name)
end

Artist.finder :by_name

This creates an optimized first_by_name method, which you can call normally:

Artist.first_by_name("Joe")

The alternative way to use this to pass your own block:

Artist.finder(name: :first_by_name){|pl, ds| ds.where(name: pl.arg).limit(1)}

Note that if you pass your own block, you are responsible for manually setting limits if necessary (as shown above).

Options:

:arity

When using a symbol method name, this specifies the arity of the method. This should be used if if the method accepts an arbitrary number of arguments, or the method has default argument values. Note that if the method is defined as a dataset method, the class method Sequel creates accepts an arbitrary number of arguments, so you should use this option in that case. If you want to handle multiple possible arities, you need to call the finder method multiple times with unique :arity and :name methods each time.

:name

The name of the method to create. This must be given if you pass a block. If you use a symbol, this defaults to the symbol prefixed by the type.

:mod

The module in which to create the finder method. Defaults to the singleton class of the model.

:type

The type of query to run. Can be :first, :each, :all, or :get, defaults to :first.

Caveats:

This doesn't handle all possible cases. For example, if you have a method such as:

def Artist.by_name(name)
  name ? where(name: name) : exclude(name: nil)
end

Then calling a finder without an argument will not work as you expect.

Artist.finder :by_name
Artist.by_name(nil).first
# WHERE (name IS NOT NULL)
Artist.first_by_name(nil)
# WHERE (name IS NULL)

See Dataset::PlaceholderLiteralizer for additional caveats.

# File lib/sequel/plugins/finder.rb, line 101
def finder(meth=OPTS, opts=OPTS, &block)
  if block
    raise Error, "cannot pass both a method name argument and a block of Model.finder" unless meth.is_a?(Hash)
    raise Error, "cannot pass two option hashes to Model.finder" unless opts.equal?(OPTS)
    opts = meth
    raise Error, "must provide method name via :name option when passing block to Model.finder" unless meth_name = opts[:name]
  end

  type = opts.fetch(:type, :first)
  unless prepare = opts[:prepare]
    raise Error, ":type option to Model.finder must be :first, :all, :each, or :get" unless FINDER_TYPES.include?(type)
  end
  limit1 = type == :first || type == :get
  meth_name ||= opts[:name] || :"#{type}_#{meth}"

  argn = lambda do |model|
    if arity = opts[:arity]
      arity
    else
      method = block || model.method(meth)
      (method.arity < 0 ? method.arity.abs - 1 : method.arity)
    end
  end

  loader_proc = if prepare
    proc do |model|
      args = prepare_method_args('$a', argn.call(model))
      ds = if block
        model.instance_exec(*args, &block)
      else
        model.public_send(meth, *args)
      end
      ds = ds.limit(1) if limit1
      model_name = model.name
      if model_name.to_s.empty?
        model_name = model.object_id
      else
        model_name = model_name.gsub(/\W/, '_')
      end
      ds.prepare(type, :"#{model_name}_#{meth_name}")
    end
  else
    proc do |model|
      n = argn.call(model)
      block ||= lambda do |pl, model2|
        args = (0...n).map{pl.arg}
        ds = model2.public_send(meth, *args)
        ds = ds.limit(1) if limit1
        ds
      end

      Sequel::Dataset::PlaceholderLiteralizer.loader(model, &block) 
    end
  end

  @finder_loaders[meth_name] = loader_proc
  mod = opts[:mod] || singleton_class
  if prepare
    def_prepare_method(mod, meth_name)
  else
    def_finder_method(mod, meth_name, type)
  end
end
freeze() click to toggle source
Calls superclass method
# File lib/sequel/plugins/finder.rb, line 165
def freeze
  @finder_loaders.freeze
  @finder_loaders.each_key{|k| finder_for(k)} if @dataset
  @finders.freeze
  super
end
prepared_finder(meth=OPTS, opts=OPTS, &block) click to toggle source

Similar to finder, but uses a prepared statement instead of a placeholder literalizer. This makes the SQL used static (cannot vary per call), but allows binding argument values instead of literalizing them into the SQL query string.

If a block is used with this method, it is instance_execed by the model, and should accept the desired number of placeholder arguments.

The options are the same as the options for finder, with the following exception:

:type

Specifies the type of prepared statement to create

# File lib/sequel/plugins/finder.rb, line 183
def prepared_finder(meth=OPTS, opts=OPTS, &block)
  if block
    raise Error, "cannot pass both a method name argument and a block of Model.finder" unless meth.is_a?(Hash)
    meth = meth.merge(:prepare=>true)
  else
    opts = opts.merge(:prepare=>true)
  end
  finder(meth, opts, &block)
end

Private Instance Methods

def_finder_method(mod, meth, type) click to toggle source

Define a finder method in the given module with the given method name that load rows using the finder with the given name.

# File lib/sequel/plugins/finder.rb, line 199
def def_finder_method(mod, meth, type)
  mod.send(:define_method, meth){|*args, &block| finder_for(meth).public_send(type, *args, &block)}
end
def_prepare_method(mod, meth) click to toggle source

Define a #prepared_finder method in the given module that will call the associated prepared statement.

# File lib/sequel/plugins/finder.rb, line 205
def def_prepare_method(mod, meth)
  mod.send(:define_method, meth){|*args, &block| finder_for(meth).call(prepare_method_arg_hash(args), &block)}
end
finder_for(meth) click to toggle source

Find the finder to use for the give method. If a finder has not been loaded for the method, load the finder and set correctly in the finders hash, then return the finder.

# File lib/sequel/plugins/finder.rb, line 212
def finder_for(meth)
  unless finder = (frozen? ? @finders[meth] : Sequel.synchronize{@finders[meth]})
    finder_loader = @finder_loaders.fetch(meth)
    finder = finder_loader.call(self)
    Sequel.synchronize{@finders[meth] = finder}
  end
  finder
end
prepare_method_arg_hash(args) click to toggle source

An hash of prepared argument values for the given arguments, with keys starting at a. Used by the methods created by prepared_finder.

# File lib/sequel/plugins/finder.rb, line 223
def prepare_method_arg_hash(args)
  h = {}
  prepare_method_args('a', args.length).zip(args).each{|k, v| h[k] = v}
  h
end
prepare_method_args(base, n) click to toggle source

An array of prepared statement argument names, of length n and starting with base.

# File lib/sequel/plugins/finder.rb, line 230
def prepare_method_args(base, n)
  (0...n).map do
    s = base.to_sym
    base = base.next
    s
  end
end
reset_instance_dataset() click to toggle source

Clear any finders when reseting the instance dataset

Calls superclass method
# File lib/sequel/plugins/finder.rb, line 239
def reset_instance_dataset
  Sequel.synchronize{@finders.clear} if @finders && !@finders.frozen?
  super
end