whereable 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fb9a55c5cc4baff3d60aaaa56e5ce74fde2a8a2b20ff4abec5ca7268cca927c
-  data.tar.gz: dd20820bcb8b5a46bdd30458e9c135f41892db53062caeb088590e98e33851c3
+  metadata.gz: e05606c44046b2bbc2afb63ad64dc40dfbd950c7e2417f8303ac9d504033fcf9
+  data.tar.gz: e279cfd12a42d0dcc22bd33c2a934875d8c6bf16432c3fd62f53cb3d51bcdb5b
 SHA512:
-  metadata.gz: '055580e74876c9f5e1746ce1eb16d2fba7a20efc9fb32f87b1a0fe6faf5648d84b35f9435d11c1749c856d7ab8ee8f0f6f87bcf9f21b7ce7dbaf5a707765fa2b'
-  data.tar.gz: 05e88aef960b3a18d6dcc72d119a8e172adb3c83256215cb1555198dbd9b330b5dfd79b7203e7f3ad9258a40af5956efc5bcdbe9d62882fe783d9f3f9e48762d
+  metadata.gz: 888cd81cd96258b790b2f789e001572155628837d10bc8e813219618c879540530916b62652249d3334a861ba9e091a2599dfe45acef67e388ad013d79e784f2
+  data.tar.gz: 17764113a90b3dc10742ce4f566029c2a7bb0e9ad7249a701cd598c4666f483e3a4e9dec92a974046f11cb7b65b408cc06f3623f039ebcf3fa2339f730116af0

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+Release History
+===============
+# 0.1.1
+* Make operators case-insensitive
+
+# 0.1.0
+* Initial release

data/README.md

@@ -1,14 +1,13 @@
 # Whereable
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/whereable`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Translates where-like filter syntax into an Arel-based ActiveRecord scope, so you can safely use SQL syntax in Rails controller parameters.
+Not as powerful as [Ransack](https://github.com/activerecord-hackery/ransack), but simple and lightweight.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-```ruby
+``` ruby
 gem 'whereable'
 ```
 
@@ -22,7 +21,66 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Imagine a User model:
+``` ruby
+class User < ActiveRecord::Base
+  include Whereable
+
+  validates :username, presence: true, uniqueness: true
+
+  enum role: { standard: 0, admin: 1 }
+end
+```
+With this data:
+``` ruby
+User.create!(username: 'Morpheus', role: :admin, born_on: '1961-07-30')
+User.create!(username: 'Neo', role: :standard, born_on: '1964-09-02')
+```
+Let's assume you're allowing filtered API access to your Users,
+but using the `#standard` scope to keep admins hidden. So your controller might include:
+``` ruby
+User.standard.where(params[:filter])
+```
+And your white hat API consumers pass in `filter=born_on < '1970-11-11'` to get Users over 50, and &hellip;
+``` ruby
+User.standard.where("born_on < '1970-11-11'")
+```
+returns Neo as expected, so we're all good.
+
+*Meanwhile&hellip;* Your black hat API consumer passes in `filter=true) or (1=1`, and &hellip;
+``` ruby
+User.standard.where("true) or (1=1")
+```
+returns **EVERYONE!!!** *This is how the Matrix gets hacked.*
+
+Instead add `include Whereable` to your model, and change your controller to:
+``` ruby
+User.standard.whereable(params[:filter])
+```
+And then &hellip;
+``` ruby
+User.standard.whereable("born_on < '1970-11-11'")
+```
+returns Neo as before, but &hellip;
+``` ruby
+User.standard.whereable("true) or (1=1")
+```
+raises exception &hellip;
+``` ruby
+Whereable::FilterInvalid ('Invalid filter at ) or (1=1')
+```
+
+### Syntax
+* Supports and/or with nested parentheses as needed
+* Recognizes these operators: `eq ne gte gt lte lt = != <> >= > <= <`
+* Column must be to left of operator, and literal to right
+  * Comparing columns is *not* supported
+* Quotes are optional unless the literal contains spaces or quotes
+  * Supports double or single quotes, and embedded quotes may be backslash escaped
+  * Also supports the PostgreSQL double-single embedded quote
+* Enum literals must use the *name*, not the database value:
+  * 👍 `User.whereable('role = admin')`
+  * 👎 `User.whereable('role = 1')`
 
 ## Development
 
@@ -32,7 +90,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/whereable.
+Bug reports and pull requests are welcome on GitHub at https://github.com/MacksMind/whereable.
 
 
 ## License

data/lib/whereable.rb

@@ -78,7 +78,7 @@ module Whereable
   module Operator
     # Arel comparion method
     def to_sym
-      OP_SYMS[text_value] || text_value.downcase.to_sym
+      OP_SYMS[text_value.downcase] || text_value.downcase.to_sym
     end
   end
 

data/lib/whereable.treetop

@@ -28,7 +28,7 @@ grammar Whereable
   end
 
   rule operator
-    ( 'eq' / 'ne' / 'gte' / 'gt' / 'lte' / 'lt' / '=' / '!=' / '<>' / '>=' / '>' / '<=' / '<' ) <Operator>
+    ( 'eq'i / 'ne'i / 'gte'i / 'gt'i / 'lte'i / 'lt'i / '=' / '!=' / '<>' / '>=' / '>' / '<=' / '<' ) <Operator>
   end
 
   rule literal

data/lib/whereable/version.rb

@@ -3,6 +3,6 @@
 # Copyright 2020 Mack Earnhardt
 
 module Whereable
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
   public_constant :VERSION
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whereable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Mack Earnhardt
@@ -38,9 +38,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 'Translate where-like filter syntax into Arel-based ActiveRecord scope.
-
-  '
+description: |
+  Translates where-like filter syntax into an Arel-based ActiveRecord scope,
+  so you can safely use SQL syntax in Rails controller parameters.
+  Not as powerful as Ransack, but simple and lightweight.
 email:
 - mack@agilereasoning.com
 executables: []
@@ -78,5 +79,5 @@ requirements: []
 rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
-summary: Translate where-like filter syntax into Arel-based ActiveRecord scope.
+summary: Translates where-like filter syntax into an Arel-based ActiveRecord scope.
 test_files: []