know_it_all 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 85674d4642b03b912a9963a5f5d9845946c38961
-  data.tar.gz: 7d38e9a2dd38d6b68365d448d127268eef9f8f53
+  metadata.gz: f2c9d3f6e989ec8e15956f85a2734e15ce858a7b
+  data.tar.gz: 1e7194c8936f99fcecbd5c543855c69bdc5577e2
 SHA512:
-  metadata.gz: 1d6f9f57dcb2ca6e63091c35d5f2461e819696697e36f37bae808673e2928e068ac6e20763d9489cb8b435134c645e2e718f202472e90b76bc2db11e7e532175
-  data.tar.gz: 916d1060f7d361600b95a9714eb535c185d73f48212f32d562900bfc0defaa3aaf6372b0d6e183c33c7125e71cc9c3578d4b3163481d76ecfc88fced0d4da15a
+  metadata.gz: 8efd4ad6004315675decbf3038628d5178319e5895c7d0d2a7e80df15984dce504d5c315d33893b6988ced57d63fafbc65e66bba58ebe10a0caf10cb36884ac3
+  data.tar.gz: 26183fd792e49f71e69bed56a522648a5fc0854500f72823223dd127c162b314b1462a46a9f1f8f63f7114cd0858913f0e7dc05c857c09a98df7daa0ff67322a

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Change Log
+
+## [v0.1.5](https://github.com/mrodrigues/know_it_all/tree/v0.1.5) (2016-08-17)
+[Full Changelog](https://github.com/mrodrigues/know_it_all/compare/v0.1.4...v0.1.5)
+
+- Add Rails generators for installing the gem and creating policies
+- Deprecating `assert` in favor of `validate`
+
+## [v0.1.4](https://github.com/mrodrigues/know_it_all/tree/v0.1.4) (2016-07-03)
+[Full Changelog](https://github.com/mrodrigues/know_it_all/compare/v0.1.3...v0.1.4)
+
+- Add support to define error message with a block
+
+## [v0.1.3](https://github.com/mrodrigues/know_it_all/tree/v0.1.3) (2016-07-03)
+[Full Changelog](https://github.com/mrodrigues/know_it_all/compare/v0.1.2...v0.1.3)
+
+- Remove ActiveSupport dependency [\#3](https://github.com/mrodrigues/know_it_all/issues/3)
+
+## [v0.1.2](https://github.com/mrodrigues/know_it_all/tree/v0.1.2) (2016-06-30)
+[Full Changelog](https://github.com/mrodrigues/know_it_all/compare/v0.1.1...v0.1.2)
+
+- Add support to inheritance chain of `KnowItAll::Base`
+
+## [v0.1.1](https://github.com/mrodrigues/know_it_all/tree/v0.1.1) (2016-06-30)
+[Full Changelog](https://github.com/mrodrigues/know_it_all/compare/v0.1.0...v0.1.1)
+
+- Fix bug when extending `KnowItAll::Base` with more than one class
+
+## [v0.1.0](https://github.com/mrodrigues/know_it_all/tree/v0.1.0) (2016-06-29)
+
+- Initial release

data/README.md

@@ -4,6 +4,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/know_it_all.svg)](https://badge.fury.io/rb/know_it_all)
 [![Join the chat at https://gitter.im/mrodrigues/know_it_all](https://badges.gitter.im/mrodrigues/know_it_all.svg)](https://gitter.im/mrodrigues/know_it_all?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Twitter Follow](https://img.shields.io/twitter/follow/know_it_all_gem.svg?style=social&label=Follow&maxAge=2592000)](https://twitter.com/know_it_all_gem)
 
 KnowItAll is a small, object-oriented approach to authorization. It knows everything about your application!
 
@@ -18,6 +19,9 @@ Table of Contents
     * [Why?](#why)
     * [Why not just Pundit?](#why-not-just-pundit)
     * [Installation](#installation)
+      * [Generators](#generators)
+        * [Install](#install)
+        * [Policy](#policy)
     * [Usage](#usage)
       * [Creating policies](#creating-policies)
         * [Naming convention](#naming-convention)
@@ -28,6 +32,8 @@ Table of Contents
         * [Avoiding conflicts in the controller](#avoiding-conflicts-in-the-controller)
         * [Overrides](#overrides)
     * [Enforcing authorization checks](#enforcing-authorization-checks)
+    * [Get help](#get-help)
+    * [Alternatives](#alternatives)
     * [Development](#development)
     * [Contributing](#contributing)
     * [License](#license)
@@ -112,17 +118,47 @@ Or install it yourself as:
 
     $ gem install know_it_all
 
+Then include `KnowItAll` in your application controller:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include KnowItAll
+end
+```
+
+### Generators
+
+#### Install
+
+When adding the gem to your application, you can optionally run:
+
+```bash
+rails generate know_it_all:install
+```
+
+This will include the `KnowItAll` module in your application controller and create a `ApplicationPolicy`, which you can use to define some defaults for your policies.
+
+#### Policy
+
+To create a new policy, you can use the following generator:
+
+```bash
+rails generate know_it_all:policy orders index create update destroy
+```
+
+This will create, in addition to one policy file for each action (`app/policies/orders_policies/index.rb`, `app/policies/orders_policies/create.rb`, etc.), a `app/policies/stores_policy.rb` file containing both the `StoresPolicies` module declaration and a `StoresPolicies::Base` class to share common behaviors specific to that controller's policies.
+
 ## Usage
 
 There are two steps to using this gem: creating and using policies:
 
 ### Creating policies
 
-A policy is simply a class obeys some rules:
+The core of this gem, policies are regular Ruby classes that perform some validation and obey some rules:
 
 * It is initialized with the same arguments that are passed to the `authorize`, `authorize!` and `authorize?` methods in the controller;
 * It responds to a method `errors`;
-* Calling `errors` returns an object that responds to the method `empty?` and is serializable. It's usually an array, but it could easily be an `ActiveModel::Errors`.
+* Calling `errors` returns an object that responds to the method `empty?` and is serializable (so you can render it as the response to the request). It's usually an array of `String`s, but it could easily be an `ActiveModel::Errors`.
 
 Here's an example:
 
@@ -148,7 +184,7 @@ module OrdersPolicies
 end
 ```
 
-Using `ActiveModel::Validations`:
+Notice that I didn't include any module or extend from any class here. `KnowItAll` will simply infer the name of the class (based on the [Naming convention](#naming-convention)) and instantiate it, even if it's a PORO. Now, using `ActiveModel::Validations`:
 
 ```ruby
 module OrdersPolicies
@@ -189,12 +225,12 @@ If you don't want to write your own policy from the scratch, I've also provided
 ```ruby
 module OrdersPolicies
   class Create < KnowItAll::Base
-    assert :user_signed_in?, "User must be signed in" 
-    assert :address_present?, "User must have a registered address" 
-    assert :address_in_range?, "Registered address is outside the range" 
-    assert :cart_has_minimum?, "Cart must contain at least $10 in items" 
-    assert :items_available?, "Some of the items are not available" 
-    assert :store_open?, "The store is closed" 
+    validate :user_signed_in?, "User must be signed in"
+    validate :address_present?, "User must have a registered address"
+    validate :address_in_range?, "Registered address is outside the range"
+    validate :cart_has_minimum?, "Cart must contain at least $10 in items"
+    validate :items_available?, "Some of the items are not available"
+    validate :store_open?, "The store is closed"
 
     def initialize(current_user, cart, store)
       @current_user = current_user
@@ -205,7 +241,25 @@ module OrdersPolicies
 end
 ```
 
-The class method `assert` expects a `Symbol` representing the name of a predicate and a `String` containing the error message in case the predicate fails. The default `errors` method returns an array containing the messages for all the assertions that didn't pass.
+The class method `validate` expects a `Symbol` representing the name of a predicate and a `String` containing the error message in case the predicate fails. The default `errors` method returns an array containing the messages for all the validations that didn't pass.
+
+In case you need to define dynamically the error message (e.g. for internationalization), the `validate` method also accepts any object that responds to `call`, as a lambda. It'll pass the policy itself as an argument:
+
+```ruby
+module OrdersPolicies
+  class Create < KnowItAll::Base
+    attr_reader :cart
+
+    validate :cart_has_minimum?, -> (policy) {
+      I18n.t(:cart_minimum_total_error, total: policy.cart.total)
+    }
+
+    def initialize(cart)
+      @cart = cart
+    end
+  end
+end
+```
 
 ### Using policies
 
@@ -390,6 +444,14 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+## Get help
+
+Follow me on [Twitter](https://twitter.com/know_it_all_gem) or chat with me on [Gitter](https://gitter.im/mrodrigues/know_it_all)! :)
+
+## Alternatives
+
+As I said in the beginning, this project is heavily inspired by [Pundit](https://github.com/elabs/pundit), so obviously it is an excellent alternative. I've also used for several years the [CanCan](https://github.com/ryanb/cancan) gem, but it's been abandoned since then; the [CanCanCan](https://github.com/CanCanCommunity/cancancan) gem is a continuation that seems to be thriving. For more alternatives, check [The Ruby Toolbox](https://www.ruby-toolbox.com/categories/rails_authorization) page.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/generators/know_it_all/install/USAGE

@@ -0,0 +1,11 @@
+Description:
+    Installs KnowItAll in the current application
+
+Example:
+    rails generate know_it_all:install
+
+    This will create:
+        app/policies/application_policy.rb
+    
+    And add the KnowItAll module to:
+        app/controllers/application_controller.rb

data/lib/generators/know_it_all/install/install_generator.rb

@@ -0,0 +1,18 @@
+module KnowItAll
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      def add_module_to_application_controller
+        inject_into_file "app/controllers/application_controller.rb",
+          after: "class ApplicationController < ActionController::Base\n" do
+          "  include KnowItAll\n"
+        end
+      end
+
+      def create_application_policy_file
+        template "application_policy.rb", "app/policies/application_policy.rb"
+      end
+    end
+  end
+end

data/lib/generators/know_it_all/install/templates/application_policy.rb

@@ -0,0 +1,2 @@
+class ApplicationPolicy < KnowItAll::Base
+end

data/lib/generators/know_it_all/policy/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Generates a new policy
+
+Example:
+    rails generate know_it_all:policy controller_name action_name [first_validation first_message second_validation second_message...]
+
+    This will create:
+        app/policies/controller_name_policies.rb
+        app/policies/controller_name_policies/action_name.rb

data/lib/generators/know_it_all/policy/policy_generator.rb

@@ -0,0 +1,29 @@
+require 'pry'
+
+module KnowItAll
+  module Generators
+    class PolicyGenerator < ::Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      argument :controller_name, type: :string
+      argument :action_names, type: :array
+
+      def create_policy_file
+        unless File.exists?("app/policies/#{module_name}.rb")
+          template 'module.rb', "app/policies/#{module_name}.rb"
+        end
+
+        action_names.each do |action_name|
+          @action_name = action_name
+          template 'policy.rb', "app/policies/#{module_name}/#{action_name}.rb"
+        end
+      end
+
+      private
+
+        def module_name
+          "#{controller_name}_policies"
+        end
+    end
+  end
+end

data/lib/generators/know_it_all/policy/templates/module.rb

@@ -0,0 +1,4 @@
+module <%= module_name.camelize %>
+  class Base < ApplicationPolicy
+  end
+end

data/lib/generators/know_it_all/policy/templates/policy.rb

@@ -0,0 +1,4 @@
+module <%= module_name.camelize %>
+  class <%= @action_name.camelize %> < <%= module_name.camelize %>::Base
+  end
+end

data/lib/know_it_all/base.rb

@@ -12,7 +12,13 @@ module KnowItAll
       subclass.validations = validations.dup
     end
 
-    def self.assert(method_name, message)
+    # <b>DEPRECATED:</b> Please use <tt>validate</tt> instead.
+    def self.assert(*args)
+      warn "[DEPRECATION] `assert` is deprecated. Please use `validate` instead."
+      validate(*args)
+    end
+
+    def self.validate(method_name, message)
       validations[method_name] = message
     end
 

data/lib/know_it_all/version.rb

@@ -1,3 +1,3 @@
 module KnowItAll
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: know_it_all
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - mrodrigues
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-07-03 00:00:00.000000000 Z
+date: 2016-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -89,6 +89,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -97,6 +98,13 @@ files:
 - bin/console
 - bin/setup
 - know_it_all.gemspec
+- lib/generators/know_it_all/install/USAGE
+- lib/generators/know_it_all/install/install_generator.rb
+- lib/generators/know_it_all/install/templates/application_policy.rb
+- lib/generators/know_it_all/policy/USAGE
+- lib/generators/know_it_all/policy/policy_generator.rb
+- lib/generators/know_it_all/policy/templates/module.rb
+- lib/generators/know_it_all/policy/templates/policy.rb
 - lib/know_it_all.rb
 - lib/know_it_all/authorizer.rb
 - lib/know_it_all/base.rb
@@ -127,4 +135,3 @@ signing_key:
 specification_version: 4
 summary: OO authorization for APIs
 test_files: []
-has_rdoc: