clearly-query 0.3.1.pre → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d045cfa5f732a083d9a8b102bd7c2cdd67b24722
-  data.tar.gz: 8c486d7e7add811d6898ac9d695fa2981b108e21
+  metadata.gz: 8b1fc977200d949ff4d1aa8db533b56d6d987a91
+  data.tar.gz: 0e5dc84af5e9b77647bfcb3ffe6dd77d1daf356b
 SHA512:
-  metadata.gz: 25e62009d801425f4f18a5955bc88656f6fab91ba071653b398caa0221abc8f2420c0ba48969dcf6289715e9a88580bc5a62cd08c5de2d1eada28bcfd63dc308
-  data.tar.gz: b9604376d04f1f49ac70a4b01267af962a7607fa03e03f9e28b702484c26975636a59c9ee350e7660a93d5bc9a206cc791b2df32c706ea770003f71f4f2409ca
+  metadata.gz: 83e6b022830e7026f87eebfc3ef8f27a9053127493b8c4aaa327843a2eaeadebd9177f27f81cb91d77a1d1386b27af4f829645e77711f97bfc63c53bb61fba5f
+  data.tar.gz: abcaf272739a41933356e229ff6b4a2d3a5a04ebf90bebd2ecd3bd501c2ab65a9fee76f885fba8abc70ce714e695e0d51e850e34a66cfe96b1c1cffd005aeb5c

data/CHANGELOG.md

@@ -6,6 +6,20 @@ and [keeps a change log](http://keepachangelog.com/) (you're reading it!).
 
 ## Unreleased
 
+## Release [v1.0.0](https://github.com/cofiem/clearly-query/releases/tag/v1.0.0) (2015-11-10)
+
+### Added
+ - Operator to compare all text fields using OR.
+ - Improved tests and coverage.
+
+### Changed
+ - Two methods for Composer: `#query` to compose an ActiveRecord query and `#conditions` to compose an array of Arel conditions.
+ - Hash cleaner applied within Composer methods.
+ - Graph traversal results are now cached.
+
+### Fixed
+ - fixed a number of typos in SPEC and README.
+
 ## Release [v0.3.1-pre](https://github.com/cofiem/clearly-query/releases/tag/v0.3.1-pre) (2015-11-01)
 
 ### Added
@@ -22,6 +36,16 @@ and [keeps a change log](http://keepachangelog.com/) (you're reading it!).
  - Transported hash filter modules and classes from [baw-server](https://github.com/QutBioacoustics/baw-server)
   - Created change log
 
+----
+
+## Semver Summary
+
+Given a version number MAJOR.MINOR.PATCH, increment the:
+
+1. MAJOR version when you make incompatible API changes,
+1. MINOR version when you add functionality in a backwards-compatible manner, and
+1. PATCH version when you make backwards-compatible bug fixes.
+
 ## Change log categories
 
 ### Added

data/README.md

@@ -2,6 +2,9 @@
 
 A library for constructing an sql query from a hash.
 
+From a hash, validate, construct, and execute a query or create Arel conditions.
+There are no assumptions or opinions on what is done with the results from the query.
+
 Uses [Arel](https://github.com/rails/arel) and [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord).
 
 ## Project Status
@@ -13,6 +16,7 @@ Uses [Arel](https://github.com/rails/arel) and [ActiveRecord](https://github.com
 [![Documentation Status](https://inch-ci.org/github/cofiem/clearly-query.svg?branch=master)](https://inch-ci.org/github/cofiem/clearly-query)
 [![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/github/cofiem/clearly-query)
 [![Join the chat at https://gitter.im/cofiem/clearly-query](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/cofiem/clearly-query?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Gem Version](https://badge.fury.io/rb/clearly-query.svg)](https://badge.fury.io/rb/clearly-query)
 
 ## Installation
 
@@ -31,7 +35,7 @@ Or install it yourself as:
 ## Usage
 
 There are two main public classes in this gem. 
-The Definition class makes use of a settings declared in a model.
+The Definition class makes use of settings declared in a model.
 The Composer converts a hash of options into an Arel query.
 
 ### [Clearly::Query::Definition](./lib/clearly/query/definition.rb)
@@ -50,12 +54,12 @@ and
             fields: {
                 valid: [:name, :last_contact_at],
                 text: [:name],
-                mappings: [
+                mappings: [ # these mappings are built in the database, and are only used for comparison, not projection
                     {
                         name: :title,
                         value: Clearly::Query::Helper.string_concat(
                             Customer.arel_table[:name],
-                            Arel::Nodes.build_quoted(' title'))
+                            Clearly::Query::Helper.sql_quoted(' title'))
                     }
                 ]
             },
@@ -66,37 +70,87 @@ and
                     available: true,
                     associations: []
                 }
-            ],
-            defaults: {
-                order_by: :created_at,
-                direction: :desc
-            }
+            ]
         }
       end
 
+The available specification keys are detailed below.
+
+All field names that are available to include in a query hash:
+
+    {fields: { valid: [<Symbols>, ...] } }
+
+All fields that contain text (e.g. `varchar`, `text`) that are available to include in a query hash. 
+This must be a subset (or equal) to the `valid` field array:
+
+    {fields: { text:  [<Symbols>, ...] } }
+
+Field mappings that specify a calculated value:
+
+    {fields: { mappings: [{ name: <Symbol>, value: <Arel::Nodes::Node, String, Arel::Attribute, others...> }, ... ]  } }
+
+Associations between tables, and whether the association is available in queries or not:
+
+    {
+        associations: [
+            { 
+                join: <Model or Arel Table>,
+                on: <Arel fragment>,
+                available: <true or false>, # is this association available to be used in queries?
+                associations: [ <further associations for this table>,  ... ]
+            }
+    }
+
 ### [Clearly::Query::Composer](./lib/clearly/query/composer.rb)
 
-Constructs an Arel query from a hash of options.
+Use the Composer to Construct an Arel query from a hash of options.
 See the [query hash specification](SPEC.md) for a comprehensive overview.
 
-For example:
+There are two ways to do this. Either compose an ActiveRecord query or compose the Arel conditions.
 
     composer = Clearly::Query::Composer.from_active_record
     query_hash = {and: {name: {contains: 'test'}}} # from e.g. HTTP request
-    cleaned_query_hash = Clearly::Query::Cleaner.new.do(query_hash)
     model = Customer
-    conditions = composer.query(model, cleaned_query_hash)
-    query = model.where(conditions)
+    arel_conditions = composer.conditions(model, query_hash)
+    # or
+    query = composer.query(model, query_hash)
 
-## Contributing
+### Building custom Arel queries
 
-1. [Fork this repo](https://github.com/cofiem/clearly-query/fork)
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new [pull request](https://github.com/cofiem/clearly-query/compare)
+There is also a class to aid in building Arel queries yourself.
+
+Have a look at the [Clearly::Query::Compose::Custom](./lib/clearly/query/compose/custom.rb) class and the
+[tests](./spec/lib/clearly/query/compose/custom_spec.rb)
+for more details.
+
+## Helper methods and classes
+
+There are a number of helper methods and classes available to make working with Arel, hashes, and ActiveRecord easier.
+
+[Clearly::Query::Cleaner](./lib/clearly/query/cleaner.rb) validates a hash to make sure all hash keys are symbols (even in nested hashes and arrays):
+ 
+    cleaned_query_hash = Clearly::Query::Cleaner.new.do(hash)
+
+This library uses the custom error `Clearly::Query::QueryArgumentError` (it inherits from `ArgumentError`).
+
+There are a bunch of validation methods in the `Clearly::Query::Validate` module. Sometimes duck typing is not that great :/
+
+There is also the `Clearly::Query::Graph` class, currently used only for constructing root to leaf routes for building joins.
+
+Class methods in the `Clearly::Query::Helper` class provide abstractions over differences in database string concatenation,
+help construct Arel infix operators, EXISTS clauses, literals, and SQL fragments. 
+These helper methods are mostly a result of obscure or odd functionality. 
+It's a collection of Arel experience that will probably be helpful.
 
 ## More Information about Arel
 
  - [Using Arel to Compose SQL Queries](http://robots.thoughtbot.com/using-arel-to-compose-sql-queries)
  - [The definitive guide to Arel, the SQL manager for Ruby](http://jpospisil.com/2014/06/16/the-definitive-guide-to-arel-the-sql-manager-for-ruby.html)
+
+## Contributing
+
+1. [Fork this repo](https://github.com/cofiem/clearly-query/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new [pull request](https://github.com/cofiem/clearly-query/compare)

data/SPEC.md

@@ -1,10 +1,10 @@
 # Query Hash Specification
 
-Inspired by [elastic search filters](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-filters.html).
+Inspired by [Elastic Search filters](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-filters.html).
 
 ## Available Filter Operators
 
-### Combine Operators
+### Combine / logical Operators
 
      Operator |   Query hash   |       SQL
     ----------|----------------|---------------------
@@ -12,13 +12,14 @@ Inspired by [elastic search filters](http://www.elasticsearch.org/guide/en/elast
     or        | {or:  { ... }} | WHERE ... OR  (...)
     not       | {not: { ... }} | WHERE ... NOT (...)
     
-Implicit `and` is used when no combine operator is specified.
+An implicit `and` operator is used when no logical operator is specified.
 
 ### Filter Operators
 
-Filter comparison operator has multiple forms to help with constructing queries that read more 'naturally'.
-Be aware that it is possible operators may be 'case sensitive by default 
-for unicode characters that are beyond the ASCII range'. For example, in [sqlite](https://www.sqlite.org/lang_expr.html).
+All filter operators have multiple forms to help with constructing queries that read more 'naturally'.
+Be aware that it is possible operators may be 
+'case sensitive by default for unicode characters that are beyond the ASCII range'. 
+For example, in [sqlite](https://www.sqlite.org/lang_expr.html).
 
 #### Comparison Operators
 
@@ -41,7 +42,6 @@ Comparison operators are self-explanatory.
 
 There are special operators for `null` comparisons. 
 The only valid values for these operators is `true` or `false`.
-Any other value is invalid.
 
             Operator       |         Query hash         |        SQL
     -----------------------|----------------------------|---------------------------------
@@ -51,30 +51,31 @@ Any other value is invalid.
 
 ##### Range
 
-A simple range is inclusive lower bound and exclusive upper bound.
+A simple range can be specified from an inclusive lower bound and to an exclusive upper bound.
 
               Operator      |                      Query hash                     |                             SQL
     ------------------------|-----------------------------------------------------|------------------------------------------------------------------
     range, in_range         | {attr: {range: {from: 'value1', to: 'value2'}}}     | "table"."attr" >= 'value1' AND "table"."attr" < 'value2'
-    not_range, not_in_range | {attr: {not_range: {from: 'value1', to: 'value2'}}} | ("table"."attr" > 'value1' OR "table"."attr" >= 'value2')
+    not_range, not_in_range | {attr: {not_range: {from: 'value1', to: 'value2'}}} | ("table"."attr" < 'value1' OR "table"."attr" >= 'value2')
     
-A more complex range can be specified using a regex which allows for inclusive or exclusive bounds.
+A more complex range can be specified using a special format which allows for inclusive or exclusive bounds.
 
-       Operator  |              Query hash               |                           SQL
-    -------------|---------------------------------------|----------------------------------------------------------
-    interval     | {attr: {interval: '(value1,value2]'}} | "table"."attr" > 'value1' AND "table"."attr" <= 'value2'
-    not_interval | {attr: {interval: '(value1,value2]'}} | ("table"."attr" <= 'value1' OR "table"."attr" > 'value2')
+       Operator  |                Query hash                 |                           SQL
+    -------------|-------------------------------------------|----------------------------------------------------------
+    interval     | {attr: {interval: '(value1,value2]'}}     | "table"."attr" > 'value1' AND "table"."attr" <= 'value2'
+    not_interval | {attr: {not_interval: '(value1,value2]'}} | ("table"."attr" <= 'value1' OR "table"."attr" > 'value2')
 
-The `interval` must match the regex  `/(\[|\()(.*),(.*)(\)|\])/` 
+The `interval` must match the regex  `/(\[|\()(.*),(.*)(\)|\])/`, 
 where `(` or `)` indicates exclusive and `[` or `]` indicates inclusive.
 Specifying `[value1,value2]` is equivalent to `BETWEEN value1 AND value2`.
 
 Any spaces between the brackets will be included in the value.
 The result of including commas (`,`) in either value is undefined. 
+Use a single comma for separating the two values.
 
-##### Arrays
+##### Array
 
-An array of values to match the attribute value exactly.
+An array of values to match the attribute value. Compared using an exact match (which may be case sensitive, depending on the database).
 
     Operator |            Query hash               |                             SQL
     ---------|-------------------------------------|-----------------------------------------------
@@ -83,11 +84,11 @@ An array of values to match the attribute value exactly.
     
 ##### Contents Match
 
-Match the contents of a model attributes. 
-These comparison operators are case insensitive where possible (usually depends on database).
-It is possible to match at the entire content, at the start of the content, or at the end.
+A variety of ways to match the contents of model attribute content. 
+These comparison operators are case insensitive where possible (again, depends on the database).
+It is possible to match the entire content, at the start of the content, at the end, or using a regular expression.
 
-Regular expression match **may not be supported by all databases**.
+Regular expression match may not be supported by all databases.
 
                         Operator                          |           Query hash              |                SQL
     ------------------------------------------------------|-----------------------------------|-----------------------------------------------

data/clearly-query.gemspec

@@ -6,7 +6,7 @@ require 'clearly/query/version'
 Gem::Specification.new do |spec|
   spec.name          = 'clearly-query'
   spec.version       = Clearly::Query::VERSION
-  spec.authors       = ['@cofiem']
+  spec.authors       = ['Mark Cottman-Fields']
   spec.email         = ['cofiem@gmail.com']
   spec.summary       = %q{A library for constructing an sql query from a hash.}
   spec.description   = %q{A library for constructing an sql query from a hash. Uses a strict, yet flexible specification.}

data/lib/clearly/query/compose/conditions.rb

@@ -60,23 +60,6 @@ module Clearly
                 OPERATORS_REGEX +
                 OPERATORS_SPECIAL
 
-        # Add conditions to a query.
-        # @param [ActiveRecord::Relation] query
-        # @param [Array<Arel::Nodes::Node>, Arel::Nodes::Node] conditions
-        # @return [ActiveRecord::Relation] the modified query
-        def condition_apply(query, conditions)
-          conditions = [conditions].flatten
-          validate_not_blank(conditions)
-          validate_array(conditions)
-
-          conditions.each do |condition|
-            validate_condition(condition)
-            query = query.where(condition)
-          end
-
-          query
-        end
-
         # Combine multiple conditions.
         # @param [Symbol] combiner
         # @param [Arel::Nodes::Node, Array<Arel::Nodes::Node>] conditions

data/lib/clearly/query/composer.rb

@@ -6,6 +6,9 @@ module Clearly
       include Clearly::Query::Compose::Conditions
       include Clearly::Query::Validate
 
+      # All text fields operator.
+      OPERATOR_ALL_TEXT = :all_text_fields
+
       # @return [Array<Clearly::Query::Definition>] available definitions
       attr_reader :definitions
 
@@ -26,10 +29,10 @@ module Clearly
       # @return [Clearly::Query::Composer]
       def self.from_active_record
         models = ActiveRecord::Base
-            .descendants
-            .reject { |d| d.name == 'ActiveRecord::SchemaMigration' }
-            .sort { |a, b| a.name <=> b.name }
-            .uniq { |d| d.arel_table.name }
+                     .descendants
+                     .reject { |d| d.name == 'ActiveRecord::SchemaMigration' }
+                     .sort { |a, b| a.name <=> b.name }
+                     .uniq { |d| d.arel_table.name }
 
         definitions = models.map do |d|
           if d.name.include?('HABTM_')
@@ -45,11 +48,31 @@ module Clearly
       # Composes a query from a parsed filter hash.
       # @param [ActiveRecord::Base] model
       # @param [Hash] hash
-      # @return [Arel::Nodes::Node, Array<Arel::Nodes::Node>]
+      # @return [ActiveRecord::Relation]
       def query(model, hash)
+        conditions = conditions(model, hash)
+        query = model.all
+        validate_query(query)
+        conditions.each do |condition|
+          validate_condition(condition)
+          query = query.where(condition)
+        end
+        query
+      end
+
+      # Composes Arel conditions from a parsed filter hash.
+      # @param [ActiveRecord::Base] model
+      # @param [Hash] hash
+      # @return [Array<Arel::Nodes::Node>]
+      def conditions(model, hash)
+        validate_model(model)
+        validate_hash(hash)
+
         definition = select_definition_from_model(model)
+        cleaned_query_hash = Clearly::Query::Cleaner.new.do(hash)
+
         # default combiner is :and
-        parse_query(definition, :and, hash)
+        parse_conditions(definition, :and, cleaned_query_hash)
       end
 
       private
@@ -82,17 +105,15 @@ module Clearly
       # @param [Symbol] query_key
       # @param [Hash] query_value
       # @return [Array<Arel::Nodes::Node>]
-      def parse_query(definition, query_key, query_value)
+      def parse_conditions(definition, query_key, query_value)
         if query_value.blank? || query_value.size < 1
           msg = "filter hash must have at least 1 entry, got '#{query_value.size}'"
           fail Clearly::Query::QueryArgumentError.new(msg, {hash: query_value})
         end
 
         logical_operators = Clearly::Query::Compose::Conditions::OPERATORS_LOGICAL
-
         mapped_fields = definition.field_mappings.keys
         standard_fields = definition.all_fields - mapped_fields
-
         conditions = []
 
         if logical_operators.include?(query_key)
@@ -105,6 +126,11 @@ module Clearly
           field_conditions = parse_standard_field(definition, query_key, query_value)
           conditions.push(*field_conditions)
 
+        elsif OPERATOR_ALL_TEXT == query_key
+          # build conditions for all text fields combined with or
+          field_condition = parse_all_text_fields(definition, query_value)
+          conditions.push(field_condition)
+
         elsif mapped_fields.include?(query_key)
           # then deal with mapped fields
           field_conditions = parse_mapped_field(definition, query_key, query_value)
@@ -114,12 +140,12 @@ module Clearly
           # finally deal with fields from other tables
           field_conditions = parse_custom(definition, query_key, query_value)
           conditions.push(field_conditions)
+
         else
           fail Clearly::Query::QueryArgumentError.new("unrecognised operator or field '#{query_key}'")
         end
 
         conditions
-
       end
 
       # Parse a logical operator and it's value.
@@ -130,8 +156,9 @@ module Clearly
       def parse_logical_operator(definition, logical_operator, value)
         validate_definition_instance(definition)
         validate_symbol(logical_operator)
+        validate_not_blank(value)
         validate_hash(value)
-        conditions = value.map { |key, value| parse_query(definition, key, value) }
+        conditions = value.map { |key, value| parse_conditions(definition, key, value) }
         condition_combine(logical_operator, *conditions)
       end
 
@@ -143,12 +170,40 @@ module Clearly
       def parse_standard_field(definition, field, value)
         validate_definition_instance(definition)
         validate_symbol(field)
+        validate_not_blank(value)
         validate_hash(value)
         value.map do |operator, operation_value|
           condition_components(operator, definition.table, field, definition.all_fields, operation_value)
         end
       end
 
+      # Parse the conditions for all text fields.
+      # @param [Clearly::Query::Definition] definition
+      # @param [Hash] value
+      # @return [Array<Arel::Nodes::Node>]
+      def parse_all_text_fields(definition, value)
+        validate_definition_instance(definition)
+        validate_not_blank(value)
+        validate_hash(value)
+
+        # build conditions for all text fields
+        conditions = definition.text_fields.map do |text_field|
+          value.map do |operator, operation_value|
+            # cater for standard fields and mapped fields
+            mapping = definition.get_field_mapping(text_field)
+            if mapping.nil?
+              condition_components(operator, definition.table, text_field, definition.text_fields, operation_value)
+            else
+              validate_node_or_attribute(mapping)
+              condition_node(operator, mapping, operation_value)
+            end
+          end
+        end
+
+        # combine conditions using :or
+        condition_combine(:or, conditions)
+      end
+
       # Parse a mapped field and it's conditions.
       # @param [Clearly::Query::Definition] definition
       # @param [Symbol] field
@@ -159,6 +214,7 @@ module Clearly
         validate_symbol(field)
         fail Clearly::Query::QueryArgumentError.new('field name must contain a dot (.)') unless field.to_s.include?('.')
 
+        validate_not_blank(value)
         validate_hash(value)
 
         # extract table and field
@@ -189,6 +245,7 @@ module Clearly
         validate_definition_instance(definition)
         mapping = definition.get_field_mapping(field)
         validate_node_or_attribute(mapping)
+        validate_not_blank(value)
         validate_hash(value)
         value.map do |operator, operation_value|
           condition_node(operator, mapping, operation_value)
@@ -206,12 +263,12 @@ module Clearly
         [conditions].flatten.each { |c| validate_node_or_attribute(c) }
 
         current_model = definition.model
-        current_table = definition.table
+        #current_table = definition.table
         current_joins = definition.joins
 
         other_table = other_definition.table
         other_model = other_definition.model
-        other_joins = other_definition.joins
+        #other_joins = other_definition.joins
 
         # build an exist subquery to apply conditions that
         # refer to another table

data/lib/clearly/query/graph.rb

@@ -18,15 +18,19 @@ module Clearly
       def initialize(root_node, child_key)
         @root_node = root_node
         @child_key = child_key
+
+        @discovered_nodes = []
+        @paths = []
+
         self
       end
 
       # build an array that contains paths from the root to all leaves
       # @return [Array] paths from root to leaf
       def branches
-        @discovered_nodes = []
-        @paths = []
-        traverse_branches(@root_node, nil)
+        if @discovered_nodes.blank? && @paths.blank?
+          traverse_branches(@root_node, nil)
+        end
         @paths
       end
 

data/lib/clearly/query/helper.rb

@@ -13,7 +13,7 @@ module Clearly
 
           case adapter
             when 'mysql'
-              Arel::Nodes::NamedFunction.new('concat', *args)
+              named_function('concat', args)
             when 'sqlserver'
               string_concat_infix('+', *args)
             when 'postgres'
@@ -44,6 +44,38 @@ module Clearly
           result
         end
 
+        # Construct a SQL literal.
+        # This is useful for sql that is too complex for Arel.
+        # @param [String] value
+        # @return [Arel::Nodes::Node]
+        def sql_literal(value)
+          Arel::Nodes::SqlLiteral.new(value)
+        end
+
+        # Construct a SQL quoted string.
+        # This is used for fragments of SQL.
+        # @param [String] value
+        # @return [Arel::Nodes::Node]
+        def sql_quoted(value)
+          Arel::Nodes.build_quoted(value)
+        end
+
+        # Construct a SQL EXISTS clause.
+        # @param [Arel::Nodes::Node] node
+        # @return [Arel::Nodes::Node]
+        def exists(node)
+          Arel::Nodes::Exists.new(node)
+        end
+
+        # Construct an Arel representation of a SQL function.
+        # @param [String] name
+        # @param [String, Arel::Nodes::Node] expression
+        # @param [String] function_alias
+        # @return [Arel::Nodes::Node]
+        def named_function(name, expression, function_alias = nil)
+          Arel::Nodes::NamedFunction.new(name, expression, function_alias)
+        end
+
       end
     end
   end

data/lib/clearly/query/validate.rb

@@ -4,18 +4,6 @@ module Clearly
     # Provides common validations for composing queries.
     module Validate
 
-      # Validate query, table, and column values.
-      # @param [Arel::Query] query
-      # @param [Arel::Table] table
-      # @param [Symbol] column_name
-      # @param [Array<Symbol>] allowed
-      # @return [void]
-      def validate_query_table_column(query, table, column_name, allowed)
-        validate_query(query)
-        validate_table(table)
-        validate_name(column_name, allowed)
-      end
-
       # Validate table and column values.
       # @param [Arel::Table] table
       # @param [Symbol] column_name
@@ -39,15 +27,6 @@ module Clearly
         fail Clearly::Query::QueryArgumentError, "model must be in '#{models_allowed}', got '#{model}'" unless models_allowed.include?(model)
       end
 
-      # Validate query and hash values.
-      # @param [ActiveRecord::Relation] query
-      # @param [Hash] hash
-      # @return [void]
-      def validate_query_hash(query, hash)
-        validate_query(query)
-        validate_hash(hash)
-      end
-
       # Validate table value.
       # @param [Arel::Table] table
       # @raise [FilterArgumentError] if table is not an Arel::Table
@@ -154,7 +133,6 @@ module Clearly
       # @raise [FilterArgumentError] if value is not a valid Hash.
       # @return [void]
       def validate_hash(value)
-        validate_not_blank(value)
         fail Clearly::Query::QueryArgumentError, "value must be a Hash, got '#{value}'" unless value.is_a?(Hash)
       end
 
@@ -181,7 +159,7 @@ module Clearly
         fail Clearly::Query::QueryArgumentError, "value must be a boolean, got '#{value}'" if !value.is_a?(TrueClass) && !value.is_a?(FalseClass)
       end
 
-      # Escape wildcards in like value..
+      # Escape wildcards in LIKE value.
       # @param [String] value
       # @return [String] sanitized value
       def sanitize_like_value(value)
@@ -247,16 +225,17 @@ module Clearly
       # @param [Hash] value
       # @return [void]
       def validate_definition(value)
+        validate_not_blank(value)
         validate_hash(value)
 
         # fields
+        validate_not_blank(value[:fields])
         validate_hash(value[:fields])
 
         validate_not_blank(value[:fields][:valid])
         validate_array(value[:fields][:valid])
         validate_array_items(value[:fields][:valid])
 
-        validate_not_blank(value[:fields][:text])
         validate_array(value[:fields][:text])
         validate_array_items(value[:fields][:text])
 
@@ -264,6 +243,7 @@ module Clearly
         validate_array(value[:fields][:mappings])
 
         value[:fields][:mappings].each do |mapping|
+          validate_not_blank(mapping)
           validate_hash(mapping)
           validate_symbol(mapping[:name])
           validate_not_blank(mapping[:value])
@@ -271,9 +251,6 @@ module Clearly
 
         # associations
         validate_spec_association(value[:associations])
-
-        # defaults
-        validate_hash(value[:defaults])
       end
 
       # Validate association specification
@@ -283,6 +260,7 @@ module Clearly
         validate_array(value)
 
         value.each do |association|
+          validate_not_blank(association)
           validate_hash(association)
           validate_not_blank(association[:join])
           validate_not_blank(association[:on])

data/lib/clearly/query/version.rb

@@ -3,6 +3,6 @@ module Clearly
   # Clearly Query namespace
   module Query
     # Gem version
-    VERSION = '0.3.1.pre'
+    VERSION = '1.0.0'
   end
 end

data/spec/lib/clearly/query/compose/custom_spec.rb

@@ -2,15 +2,25 @@ require 'spec_helper'
 
 describe Clearly::Query::Compose::Custom do
   include_context 'shared_setup'
+
+  # for access to compose_and, relation_none, and relation_all
   include Clearly::Query::Compose::Core
 
   it 'can be instantiated' do
     Clearly::Query::Compose::Custom.new
   end
 
-  it 'build expected sql' do
+  it 'constructs sql for select all' do
+    query = self.send(:relation_all, Order).where(customer_id: 10)
+    expect(query.to_sql).to eq('SELECT "orders".* FROM "orders" WHERE "orders"."customer_id" = 10')
+  end
 
+  it 'constructs sql for select none' do
+    query = self.send(:relation_none, Order).where(customer_id: 10)
+    expect(query.to_sql).to eq('')
+  end
 
+  it 'builds expected sql' do
     custom = Clearly::Query::Compose::Custom.new
 
     table = product_def.table

data/spec/lib/clearly/query/composer_query_spec.rb

@@ -2,19 +2,34 @@ require 'spec_helper'
 
 describe Clearly::Query::Composer do
   include_context 'shared_setup'
-  let(:product_attributes) { {name: 'plastic cup',
-                                        code: '000475PC',
-                                        brand: 'Generic',
-                                        introduced_at: '2015-01-01 00:00:00',
-                                        discontinued_at: nil}}
+  let(:product_attributes) {
+    {
+        name: 'plastic cup',
+        code: '000475PC',
+        brand: 'Generic',
+        introduced_at: '2015-01-01 00:00:00',
+        discontinued_at: nil
+    }
+  }
+
+  let(:customer_attributes) {
+    {
+        name: 'first last',
+        last_contact_at: '2015-11-09 10:00:00'
+    }
+  }
+
+  let(:order_attributes) {
+    {
+
+    }
+  }
 
   it 'finds the only product' do
     product = Product.create!(product_attributes)
     query_hash = cleaner.do({name: {contains: 'cup'}})
-    result = composer.query(Product, query_hash)
-    expect(result.size).to eq(1)
+    query_ar = composer.query(Product, query_hash)
 
-    query_ar = Product.where(result[0])
     expect(query_ar.count).to eq(1)
 
     result_item = query_ar.to_a[0]
@@ -34,10 +49,8 @@ describe Clearly::Query::Composer do
     end
 
     query_hash = cleaner.do({name: {contains: '5'}})
-    result = composer.query(Product, query_hash)
-    expect(result.size).to eq(1)
+    query_ar = composer.query(Product, query_hash)
 
-    query_ar = Product.where(result[0])
     expect(query_ar.count).to eq(1)
 
     result_item = query_ar.to_a[0]
@@ -47,4 +60,35 @@ describe Clearly::Query::Composer do
     expect(result_item.introduced_at).to eq(product_attributes[:introduced_at])
     expect(result_item.discontinued_at).to eq(product_attributes[:discontinued_at])
   end
+
+  it 'finds the matching order using mapped field' do
+    customer = Customer.create!(customer_attributes)
+    order_pending = Order.create!(customer: customer)
+    order_shipped = Order.create!(customer: customer, shipped_at: '2015-11-09 11:00:00')
+
+    query_hash = cleaner.do({title: {contains: 'not shipped'}})
+    query_ar = composer.query(Order, query_hash)
+
+    expect(query_ar.count).to eq(1)
+
+    result_item = query_ar.to_a[0]
+    expect(result_item.shipped_at).to eq(order_pending.shipped_at)
+    expect(result_item.customer_id).to eq(order_pending.customer_id)
+  end
+
+  it 'finds the correct order comparing dates' do
+    customer = Customer.create!(customer_attributes)
+    order1 = Order.create!(customer: customer, shipped_at: '2015-11-09 11:00:01')
+    order2 = Order.create!(customer: customer, shipped_at: '2015-11-09 11:00:00')
+
+    query_hash = cleaner.do({shipped_at: {gteq: '2015-11-09 11:00:01'}})
+    query_ar = composer.query(Order, query_hash)
+
+    expect(query_ar.count).to eq(1)
+
+    result_item = query_ar.to_a[0]
+    expect(result_item.shipped_at).to eq(order1.shipped_at)
+    expect(result_item.customer_id).to eq(order1.customer_id)
+  end
+
 end

data/spec/lib/clearly/query/composer_spec.rb

@@ -17,7 +17,7 @@ describe Clearly::Query::Composer do
     invalid_composer = Clearly::Query::Composer.new([customer_def, customer_def])
     query = cleaner.do({})
     expect {
-      invalid_composer.query(Customer, query)
+      invalid_composer.conditions(Customer, query)
     }.to raise_error(Clearly::Query::QueryArgumentError, "exactly one definition must match, found '2'")
   end
 
@@ -36,13 +36,13 @@ describe Clearly::Query::Composer do
       it 'is given an empty query' do
         query = cleaner.do({})
         expect {
-          composer.query(Customer, query)
+          composer.conditions(Customer, query)
         }.to raise_error(Clearly::Query::QueryArgumentError, "filter hash must have at least 1 entry, got '0'")
       end
 
       it 'uses a regex operator using sqlite' do
         expect {
-          conditions = composer.query(Product, {name: {regex: 'test'}})
+          conditions = composer.conditions(Product, {name: {regex: 'test'}})
           query = Product.all
           conditions.each { |c| query = query.where(c) }
           expect(query.to_a).to eq([])
@@ -55,7 +55,7 @@ describe Clearly::Query::Composer do
 
         it 'contains an unrecognised filter' do
           expect {
-            composer.query(Customer, {
+            composer.conditions(Customer, {
                         or: {
                             name: {
                                 not_a_real_filter: 'Hello'
@@ -67,7 +67,7 @@ describe Clearly::Query::Composer do
 
         it 'has no entry' do
           expect {
-            composer.query(Customer, {
+            composer.conditions(Customer, {
                         or: {
                             name: {
 
@@ -79,7 +79,7 @@ describe Clearly::Query::Composer do
 
         it 'has not with no entries' do
           expect {
-            composer.query(Customer, {
+            composer.conditions(Customer, {
                         not: {
                         }
                     })
@@ -88,7 +88,7 @@ describe Clearly::Query::Composer do
 
         it 'has or with no entries' do
           expect {
-            composer.query(Customer, {
+            composer.conditions(Customer, {
                         or: {
                         }
                     })
@@ -97,7 +97,7 @@ describe Clearly::Query::Composer do
 
         it 'has not with more than one field' do
           expect {
-            composer.query(Product, {
+            composer.conditions(Product, {
                         not: {
                             name: {
                                 contains: 'Hello'
@@ -112,7 +112,7 @@ describe Clearly::Query::Composer do
 
         it 'has not with more than one filter' do
           expect {
-            composer.query(Product, {
+            composer.conditions(Product, {
                         not: {
                             name: {
                                 contains: 'Hello',
@@ -125,7 +125,7 @@ describe Clearly::Query::Composer do
 
         it 'has a combiner that is not recognised with valid filters' do
           expect {
-            composer.query(Product, {
+            composer.conditions(Product, {
                         not_a_valid_combiner: {
                             name: {
                                 contains: 'Hello'
@@ -140,7 +140,7 @@ describe Clearly::Query::Composer do
 
         it "has a range missing 'from'" do
           expect {
-            composer.query(Customer, {
+            composer.conditions(Customer, {
                         and: {
                             name: {
                                 range: {
@@ -154,7 +154,7 @@ describe Clearly::Query::Composer do
 
         it "has a range missing 'to'" do
           expect {
-            composer.query(Product, {
+            composer.conditions(Product, {
                         and: {
                             code: {
                                 range: {
@@ -168,7 +168,7 @@ describe Clearly::Query::Composer do
 
         it 'has a range with from/to and interval' do
           expect {
-            composer.query(Customer, {
+            composer.conditions(Customer, {
                         and: {
                             name: {
                                 range: {
@@ -183,7 +183,7 @@ describe Clearly::Query::Composer do
 
         it 'has a range with no recognised properties' do
           expect {
-            composer.query(Customer, {
+            composer.conditions(Customer, {
                         and: {
                             name: {
                                 range: {
@@ -197,7 +197,7 @@ describe Clearly::Query::Composer do
 
         it 'has a property that has no filters' do
           expect {
-            composer.query(Customer, {
+            composer.conditions(Customer, {
                         or: {
                             name: {
                             }
@@ -216,7 +216,7 @@ describe Clearly::Query::Composer do
 
           expect {
             query = cleaner.do(filter_params)
-            composer.query(Customer, query)
+            composer.conditions(Customer, query)
           }.to raise_error(Clearly::Query::QueryArgumentError, 'array values cannot be hashes')
         end
 
@@ -224,7 +224,7 @@ describe Clearly::Query::Composer do
           filter_params = {"name" => {"inRange" => "(5,6)"}}
           expect {
             query = cleaner.do(filter_params)
-            composer.query(Customer, query)
+            composer.conditions(Customer, query)
           }.to raise_error(Clearly::Query::QueryArgumentError, "range filter must be {'from': 'value', 'to': 'value'} or {'interval': '(|[.*,.*]|)'} got '(5,6)'")
         end
 
@@ -233,7 +233,7 @@ describe Clearly::Query::Composer do
     context 'succeeds when it' do
       it 'is given a valid query without combiners' do
         hash = cleaner.do({name: {contains: 'test'}})
-        conditions = composer.query(Customer, hash)
+        conditions = composer.conditions(Customer, hash)
         expect(conditions.size).to eq(1)
 
         # sqlite only supports LIKE
@@ -246,7 +246,7 @@ describe Clearly::Query::Composer do
 
       it 'is given a valid query with or combiner' do
         hash = cleaner.do({or: {name: {contains: 'test'}, code: {eq: 4}}})
-        conditions = composer.query(Product, hash)
+        conditions = composer.conditions(Product, hash)
         expect(conditions.size).to eq(1)
 
         expect(conditions.first.to_sql).to eq("(\"products\".\"name\" LIKE '%test%' OR \"products\".\"code\" = '4')")
@@ -258,7 +258,7 @@ describe Clearly::Query::Composer do
 
       it 'is given a valid query with camel cased keys' do
         hash = cleaner.do({name: {does_not_start_with: 'test'}})
-        conditions = composer.query(Customer, hash)
+        conditions = composer.conditions(Customer, hash)
         expect(conditions.size).to eq(1)
 
         expect(conditions.first.to_sql).to eq("\"customers\".\"name\" NOT LIKE 'test%'")
@@ -270,7 +270,7 @@ describe Clearly::Query::Composer do
 
       it 'is given a valid range query that excludes the start and includes the end' do
         hash = cleaner.do({name: {notInRange: {interval: '(2,5]'}}})
-        conditions = composer.query(Customer, hash)
+        conditions = composer.conditions(Customer, hash)
         expect(conditions.size).to eq(1)
         
         expect(conditions.first.to_sql).to eq("(\"customers\".\"name\" <= '2' OR \"customers\".\"name\" > '5')")
@@ -282,7 +282,7 @@ describe Clearly::Query::Composer do
 
       it 'is given a valid query that uses a table one step away' do
         hash = cleaner.do({and: {name: {contains: 'test'}, 'orders.shipped_at' => {lt: '2015-10-24'}}})
-        conditions = composer.query(Customer, hash)
+        conditions = composer.conditions(Customer, hash)
         expect(conditions.size).to eq(1)
 
         expected = "\"customers\".\"name\" LIKE '%test%' AND EXISTS (SELECT 1 FROM \"orders\" WHERE \"orders\".\"shipped_at\" < '2015-10-24' AND \"orders\".\"customer_id\" = \"customers\".\"id\")"
@@ -298,7 +298,7 @@ describe Clearly::Query::Composer do
         # instead of the hash in Definition#parse_table_field
 
         hash = cleaner.do({and: {name: {contains: 'test'}, 'customers.name' => {lt: '2015-10-24'}}})
-        conditions = composer.query(Part, hash)
+        conditions = composer.conditions(Part, hash)
         expect(conditions.size).to eq(1)
 
         expected = "\"parts\".\"name\" LIKE '%test%' AND EXISTS (SELECT 1 FROM \"customers\" INNER JOIN \"parts_products\" ON \"products\".\"id\" = \"parts_products\".\"product_id\" INNER JOIN \"products\" ON \"products\".\"id\" = \"orders_products\".\"product_id\" INNER JOIN \"orders_products\" ON \"orders\".\"id\" = \"orders_products\".\"order_id\" INNER JOIN \"orders\" ON \"orders\".\"customer_id\" = \"customers\".\"id\" WHERE \"customers\".\"name\" < '2015-10-24' AND \"customers\".\"id\" = \"orders\".\"customer_id\")"
@@ -311,10 +311,37 @@ describe Clearly::Query::Composer do
 
       it 'is given a valid query that uses a custom field mapping' do
         hash = cleaner.do({and: {shipped_at: {lt: '2015-10-24'}, title: {does_not_start_with: 'alice'}}})
-        conditions = composer.query(Order, hash)
+        conditions = composer.conditions(Order, hash)
         expect(conditions.size).to eq(1)
 
-        expected = "\"orders\".\"shipped_at\" < '2015-10-24' AND (SELECT \"customers\".\"name\" FROM \"customers\" WHERE \"customers\".\"id\" = \"orders\".\"customer_id\") || ' (' || CASE WHEN \"orders\".\"shipped_at\" IS NULL THEN 'not shipped' ELSE \"orders\".\"shipped_at\" END || ')' NOT LIKE 'alice%'"
+        expected = "\"orders\".\"shipped_at\" < '2015-10-24' AND (SELECT \"customers\".\"name\" FROM \"customers\" WHERE \"customers\".\"id\" = \"orders\".\"customer_id\") || ' (' || (CASE WHEN \"orders\".\"shipped_at\" IS NULL THEN 'not shipped' ELSE \"orders\".\"shipped_at\" END) || ') ' NOT LIKE 'alice%'"
+        expect(conditions.first.to_sql).to eq(expected)
+
+        query = Order.all
+        conditions.each { |c| query = query.where(c) }
+        expect(query.to_a).to eq([])
+      end
+
+      it 'is given a valid query for all text fields' do
+        hash = cleaner.do({and: {all_text_fields: {starts_with: 'a'}}})
+        conditions = composer.conditions(Product, hash)
+        expect(conditions.size).to eq(1)
+
+        expected = "(((\"products\".\"brand\" || ' ' || \"products\".\"name\" || ' (' || \"products\".\"code\" || ')' LIKE 'a%' OR \"products\".\"name\" LIKE 'a%') OR \"products\".\"code\" LIKE 'a%') OR \"products\".\"brand\" LIKE 'a%')"
+        expect(conditions.first.to_sql).to eq(expected)
+
+        query = Product.all
+        conditions.each { |c| query = query.where(c) }
+        expect(query.to_a).to eq([])
+      end
+
+      it 'escapes characters in SQL like' do
+        hash = cleaner.do({and: {shipped_at: {lt: '2015-10-24'}, title: {does_not_start_with: 'a\l_i%c\'e|'}}})
+        conditions = composer.conditions(Order, hash)
+        expect(conditions.size).to eq(1)
+
+        escaped = 'a\\\l\\_i\\%c\'\'e\\|%'
+        expected = "\"orders\".\"shipped_at\" < '2015-10-24' AND (SELECT \"customers\".\"name\" FROM \"customers\" WHERE \"customers\".\"id\" = \"orders\".\"customer_id\") || ' (' || (CASE WHEN \"orders\".\"shipped_at\" IS NULL THEN 'not shipped' ELSE \"orders\".\"shipped_at\" END) || ') ' NOT LIKE '#{escaped}'"
         expect(conditions.first.to_sql).to eq(expected)
 
         query = Order.all
@@ -355,7 +382,7 @@ describe Clearly::Query::Composer do
         end
 
         hash = cleaner.do({and: {name: operator_hash}})
-        conditions = composer.query(Product, hash)
+        conditions = composer.conditions(Product, hash)
         expect(conditions.size).to eq(1)
 
         expected = {

data/spec/lib/clearly/query/helper_spec.rb

@@ -14,4 +14,23 @@ describe Clearly::Query::Helper do
       Clearly::Query::Helper.string_concat_infix('+')
     }.to raise_error(ArgumentError,"string concatenation requires operator and two or more arguments, given '0'")
   end
+
+  it 'builds a SQL function' do
+    format_date = 'YYYY-MM-DD'
+    format_date_quoted = Arel::Nodes.build_quoted(format_date)
+    table = Order.arel_table
+    column =:shipped_at
+    alias_name = 'as_alias'
+
+    query = Clearly::Query::Helper.named_function('to_char', [table[column], format_date_quoted], alias_name)
+    expect(query.to_sql).to eq("to_char(\"orders\".\"shipped_at\", 'YYYY-MM-DD') AS as_alias")
+  end
+
+  it 'builds a SQL EXISTS condition' do
+    table = Order.arel_table
+    column =:shipped_at
+
+    query = Clearly::Query::Helper.exists(table[column])
+    expect(query.to_sql).to eq("EXISTS (\"orders\".\"shipped_at\")")
+  end
 end

data/spec/support/models/customer.rb

@@ -14,7 +14,7 @@ class Customer < ActiveRecord::Base
                     name: :title,
                     value: Clearly::Query::Helper.string_concat(
                         Customer.arel_table[:name],
-                        Arel::Nodes.build_quoted(' title'))
+                        Clearly::Query::Helper.sql_quoted(' title'))
                 }
             ]
         },
@@ -53,11 +53,7 @@ class Customer < ActiveRecord::Base
                     }
                 ]
             }
-        ],
-        defaults: {
-            order_by: :created_at,
-            direction: :desc
-        }
+        ]
     }
   end
 end

data/spec/support/models/order.rb

@@ -14,12 +14,15 @@ class Order < ActiveRecord::Base
                 {
                     name: :title,
                     value: Clearly::Query::Helper.string_concat(
-                        Customer.arel_table
-                            .where(Customer.arel_table[:id].eq(Order.arel_table[:customer_id]))
-                            .project(Customer.arel_table[:name]),
-                        Arel::Nodes.build_quoted(' ('),
-                        Arel::Nodes::SqlLiteral.new('CASE WHEN "orders"."shipped_at" IS NULL THEN \'not shipped\' ELSE "orders"."shipped_at" END'),
-                        Arel::Nodes.build_quoted(')'))
+                        Clearly::Query::Helper.sql_literal(
+                            '(' +
+                                Customer.arel_table
+                                    .where(Customer.arel_table[:id].eq(Order.arel_table[:customer_id]))
+                                    .project(Customer.arel_table[:name]).to_sql + ')'),
+                        Clearly::Query::Helper.sql_quoted(' ('),
+                        Clearly::Query::Helper.sql_literal('(CASE WHEN "orders"."shipped_at" IS NULL THEN \'not shipped\' ELSE "orders"."shipped_at" END)'),
+                        Clearly::Query::Helper.sql_quoted(') ')
+                    )
                 }
             ]
         },
@@ -56,11 +59,7 @@ class Order < ActiveRecord::Base
                     }
                 ]
             }
-        ],
-        defaults: {
-            order_by: :created_at,
-            direction: :desc
-        }
+        ]
     }
   end
 end

data/spec/support/models/part.rb

@@ -14,7 +14,7 @@ class Part < ActiveRecord::Base
                     name: :title,
                     value: Clearly::Query::Helper.string_concat(
                         Part.arel_table[:code],
-                        Arel::Nodes.build_quoted(' '),
+                        Clearly::Query::Helper.sql_quoted(' '),
                         Part.arel_table[:manufacturer])
                 }
             ]
@@ -53,11 +53,7 @@ class Part < ActiveRecord::Base
                     }
                 ]
             }
-        ],
-        defaults: {
-            order_by: :name,
-            direction: :asc
-        }
+        ]
     }
   end
 end

data/spec/support/models/product.rb

@@ -15,11 +15,11 @@ class Product < ActiveRecord::Base
                     name: :title,
                     value: Clearly::Query::Helper.string_concat(
                         Product.arel_table[:brand],
-                        Arel::Nodes.build_quoted(' '),
+                        Clearly::Query::Helper.sql_quoted(' '),
                         Product.arel_table[:name],
-                        Arel::Nodes.build_quoted(' ('),
+                        Clearly::Query::Helper.sql_quoted(' ('),
                         Product.arel_table[:code],
-                        Arel::Nodes.build_quoted(')'))
+                        Clearly::Query::Helper.sql_quoted(')'))
                 }
             ]
         },
@@ -57,11 +57,7 @@ class Product < ActiveRecord::Base
                     }
                 ]
             }
-        ],
-        defaults: {
-            order_by: :name,
-            direction: :asc
-        }
+        ]
     }
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clearly-query
 version: !ruby/object:Gem::Version
-  version: 0.3.1.pre
+  version: 1.0.0
 platform: ruby
 authors:
-- "@cofiem"
+- Mark Cottman-Fields
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-01 00:00:00.000000000 Z
+date: 2015-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: arel
@@ -235,9 +235,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.4.8