arcane 0.0.3 → 0.1.0

data/.travis.yml

@@ -7,7 +7,6 @@ rvm:
   - rbx-19mode
 
 env:
-  - "strong_parameters=0.2.0"
   - "strong_parameters=0.2.1"
   - "activesupport=3.2.13"
   - "activesupport=4.0.0"

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+### Arcane **0.1.0** [head] – 2013-07-11
+* **[bugfix]** Arcane should no longer error when there is
+  no current_user present.
+* **[feature]** Added new query syntax for the `refine`
+  helper. It now supports custom params and/or refinery
+  keys to be sent as arguments.
+
+### Arcane **0.0.3** [current] – 2013-07-11
+* Initial Release

data/README.md

@@ -10,6 +10,114 @@ design patterns to organise and easily harnass the power of strong parameters in
 Arcane magic is real and reliable, no cheap tricks.
 Inspired by [Pundit](https://github.com/elabs/pundit)
 
+## Usage
+
+First of all, include `Arcane` in your controller. This will give you access to the `refine` helper.
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  include Arcane
+end
+```
+
+Before you can use the `refine` helper, you need a Refinery for the model you want to pass parameters to.
+Simply create the directory `/app/refineries` in your Rails project. Create a Refinery your model, in this
+case Article. `/app/refineries/article_refinery.rb`. Create a class in that file called `ArticleRefinery`.
+
+Methods defined in the refinery should reflect the controller method for clarity, but can be anything you
+want it to be. These methods must return an array containing the same parameters you would otherwise send
+to strong parameters.
+
+```ruby
+# app/refineries/article_refinery.rb
+class ArticleRefinery < Arcane::Refinery
+  def create
+    [:title] + update
+  end
+  def update
+    [:content]
+  end
+end
+```
+
+Next up, using the `refine` helper. The helper can be called from anywhere in your controller and views
+and accepts one parameter, the object for which you want to *refine* the parameters, then followed by
+calling the method for what parameters you want.
+
+```ruby
+refined_params = refine @article, :create
+```
+
+In context of the controller method it might look something like this:
+
+```ruby
+class ArticlesController < ApplicationController
+
+  def create
+    @article = Article.new(refine(Article,:create))
+    @article.save
+  end
+
+  def update
+    @article = Article.find(params[:id])
+    @article.update_attributes(refine(@article,:update))
+  end
+
+end
+
+```
+
+## Features
+
+### Custom Parameters
+Arcane isn't all magic (though mostly). You can pass your own parameters to the `refine` method, without
+having to worry which order you put them in as long as the permit object is the first one.
+
+```ruby
+  my_params = { article: { title: "Hello" } }
+  refine(@article,my_params,:create)
+  refine(@article,:update,my_params)
+```
+
+### Default Parameters
+You are able to specify a `default` method in your refinery which will be prioritized if no the method
+you call does not exist. **While you should probably never put yourself in this situation**, the feature
+is available for those edge case scenarios where you need it.
+
+```ruby
+class AmbiguityRefinery < Arcane::Refinery
+  def default
+    [:data]
+  end
+end
+```
+
+### Root Requirement
+You are able to disable or change the root requirement. Let's say you have a sessions endpoint where
+you don't have your username and password parameters wrapped in a root. Now you can use the root class
+method and set it to nil or false and it will automatically not require it.
+
+```ruby
+class SessionRefinery < Arcane::Refinery
+  def self.root
+    false
+  end
+end
+```
+
+Or if you have a `MeRefinery` for allowing certain parameters on a `/me.json` which is still a user
+object. You can just set a root class method on your refinery and it will use this to determine if
+the requirements.
+
+```ruby
+class MeRefinery < UserRefinery
+  def self.root
+    :user
+  end
+end
+```
+
 ## Requirements
 
 Currently this gem is only supported for Rails and with any of these ruby versions:
@@ -34,13 +142,13 @@ And then execute:
 $ bundle
 ```
 
-## Features
-
 ## To-do
 
-* Write rails generators
-* List features
-* Add Documentation
+- [ ] Write rails generators
+- [x] List features
+- [x] Add Documentation
+- [ ] Add documentation for HATEOAS
+- [ ] Automatic method detection
 
 ## Contributing
 

data/lib/arcane.rb

@@ -22,7 +22,27 @@ module Arcane
   end
 
   def refine(object,*args)
-    Arcane::Chain.new(params,object,current_user)
+
+    current_user = nil unless respond_to?(:current_user)
+
+    opts = { }
+
+    args.each do |arg|
+      if [String,Symbol].any? { |c| arg.kind_of?(c) }
+        opts[:method] ||= arg
+      elsif [Hash,HashWithIndifferentAccess,ActionController::Parameters].any? { |c| arg.kind_of?(c) }
+        opts[:params] ||= arg
+      elsif current_user.nil?
+        opts[:user]   ||= arg
+      end
+    end
+
+    opts[:params] ||= params
+    opts[:user]   ||= current_user
+    opts[:object] ||= object.respond_to?(:new) ? object.new : object
+
+    chain = Arcane::Chain.new(opts[:params],opts[:object],opts[:user])
+    return opts[:method].present? ? chain.send(opts[:method]) : chain
   end
 
 end

data/lib/arcane/version.rb

@@ -1,3 +1,3 @@
 module Arcane
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/spec/arcane_spec.rb

@@ -19,11 +19,20 @@ describe Arcane do
       }
     })
   end
+  let(:custom_params) do
+    HashWithIndifferentAccess.new({
+      article: {
+        tags: ["test","greeting"]
+      }
+    })
+  end
 
   describe '#refine' do
 
     it { controller.refine(article).should be_a Arcane::Chain }
+    it { controller.refine(article,:update).should be_a ActionController::Parameters }
     it { controller.refine(article).update.should be_a ActionController::Parameters }
+    it { controller.refine(Article)._object.should be_a Article }
 
     it 'filters parameters correctly' do
       controller.refine(article).update.should eq expected_params(:title,:content)
@@ -37,6 +46,11 @@ describe Arcane do
       controller.refine(article).publish.should eq expected_params(:title,:content,:tags)
     end
 
+    it 'filters custom parameters correctly' do
+      controller.refine(article,custom_params,:publish).should eq expected_params(:tags)
+      controller.refine(article,:publish,custom_params).should eq expected_params(:tags)
+    end
+
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: arcane
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -118,6 +118,7 @@ files:
 - .gitignore
 - .rspec
 - .travis.yml
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -147,7 +148,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3121159589769937332
+      hash: 2536535515859705955
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -156,7 +157,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 3121159589769937332
+      hash: 2536535515859705955
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25