rql 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7b4ab947240986e99b39fe5a70b079e1fbd6e047
-  data.tar.gz: 3e3962ff1f6062d0c39494f17adeebc443927697
+  metadata.gz: 084bde9b357cebc0e8e7d46ccddc7158bd1b0365
+  data.tar.gz: 87759ddc7eaf7f44d495d148cb1d6ef2039b1ee2
 SHA512:
-  metadata.gz: dd912988d5e371defaf25597e97b8f6b3b1c162be6f43e4c543eff1db2eca2d5af096de63cccd3982b350e91182137368f7306307b6e3550ed6323788e69cb15
-  data.tar.gz: 249aa513b6aa047032c23732900986e009e4b3090834c85b94995f2c10946c217a462f74a4cba043b7f504a925249547b0e8b37f3f93811dc3ea91f4f0801125
+  metadata.gz: 7c05432fb7fe1f44af0eea3f5ff4767debf22a3d18f07658af5358587e4418719ff1333cb875d5eb3e8b8753b65b15aa8cf2d6f8166c52e6ed03745552510636
+  data.tar.gz: 65573f3f235301296dcf4240374c2aa90b8e9476ae4762860cd140f4b088de9ca06bb30989bdbdb61c4500e0d052664bcc43f0a4c23b9102530702e2d3fc7463

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**(please complete the following information if relevant):**
+ - OS: [e.g. MacOS 10.13.5]
+ - Gem Version [e.g. 0.1.1]
+ - Ruby Version
+ - Rails Version
+ - DBMS/Adapter
+ - Stack trace
+ - Related code and data
+
+**Additional context**
+Add any other context about the problem here.

data/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [INSERT EMAIL ADDRESS]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

data/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+Bug reports and pull requests are welcome on GitHub at https://github.com/liefni/rql. This project is intended to be a 
+safe, welcoming space for collaboration, and contributors are expected to adhere to the 
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+**Summary**
+
+**Details**
+
+**Addressed Issues**
+
+**Note**

data/README.md

@@ -1,6 +1,8 @@
-# RQL
+# RQL [![Build Status](https://secure.travis-ci.org/liefni/rql.png)](http://travis-ci.org/liefni/rql)
 
-RQL is a DSL for active record designed to allow derived/calculated attributes on models to be used in database queries.
+RQL is a DSL for ActiveRecord designed to allow derived/calculated attributes on models to be used in database queries.
+
+[Api Documentation](https://www.rubydoc.info/gems/rql/)
 
 ## Installation
 
@@ -20,7 +22,7 @@ Or install it yourself as:
 
 ## Usage
 
-You can define a derived attribute in your model like this:
+Define a derived attribute in your model:
 ```ruby
 class Book < ActiveRecord::Base
   include Rql::Queryable
@@ -31,26 +33,68 @@ class Book < ActiveRecord::Base
 end
 ```
 
-and use it in a query like this:
+then use it in a query:
 ```ruby
 Book.rql.where(leaves: 100)
 ```
 
-or
+or using the dsl
 
 ```ruby
 Book.rql.where{leaves > 100}
 ```
 
+### Aggregate Functions
+
+Aggregate functions can be used in derived attributes:
+
+```ruby
+class Author < ActiveRecord::Base
+  include Rql::Queryable
+  
+  has_many :books
+  
+  derive_attr :total_books do
+    books.count
+  end
+  
+  derive_attr :total_pages do
+    books.sum(:page)
+  end
+  
+  derive_attr :long_books do
+    books.rql.where{pages > 300}.count
+  end
+end
+```
+
+### Preloading
+
+Derived attributes can be preloaded from the database database to prevent multiple calls to the database when accessing 
+derived attributes that use associated models. To preload derived attributes:
+
+```ruby
+Authors.derive(:total_books, :total_pages)
+```
+
+If a derived attribute has not been preloaded then the code will be evaluated in the context of the model when it is
+accessed. For instance calling `Book.first.leaves` will return `pages / 2` just as a normal method would, without having
+to query the database.
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can 
+also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the 
+version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, 
+push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/liefni/rql.
+Bug reports and pull requests are welcome on GitHub at https://github.com/liefni/rql. This project is intended to be a 
+safe, welcoming space for collaboration, and contributors are expected to adhere to the 
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 

data/lib/rql/queryable.rb

@@ -5,26 +5,47 @@ module Rql
     extend ActiveSupport::Concern
 
     class_methods do
+      # Gets and RQL scope object for access to rql query methods
+      #
+      # @return [Rql::Scope::RqlScope] object wrapping the current scope
       def rql
         return Scope::RqlScope.new(all)
       end
 
-      def eval_rql(alias_derived_attr = false, &query)
-        Dsl::Base.new(self, alias_derived_attr).instance_eval(&query)
+      # Evaluates a block of code against the RQL DSL
+      #
+      # @param alias_derived_attr [Boolean] value specifying if derived attributes will be assigned an alias
+      # @param &block [Block] the code block to be converted to sql
+      # @return [Rql::Dsl::Context] object wrapping arel for the evaluated block of code
+      def eval_rql(alias_derived_attr = false, &block)
+        Dsl::Base.new(self, alias_derived_attr).instance_eval(&block)
       end
 
-      def derive_attr(name, &query)
+      # Defines a derived attribute on a model
+      #
+      # @param name [Symbol] the name of the derived attribute
+      # @param &block [Block] the code to derive the attribute
+      # @!macro [attach] derive_attr
+      #   @return [Object] the value of the derived attribute
+      def derive_attr(name, &block)
         define_method(name) do
-          attributes.has_key?(name.to_s) ? attributes[name.to_s] : instance_eval(&query)
+          attributes.has_key?(name.to_s) ? attributes[name.to_s] : instance_eval(&block)
         end
 
-        derived_attributes[name] = query
+        derived_attributes[name] = block
       end
 
+      # Preloads the specified derived attributes from the database
+      #
+      # @param *attributes [Array<Symbol>] the attributes to be preloaded
+      # @return scope including derived attributes
       def derive(*attributes)
         rql.select(self.arel_table[Arel.star], *attributes).all
       end
 
+      # Gets the derived attributes defined on the model
+      #
+      # @returns [Hash<Symbol, Proc>] hash of derived attributes indexed by name
       def derived_attributes
         @derive_attribute ||= {}
       end

data/lib/rql/scope/param_methods.rb

@@ -6,7 +6,7 @@ module Rql
       end
 
       def select(*attributes)
-        scope.select(*attributes.map{|attr| scope.derived_attributes[attr] ? scope.eval_rql(true, &scope.derived_attributes[attr]).arel : attr})
+        scope.select(*attributes.map{|attr| scope.derived_attributes[attr] ? scope.eval_rql(&scope.derived_attributes[attr]).as(attr).arel : attr})
       end
 
       def order(*attributes)

data/lib/rql/scope/rql_scope.rb

@@ -33,6 +33,10 @@ module Rql
         RqlScope.new(scope.merge(other))
       end
 
+      def arel
+        scope.arel
+      end
+
       def to_a
         scope.to_a
       end

data/lib/rql/version.rb

@@ -1,3 +1,3 @@
 module Rql
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rql
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Lief Nikkel
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-14 00:00:00.000000000 Z
+date: 2018-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -88,11 +88,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/ISSUE_TEMPLATE/bug_report.md"
+- ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
+- PULL_REQUEST_TEMPLATE.md
 - README.md
 - Rakefile
 - bin/console