flippeur 0.0.1 → 1.0.0

data/Gemfile

@@ -1,4 +1,2 @@
 source 'https://rubygems.org'
-
-# Specify your gem's dependencies in flippeur.gemspec
 gemspec

data/README.md

@@ -1,6 +1,10 @@
 # Flippeur
 
-TODO: Write a gem description
+Flippeur is a simple feature flipper.  Features are setup with a simple Ruby DSL where you specify whether a feature is available to a user.
+
+If you're using Rails you can pop your feature definition file in an initializer.
+
+Features are not stored in a database and there's no web UI for toggling them.
 
 ## Installation
 
@@ -18,12 +22,103 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+The basic idea is that a feature is, or isn't, available to a user of your webapp.  So the logic determining whether or not a feature is available acts on a user.
+
+In the view and the controller layers, the user is obtained automatically by calling the controller's `current_person` method (currently and regrettably hardcoded).  In the model layer you need to pass an appropriate user instance explicitly.
+
+(This is suboptimal and I'm exploring alternatives.)
+
+First, setup your features.  With Rails this would go in `config/initializers/flippeur.rb`.
+
+```ruby
+Flippeur.setup do
+
+  feature :something_fancy do |user|
+    user.is_fancy?
+  end
+
+  feature :something_else do |user|
+    user.name =~ /bob/i
+  end
+
+end
+```
+
+Give each feature a name and a block.  The block should return a truthy value if the feature is available to the user, and a falsey value otherwise.
+
+N.B. to return early from the block, use `next retvalue` instead of `return retvalue`.  For example:
+
+```ruby
+feature :add_widget do |user|
+  next false unless user.company.pays_lots_of_money?
+  user.admin? || user.my_friend?
+end
+```
+
+Second, use the helpers to determine whether or not features are available to your current user.
+
+### View
+
+Use the `feature?(name)` helper with or without a block.
+
+Without a block it acts as a simple conditional.  For example:
+
+```erb
+<% if feature? :something_fancy %>
+  <p>Here is something fancy.</p>
+<% else %>
+  <p>You could have something fancy if you upgraded...</p>
+<% end %>
+```
+
+If you pass a block it will only be called if the feature is available.  For example:
+
+```erb
+<% feature? :something_fancy do %>
+  <p>Here is something fancy.</p>
+<% end %>
+```
+
+### Controller
+
+Exactly the same as the view.  For example:
+
+```ruby
+def create
+  if feature? :something_fancy
+    # the usual stuff
+  else
+    redirect_to :index, notice: 'You need to upgrade to create something fancy.'
+  end
+end
+```
+
+### Model
+
+Here you also need to pass a user instance to the helper.  For example:
+
+```ruby
+class Project < ActiveRecord::Base
+  belongs_to :account
+  def do_something_fancy
+    if feature? :something_fancy, account.users.first
+      # something fancy
+    end
+  end
+end
+```
+
+This is suboptimal and should be revisited...
+
+
+## See Also
+
+* [Flipper](https://github.com/jnunemaker/flipper)
+* [Flip](https://github.com/pda/flip)
+* [Rollout](https://github.com/jamesgolick/rollout)
+
+
+## Intellectual Property
 
-## Contributing
+Copyright Andy Stewart, AirBlade Software.  Released under the MIT licence.
 
-1. Fork it
-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 new Pull Request

data/Rakefile

@@ -1 +1,8 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose  = true
+end

data/flippeur.gemspec

@@ -10,10 +10,12 @@ Gem::Specification.new do |gem|
   gem.email         = ["boss@airbladesoftware.com"]
   gem.description   = %q{Simple feature flipping.}
   gem.summary       = %q{Simple feature flipping.}
-  gem.homepage      = ""
+  gem.homepage      = "https://github.com/airblade/flippeur"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
+
+  gem.add_development_dependency 'rake', '~> 10.0.0'
 end

data/lib/flippeur/feature.rb

@@ -0,0 +1,14 @@
+module Flippeur
+  class Feature
+    attr_reader :name, :block
+
+    def initialize(name, &block)
+      @name = name
+      @block = block
+    end
+
+    def available?(user)
+      block.call user
+    end
+  end
+end

data/lib/flippeur/rails_helpers.rb

@@ -0,0 +1,24 @@
+module Flippeur
+
+  module ViewHelpers
+    def feature?(name)
+      available = Flippeur.find(name).available? @controller.current_person
+      block_given? ? (yield if available) : available
+    end
+  end
+
+  module ControllerHelpers
+    def feature?(name)
+      available = Flippeur.find(name).available? current_person
+      block_given? ? (yield if available) : available
+    end
+  end
+
+  module ModelHelpers
+    def feature?(name, person)
+      available = Flippeur.find(name).available? person
+      block_given? ? (yield if available) : available
+    end
+  end
+
+end

data/lib/flippeur/railtie.rb

@@ -0,0 +1,11 @@
+require 'flippeur/rails_helpers'
+
+module Flippeur
+  class Railtie < Rails::Railtie
+    initializer 'flippeur.rails_helpers' do
+      ActionView::Base.send       :include, Flippeur::ViewHelpers
+      ActionController::Base.send :include, Flippeur::ControllerHelpers
+      ActiveRecord::Base.send     :include, Flippeur::ModelHelpers
+    end
+  end
+end

data/lib/flippeur/version.rb

@@ -1,3 +1,3 @@
 module Flippeur
-  VERSION = "0.0.1"
+  VERSION = "1.0.0"
 end

data/lib/flippeur.rb

@@ -1,5 +1,32 @@
+require 'flippeur/railtie' if defined?(Rails)
+require 'flippeur/feature'
 require "flippeur/version"
 
 module Flippeur
-  # Your code goes here...
+
+  UnknownFeature = Class.new RuntimeError
+
+  def self.setup(&block)
+    reset
+    module_eval &block
+  end
+
+  def self.feature(name, &block)
+    features[name] = Feature.new(name, &block)
+  end
+
+  def self.find(name)
+    features[name]
+  end
+
+  private
+
+  def self.features
+    @features ||= Hash.new { |_,k| raise UnknownFeature, "Unknown feature: #{k}" }
+  end
+
+  def self.reset
+    @features = nil
+  end
+  
 end

data/test/controller_helpers_test.rb

@@ -0,0 +1,63 @@
+require 'minitest/autorun'
+require 'flippeur'
+require 'flippeur/rails_helpers'
+
+
+class Controller
+  include Flippeur::ControllerHelpers
+  def current_person
+    Object.new
+  end
+end
+
+
+class ControllerHelpersTest < MiniTest::Unit::TestCase
+
+  def setup
+    @controller = Controller.new
+  end
+
+  def test_unknown_feature_raises_exception
+    Flippeur.setup { }
+    assert_raises Flippeur::UnknownFeature do
+      @controller.feature? :foo
+    end
+  end
+
+  def test_available_feature_as_boolean
+    Flippeur.setup do
+      feature(:foo) { |user| true }
+    end
+    assert @controller.feature?(:foo)
+  end
+
+  def test_available_feature_with_block
+    Flippeur.setup do
+      feature(:foo) { |user| true }
+    end
+    block_called = false
+    @controller.feature?(:foo) do
+      block_called = true
+    end
+    assert block_called
+  end
+
+  def test_unavailable_feature_as_boolean
+    Flippeur.setup do
+      feature(:foo) { |user| false }
+    end
+    refute @controller.feature?(:foo)
+  end
+
+  def test_unavailable_feature_with_block
+    Flippeur.setup do
+      feature(:foo) { |user| false }
+    end
+    block_called = false
+    @controller.feature?(:foo) do
+      block_called = true
+    end
+    refute block_called
+  end
+
+end

data/test/feature_test.rb

@@ -0,0 +1,34 @@
+require 'minitest/autorun'
+require 'flippeur'
+
+class FeatureTest < MiniTest::Unit::TestCase
+
+  def test_unknown_features_raises_exception
+    Flippeur.setup { }
+    assert_raises Flippeur::UnknownFeature do
+      Flippeur.find :foo
+    end
+  end
+
+  def test_finds_known_feature
+    Flippeur.setup do
+      feature(:foo) { }
+    end
+    assert_instance_of Flippeur::Feature, Flippeur.find(:foo)
+  end
+
+  def test_available_feature
+    Flippeur.setup do
+      feature(:foo) { |user| user.id == 42 }
+    end
+    assert Flippeur.find(:foo).available?( OpenStruct.new(id: 42) )
+  end
+
+  def test_unavailable_feature
+    Flippeur.setup do
+      feature(:foo) { |user| user.id == 42 }
+    end
+    refute Flippeur.find(:foo).available?( OpenStruct.new(id: 153) )
+  end
+
+end

data/test/model_helpers_test.rb

@@ -0,0 +1,60 @@
+require 'minitest/autorun'
+require 'flippeur'
+require 'flippeur/rails_helpers'
+
+
+class Model
+  include Flippeur::ModelHelpers
+end
+
+
+class ModelHelpersTest < MiniTest::Unit::TestCase
+
+  def setup
+    @model = Model.new
+  end
+
+  def test_unknown_feature_raises_exception
+    Flippeur.setup { }
+    assert_raises Flippeur::UnknownFeature do
+      @model.feature? :foo, Object.new
+    end
+  end
+
+  def test_available_feature_as_boolean
+    Flippeur.setup do
+      feature(:foo) { |user| true }
+    end
+    assert @model.feature?(:foo, Object.new)
+  end
+
+  def test_available_feature_with_block
+    Flippeur.setup do
+      feature(:foo) { |user| true }
+    end
+    block_called = false
+    @model.feature?(:foo, Object.new) do
+      block_called = true
+    end
+    assert block_called
+  end
+
+  def test_unavailable_feature_as_boolean
+    Flippeur.setup do
+      feature(:foo) { |user| false }
+    end
+    refute @model.feature?(:foo, Object.new)
+  end
+
+  def test_unavailable_feature_with_block
+    Flippeur.setup do
+      feature(:foo) { |user| false }
+    end
+    block_called = false
+    @model.feature?(:foo, Object.new) do
+      block_called = true
+    end
+    refute block_called
+  end
+
+end

data/test/view_helpers_test.rb

@@ -0,0 +1,63 @@
+require 'minitest/autorun'
+require 'flippeur'
+require 'flippeur/rails_helpers'
+
+
+class View
+  include Flippeur::ViewHelpers
+  def initialize
+    @controller = OpenStruct.new(current_person: Object.new)
+  end
+end
+
+
+class ViewHelpersTest < MiniTest::Unit::TestCase
+
+  def setup
+    @view = View.new
+  end
+
+  def test_unknown_feature_raises_exception
+    Flippeur.setup { }
+    assert_raises Flippeur::UnknownFeature do
+      @view.feature? :foo
+    end
+  end
+
+  def test_available_feature_as_boolean
+    Flippeur.setup do
+      feature(:foo) { |user| true }
+    end
+    assert @view.feature?(:foo)
+  end
+
+  def test_available_feature_with_block
+    Flippeur.setup do
+      feature(:foo) { |user| true }
+    end
+    block_called = false
+    @view.feature?(:foo) do
+      block_called = true
+    end
+    assert block_called
+  end
+
+  def test_unavailable_feature_as_boolean
+    Flippeur.setup do
+      feature(:foo) { |user| false }
+    end
+    refute @view.feature?(:foo)
+  end
+
+  def test_unavailable_feature_with_block
+    Flippeur.setup do
+      feature(:foo) { |user| false }
+    end
+    block_called = false
+    @view.feature?(:foo) do
+      block_called = true
+    end
+    refute block_called
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flippeur
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-20 00:00:00.000000000 Z
-dependencies: []
+date: 2013-05-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 10.0.0
 description: Simple feature flipping.
 email:
 - boss@airbladesoftware.com
@@ -25,8 +41,15 @@ files:
 - Rakefile
 - flippeur.gemspec
 - lib/flippeur.rb
+- lib/flippeur/feature.rb
+- lib/flippeur/rails_helpers.rb
+- lib/flippeur/railtie.rb
 - lib/flippeur/version.rb
-homepage: ''
+- test/controller_helpers_test.rb
+- test/feature_test.rb
+- test/model_helpers_test.rb
+- test/view_helpers_test.rb
+homepage: https://github.com/airblade/flippeur
 licenses: []
 post_install_message: 
 rdoc_options: []
@@ -38,16 +61,26 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1803748012281727158
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1803748012281727158
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Simple feature flipping.
-test_files: []
+test_files:
+- test/controller_helpers_test.rb
+- test/feature_test.rb
+- test/model_helpers_test.rb
+- test/view_helpers_test.rb