philtre 0.0.0 → 0.0.1

data/lib/philtre/grinder.rb

@@ -0,0 +1,195 @@
+require 'ripar'
+
+require 'philtre/filter.rb'
+require 'philtre/place_holder.rb'
+require 'philtre/empty_expression.rb'
+
+# Using the expressions in the filter, transform a dataset with
+# placeholders into a real dataset with expressions, for example:
+#
+#  ds = Personage.filter( :brief.lieu, :title.lieu ).order( :age.lieu )
+#  g = Grinder.new( Philtre.new(title: 'Grand High Poobah', :order => :age.desc  ) )
+#  nds = g.transform( ds )
+#  nds.sql
+#
+#  => SELECT * FROM "personages" WHERE (("title" = 'Grand High Poobah'))
+#
+# In a sense, this is a means to defining SQL functions with
+# optional keyword arguments.
+class Philtre::Grinder < Sequel::ASTTransformer
+  # filter must respond to expr_for( key, sql_field = nil ), expr_hash and order_hash
+  def initialize( filter = Philtre::Filter.new )
+    @filter = filter
+  end
+
+  attr_reader :filter
+
+  # pass in a dataset containing PlaceHolder expressions.
+  # you'll get back a modified dataset with the filter values
+  # filled in.
+  def transform( dataset, apply_unknown: true )
+    @unknown = []
+    @places = {}
+    @subsets = []
+
+    # handy for debugging
+    @original_dataset = dataset
+
+    # the transformed dataset with placeholders that
+    # exist in filter replaced. unknown might have values
+    # after this.
+    t_dataset = super(dataset)
+    unknown_placeholders
+
+    if unknown.any?
+      if apply_unknown
+        # now filter by whatever predicates are left over
+        # ie those not in the incoming dataset. Leftover
+        # order parameters will overwrite existing ones
+        # that are not protected by an outer select.
+        filter.subset( *unknown ).apply t_dataset
+      else
+        raise "unknown values #{unknown.inspect} for\n#{dataset.sql}"
+      end
+    else
+      t_dataset
+    end
+  end
+
+  alias [] transform
+
+  # Grouped hash of place holders in the original dataset from the last transform.
+  # Only has values after transform has been called.
+  def places
+    @places || raise("Call transform to find place holders.")
+  end
+
+  # collection of values in the filter that were not found as placeholders
+  # in the original dataset.
+  def unknown
+    @unknown || raise("Call transform to find placeholders not provided by the filter.")
+  end
+
+protected
+
+  # Set of all keys that are not in the placeholders
+  def extra_keys( keys )
+    incoming = keys
+    existing = places.flat_map{|subset, placeholders| placeholders.keys}
+
+    # find the elements in incoming that are not in existing
+    incoming - existing & incoming
+  end
+
+  def unknown_placeholders
+    unknown.concat extra_keys( filter.expr_hash.keys )
+    unknown.concat extra_keys( filter.order_hash.keys )
+  end
+
+  def context_places
+    @places ||= {}
+    @places[subset] ||= {}
+  end
+
+  # TODO rename subset to clause
+  def subset
+    @subsets.last || :none
+  end
+
+  def subset_stack
+    @subsets ||= []
+  end
+
+  def push_subset( latest_subset, &block )
+    subset_stack.push latest_subset
+    rv = yield
+    subset_stack.pop
+    rv
+  end
+
+  # Override the ASTTransformer method, which is where the work
+  # is done to transform the dataset containing placeholders into
+  # a dataset containing a proper SQL statement.
+  # Yes, this is in fact every OO purist's worst nightware - a Giant Switch Statement.
+  def v( obj )
+    case obj
+    when Sequel::Dataset
+      # transform empty expressions to false (or nil, but false is more debuggable)
+      # can't use nil for all kinds of expressions because nil mean NULL for
+      # most of the Sequel::SQL expressions.
+      obj.clone Hash[ v(obj.opts).map{|k,val| [k, val.is_a?(Philtre::EmptyExpression) ? false : val]} ]
+
+    # for Sequel::Models
+    when ->(obj){obj.respond_to? :dataset}
+      v obj.dataset
+
+    # for other things that are convertible to dataset
+    when ->(obj){obj.respond_to? :to_dataset}
+      v obj.to_dataset
+
+    # Keep the context for place holders,
+    # so we know what kind of expression to insert later.
+    # Each of :where, :order, :having, :select etc will come as a hash.
+    # There are some other top-level options too.
+    when Hash
+      rv = {}
+      obj.each do |key, val|
+        push_subset key do
+          rv[v(key)] = v(val)
+        end
+      end
+      rv
+
+    when Philtre::PlaceHolder
+      # get the expression for the placeholder.
+      # use the placeholder's field name if given
+      expr =
+      case subset
+      # substitute a comparison or some other predicate
+      when :where, :having
+        filter.expr_for obj.name, obj.sql_field
+
+      # substitute an order by expression
+      when :order
+        filter.order_for obj.name
+
+      # Substitute the field name only if it has a value.
+      # nil when the name doesn't have a value. This way,
+      #  select :some_field.lieu
+      # is left out when some_field does not have a value.
+      when :select
+        if filter[obj.name]
+          obj.sql_field || obj.name
+        end
+
+      else
+        raise "don't understand subset #{subset}"
+      end
+
+      # keep it, just in case
+      context_places[obj.name] = expr
+
+      # transform
+      expr || Philtre::EmptyExpression.new
+
+    when Array
+      # sometimes things are already an empty array, in which
+      # case just leave them alone.
+      return super if obj.empty?
+
+      # collect expressions, some may be empty.
+      exprs = super.reject{|e| e.is_a? Philtre::EmptyExpression}
+
+      # an empty array of expressions must be translated
+      # to an empty expression at this point.
+      exprs.empty? ? Philtre::EmptyExpression.new : exprs
+
+    when Sequel::SQL::ComplexExpression
+      # use the Array case above, otherwise copy the expression itself
+      v( obj.args ).empty? ? Philtre::EmptyExpression.new : super
+
+    else
+      super
+    end
+  end
+end

data/lib/philtre/place_holder.rb

@@ -0,0 +1,41 @@
+module Philtre
+  class PlaceHolder < Sequel::SQL::Expression
+    # name is what gets replaced by the operation and correspondingly named value in the filter
+    # sql_field is the name of the field that the operation will compare the named value to.
+    def initialize( name, sql_field = nil, bt = caller )
+      # backtrace
+      @bt = bt
+
+      @name = name
+      @sql_field = sql_field
+    end
+
+    attr_reader :bt
+    attr_reader :name
+    attr_reader :sql_field
+
+    # this is inserted into the generated SQL from a dataset that
+    # contains PlaceHolder instances.
+    def to_s_append( ds, s )
+      s << '$' << name.to_s
+      s << ':' << sql_field.to_s if sql_field
+      s << '/*' << small_source  << '*/'
+    end
+
+    def source
+      bt[1]
+    end
+
+    def small_source
+      source.split('/').last(2).join('/').split(':')[0..1].join(':')
+    end
+
+    def inspect
+      "#<#{self.class} #{name}:#{sql_field} @#{source}>"
+    end
+
+    def to_s
+      "#{name}:#{sql_field} @#{small_source}"
+    end
+  end
+end

data/lib/philtre/predicate_dsl.rb

@@ -0,0 +1,25 @@
+module Philtre
+  # This is a specialised module that also understands a simple
+  # DSL for creating predicates as methods.
+  #
+  # This is how the DSL works:
+  # each meth is a predicate, args is a set of alternatives
+  # and the block must return something convertible to a Sequel.expr
+  # to create the expression for that predicate.
+  class PredicateDsl < Module
+    def initialize( &bloc )
+      if bloc
+        if bloc.arity == 0
+          module_eval &bloc
+        else
+          bloc.call self
+        end
+      end
+    end
+
+    def method_missing(meth, *args, &bloc)
+      define_method meth, &bloc
+      args.each{|arg| send :alias_method, arg, meth }
+    end
+  end
+end

data/lib/philtre/predicate_splitter.rb

@@ -0,0 +1,40 @@
+require 'fastandand'
+
+module Philtre
+  # This is to split things like birth_year_gt into
+  #  - birth_year (the field)
+  #  - gt (the predicate)
+  # Yes, there are side effects.
+  # === is provided so it can be used in case statements
+  # (which doesn't really work cos they're backwards).
+  class PredicateSplitter
+    def initialize( key, value )
+      @key, @value = key, value
+    end
+
+    attr_reader :key, :value
+
+    # split suffix from the key and store the two values as name and op
+    # return truthy if successful
+    def split_key( suffix )
+      rv = @key =~ /(.*?)_?(#{suffix})$/
+      @field, @op = $1, $2
+      rv
+    end
+
+    alias_method :===, :split_key
+    alias_method :=~, :split_key
+
+    # return name if the split was successful, or fall back to key
+    # which is handy when none of the predicates match and so key
+    # is probably just a field name.
+    def field
+      (@field || @key).andand.to_sym
+    end
+
+    # the operator, or predicate
+    def op
+      @op.andand.to_sym
+    end
+  end
+end

data/lib/philtre/predicates.rb

@@ -0,0 +1,109 @@
+module Philtre
+  # Container for methods which return Sequel::SQL::Expression or something
+  # that can become one through Sequel.expr, eg {year: 2013}
+  #
+  # Reminder: they're defined as methods so we can benefit from
+  # using them inside this class to define other predicates.
+  #
+  # This can be extended in all the usual ruby ways: by including a module,
+  # reopening the class. Also using extend_with which takes a PredicateDsl block.
+  class Predicates
+    def initialize( &bloc )
+      extend_with &bloc
+    end
+
+    # pass a block that can contain a combination of def meth_name() or the
+    # DSL defined by PredicateDsl.
+    def extend_with( &bloc )
+      extend PredicateDsl.new(&bloc)
+    end
+
+    # Convert a field_predicate (field_op format), a value and a SQL field
+    # name using the set of predicates, to something convertible to a Sequel
+    # expression.
+    #
+    # field_predicate:: is a key from the parameter hash. Usually name_pred, eg birth_year_gt
+    # value:: is the value from the parameter hash. Could be a collection.
+    # field:: is the name of the SQL field to use, or nil where it would default to key without its predicate.
+    def define_name_predicate( field_predicate, value, field = nil )
+      splitter = PredicateSplitter.new field_predicate, value
+
+      # the default / else / fall-through is just an equality
+      default_proc = ->{:eq}
+
+      # find a better predicate, if there is one
+      suffix = predicate_names.find default_proc do |suffix|
+        splitter =~ suffix
+      end
+
+      # wrap the field name first, to infect the expressions so all the
+      # operators work.
+      field_name = Sequel.expr(field || splitter.field)
+
+      define_singleton_method field_predicate do |value|
+        send suffix, field_name, value
+      end
+    end
+
+    protected :define_name_predicate
+
+    # TODO this should probably also be method_missing?
+    # field is only used once for any given field_predicate
+    def call( field_predicate, value, field = nil )
+      unless respond_to? field_predicate
+        define_name_predicate field_predicate, value, field
+      end
+      send field_predicate, value
+    end
+
+    # The main interface from Filter#to_expr
+    alias [] call
+
+    def predicate_names
+      DefaultPredicates.instance_methods
+    end
+
+    # Define the set of default predicates.
+    DefaultPredicates = PredicateDsl.new do
+      # longer suffixes first, so they match first in define_name_predicate
+      not_eq           {|expr, val| ~Sequel.expr( expr => val)       }
+
+      def not_like( expr, val )
+        Sequel.~(like expr, val)
+      end
+
+      matches( :like ) {|expr, val|  Sequel.expr( expr => /#{val}/i) }
+
+      def not_blank(expr, val)
+        Sequel.~(blank expr, val)
+      end
+
+      def blank(expr, _)
+        is_nil = Sequel.expr(expr => nil)
+        is_empty = Sequel.expr(expr => '')
+        Sequel.| is_nil, is_empty
+      end
+
+      # and now the shorter suffixes
+      eq               {|expr, val|  Sequel.expr( expr => val)       }
+      gt               {|expr, val|    expr >  val                   }
+      gte( :gteq )     {|expr, val|    expr >= val                   }
+      lt               {|expr, val|    expr <  val                   }
+      lte( :lteq )     {|expr, val|    expr <= val                   }
+
+      # more complex predicates
+      def like_all( expr, arg )
+        exprs = Array(arg).map {|value| like expr, value }
+        Sequel.& *exprs
+      end
+
+      def like_any( expr, arg )
+        exprs = Array(arg).map {|value| like expr, value }
+        Sequel.| *exprs
+      end
+    end
+
+    # make the available to Predicates instances.
+    include DefaultPredicates
+  end
+end

data/lib/philtre/sequel_extensions.rb

@@ -0,0 +1,30 @@
+# TODO docs for this
+class Sequel::Dataset
+  include Ripar
+
+  # make the roller understand dataset method
+  def roller
+    rv = super
+    class << rv
+      def to_dataset; riven end
+    end
+    rv
+  end
+
+  # roll the block and return the resulting dataset immediately
+  def rolled( &blk )
+    roller.rive &blk
+  end
+end
+
+class Sequel::Dataset
+  # filter must respond_to expr_hash and order_hash
+  # will optionally yield a Grinder instance to the block
+  def grind( filter = Philtre::Filter.new, apply_unknown: true )
+    grinder = Philtre::Grinder.new filter
+    t_dataset = grinder.transform self, apply_unknown: apply_unknown
+    # only yield after the transform, so the grinder has the place holders
+    yield grinder if block_given?
+    t_dataset
+  end
+end

data/lib/philtre/version.rb

@@ -1,3 +1,3 @@
-module Philtre
-  VERSION = "0.0.0"
+module Philtre #:nodoc:
+  VERSION = "0.0.1"
 end