clearly-query 0.3.1.pre

checksums.yaml

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

data/.codeclimate.yml

@@ -0,0 +1,8 @@
+engines:
+  rubocop:
+    enabled: true
+ratings:
+  paths:
+  - "**.rb"
+exclude_paths:
+- spec/**/*

data/.gitignore

@@ -0,0 +1,42 @@
+*.gem
+*.rbc
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/*
+!/tmp/.gitkeep
+/.idea/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+/Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+cache: bundler
+sudo: false
+rvm:
+  - 2.2.3
+script:
+  - bin/rspec
+addons:
+    code_climate:
+        repo_token: 7f46a15011c053c6e456e9ad33bcf9a7a22277fe99107996721dfd2ae301a38b

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+Non-trivial changes will be documented here. 
+This project adheres to [Semantic Versioning](http://semver.org/) 
+and [keeps a change log](http://keepachangelog.com/) (you're reading it!).
+
+## Unreleased
+
+## Release [v0.3.1-pre](https://github.com/cofiem/clearly-query/releases/tag/v0.3.1-pre) (2015-11-01)
+
+### Added
+ - new DFS graph traversal for calculating joins between tables
+ - additional tests for Composer
+
+### Changed
+ - composer and definition functionality redistributed to be more obvious and have simpler methods
+
+## Release [v0.2.0-pre](https://github.com/cofiem/clearly-query/releases/tag/0.2.0) (2015-10-27)
+
+### Added
+
+ - Transported hash filter modules and classes from [baw-server](https://github.com/QutBioacoustics/baw-server)
+  - Created change log
+
+## Change log categories
+
+### Added
+new features
+
+### Changed
+changes in existing functionality
+
+### Deprecated
+once-stable features removed in upcoming releases
+
+### Removed
+deprecated features removed in this release
+
+### Fixed
+bug fixes
+
+### Security
+vulnerabilities or other problems that should be highlighted

data/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in clearly/query.gemspec
+gemspec
+
+# for reporting code coverage to code climate
+gem 'codeclimate-test-reporter', group: :test, require: nil

data/Guardfile

@@ -0,0 +1,19 @@
+guard :rspec, cmd: 'bin/rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+end
+
+guard :yard, cmd: 'bin/yard doc' do
+  watch(%r{lib/.+\.rb})
+end

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Mark
+
+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 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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,102 @@
+# Clearly Query
+
+A library for constructing an sql query from a hash.
+
+Uses [Arel](https://github.com/rails/arel) and [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord).
+
+## Project Status
+
+[![Build Status](https://travis-ci.org/cofiem/clearly-query.svg?branch=master)](https://travis-ci.org/cofiem/clearly-query)
+[![Dependency Status](https://gemnasium.com/cofiem/clearly-query.svg)](https://gemnasium.com/cofiem/clearly-query)
+[![Code Climate](https://codeclimate.com/github/cofiem/clearly-query/badges/gpa.svg)](https://codeclimate.com/github/cofiem/clearly-query)
+[![Test Coverage](https://codeclimate.com/github/cofiem/clearly-query/badges/coverage.svg)](https://codeclimate.com/github/cofiem/clearly-query/coverage)
+[![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)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'clearly-query'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install clearly-query
+
+## Usage
+
+There are two main public classes in this gem. 
+The Definition class makes use of a settings declared in a model.
+The Composer converts a hash of options into an Arel query.
+
+### [Clearly::Query::Definition](./lib/clearly/query/definition.rb)
+
+Contains the query specification for ActiveRecord models.
+
+For example:
+
+    Clearly::Query::Definition.new(Customer, Customer.clearly_query_def)
+
+and
+
+    # model/customer.rb
+        def self.clearly_query_def
+        {
+            fields: {
+                valid: [:name, :last_contact_at],
+                text: [:name],
+                mappings: [
+                    {
+                        name: :title,
+                        value: Clearly::Query::Helper.string_concat(
+                            Customer.arel_table[:name],
+                            Arel::Nodes.build_quoted(' title'))
+                    }
+                ]
+            },
+            associations: [
+                {
+                    join: Order,
+                    on: Order.arel_table[:customer_id].eq(Customer.arel_table[:id]),
+                    available: true,
+                    associations: []
+                }
+            ],
+            defaults: {
+                order_by: :created_at,
+                direction: :desc
+            }
+        }
+      end
+
+### [Clearly::Query::Composer](./lib/clearly/query/composer.rb)
+
+Constructs an Arel query from a hash of options.
+See the [query hash specification](SPEC.md) for a comprehensive overview.
+
+For example:
+
+    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)
+
+## 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)
+
+## 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)

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+

data/SPEC.md

@@ -0,0 +1,101 @@
+# Query Hash Specification
+
+Inspired by [elastic search filters](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/query-dsl-filters.html).
+
+## Available Filter Operators
+
+### Combine Operators
+
+     Operator |   Query hash   |       SQL
+    ----------|----------------|---------------------
+    and       | {and: { ... }} | WHERE ... AND  ...
+    or        | {or:  { ... }} | WHERE ... OR  (...)
+    not       | {not: { ... }} | WHERE ... NOT (...)
+    
+Implicit `and` is used when no combine 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).
+
+#### Comparison Operators
+
+Comparison operators are self-explanatory. 
+
+                   Operator              |         Query hash         |        SQL
+    -------------------------------------|----------------------------|---------------------------------
+    eq, equal                            | {attr: {eq: 'test'}}       | "table"."attr" = 'test'
+    not_eq, not_equal                    | {attr: {not_eq: 'test'}}   | "table"."attr" != 'test'
+    lt, less_than                        | {attr: {lt: 'test'}}       | "table"."attr" < 'test'
+    not_lt, not_less_than                | {attr: {not_lt: 'test'}}   | "table"."attr" >= 'test'
+    gt, greater_than                     | {attr: {gt: 'test'}}       | "table"."attr" > 'test'
+    not_gt, not_greater_than             | {attr: {not_gt: 'test'}}   | "table"."attr" <= 'test'
+    lteq, less_than_or_equal             | {attr: {lteq: 'test'}}     | "table"."attr" <= 'test'
+    not_lteq, not_less_than_or_equal     | {attr: {not_lteq: 'test'}} | "table"."attr" > 'test'
+    gteq, greater_than_or_equal          | {attr: {gteq: 'test'}}     | "table"."attr" >= 'test'
+    not_gteq, not_greater_than_or_equal  | {attr: {not_gteq: 'test'}} | "table"."attr" < 'test'
+
+#### Special Comparisons
+
+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
+    -----------------------|----------------------------|---------------------------------
+    null, is_null          | {attr: {null: true}}       | "table"."attr" IS NULL
+
+#### Subset Operators
+
+##### Range
+
+A simple range is inclusive lower bound and 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')
+    
+A more complex range can be specified using a regex 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')
+
+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. 
+
+##### Arrays
+
+An array of values to match the attribute value exactly.
+
+    Operator |            Query hash               |                             SQL
+    ---------|-------------------------------------|-----------------------------------------------
+    in       | {attr: {in: ['value1,value2']}}     | "table"."attr" IN ('value1', 'value2')
+    not_in   | {attr: {not_in: ['value1,value2']}} | "table"."attr" NOT IN ('value1', 'value2')
+    
+##### 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.
+
+Regular expression match **may not be supported by all databases**.
+
+                        Operator                          |           Query hash              |                SQL
+    ------------------------------------------------------|-----------------------------------|-----------------------------------------------
+    contains, contain                                     | {attr: {contain: 'value'}}        | "table"."attr" LIKE 'value'
+    not_contains, not_contain, does_not_contain           | {attr: {not_contain: 'value'}}    | "table"."attr" NOT LIKE 'value'
+    starts_with, start_with                               | {attr: {start_with: 'value'}}     | "table"."attr" LIKE 'value%'
+    not_starts_with,not_start_with, does_not_start_with   | {attr: {not_start_with: 'value'}} | "table"."attr" NOT LIKE 'value%'
+    ends_with, end_with                                   | {attr: {end_with: 'value'}}       | "table"."attr" LIKE '%value'
+    not_ends_with, not_end_with, does_not_end_with        | {attr: {not_end_with: 'value'}}   | "table"."attr" NOT LIKE '%value'
+    regex, regex_match, matches, match                    | {attr: {regex: 'value'}}          | "table"."attr" SIMILAR TO 'value'
+    not_regex, not_regex_match, does_not_match, not_match | {attr: {not_end_with: 'value'}}   | "table"."attr" NOT SIMILAR TO 'value'

data/bin/guard

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('guard', 'guard')

data/bin/rake

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')