@@ -1,5 +1,5 @@ Copyright (c) 2008 Willem van Bergen - + Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including @@ -7,10 +7,10 @@ without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - + The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND LICENSE @@ -1,6 +1,6 @@ = Scoped search -The <b>scoped_search</b> Rails plugin makes it easy to search your ActiveRecord models. Searching is +The <b>scoped_search</b> Rails plugin makes it easy to search your ActiveRecord models. Searching is performed using a query string, which should be passed to the named_scope <tt>search_for</tt>. Based on a definition in what fields to look, it will build query conditions and return those as a named scope. @@ -10,7 +10,7 @@ The recommended method to enable scoped_search in your project is adding the sco Rails::Initializer.run do |config| ... - config.gem 'wvanbergen-scoped_search', :lib => 'scoped_search', + config.gem 'wvanbergen-scoped_search', :lib => 'scoped_search', :source => 'http://gems.github.com/' end @@ -31,7 +31,7 @@ Scoped search requires you to define the fields you want to search in: For more information about options and using fields from relations, see the project wiki on search definitions: http://wiki.github.com/wvanbergen/scoped_search/search-definition -Now, the <b>search_for</b> scope is available for queries. You should pass a query string to the scope. +Now, the <b>search_for</b> scope is available for queries. You should pass a query string to the scope. This can be empty or nil, in which case all no search conditions are set (and all records will be returned). User.search_for('my search string').each { |user| ... } @@ -57,7 +57,7 @@ words:: require every word to be present, e.g.: <tt>some search keywords phrases:: use quotes for multi-word phrases, e.g. <tt>"police car"</tt> -negation:: look for "everything but", e.g. <tt>police -uniform</tt>, <tt>-"police car"</tt>, +negation:: look for "everything but", e.g. <tt>police -uniform</tt>, <tt>-"police car"</tt>, <tt>police NOT car</tt> logical keywords:: make logical constructs using AND, OR, &&, ||, &, | operators, e.g. @@ -90,5 +90,5 @@ For more info, see the the project wiki: http://wiki.github.com/wvanbergen/scope == License -This plugin is released under the MIT license. Please contact weshays (http://github.com/weshays) +This plugin is released under the MIT license. Please contact weshays (http://github.com/weshays) or wvanbergen (http://github.com/wvanbergen) for any questions. README.rdoc @@ -1,7 +1,10 @@ module ScopedSearch - + + # The ClassMethods module will be included into the ActiveRecord::Base class to add + # the ActiveRecord::Base.scoped_search method and the ActiveRecord::Base.search_for + # named scope. module ClassMethods - + # Export the scoped_search method fo defining the search options. # This method will create a definition instance for the class if it does not yet exist, # and use the object as block argument and retun value. @@ -16,35 +19,50 @@ module ScopedSearch end return @scoped_search end - end - + + # The BackwardsCompatibility module can be included into ActiveRecord::Base to provide + # a search field definition syntax that is compatible with scoped_seach 1.x + # + # Currently, it is included into ActiveRecord::Base by default, but this may change in + # the future. So, please uodate to the newer syntax as soon as possible. module BackwardsCompatibility + # Defines fields to search on using a syntax compatible with scoped_search 1.2 def searchable_on(*fields) - + options = fields.last.kind_of?(Hash) ? fields.pop : {} # TODO: handle options? - - fields.each do |field| + + fields.each do |field| if relation = self.reflections.keys.detect { |relation| field.to_s =~ Regexp.new("^#{relation}_(\\w+)$") } - scoped_search(:in => relation, :on => $1.to_sym) + scoped_search(:in => relation, :on => $1.to_sym) else scoped_search(:on => field) end end - end + end end - + + # The default ScopedSearch exception class. class Exception < StandardError end + # The default exception class that is raised when there is something + # wrong with the scoped_search definition call. + # + # You usually do not want to catch this exception, but fix the faulty + # scoped_search method call. class DefinitionError < ScopedSearch::Exception end - + + # The default exception class that is raised when there is a problem + # with parsing or interpreting a search query. + # + # You may want to catch this exception and handle this gracefully. class QueryNotSupported < ScopedSearch::Exception end - + end # Load all lib files lib/scoped_search.rb @@ -1,41 +1,51 @@ -module ScopedSearch - module Adapter +# The ScopedSearch::Adapter module contains adapters for the different +# database backends that can be used, to ensure that the experience on +# DBMSs are compatible. +module ScopedSearch::Adapter + + # Loads the appropriate database adapter for scoped search given the + # current database connection, and calls its setup method to adapt + # things as needed. + def self.setup(connection) + adapter = connection.class.name.split('::').last + const_get(adapter).setup(connection) if const_defined?(adapter) + end + + # The MySQL adapter changes the equals operator to make sure it is + # case sensitive, whatever column collation is used. + module MysqlAdapter def self.setup(connection) - adapter = connection.class.name.split('::').last - const_get(adapter).setup(connection) if const_defined?(adapter) + ScopedSearch::Definition::Field.send :include, FieldInstanceMethods end - module MysqlAdapter + module FieldInstanceMethods - def self.setup(connection) - ScopedSearch::Definition::Field.send :include, FieldInstanceMethods - end + # Monkey patch Field#to_sql method to ensure that comparisons using :eq / :ne + # are case sensitive by adding a BINARY operator in front of the field name. + def to_sql(operator = nil, &block) + + # Normal implementation + yield(:include, relation) if relation + field_name = definition.klass.connection.quote_table_name(klass.table_name) + "." + + definition.klass.connection.quote_column_name(field) - module FieldInstanceMethods - - # Monkey patch Field#to_sql method to ensure that comparisons using :eq / :ne - # are case sensitive by adding a BINARY operator in front of the field name. - def to_sql(operator = nil, &block) - - # Normal implementation - yield(:include, relation) if relation - field_name = definition.klass.connection.quote_table_name(klass.table_name) + "." + - definition.klass.connection.quote_column_name(field) - - # Add BINARY operator if the field is textual and = or <> is used. - field_name = "BINARY #{field_name}" if textual? && [:ne, :eq].include?(operator) - return field_name - end + # Add BINARY operator if the field is textual and = or <> is used. + field_name = "BINARY #{field_name}" if textual? && [:ne, :eq].include?(operator) + return field_name end - end - - module PostgreSQLAdapter - def self.setup(connection) - ScopedSearch::QueryBuilder::SQL_OPERATORS[:like] = 'ILIKE' - ScopedSearch::QueryBuilder::SQL_OPERATORS[:unlike] = 'NOT ILIKE' - end + + end + + # The PostgreSQL adapter uses the ILKE operator instead of the LIKE operator that + # is used by default, to make sure that queries are case-insensitive. + module PostgreSQLAdapter + + # Change the LIKE operator to ILIKE. + def self.setup(connection) + ScopedSearch::QueryBuilder::SQL_OPERATORS[:like] = 'ILIKE' + ScopedSearch::QueryBuilder::SQL_OPERATORS[:unlike] = 'NOT ILIKE' end end end lib/scoped_search/adapters.rb @@ -1,11 +1,23 @@ module ScopedSearch - + + # The ScopedSearch definition class defines on what fields should be search + # in the model in what cases + # + # A definition can be created by calling the <tt>scoped_search</tt> method on + # an ActiveRecord-based class, so you should not create an instance of this + # class yourself. class Definition - + + # The Field class specifies a field of a model that is available for searching, + # in what cases this field should be searched and its default search behavior. + # + # Instances of this class are created when calling scoped_search in your model + # class, so you should not create instances of this class yourself. class Field - + attr_reader :definition, :field, :only_explicit, :relation - + + # The ActiveRecord-based class that belongs to this field. def klass if relation definition.klass.reflections[relation].klass @@ -13,36 +25,43 @@ module ScopedSearch definition.klass end end - - # Find the relevant column definition in the AR class + + # Returns the ActiveRecord column definition that corresponds to this field. def column klass.columns_hash[field.to_s] end - + + # Returns the column type of this field. def type column.type end - + + # Returns true if this field is a datetime-like column def datetime? [:datetime, :time, :timestamp].include?(type) end - + + # Returns true if this field is a date-like column def date? type == :date end - + + # Returns true if this field is a date or datetime-like column. def temporal? datetime? || date? end - + + # Returns true if this field is numerical. + # Numerical means either integer, floating point or fixed point. def numerical? [:integer, :double, :float, :decimal].include?(type) end - + + # Returns true if this is a textual column. def textual? [:string, :text].include?(type) end - + # Returns the default search operator for this field. def default_operator @default_operator ||= case type @@ -51,6 +70,8 @@ module ScopedSearch end end + # Initializes a Field instance given the definition passed to the + # scoped_search call on the ActiveRecord-based model class. def initialize(definition, options = {}) @definition = definition case options @@ -64,59 +85,67 @@ module ScopedSearch @only_explicit = !!options[:only_explicit] @default_operator = options[:default_operator] if options.has_key?(:default_operator) end - + # Store this field is the field array definition.fields[@field] ||= self definition.unique_fields << self - + # Store definition for alias / aliases as well definition.fields[options[:alias]] ||= self if options[:alias] - options[:aliases].each { |al| definition.fields[al] ||= self } if options[:aliases] + options[:aliases].each { |al| definition.fields[al] ||= self } if options[:aliases] end end - + attr_reader :klass, :fields, :unique_fields - + + # Initializes a ScopedSearch definition instance. + # This method will also setup a database adapter and create the :search_for + # named scope if it does not yet exist. def initialize(klass) @klass = klass @fields = {} @unique_fields = [] - + setup_adapter! unless klass.connection.nil? register_named_scope! unless klass.respond_to?(:search_for) end - - NUMBER_REGXP = /^\-?\d+(\.\d+)?$/ - + + NUMERICAL_REGXP = /^\-?\d+(\.\d+)?$/ + + # Returns a list of appropriate fields to search in given a search keyword and operator. def default_fields_for(value, operator = nil) - # Use the value to detect + column_types = [] column_types += [:string, :text] if [nil, :like, :unlike, :ne, :eq].include?(operator) - column_types += [:integer, :double, :float, :decimal] if value =~ NUMBER_REGXP + column_types += [:integer, :double, :float, :decimal] if value =~ NUMERICAL_REGXP column_types += [:datetime, :date, :timestamp] if ScopedSearch::QueryBuilder.parse_temporal(value) default_fields.select { |field| column_types.include?(field.type) } end - + + # Returns a list of fields that should be searched on by default. + # + # Every field will show up in this method's result, except for fields for + # which the only_explicit parameter is set to true. def default_fields unique_fields.reject { |field| field.only_explicit } end - + + # Defines a new search field for this search definition. def define(options) Field.new(self, options) end - + protected - - # Registers the search_for named scope within the class + + # Registers the search_for named scope within the class that is used for searching. def register_named_scope! # :nodoc @klass.named_scope(:search_for, lambda { |*args| ScopedSearch::QueryBuilder.build_query(args[1] || self, args[0]) }) end - + + # Installs the database adapter based on the current database connection. def setup_adapter! ScopedSearch::Adapter.setup(@klass.connection) end - end - -end \ No newline at end of file +end lib/scoped_search/definition.rb @@ -1,12 +1,20 @@ module ScopedSearch + # The QueryBuilder class builds an SQL query based on aquery string that is + # provided to the search_for named scope. It uses a SearchDefinition instance + # to shape the query. class QueryBuilder - + attr_reader :ast, :definition - - # Creates a find parameter hash given a class, and query string. - def self.build_query(definition, query) - # Return all record when an empty search string is given + + # Creates a find parameter hash that can be passed to ActiveRecord::Base#find, + # given a search definition and query string. This method is called from the + # search_for named scope. + # + # This method will parse the query string and build an SQL query using the search + # query. It will return an ampty hash if the search query is empty, in which case + # the scope call will simply return all records. + def self.build_query(definition, query) if query.kind_of?(ScopedSearch::QueryLanguage::AST::Node) return self.new(definition, query).build_find_params elsif query.kind_of?(String) @@ -22,15 +30,16 @@ module ScopedSearch def initialize(definition, ast) @definition, @ast = definition, ast end - - # Actually builds the find parameters + + # Actually builds the find parameters hash that should be used in the search_for + # named scope. def build_find_params parameters = [] includes = [] - + # Build SQL WHERE clause using the AST sql = @ast.to_sql(definition) do |notification, value| - + # Handle the notifications encountered during the SQL generation: # Store the parameters, includes, etc so that they can be added to # the find-hash later on. @@ -40,7 +49,7 @@ module ScopedSearch else raise ScopedSearch::QueryNotSupported, "Cannot handle #{notification.inspect}: #{value.inspect}" end end - + # Build hash for ActiveRecord::Base#find for the named scope find_attributes = {} find_attributes[:conditions] = [sql] + parameters unless sql.nil? @@ -48,31 +57,42 @@ module ScopedSearch # p find_attributes # Uncomment for debugging return find_attributes end - - SQL_OPERATORS = { :eq =>'=', :ne => '<>', - :like => 'LIKE', :unlike => 'NOT LIKE', - :gt => '>', :lt =>'<', :lte => '<=', :gte => '>=' } - - # Return the SQL operator to use + + # A hash that maps the operators of the query language with the corresponding SQL operator. + SQL_OPERATORS = { :eq =>'=', :ne => '<>', :like => 'LIKE', :unlike => 'NOT LIKE', + :gt => '>', :lt =>'<', :lte => '<=', :gte => '>=' } + + # Return the SQL operator to use given an operator symbol and field definition. + # + # By default, it will simply look up the correct SQL operator in the SQL_OPERATORS + # hash, but this can be overrided by a database adapter. def self.sql_operator(operator, field) SQL_OPERATORS[operator] end # Perform a comparison between a field and a Date(Time) value. - # Makes sure the date is valid and adjust the comparison in - # some cases to return more logical results - def self.datetime_test(field, operator, value, &block) - + # + # This function makes sure the date is valid and adjust the comparison in + # some cases to return more logical results. + # + # This function needs a block that can be used to pass other information about the query + # (parameters that should be escaped, includes) to the query builder. + # + # <tt>field</tt>:: The field to test. + # <tt>operator</tt>:: The operator used for comparison. + # <tt>value</tt>:: The value to compare the field with. + def self.datetime_test(field, operator, value, &block) # :yields: finder_option_type, value + # Parse the value as a date/time and ignore invalid timestamps timestamp = parse_temporal(value) - return nil unless timestamp - timestamp = Date.parse(timestamp.strftime('%Y-%m-%d')) if field.date? - + return nil unless timestamp + timestamp = Date.parse(timestamp.strftime('%Y-%m-%d')) if field.date? + # Check for the case that a date-only value is given as search keyword, # but the field is of datetime type. Change the comparison to return # more logical results. if timestamp.day_fraction == 0 && field.datetime? - + if [:eq, :ne].include?(operator) # Instead of looking for an exact (non-)match, look for dates that # fall inside/outside the range of timestamps of that day. @@ -81,28 +101,35 @@ module ScopedSearch negate = (operator == :ne) ? 'NOT' : '' field_sql = field.to_sql(operator, &block) return "#{negate}(#{field_sql} >= ? AND #{field_sql} < ?)" - + elsif operator == :gt # Make sure timestamps on the given date are not included in the results # by moving the date to the next day. timestamp += 1 operator = :gte - + elsif operator == :lte - # Make sure the timestamps of the given date are included by moving the + # Make sure the timestamps of the given date are included by moving the # date to the next date. timestamp += 1 operator = :lt end end - + # Yield the timestamp and return the SQL test yield(:parameter, timestamp) "#{field.to_sql(operator, &block)} #{self.sql_operator(operator, field)} ?" end - + # Generates a simple SQL test expression, for a field and value using an operator. - def self.sql_test(field, operator, value, &block) + # + # This function needs a block that can be used to pass other information about the query + # (parameters that should be escaped, includes) to the query builder. + # + # <tt>field</tt>:: The field to test. + # <tt>operator</tt>:: The operator used for comparison. + # <tt>value</tt>:: The value to compare the field with. + def self.sql_test(field, operator, value, &block) # :yields: finder_option_type, value if [:like, :unlike].include?(operator) && value !~ /^\%/ && value !~ /\%$/ yield(:parameter, "%#{value}%") return "#{field.to_sql(operator, &block)} #{self.sql_operator(operator, field)} ?" @@ -113,26 +140,32 @@ module ScopedSearch return "#{field.to_sql(operator, &block)} #{self.sql_operator(operator, field)} ?" end end - + # Try to parse a string as a datetime. def self.parse_temporal(value) DateTime.parse(value, true) rescue nil end + # This module gets included into the Field class to add SQL generation. module Field - + # Return an SQL representation for this field. Also make sure that # the relation which includes the search field is included in the # SQL query. - def to_sql(operator = nil, &block) + # + # This function may yield an :include that should be used in the + # ActiveRecord::Base#find call, to make sure that the field is avalable + # for the SQL query. + def to_sql(operator = nil, &block) # :yields: finder_option_type, value yield(:include, relation) if relation - definition.klass.connection.quote_table_name(klass.table_name) + "." + + definition.klass.connection.quote_table_name(klass.table_name) + "." + definition.klass.connection.quote_column_name(field) end end + # This module contains modules for every AST::Node class to add SQL generation. module AST - + # Defines the to_sql method for AST LeadNodes module LeafNode def to_sql(definition, &block) @@ -143,47 +176,47 @@ module ScopedSearch "(#{fragments.join(' OR ')})" end end - + # Defines the to_sql method for AST operator nodes module OperatorNode - - # Returns a NOT(...) SQL fragment that negates the current AST node's children + + # Returns a NOT(...) SQL fragment that negates the current AST node's children def to_not_sql(definition, &block) "(NOT(#{rhs.to_sql(definition, &block)}) OR #{rhs.to_sql(definition, &block)} IS NULL)" end - - # Returns a IS (NOT) NULL SQL fragment + + # Returns an IS (NOT) NULL SQL fragment def to_null_sql(definition, &block) - field = definition.fields[rhs.value.to_sym] + field = definition.fields[rhs.value.to_sym] raise ScopedSearch::QueryNotSupported, "Field '#{rhs.value}' not recognized for searching!" unless field - + case operator when :null then "#{field.to_sql(&block)} IS NULL" when :notnull then "#{field.to_sql(&block)} IS NOT NULL" end end - + # No explicit field name given, run the operator on all default fields def to_default_fields_sql(definition, &block) - raise ScopedSearch::QueryNotSupported, "Value not a leaf node" unless rhs.kind_of?(ScopedSearch::QueryLanguage::AST::LeafNode) - + raise ScopedSearch::QueryNotSupported, "Value not a leaf node" unless rhs.kind_of?(ScopedSearch::QueryLanguage::AST::LeafNode) + # Search keywords found without context, just search on all the default fields fragments = definition.default_fields_for(rhs.value, operator).map { |field| ScopedSearch::QueryBuilder.sql_test(field, operator, rhs.value, &block) }.compact fragments.empty? ? nil : "(#{fragments.join(' OR ')})" end - + # Explicit field name given, run the operator on the specified field only def to_single_field_sql(definition, &block) raise ScopedSearch::QueryNotSupported, "Field name not a leaf node" unless lhs.kind_of?(ScopedSearch::QueryLanguage::AST::LeafNode) raise ScopedSearch::QueryNotSupported, "Value not a leaf node" unless rhs.kind_of?(ScopedSearch::QueryLanguage::AST::LeafNode) - + # Search only on the given field. field = definition.fields[lhs.value.to_sym] raise ScopedSearch::QueryNotSupported, "Field '#{lhs.value}' not recognized for searching!" unless field ScopedSearch::QueryBuilder.sql_test(field, operator, rhs.value, &block) end - + # Convert this AST node to an SQL fragment. def to_sql(definition, &block) if operator == :not && children.length == 1 @@ -191,27 +224,30 @@ module ScopedSearch elsif [:null, :notnull].include?(operator) to_null_sql(definition, &block) elsif children.length == 1 - to_default_fields_sql(definition, &block) + to_default_fields_sql(definition, &block) elsif children.length == 2 to_single_field_sql(definition, &block) else raise ScopedSearch::QueryNotSupported, "Don't know how to handle this operator node: #{operator.inspect} with #{children.inspect}!" end - end + end end - + # Defines the to_sql method for AST AND/OR operators module LogicalOperatorNode def to_sql(definition, &block) fragments = children.map { |c| c.to_sql(definition, &block) }.compact fragments.empty? ? nil : "(#{fragments.join(" #{operator.to_s.upcase} ")})" - end - end + end + end end end + # Include the modu;es into the corresponding classes + # to add SQL generation capabilities to them. + Definition::Field.send(:include, QueryBuilder::Field) QueryLanguage::AST::LeafNode.send(:include, QueryBuilder::AST::LeafNode) QueryLanguage::AST::OperatorNode.send(:include, QueryBuilder::AST::OperatorNode) - QueryLanguage::AST::LogicalOperatorNode.send(:include, QueryBuilder::AST::LogicalOperatorNode) + QueryLanguage::AST::LogicalOperatorNode.send(:include, QueryBuilder::AST::LogicalOperatorNode) end lib/scoped_search/query_builder.rb @@ -4,26 +4,34 @@ module ScopedSearch::QueryLanguage require 'scoped_search/query_language/tokenizer' require 'scoped_search/query_language/parser' - class Compiler + # The Compiler class can compile a query string into an Abstract Syntax Tree, + # which in turn is used to build the SQL query. + # + # This class inclused the Tokenizer module to transform the query stream into + # a stream of tokens, and includes the Parser module that will transform the + # stream of tokens into an Abstract Syntax Tree (AST). + class Compiler include Tokenizer include Parser include Enumerable - - def initialize(str) + + def initialize(str) # :nodoc: @str = str end - + + # Parser a query string to return an abstract syntax tree. def self.parse(str) compiler = self.new(str) compiler.parse end - + + # Tokenizes a query string to return a stream of tokens. def self.tokenize(str) compiler = self.new(str) compiler.tokenize end - + end end lib/scoped_search/query_language.rb @@ -1,7 +1,7 @@ module ScopedSearch::QueryLanguage::AST - + # Constructs an AST from an array notation. - def self.from_array(arg) + def self.from_array(arg) if arg.kind_of?(Array) operator = arg.shift case operator @@ -16,46 +16,46 @@ module ScopedSearch::QueryLanguage::AST return LeafNode.new(arg) end end - + # Base AST node class. Instances of this class are used to represent an abstract syntax tree. # This syntax tree is created by the ScopedSearch::QueryLanguage parser and visited by the # ScopedSearch::QueryBuilder to create SQL query conditions. class Node - + def inspect # :nodoc "<AST::#{self.class.to_s.split('::').last} #{self.to_a.inspect}>" end - + # Tree simplification. By default, do nothing and return the node as is. - def simplify + def simplify return self end - + def compatible_with(node) # :nodoc - false - end + false + end end - + # AST lead node. This node represents leafs in the AST and can represent - # either a search phrase or a search field name. + # either a search phrase or a search field name. class LeafNode < Node attr_reader :value - + def initialize(value) # :nodoc @value = value end - - # Return an array representation for the node + + # Return an array representation for the node def to_a value end - + def eql?(node) # :nodoc node.kind_of?(LeafNode) && node.value == value end end - # AST class for representing operators in the query. An operator node has an operator + # AST class for representing operators in the query. An operator node has an operator # and operands that are represented as AST child nodes. Usually, operator nodes have # one or two children. # For logical operators, a distinct subclass exists to implement some tree @@ -63,67 +63,67 @@ module ScopedSearch::QueryLanguage::AST class OperatorNode < Node attr_reader :operator attr_reader :children - + def initialize(operator, children) # :nodoc @operator = operator @children = children end - - # Tree simplicication: returns itself after simpifying its children + + # Tree simplicication: returns itself after simpifying its children def simplify @children = children.map { |c| c.simplify } return self end - - # Return an array representation for the node + + # Return an array representation for the node def to_a [@operator] + @children.map { |c| c.to_a } end - + def eql?(node) # :nodoc node.kind_of?(OperatorNode) && node.operator == operator && node.children.eql?(children) end - + # Return the left-hand side (LHS) operand for this operator. def lhs raise ScopedSearch::Exception, "Operator does not have a LHS" if prefix? raise ScopedSearch::Exception, "Operators with more than 2 children do not have LHS/RHS" if children.length > 2 children[0] - end - - # Return the right-hand side (RHS) operand for this operator. + end + + # Return the right-hand side (RHS) operand for this operator. def rhs - raise ScopedSearch::Exception, "Operators with more than 2 children do not have LHS/RHS" if children.length > 2 + raise ScopedSearch::Exception, "Operators with more than 2 children do not have LHS/RHS" if children.length > 2 children.length == 1 ? children[0] : children[1] end - + # Returns true if this is an infix operator def infix? children.length > 1 end - + # Returns true if this is a prefix operator def prefix? children.length == 1 end - + # Returns a child node by index, starting with 0. def [](child_nr) children[child_nr] end - + end - + # AST class for representing AND or OR constructs. # Logical constructs can be simplified resulting in a less complex AST. class LogicalOperatorNode < OperatorNode - + # Checks whether another node is comparable so that it can be used for tree simplification. # A node can only be simplified if the logical operator is equal. def compatible_with(node) node.kind_of?(LogicalOperatorNode) && node.operator == self.operator end - + # Simplifies nested AND and OR constructs to single constructs with multiple arguments: # e.g. (a AND (b AND c)) -> (a AND b AND c) def simplify @@ -134,7 +134,7 @@ module ScopedSearch::QueryLanguage::AST else # nested AND or OR constructs can be combined into one construct @children = children.map { |c| c.simplify }.map { |c| self.compatible_with(c) ? c.children : c }.flatten - return self + return self end end end lib/scoped_search/query_language/ast.rb @@ -1,29 +1,34 @@ +# The Parser module adss methods to the query language compiler that transform a string +# into an abstract syntax tree, which can be used for query generation. +# +# This module depends on the tokeinzer module to transform the string into a stream +# of tokens, which is more appropriate for parsing. The parser itself is a LL(1) +# recursive descent parser. module ScopedSearch::QueryLanguage::Parser DEFAULT_SEQUENCE_OPERATOR = :and - + LOGICAL_INFIX_OPERATORS = [:and, :or] LOGICAL_PREFIX_OPERATORS = [:not] NULL_PREFIX_OPERATORS = [:null, :notnull] COMPARISON_OPERATORS = [:eq, :ne, :gt, :gte, :lt, :lte, :like, :unlike] ALL_INFIX_OPERATORS = LOGICAL_INFIX_OPERATORS + COMPARISON_OPERATORS ALL_PREFIX_OPERATORS = LOGICAL_PREFIX_OPERATORS + COMPARISON_OPERATORS + NULL_PREFIX_OPERATORS - + # Start the parsing process by parsing an expression sequence def parse - @tokens = tokenize + @tokens = tokenize parse_expression_sequence(true).simplify end # Parses a sequence of expressions def parse_expression_sequence(initial = false) expressions = [] - next_token if !initial && peek_token == :lparen # skip staring :lparen + next_token if !initial && peek_token == :lparen # skip staring :lparen expressions << parse_logical_expression until peek_token.nil? || peek_token == :rparen next_token if !initial && peek_token == :rparen # skip final :rparen return ScopedSearch::QueryLanguage::AST::LogicalOperatorNode.new(DEFAULT_SEQUENCE_OPERATOR, expressions) end - # Parses a logical expression. def parse_logical_expression @@ -42,34 +47,34 @@ module ScopedSearch::QueryLanguage::Parser else lhs end - end - + end + # Parses a NOT expression def parse_logical_not_expression next_token # = skip NOT operator negated_expression = case peek_token - when :not; parse_logical_not_expression + when :not; parse_logical_not_expression when :lparen; parse_expression_sequence else parse_comparison end return ScopedSearch::QueryLanguage::AST::OperatorNode.new(:not, [negated_expression]) end - + # Parses a set? or null? expression def parse_null_expression return ScopedSearch::QueryLanguage::AST::OperatorNode.new(next_token, [parse_value]) end - + # Parses a comparison def parse_comparison - next_token if peek_token == :comma # skip comma + next_token if peek_token == :comma # skip comma return (String === peek_token) ? parse_infix_comparison : parse_prefix_comparison end - + # Parses a prefix comparison, i.e. without an explicit field: <operator> <value> def parse_prefix_comparison return ScopedSearch::QueryLanguage::AST::OperatorNode.new(next_token, [parse_value]) - end + end # Parses an infix expression, i.e. <field> <operator> <value> def parse_infix_comparison @@ -89,8 +94,8 @@ module ScopedSearch::QueryLanguage::Parser lhs end end - end - + end + # Parses a single value. # This can either be a constant value or a field name. def parse_value @@ -98,18 +103,18 @@ module ScopedSearch::QueryLanguage::Parser ScopedSearch::QueryLanguage::AST::LeafNode.new(next_token) end - protected - - def current_token + protected + + def current_token # :nodoc: @current_token end - - def peek_token(amount = 1) + + def peek_token(amount = 1) # :nodoc: @tokens[amount - 1] end - def next_token + def next_token # :nodoc: @current_token = @tokens.shift - end + end end \ No newline at end of file lib/scoped_search/query_language/parser.rb @@ -1,28 +1,39 @@ +# The Tokenizer module adds methods to the query language compiler that transforms a query string +# into a stream of tokens, which are more appropriate for parsing a query string. module ScopedSearch::QueryLanguage::Tokenizer + # All keywords that the language supports KEYWORDS = { 'and' => :and, 'or' => :or, 'not' => :not, 'set?' => :notnull, 'null?' => :null } + + # Every operator the language supports. OPERATORS = { '&' => :and, '|' => :or, '&&' => :and, '||' => :or, '-'=> :not, '!' => :not, '~' => :like, '!~' => :unlike, '=' => :eq, '==' => :eq, '!=' => :ne, '<>' => :ne, '>' => :gt, '<' => :lt, '>=' => :gte, '<=' => :lte } - + # Tokenizes the string and returns the result as an array of tokens. def tokenize @current_char_pos = -1 to_a end + # Returns the current character of the string def current_char @current_char end + # Returns a following character of the string (by default, the next + # character), without updating the position pointer. def peek_char(amount = 1) @str[@current_char_pos + amount, 1] end + # Returns the next character of the string, and moves the position + # pointer one step forward def next_char @current_char_pos += 1 @current_char = @str[@current_char_pos, 1] end + # Tokenizes the string by iterating over the characters. def each_token(&block) while next_char case current_char @@ -35,28 +46,33 @@ module ScopedSearch::QueryLanguage::Tokenizer else; tokenize_keyword(&block) end end - end + end + # Tokenizes an operator that occurs in the OPERATORS hash def tokenize_operator(&block) operator = current_char operator << next_char if OPERATORS.has_key?(operator + peek_char) yield(OPERATORS[operator]) end + # Tokenizes a keyword, and converts it to a Symbol if it is recognized as a + # reserved language keyword (the KEYWORDS array). def tokenize_keyword(&block) keyword = current_char - keyword << next_char while /[^=<>\s\&\|\)\(,]/ =~ peek_char + keyword << next_char while /[^=<>\s\&\|\)\(,]/ =~ peek_char KEYWORDS.has_key?(keyword.downcase) ? yield(KEYWORDS[keyword.downcase]) : yield(keyword) end + # Tokenizes a keyword that is quoted using double quotes. Allows escaping + # of double quote characters by backslashes. def tokenize_quoted_keyword(&block) keyword = "" until next_char.nil? || current_char == '"' keyword << (current_char == "\\" ? next_char : current_char) end - yield(keyword) + yield(keyword) end alias :each :each_token - + end \ No newline at end of file lib/scoped_search/query_language/tokenizer.rb @@ -2,20 +2,26 @@ Gem::Specification.new do |s| s.name = 'scoped_search' s.version = '2.0.0' s.date = '2009-08-26' - - s.summary = "A Rails plugin to search your models using a named_scope" - s.description = "Scoped search makes it easy to search your ActiveRecord-based models. It will create a named scope according to a provided query string. The named_scope can be used like any other named_scope, so it can be cchained or combined with will_paginate." - + + s.summary = "A Rails plugin to search your models with a simple query language, implemented using a named_scope" + s.description = <<EOS + Scoped search makes it easy to search your ActiveRecord-based models. + It will create a named scope :search_for that can be called with a query string. It will build an SQL query using + the provided query string and a definition that specifies on what fields to search. Because the functionality is + built on named_scope, the result of the search_for call can be used like any other named_scope, so it can be + chained with another scope or combined with will_paginate." +EOS + s.authors = ['Willem van Bergen', 'Wes Hays'] s.email = ['willem@vanbergen.org', 'weshays@gbdev.com'] s.homepage = 'http://wiki.github.com/wvanbergen/scoped_search' - + s.add_runtime_dependency('activerecord', '>= 2.1.0') s.add_development_dependency('rspec', '>= 1.1.4') - + s.rdoc_options << '--title' << s.name << '--main' << 'README.rdoc' << '--line-numbers' << '--inline-source' s.extra_rdoc_files = ['README.rdoc'] - - s.files = %w(LICENSE README.rdoc Rakefile init.rb lib lib/scoped_search lib/scoped_search.rb lib/scoped_search/adapters.rb lib/scoped_search/definition.rb lib/scoped_search/query_builder.rb lib/scoped_search/query_language lib/scoped_search/query_language.rb lib/scoped_search/query_language/ast.rb lib/scoped_search/query_language/parser.rb lib/scoped_search/query_language/tokenizer.rb spec spec/database.yml spec/integration spec/integration/api_spec.rb spec/integration/ordinal_querying_spec.rb spec/integration/relation_querying_spec.rb spec/integration/string_querying_spec.rb spec/lib spec/lib/database.rb spec/lib/matchers.rb spec/lib/mocks.rb spec/spec_helper.rb spec/unit spec/unit/ast_spec.rb spec/unit/definition_spec.rb spec/unit/parser_spec.rb spec/unit/query_builder_spec.rb spec/unit/tokenizer_spec.rb tasks tasks/database_tests.rake tasks/github-gem.rake) + + s.files = %w(LICENSE README.rdoc Rakefile init.rb lib lib/scoped_search lib/scoped_search.rb lib/scoped_search/adapters.rb lib/scoped_search/definition.rb lib/scoped_search/query_builder.rb lib/scoped_search/query_language lib/scoped_search/query_language.rb lib/scoped_search/query_language/ast.rb lib/scoped_search/query_language/parser.rb lib/scoped_search/query_language/tokenizer.rb spec spec/database.yml spec/integration spec/integration/api_spec.rb spec/integration/ordinal_querying_spec.rb spec/integration/relation_querying_spec.rb spec/integration/string_querying_spec.rb spec/lib spec/lib/database.rb spec/lib/matchers.rb spec/lib/mocks.rb spec/spec_helper.rb spec/unit spec/unit/ast_spec.rb spec/unit/definition_spec.rb spec/unit/parser_spec.rb spec/unit/query_builder_spec.rb spec/unit/tokenizer_spec.rb tasks tasks/database_tests.rake tasks/github-gem.rake) s.test_files = %w(spec/integration/api_spec.rb spec/integration/ordinal_querying_spec.rb spec/integration/relation_querying_spec.rb spec/integration/string_querying_spec.rb spec/unit/ast_spec.rb spec/unit/definition_spec.rb spec/unit/parser_spec.rb spec/unit/query_builder_spec.rb spec/unit/tokenizer_spec.rb) end \ No newline at end of file scoped_search.gemspec @@ -1,17 +1,17 @@ sqlite3: adapter: "sqlite3" database: ":memory:" - + mysql: adapter: "mysql" host: "localhost" user: "root" password: database: "scoped_search_test" - + postgresql: adapter: "postgresql" host: "localhost" username: "sstest" password: "sstest" - database: "scoped_search_test" + database: "scoped_search_test" spec/database.yml @@ -1,66 +1,66 @@ require "#{File.dirname(__FILE__)}/../spec_helper" describe ScopedSearch, "API" do - + # This spec requires the API to be stable, so that projects using # scoped_search do not have to update their code if a new (minor) - # version is released. + # version is released. # # API compatibility is only guaranteed for minor version changes; - # New major versions may change the API and require code changes + # New major versions may change the API and require code changes # in projects using this plugin. # # Because of the API stability guarantee, these spec's may only # be changed for new major releases. - + before(:all) do ScopedSearch::Spec::Database.establish_connection end after(:all) do - ScopedSearch::Spec::Database.close_connection - end - + ScopedSearch::Spec::Database.close_connection + end + context 'for unprepared ActiveRecord model' do - + it "should respond to :scoped_search to setup scoped_search for the model" do Class.new(ActiveRecord::Base).should respond_to(:scoped_search) end end - + context 'for a prepared ActiveRecord model' do - + before(:all) do @class = ScopedSearch::Spec::Database.create_model(:field => :string) do |klass| klass.scoped_search :on => :field end end - + after(:all) do - ScopedSearch::Spec::Database.drop_model(@class) + ScopedSearch::Spec::Database.drop_model(@class) end - + it "should respond to :search_for to perform searches" do @class.should respond_to(:search_for) end - + it "should return an ActiveRecord::NamedScope::Scope when :search_for is called" do @class.search_for('query').class.should eql(ActiveRecord::NamedScope::Scope) end end - + context 'having backwards compatibility' do - + before(:each) do class Foo < ActiveRecord::Base belongs_to :bar end end - + after(:each) do Object.send :remove_const, :Foo end - + it "should respond to :searchable_on" do Foo.should respond_to(:searchable_on) end @@ -73,10 +73,10 @@ describe ScopedSearch, "API" do it "should create a Field with a valid relation when using the underscore notation" do ScopedSearch::Definition::Field.should_receive(:new).with( instance_of(ScopedSearch::Definition), hash_including(:in => :bar, :on => :related_field)) - + Foo.searchable_on(:bar_related_field) end - + end end spec/integration/api_spec.rb @@ -97,31 +97,31 @@ describe ScopedSearch do it "should accept YY-MM-DD as date format" do @class.search_for('date = 09-01-02').should have(1).item end - + it "should accept MM/DD/YY as date format" do @class.search_for('date = 01/02/09').should have(1).item - end - + end + it "should accept YYYY/MM/DD as date format" do @class.search_for('date = 2009/01/02').should have(1).item end - + it "should accept MM/DD/YYYY as date format" do @class.search_for('date = 01/02/2009').should have(1).item - end - + end + it "should ignore an invalid date and thus return all records" do @class.search_for('>= 2009-14-57').should have(2).items - end - + end + it "should find the records with a timestamp set some point on the provided date" do @class.search_for('>= 2009-01-02').should have(1).item end - + it "should support full timestamps" do @class.search_for('> "2009-01-02 02:02:02"').should have(1).item end - + it "should find no record with a timestamp in the past" do @class.search_for('< 2009-01-02').should have(0).item end @@ -129,14 +129,14 @@ describe ScopedSearch do it "should find all timestamps on a date if no time is given using the = operator" do @class.search_for('= 2009-01-02').should have(1).item end - + it "should find all timestamps on a date if no time is when no operator is given" do @class.search_for('2009-01-02').should have(1).item - end - + end + it "should find all timestamps not on a date if no time is given using the != operator" do @class.search_for('!= 2009-01-02').should have(0).item - end + end it "should find the records when the date part of a timestamp matches a date" do @class.search_for('>= 2009-01-02').should have(1).item spec/integration/ordinal_querying_spec.rb @@ -13,19 +13,19 @@ describe ScopedSearch do context 'querying a :belongs_to relation' do before(:all) do - + # The related class ActiveRecord::Migration.create_table(:bars) { |t| t.string :related } class Bar < ActiveRecord::Base; has_many :foos; end - + # The class on which to call search_for Foo = ScopedSearch::Spec::Database.create_model(:foo => :string, :bar_id => :integer) do |klass| klass.belongs_to :bar klass.scoped_search :in => :bar, :on => :related end - + @bar_record = Bar.create!(:related => 'bar') - + Foo.create!(:foo => 'foo', :bar => @bar_record) Foo.create!(:foo => 'foo too', :bar => @bar_record) Foo.create!(:foo => 'foo three', :bar => Bar.create!(:related => 'another bar')) @@ -85,11 +85,11 @@ describe ScopedSearch do Object.send :remove_const, :Foo Object.send :remove_const, :Bar end - + it "should find all records with at least one bar record containing 'bar'" do Foo.search_for('bar').should have(2).items end - + it "should find the only record with at least one bar record having the exact value 'bar'" do Foo.search_for('= bar').should have(1).item end @@ -97,13 +97,13 @@ describe ScopedSearch do it "should find all records for which at least one related bar record exists" do Foo.search_for('set? related').should have(2).items end - + it "should find all records for which none related bar records exist" do Foo.search_for('null? related').should have(1).items end - + end - + context 'querying a :has_one relation' do before(:all) do @@ -132,11 +132,11 @@ describe ScopedSearch do Object.send :remove_const, :Foo Object.send :remove_const, :Bar end - + it "should find all records with a bar record containing 'bar" do Foo.search_for('bar').should have(2).items end - + it "should find the only record with the bar record has the exact value 'bar" do Foo.search_for('= bar').should have(1).item end @@ -144,7 +144,7 @@ describe ScopedSearch do it "should find all records for which the related bar record exists" do Foo.search_for('set? related').should have(2).items end - + it "should find all records for which the related bar record does not exist" do Foo.search_for('null? related').should have(1).items end @@ -158,7 +158,7 @@ describe ScopedSearch do ActiveRecord::Migration.create_table(:bars) { |t| t.string :related } ActiveRecord::Migration.create_table(:bars_foos, :id => false) { |t| t.integer :foo_id; t.integer :bar_id } ActiveRecord::Migration.create_table(:foos) { |t| t.string :foo } - + # The related class class Bar < ActiveRecord::Base; end @@ -175,7 +175,7 @@ describe ScopedSearch do @bar_1 = Bar.create!(:related => 'bar') @bar_2 = Bar.create!(:related => 'other bar') @bar_3 = Bar.create!(:related => 'last bar') - + @foo_1.bars << @bar_1 << @bar_2 @foo_2.bars << @bar_2 << @bar_3 end @@ -183,15 +183,15 @@ describe ScopedSearch do after(:all) do ActiveRecord::Migration.drop_table(:bars_foos) ActiveRecord::Migration.drop_table(:bars) - ActiveRecord::Migration.drop_table(:foos) + ActiveRecord::Migration.drop_table(:foos) Object.send :remove_const, :Foo Object.send :remove_const, :Bar end - + it "should find all records with at least one associated bar record containing 'bar'" do Foo.search_for('bar').should have(2).items end - + it "should find record which is related to @bar_1" do Foo.search_for('= bar').should have(1).items end @@ -206,14 +206,14 @@ describe ScopedSearch do end context 'querying a :has_many => :through relation' do - + before(:all) do # Create some tables ActiveRecord::Migration.create_table(:bars) { |t| t.integer :foo_id; t.integer :baz_id } ActiveRecord::Migration.create_table(:bazs) { |t| t.string :related } ActiveRecord::Migration.create_table(:foos) { |t| t.string :foo } - + # The related classes class Bar < ActiveRecord::Base; belongs_to :baz; belongs_to :foo; end class Baz < ActiveRecord::Base; has_many :bars; end @@ -222,7 +222,7 @@ describe ScopedSearch do class Foo < ActiveRecord::Base has_many :bars has_many :bazs, :through => :bars - + scoped_search :in => :bazs, :on => :related end @@ -248,8 +248,8 @@ describe ScopedSearch do Object.send :remove_const, :Foo Object.send :remove_const, :Bar Object.send :remove_const, :Baz - end - + end + it "should find the two records that are related to a baz record" do Foo.search_for('baz').should have(2).items end spec/integration/relation_querying_spec.rb @@ -6,28 +6,28 @@ describe ScopedSearch, :search_for do ScopedSearch::Spec::Database.establish_connection @class = ScopedSearch::Spec::Database.create_model(:string => :string, :another => :string, :explicit => :string) do |klass| klass.scoped_search :on => :string - klass.scoped_search :on => :another, :default_operator => :eq, :alias => :alias + klass.scoped_search :on => :another, :default_operator => :eq, :alias => :alias klass.scoped_search :on => :explicit, :only_explicit => true end - + @class.create!(:string => 'foo', :another => 'temp 1', :explicit => 'baz') - @class.create!(:string => 'bar', :another => 'temp 2', :explicit => 'baz') + @class.create!(:string => 'bar', :another => 'temp 2', :explicit => 'baz') @class.create!(:string => 'baz', :another => 'temp 3', :explicit => nil) end - + after(:all) do ScopedSearch::Spec::Database.drop_model(@class) - ScopedSearch::Spec::Database.close_connection + ScopedSearch::Spec::Database.close_connection end - + context 'in an implicit string field' do it "should find the record with an exact string match" do @class.search_for('foo').should have(1).item end - + it "should find the opther two records using NOT with an exact string match" do @class.search_for('-foo').should have(2).item - end + end it "should find the record with an exact string match and an explicit field operator" do @class.search_for('string = foo').should have(1).item @@ -36,14 +36,14 @@ describe ScopedSearch, :search_for do it "should find the record with an exact string match and an explicit field operator" do @class.search_for('another = foo').should have(0).items end - + it "should find the record with an partial string match" do @class.search_for('fo').should have(1).item end - + it "should find the other two records using NOT with an partial string match" do @class.search_for('-fo').should have(2).item - end + end it "should not find the record with an explicit equals operator and a partial match" do @class.search_for('= fo').should have(0).items @@ -52,14 +52,14 @@ describe ScopedSearch, :search_for do it "should find the record with an explicit LIKE operator and a partial match" do @class.search_for('~ fo').should have(1).items end - + it "should find the all other record with an explicit NOT LIKE operator and a partial match" do @class.search_for('string !~ fo').should have(@class.count - 1).items - end + end it "should not find a record with a non-match" do @class.search_for('nonsense').should have(0).items - end + end it "should find two records if it partially matches them" do @class.search_for('ba').should have(2).item @@ -67,11 +67,11 @@ describe ScopedSearch, :search_for do it "should find no records starting with an a" do @class.search_for('a%').should have(0).item - end + end it "should find one records ending with an oo" do @class.search_for('%oo').should have(1).item - end + end it "should find records without case sensitivity when using the LIKE operator" do @class.search_for('string ~ FOO').should have(1).item @@ -88,58 +88,58 @@ describe ScopedSearch, :search_for do it "should find records without case sensitivity when using the NOT LIKE operator" do @class.search_for('string !~ FOO').should have(2).items end - + it "should find the record if one of the query words match using OR" do @class.search_for('foo OR nonsense').should have(1).item - end - + end + it "should find no records in one of the AND conditions isn't met" do @class.search_for('foo AND nonsense').should have(0).item - end + end it "should find two records every single OR conditions matches one single record" do @class.search_for('foo OR baz').should have(2).item - end + end it "should find two records every single AND conditions matches one single record" do @class.search_for('foo AND baz').should have(0).item - end - end - + end + end + context 'in a field with a different default operator' do it "should find an exact match" do @class.search_for('"temp 1"').should have(1).item end - + it "should find the orther records using NOT and an exact match" do @class.search_for('-"temp 1"').should have(2).item end - + it "should find an explicit match" do @class.search_for('another = "temp 1"').should have(1).item end - + it "should not find a partial match" do @class.search_for('temp').should have(0).item - end - + end + it "should find all records using a NOT with a partial match on all records" do @class.search_for('-temp"').should have(3).item - end + end it "should find a partial match when the like operator is given" do @class.search_for('~ temp').should have(3).item end - + it "should find a partial match when the like operator and the field name is given" do @class.search_for('another ~ temp').should have(3).item end end - + context 'using an aliased field' do it "should find an explicit match using its alias" do @class.search_for('alias = "temp 1"').should have(1).item - end + end end context 'in an explicit string field' do @@ -159,14 +159,14 @@ describe ScopedSearch, :search_for do it "should find all records when searching on the explicit field" do @class.search_for('explicit ~ ba').should have(2).items end - + it "should only find the record with string = foo and explicit = baz" do @class.search_for('foo, explicit = baz').should have(1).item end end - + context 'using null? and set? queries' do - + it "should return all records if the string field is being checked with set?" do @class.search_for('set? string').should have(3).items end @@ -182,6 +182,6 @@ describe ScopedSearch, :search_for do it "should return all records without a value if the string field is being checked with null?" do @class.search_for('null? explicit').should have(1).items end - + end end spec/integration/string_querying_spec.rb @@ -7,7 +7,7 @@ module ScopedSearch::Spec::Database self.establish_named_connection(ENV['DATABASE']) else self.establish_default_connection - end + end end def self.establish_named_connection(name) @@ -23,21 +23,21 @@ module ScopedSearch::Spec::Database def self.close_connection ActiveRecord::Base.remove_connection end - + def self.create_model(fields) table_name = "model_#{rand}".gsub(/\./, '') - ActiveRecord::Migration.create_table(table_name) do |t| - fields.each do |name, field_type| + ActiveRecord::Migration.create_table(table_name) do |t| + fields.each do |name, field_type| t.send(field_type.to_s.gsub(/^unindexed_/, '').to_sym, name) end end - + klass = Class.new(ActiveRecord::Base) klass.set_table_name(table_name) yield(klass) if block_given? return klass end - + def self.drop_model(klass) ActiveRecord::Migration.drop_table(klass.table_name) end spec/lib/database.rb @@ -19,22 +19,22 @@ module ScopedSearch::Spec::Matchers (operator.nil? || operator == node.operator) end end - + def be_leaf_node(value = nil) simple_matcher('node to be an logical operator') do |node| node.kind_of?(ScopedSearch::QueryLanguage::AST::LeafNode) && (value.nil? || value == node.value) - end + end end - - def tokenize_to(*tokens) + + def tokenize_to(*tokens) simple_matcher("to tokenize to #{tokens.inspect}") do |string| tokens == ScopedSearch::QueryLanguage::Compiler.tokenize(string) end - end + end def parse_to(tree) simple_matcher("to parse to #{tree.inspect}") do |string| - tree == ScopedSearch::QueryLanguage::Compiler.parse(string).to_a - end + tree == ScopedSearch::QueryLanguage::Compiler.parse(string).to_a + end end end spec/lib/matchers.rb @@ -10,7 +10,7 @@ module ScopedSearch::Spec::Mocks ar_mock.stub!(:connection).and_return(mock_database_connection) return ar_mock end - + def mock_database_connection c_mock = mock('ActiveRecord::Base.connection') return c_mock spec/lib/mocks.rb @@ -65,7 +65,7 @@ describe ScopedSearch::QueryLanguage::AST do it "should create a child node for every subsequent array item" do @ast.should have(2).children - end + end it "should create a nested OR structure for a nested array" do @ast.lhs.should be_leaf_node('a') @@ -134,7 +134,7 @@ describe ScopedSearch::QueryLanguage::AST::OperatorNode do context 'with 1 child' do before(:each) do - @node = tree([:not, '1']) + @node = tree([:not, '1']) end it 'should be a prefix operator' do @@ -156,7 +156,7 @@ describe ScopedSearch::QueryLanguage::AST::OperatorNode do context 'with 2 children' do before(:each) do - @node = tree([:eq, '1', '2']) + @node = tree([:eq, '1', '2']) end it "should be an infix operator" do @@ -164,7 +164,7 @@ describe ScopedSearch::QueryLanguage::AST::OperatorNode do end it "should not be a prefix operator" do - @node.should_not be_prefix + @node.should_not be_prefix end it "should return the first child as LHS" do @@ -179,7 +179,7 @@ describe ScopedSearch::QueryLanguage::AST::OperatorNode do context 'many children' do before(:each) do - @node = tree([:and, '1', '2', '3', '4']) + @node = tree([:and, '1', '2', '3', '4']) end it "should be an infix operator" do spec/unit/ast_spec.rb @@ -9,7 +9,7 @@ describe ScopedSearch::Definition do end describe '#initialize' do - + it "should create the named scope when" do @klass.should_receive(:named_scope).with(:search_for, instance_of(Proc)) ScopedSearch::Definition.new(@klass) spec/unit/definition_spec.rb @@ -1,23 +1,23 @@ require "#{File.dirname(__FILE__)}/../spec_helper" describe ScopedSearch::QueryLanguage::Parser do - + it "should create a 1-node tree for a single keyword" do 'single'.should parse_to('single') end - + it "should create a two-item AND construct for two keywords" do - 'double_1 double_2'.should parse_to([:and, 'double_1', 'double_2']) + 'double_1 double_2'.should parse_to([:and, 'double_1', 'double_2']) end - + it "should create a three-item AND construct for three keywords" do 'triplet_1 triplet_2 triplet_3'.should parse_to([:and, 'triplet_1', 'triplet_2', 'triplet_3']) end - + it "should create a four-item AND construct by simplifying AND constructs" do '1 (2 (3 4))'.should parse_to([:and, '1', '2', '3', '4']) end - + it "should create an OR construct" do 'some OR simple OR keywords'.should parse_to([:or, 'some', 'simple', 'keywords']) end @@ -25,19 +25,19 @@ describe ScopedSearch::QueryLanguage::Parser do it "should nest an OR as second argument of the AND construct" do 'some simple OR keywords'.should parse_to([:and, 'some', [:or, 'simple', 'keywords']]) end - + it "should nest an OR as first argument of an AND construct" do 'some OR simple keywords'.should parse_to([:and, [:or, 'some', 'simple'], 'keywords']) end - + it "should handle parenthesis as AND block, placed in an OR block" do 'some OR (simple keywords)'.should parse_to([:or, 'some', [:and, 'simple', 'keywords']]) end - + it "should handle parenthesis as OR block in an AND block" do '(some OR simple) keywords'.should parse_to([:and, [:or, 'some', 'simple'], 'keywords']) end - + it "should create a block for the NOT keyword" do 'not easy'.should parse_to([:not, 'easy']) end @@ -45,11 +45,11 @@ describe ScopedSearch::QueryLanguage::Parser do it "should create a nsted NOT block" do 'not !easy'.should parse_to([:not, [:not, 'easy']]) end - + it "should create a block for the NOT keyword in an AND block" do 'hard !easy'.should parse_to([:and, 'hard', [:not, 'easy']]) end - + it "should create a block for the NOT keyword in an OR block" do 'hard || !easy'.should parse_to([:or, 'hard', [:not, 'easy']]) end @@ -57,11 +57,11 @@ describe ScopedSearch::QueryLanguage::Parser do it "should create a block for the NOT keyword in an OR block" do '!easy OR !hard'.should parse_to([:or, [:not, 'easy'], [:not, 'hard']]) end - + it "should nest the NOT blocks correctly according to parantheses" do '!(easy OR !hard)'.should parse_to([:not, [:or, 'easy', [:not, 'hard']]]) end - + it "should create OR blocks in an AND block" do '(a|b)(b|c)'.should parse_to([:and, [:or, 'a', 'b'], [:or, 'b', 'c']]) end @@ -69,11 +69,11 @@ describe ScopedSearch::QueryLanguage::Parser do it "should create OR blocks in an explicit AND block" do '(a|b)&(b|c)'.should parse_to([:and, [:or, 'a', 'b'], [:or, 'b', 'c']]) end - + it "should ignore a comma under normal circumstances" do 'a,b'.should parse_to([:and, 'a', 'b']) end - + it "should correctly parse an infix comparison" do 'a>b'.should parse_to([:gt, 'a', 'b']) end @@ -85,7 +85,7 @@ describe ScopedSearch::QueryLanguage::Parser do it "should create a comparison in an AND block because of the comma delimiter" do 'a, < b'.should parse_to([:and, 'a', [:lt, 'b']]) end - + it "should create a infix and prefix comparison in an AND block because of parentheses" do '(a = b) >c'.should parse_to([:and, [:eq, 'a', 'b'], [:gt, 'c']]) end @@ -97,7 +97,7 @@ describe ScopedSearch::QueryLanguage::Parser do it "should create a infix and prefix comparison in an AND block because of first come first serve" do 'a = b > c'.should parse_to([:and, [:eq, 'a', 'b'], [:gt, 'c']]) end - + it "should parse a null? keyword" do 'set? a b null? c'.should parse_to([:and, [:notnull, 'a'], 'b', [:null, 'c']]) end spec/unit/parser_spec.rb @@ -5,17 +5,17 @@ describe ScopedSearch::QueryBuilder do before(:each) do @definition = mock('ScopedSearch::Definition') end - + it "should return empty conditions if the search query is nil" do ScopedSearch::QueryBuilder.build_query(@definition, nil).should == { } end - + it "should return empty conditions if the query is blank" do ScopedSearch::QueryBuilder.build_query(@definition, "").should == { } end - + it "should return empty conditions if the query is whitespace only" do ScopedSearch::QueryBuilder.build_query(@definition, "\t ").should == { } end - + end spec/unit/query_builder_spec.rb @@ -1,35 +1,35 @@ require "#{File.dirname(__FILE__)}/../spec_helper" describe ScopedSearch::QueryLanguage::Tokenizer do - + it "should create tokens for strings" do 'some simple keywords'.should tokenize_to('some', 'simple', 'keywords') end - + it "should ignore excessive whitespace" do " with\twhitespace \n".should tokenize_to('with', 'whitespace') end - + it "should leave quoted strings intact" do '"quoted string"'.should tokenize_to("quoted string") end - + it "should allow escaping quotes in quoted strings using a backslash" do '"quoted \"string"'.should tokenize_to('quoted "string') end - + it "should allow escaping the escape charachter" do '"quoted \\\\string"'.should tokenize_to('quoted \\string') end - + it "should handle unclosed quoted string gracefully" do '"quoted string'.should tokenize_to("quoted string") end - + it "should tokenize multiple quoted strings" do '"quoted string" "another" '.should tokenize_to("quoted string", 'another') end - + it "should tokenize multiple quoted strings without separating whitespace" do '"quoted string""another"'.should tokenize_to("quoted string", 'another') end @@ -45,23 +45,23 @@ describe ScopedSearch::QueryLanguage::Tokenizer do it "should allow quotes in the middle of a normal string" do 'a"b'.should tokenize_to('a"b') end - + it "should parse keyword characters" do 'a | -("b""c") & d'.should tokenize_to('a', :or, :not, :lparen, 'b', 'c', :rparen, :and, 'd') end - + it "should tokenize null operators" do 'set? a null? b'.should tokenize_to(:notnull, 'a', :null, 'b') - end + end it "should parse double keyword characters" do 'a || b'.should tokenize_to('a', :or, 'b') end - + it "should parse double keyword characters with whitespace as separate tokens" do 'a | | b'.should tokenize_to('a', :or, :or, 'b') end - + it "should parse keyword strings" do "a and b".should tokenize_to('a', :and, 'b') end @@ -89,9 +89,9 @@ describe ScopedSearch::QueryLanguage::Tokenizer do it "should parse an equals operator within a string as separate token" do 'a=b'.should tokenize_to('a', :eq, 'b') end - + it "should not parse an operator within a string as separate token when quoted" do '"a=b"'.should tokenize_to('a=b') - end - + end + end spec/unit/tokenizer_spec.rb @@ -1,20 +1,20 @@ require 'yaml' unless Object::const_defined?('YAML') namespace :spec do - - databases = YAML.load(File.read(File.dirname(__FILE__) + '/../spec/database.yml')) - + + databases = YAML.load(File.read(File.dirname(__FILE__) + '/../spec/database.yml')) + desc "Run testsuite on all configured databases in spec/database.yml" task(:all => databases.keys.map { |db| db.to_sym }) do puts "\nFinished testing on all configured databases!" puts "(Configure databases by adjusting test/database.yml)" end - + databases.each do |database, config| desc "Run testsuite on #{database} database." task database.to_sym do puts "Running specs for #{database} database...\n\n" sh "rake spec DATABASE=#{database}" end - end + end end \ No newline at end of file tasks/database_tests.rake 774817347ac300e3ab2c715532ca0645ba5b8df6 Willem van Bergen willem@vanbergen.org http://github.com/wvanbergen/scoped_search/commit/63d403df3ae3d34931f3889b4b94c50c61992584 63d403df3ae3d34931f3889b4b94c50c61992584 2009-09-28T21:44:28-07:00 2009-09-28T21:44:28-07:00 Improved RDoc documentation and fixed whitespace issues. 7e6d1d4429b1daec0af911284b26c71c52855e64 Willem van Bergen willem@vanbergen.org