user_preferences 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZDJiY2VjZTUyZTNjNmRlYmNmY2E0Yjk1ODljZWE2ZDQ3ZTQ1NGVlNg==
+  data.tar.gz: !binary |-
+    MmM4Zjk4MDMzYjA4ZGUzMDZlZGM0YTY0NjE3ODZkMzA4YWY2Yjc1YQ==
+SHA512:
+  metadata.gz: !binary |-
+    N2YyZTlmMzlkYmFiYzNjODU5ZjI4N2YyY2U0MGZlYmI4OTdlYzlhODkzOWQ2
+    YjhmNDRhYWU3ZTRkOWM4OTdiYmM0YTA3NzRkMTQyOTJlZGQ4NDBmOWFlY2Ix
+    YWExMTExMWYxNmRhOTFhNzZmZjRlM2U3ZDU2ODkyM2ZhYTJlMzk=
+  data.tar.gz: !binary |-
+    N2JkY2I0NTAyMjJjZGE5ZWFmMWQ4NGY3ODRjODA4OTFjMDEzYzdhMDA1OTk0
+    YzJlOGJlNmRlODdiODEyZTdmOTY3YWJmODQ5M2U2MDdiOWE4ZmQ2Nzg4YmZj
+    MGY2ZmNlOWJjZDczMTRjZjhiOTc4NDIzNjA3NGE4NTRlZmJkNWU=

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Andy Dust
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+# UserPreferences
+
+An ActiveRecord backed user preference library that supports:
+* Categories (currently non-optional)
+* Binary and non-binary preferences
+* Default values
+* Value validation
+* Retrieving users scoped by a particular preference
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'user_preferences'
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
+
+Run the installation script:
+
+```sh
+$ rails g user_preferences:install
+```
+
+This will copy across the migration and add an empty preference definition file in config/
+
+Finally, run the database migrations:
+
+```sh
+$ rake db:migrate
+```
+
+## Defining preferences
+
+Your preferences are defined in ``config/user_preferences.yml``. You define each of your
+preferences within a category. This example definition for a binary preference implies that users receive emails notifications by default but not newsletters:
+```yaml
+emails:
+  notifications: true
+  newsletters: false
+```
+
+You can configure non-binary preferences. For example, if users could choose periodical notification digests, the configuration might look like this:
+
+```yaml
+emails:
+  notifications:
+    default: instant
+    values:
+      - off
+      - instant
+      - daily
+      - weekly
+  newsletters: false
+```
+
+You can add as many categories as you like:
+
+```yaml
+emails:
+  notifications: true
+  newsletters: false
+
+beta_features:
+  two_factor_authentication: false
+  the_big_red_button: false
+```
+
+## API
+
+### set
+Similar to ActiveRecord, setting a preference returns true or false depending on whether or not it was successfully persisted:
+```ruby
+user.preferences(:emails).set(notifications: 'instant') # => true
+user.preferences(:emails).set(notifications: 'some_typo') # => false
+```
+
+You can set multiple preferences at once:
+```ruby
+user.preferences(:emails).set(notifications: 'instant', newsletter: true) # => true
+```
+
+### get
+A single preference:
+```ruby
+user.preferences(:emails).get(:notifications) # => 'instant'
+```
+
+### all
+All preferences for a category:
+```ruby
+user.preferences(:emails).all # => { notifications: 'instant', newsletter: true }
+```
+
+### reload
+Reload the preferences from the database; since something else might have changed the user's state.
+```ruby
+user.preferences(:emails).reload # => { notifications: 'instant', newsletter: true }
+```
+
+## Scoping users
+```ruby
+  newsletter_users = User.with_preference(:email, :newsletter, true) #=> an ActiveRecord::Relation
+```
+Note: this _will_ include users who have not overriden the default value if the value incidentally matches the default value.
+
+## Other useful stuff
+
+### Single preference definition
+* Get your preference definition (as per your .yml) as a hash: ``UserPreferences.definitions``
+* Get the definition for a single preference:
+```ruby
+  preference = UserPreferences[:emails, :notifications]
+  preference.default # => 'instant'
+  preference.binary? # => false
+  preference.permitted_values # => ['off', 'instant', 'daily', 'weekly']
+```
+* Retrieve the default preference state with ``UserPreferences.defaults``. You can also scope to a category: ``UserPreferences.defaults(:emails)``
+
+## Testing
+
+```sh
+$ rake test
+```
+
+## Contributing
+
+1. Fork it ( http://github.com/mubi/user_preferences/fork )
+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

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+desc 'Runs the specs'
+task default: :spec
+

data/lib/generators/user_preferences/install_generator.rb

@@ -0,0 +1,21 @@
+module UserPreferences
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('../templates', __FILE__)
+
+      def create_initializer_file
+        template 'user_preferences.yml', "config/user_preferences.yml"
+      end
+
+      def copy_migrations
+        migration_template 'migration.rb', "db/migrate/create_preferences.rb"
+      end
+
+      # TODO get rid of this
+      def self.next_migration_number(dir)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+    end
+  end
+end

data/lib/generators/user_preferences/templates/migration.rb

@@ -0,0 +1,19 @@
+class CreatePreferences < ActiveRecord::Migration
+  def self.up
+    create_table :preferences do |t|
+      t.integer :user_id, null: false
+      t.string  :category, null: false
+      t.string  :name, null: false
+      t.integer :value, null: false
+      t.timestamps
+    end
+
+    add_index :preferences, :user_id
+    add_index :preferences, [:user_id, :category]
+    add_index :preferences, [:category, :name, :value]
+  end
+
+  def self.down
+    drop_table :preferences
+  end
+end

data/lib/user_preferences.rb

@@ -0,0 +1,37 @@
+require 'yaml'
+require 'active_support'
+require 'active_support/core_ext/hash'
+
+module UserPreferences
+  extend ActiveSupport::Autoload
+
+  autoload :API, 'user_preferences/api'
+  autoload :Defaults
+  autoload :HasPreferences
+  autoload :Preference
+  autoload :PreferenceDefinition
+  autoload :VERSION
+
+  class << self
+    def [](category, name)
+      unless (pref = definitions[category].try(:[], name)).nil?
+        PreferenceDefinition.new(pref, category, name)
+      end
+    end
+
+    def defaults(category = nil)
+      @_defaults ||= Defaults.new(definitions)
+      @_defaults.get(category)
+    end
+
+    def yml_path
+      Rails.root.join('config', 'user_preferences.yml') if defined?(Rails)
+    end
+
+    def definitions
+      @_definitions ||= YAML.load_file(yml_path).with_indifferent_access
+    end
+  end
+end
+
+require 'user_preferences/railtie' if defined?(Rails)

data/lib/user_preferences/api.rb

@@ -0,0 +1,63 @@
+module UserPreferences
+  class API
+    def initialize(category, scope)
+      @category = category
+      @scope = scope.where(category: category)
+    end
+
+    def all
+      serialized_preferences
+    end
+
+    def get(name)
+      serialized_preferences[name]
+    end
+
+    def set(hash)
+      hash_setter do
+        hash.each do |name, value|
+          find_or_init_preference(name).update_value!(value)
+        end
+      end
+    end
+
+    def reload
+      @_saved_preferences = nil
+      all
+    end
+
+    private
+
+    def serialized_preferences
+      default_preferences.merge Hash[saved_preferences.map { |p| [p.name.to_sym, p.value] }]
+    end
+
+    def default_preferences
+      @_category_defaults ||= UserPreferences.defaults(@category)
+    end
+
+    def saved_preferences
+      @_saved_preferences ||= @scope.select([:id, :category, :name, :value, :user_id]).all
+    end
+
+    def find_or_init_preference(name)
+      unless preference = saved_preferences.detect { |p| p.name == name }
+        preference = @scope.find_by_name(name) || @scope.build(name: name, category: @category)
+        saved_preferences << preference
+      end
+      preference
+    end
+
+    def hash_setter(&block)
+      ActiveRecord::Base.transaction do
+        result = true
+        begin
+          yield
+        rescue ActiveRecord::RecordInvalid
+          result = false
+        end
+        result
+      end
+    end
+  end
+end

data/lib/user_preferences/defaults.rb

@@ -0,0 +1,23 @@
+module UserPreferences
+  class Defaults
+    def initialize(definitions)
+      @definitions = definitions
+    end
+
+    def get(category = nil)
+      if category
+        category_defaults(category)
+      else
+        @definitions.inject({}) { |h, (k,v)| h[k.to_sym] = category_defaults(k); h }
+      end
+    end
+
+    private
+
+    def category_defaults(category)
+      @definitions[category].inject({}) do |h, (k,v)|
+        h[k.to_sym] = v.is_a?(Hash) ? v['default'] : v; h
+      end
+    end
+  end
+end

data/lib/user_preferences/has_preferences.rb

@@ -0,0 +1,36 @@
+module UserPreferences
+  module HasPreferences
+    extend ActiveSupport::Concern
+
+    module ActiveRecordExtension
+      def has_preferences
+        include HasPreferences
+      end
+    end
+
+    included do
+      has_many :saved_preferences, class_name: 'UserPreferences::Preference', dependent: :destroy
+
+      def preferences(category)
+        @_preference_apis ||= {}
+        @_preference_apis[category] ||= UserPreferences::API.new(category, saved_preferences)
+      end
+
+      def self.with_preference(category, name, value)
+        definition = UserPreferences[category, name]
+        db_value = definition.to_db(value)
+        scope = select('users.*, p.id as preference_id')
+        join = %Q{
+          %s join #{UserPreferences::Preference.table_name} p
+          on p.category = '#{category}' and p.name = '#{name}'
+          and p.user_id = #{self.table_name}.id
+        }
+        if value != definition.default
+          scope.joins(join % 'inner').where("p.value = #{db_value}")
+        else
+          scope.joins(join % 'left').where("p.value = #{db_value} or p.id is null")
+        end
+      end
+    end
+  end
+end

data/lib/user_preferences/preference.rb

@@ -0,0 +1,21 @@
+class UserPreferences::Preference < ActiveRecord::Base
+  self.table_name = 'preferences'
+  belongs_to :user
+  validates_uniqueness_of :name, scope: [:user_id, :category]
+  validates_presence_of :user_id, :category, :name
+  validates :value, inclusion: { in: ->(p) { p.permitted_values }}
+
+  delegate :binary?, :default, :permitted_values, :lookup, :to_db, to: :definition
+
+  def update_value!(v)
+    update_attributes!(value: to_db(v))
+  end
+
+  def value
+    lookup(attributes['value'])
+  end
+
+  def definition
+    UserPreferences[category, name]
+  end
+end

data/lib/user_preferences/preference_definition.rb

@@ -0,0 +1,47 @@
+module UserPreferences
+  class PreferenceDefinition
+    attr_reader :name, :category
+
+    def initialize(definition, category, name)
+      @definition = definition
+      @category = category
+      @name = name
+    end
+
+    def permitted_values
+      if binary?
+        result = [false, true]
+      else
+        @definition[:values]
+      end
+    end
+
+    def binary?
+      !@definition.is_a?(Hash)
+    end
+
+    def default
+      binary? ? @definition : @definition[:default]
+    end
+
+    def lookup(index)
+      permitted_values[index] if index
+    end
+
+    def to_db(value)
+      value = to_bool(value) if binary?
+      permitted_values.index(value)
+    end
+
+    private
+
+    def to_bool(value)
+      return true if value == 1
+      return true if value == true || value =~ (/^(true|t|yes|y|1)$/i)
+
+      return false if value == 0
+      return false if value == false || value.blank? || value =~ (/^(false|f|no|n|0)$/i)
+      raise ArgumentError.new("invalid value for Boolean: \"#{value}\"")
+    end
+  end
+end

data/lib/user_preferences/railtie.rb

@@ -0,0 +1,9 @@
+module UserPreferences
+  class Railtie < ::Rails::Railtie
+    initializer 'user_preferences.has_preferences' do
+      ActiveSupport.on_load(:active_record) do
+        extend UserPreferences::HasPreferences::ActiveRecordExtension
+      end
+    end
+  end
+end

data/lib/user_preferences/version.rb

@@ -0,0 +1,3 @@
+module UserPreferences
+  VERSION = "0.0.1"
+end

data/spec/fixtures/user_preferences.yml

@@ -0,0 +1,19 @@
+hobbies:
+  outdoors: true
+  cultural: false
+
+food:
+  vegetarian: false
+  a_la_carte: true
+  courses:
+    default: 2
+    values:
+      - 1
+      - 2
+      - 3
+  wine:
+    default: red
+    values:
+      - red
+      - white
+

data/spec/migrations/001_create_users.rb

@@ -0,0 +1,11 @@
+class CreateUsers < ActiveRecord::Migration
+  def self.up
+    create_table :users do |t|
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :users
+  end
+end

data/spec/migrations/002_create_preferences.rb

@@ -0,0 +1,19 @@
+class CreatePreferences < ActiveRecord::Migration
+  def self.up
+    create_table :preferences do |t|
+      t.integer :user_id, null: false
+      t.string  :category, null: false
+      t.string  :name, null: false
+      t.integer :value, null: false
+      t.timestamps
+    end
+
+    add_index :preferences, :user_id
+    add_index :preferences, [:user_id, :category]
+    add_index :preferences, [:category, :name, :value]
+  end
+
+  def self.down
+    drop_table :preferences
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+require 'user_preferences'
+require 'active_record'
+require 'active_record/connection_adapters/sqlite3_adapter'
+
+RSpec.configure do |config|
+  $stdout = StringIO.new # silence migrations
+  ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+  ActiveRecord::Migrator.migrate(File.expand_path('../migrations', __FILE__))
+  $stdout = STDOUT
+
+  # prevent deprecation warnings
+  I18n.enforce_available_locales = true
+
+  config.before(:each) { stub_yml }
+end
+
+def stub_yml
+  fixture = File.expand_path("../fixtures/user_preferences.yml", __FILE__)
+  UserPreferences.stub(:yml_path).and_return(fixture)
+end
+
+class User < ActiveRecord::Base
+  include UserPreferences::HasPreferences
+end

data/spec/user_preferences/api_spec.rb

@@ -0,0 +1,81 @@
+require 'spec_helper'
+
+describe UserPreferences::API do
+  let(:user) { User.create! }
+  subject(:api) { UserPreferences::API.new(:food, user.saved_preferences) }
+
+  describe '#all' do
+    it 'returns preference state' do
+      expect(api.all).to eq({
+        vegetarian: false,
+        a_la_carte: true,
+        courses: 2,
+        wine: 'red'
+      })
+    end
+  end
+
+  describe '#get' do
+    it 'gets the preference value' do
+      expect(api.get(:a_la_carte)).to eq(true)
+      expect(api.get(:wine)).to eq('red')
+      expect(api.get(:courses)).to eq(2)
+    end
+  end
+
+  describe '#set' do
+    it 'persists the preference values' do
+      api.set(wine: 'white')
+      api.reload
+      expect(api.get(:wine)).to eq('white')
+    end
+
+    it 'allows setting of multiple preferences' do
+      api.set(wine: 'white', courses: 3)
+      api.reload
+      expect(api.get(:wine)).to eq('white')
+      expect(api.get(:courses)).to eq(3)
+    end
+
+    it 'returns true' do
+      expect(api.set(wine: 'white')).to eq(true)
+    end
+
+    context 'one or more of the preference values were invalid' do
+      it 'returns false' do
+        expect(api.set(wine: 'sparkling')).to eq(false)
+        expect(api.set(wine: 'white', courses: 10)).to eq(false)
+      end
+
+      it 'does not persist anything if any of the values were invalid' do
+        api.set(wine: 'sparkling', courses: 3)
+        api.reload
+        expect(api.get(:wine)).to eq('red')
+        expect(api.get(:courses)).to eq(2)
+      end
+    end
+  end
+
+  describe '#reload' do
+    before(:each) do
+      api.set(courses: 1)
+      other_thread_api = UserPreferences::API.new('food', User.last.saved_preferences)
+      other_thread_api.set(courses: 3)
+    end
+
+    it 'reloads the preference state' do
+      expect(api.get(:courses)).to eq(1)
+      api.reload
+      expect(api.get(:courses)).to eq(3)
+    end
+
+    it 'returns the preference state' do
+      expect(api.reload).to eq({
+        vegetarian: false,
+        a_la_carte: true,
+        courses: 3,
+        wine: 'red'
+      })
+    end
+  end
+end

data/spec/user_preferences/defaults_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe UserPreferences::Defaults do
+  subject(:defaults) { UserPreferences::Defaults.new(UserPreferences.definitions) }
+
+  describe '.get' do
+    it 'returns the default preference state' do
+      expect(defaults.get).to eq(
+        {
+          hobbies: {
+            outdoors: true,
+            cultural: false
+          },
+          food: {
+            vegetarian: false,
+            a_la_carte: true,
+            courses: 2,
+            wine: 'red'
+          }
+        }
+      )
+    end
+
+    context 'a category is supplied' do
+      it 'returns the default preference state for the category' do
+        expect(defaults.get(:hobbies)).to eq({
+          outdoors: true,
+          cultural: false
+        })
+      end
+    end
+  end
+end

data/spec/user_preferences/has_preferences_spec.rb

@@ -0,0 +1,44 @@
+require 'spec_helper'
+
+describe UserPreferences::HasPreferences do
+  let(:user) { User.create }
+
+  it 'should mix in preference methods' do
+    expect(user).to respond_to(:saved_preferences)
+    expect(user).to respond_to(:preferences)
+  end
+
+  describe '#preferences' do
+    it 'should return an API instance' do
+      expect(user.preferences(:food)).to be_kind_of(UserPreferences::API)
+    end
+  end
+
+  describe '.with_preference' do
+    before(:each) { User.destroy_all }
+
+    it 'only returns users with the matching preference' do
+      user_1, user_2 = 2.times.map { User.create }
+      user_1.preferences(:food).set(wine: 'white')
+      user_2.preferences(:food).set(wine: 'red')
+      expect(User.with_preference(:food, :wine, 'white')).to eq([user_1])
+
+      user_2.preferences(:food).set(wine: 'white')
+      expect(User.with_preference(:food, :wine, 'white')).to eq([user_1, user_2])
+    end
+
+    it 'returns a chainable active record relation' do
+      user.preferences(:food).set(wine: 'white')
+      expect(User.with_preference(:food, :wine, 'white')).to be_kind_of(ActiveRecord::Relation)
+      expect(User.with_preference(:food, :wine, 'white').where('1=1')).to eq([user])
+    end
+
+    context 'the desired preference matches the default value' do
+      it 'includes users who have not explicitely overriden the preference' do
+        user.preferences(:food).set(wine: 'red') # the default value
+        user_2 = User.create
+        expect(User.with_preference(:food, :wine, 'red')).to eq([user, user_2])
+      end
+    end
+  end
+end

data/spec/user_preferences/preference_definition_spec.rb

@@ -0,0 +1,90 @@
+require 'spec_helper'
+
+describe UserPreferences::PreferenceDefinition do
+  subject(:preference) do
+    definition = UserPreferences.definitions[:food][:wine]
+    UserPreferences::PreferenceDefinition.new(definition, :food, :wine)
+  end
+
+  describe '#name' do
+    it 'returns the preference name' do
+      expect(preference.name).to eq(:wine)
+    end
+  end
+
+  describe '#category' do
+    it 'returns the preference category' do
+      expect(preference.category).to eq(:food)
+    end
+  end
+
+  describe '#permitted_values' do
+    it 'returns an array of permitted values' do
+      expect(preference.permitted_values).to eq(['red', 'white'])
+    end
+  end
+
+  describe '#binary?' do
+    it 'is false' do
+      expect(preference.binary?).to eq(false)
+    end
+  end
+
+  describe '#default' do
+    it 'returns the default preference value' do
+      expect(preference.default).to eq('red')
+    end
+  end
+
+  describe '#lookup' do
+    it 'returns the value at the supplied index' do
+      expect(preference.lookup(0)).to eq('red')
+      expect(preference.lookup(1)).to eq('white')
+      expect(preference.lookup(2)).to be_nil
+    end
+  end
+
+  describe '#to_db' do
+    it 'returns the value index for the value' do
+      expect(preference.to_db('red')).to eq(0)
+      expect(preference.to_db('white')).to eq(1)
+    end
+  end
+
+  context 'the preference is binary' do
+    subject(:preference) do
+      definition = UserPreferences.definitions[:food][:vegetarian]
+      UserPreferences::PreferenceDefinition.new(definition, :food, :vegetarian)
+    end
+
+    describe '#permitted_values' do
+      it 'returns an array of booleans' do
+        expect(preference.permitted_values).to eq([false, true])
+      end
+    end
+
+    describe '#binary?' do
+      it 'is true' do
+        expect(preference.binary?).to eq(true)
+      end
+    end
+
+    describe '#default' do
+      it 'returns the default boolean' do
+        expect(preference.default).to eq(false)
+      end
+    end
+
+    describe '#to_db' do
+      it 'casts true/false strings to booleans' do
+        expect(preference.to_db('false')).to eq(0)
+        expect(preference.to_db('true')).to eq(1)
+      end
+
+      it 'casts integers to booleans' do
+        expect(preference.to_db(0)).to eq(0)
+        expect(preference.to_db(1)).to eq(1)
+      end
+    end
+  end
+end

data/spec/user_preferences/preference_spec.rb

@@ -0,0 +1,79 @@
+require 'spec_helper'
+
+describe UserPreferences::Preference do
+
+  let(:user) { User.create }
+  subject(:preference) { UserPreferences::Preference.new(category: :food, name: :wine, user: user) }
+
+  it 'must have a name' do
+    stub_definition
+    preference.name = nil
+    expect(preference.valid?).to eq(false)
+    expect(preference.errors.full_messages).to include("Name can't be blank")
+  end
+
+  it 'must have a category' do
+    stub_definition
+    preference.category = nil
+    expect(preference.valid?).to eq(false)
+    expect(preference.errors.full_messages).to include("Category can't be blank")
+  end
+
+  it 'must have a value' do
+    expect(preference.valid?).to eq(false)
+    expect(preference.errors.full_messages).to include("Value is not included in the list")
+  end
+
+  it 'must have a user' do
+    preference.user = nil
+    expect(preference.valid?).to eq(false)
+    expect(preference.errors.full_messages).to include("User can't be blank")
+  end
+
+  it 'must have a unique name, scoped within user and category' do
+    preference.update_value! 'white'
+    second_preference = UserPreferences::Preference.new(category: :food, name: :wine, user: user, value: 1)
+    expect(second_preference.valid?).to eq(false)
+    expect(second_preference.errors.full_messages).to include('Name has already been taken')
+  end
+
+  it 'must have a valid value' do
+    expect(preference.valid?).to eq(false)
+    expect(preference.errors.full_messages).to include("Value is not included in the list")
+  end
+
+  describe '#update_value' do
+    it 'persists the updated the value' do
+      preference.update_value! 'white'
+      expect(preference.reload.value).to eq('white')
+    end
+
+    context 'the validation fails' do
+      it 'raises' do
+        expect { preference.update_value! 'sparkling' }.to raise_error(ActiveRecord::RecordInvalid)
+      end
+    end
+  end
+
+  describe '#value' do
+    it 'casts the persisted value index back to its human readable form' do
+      preference.update_value!('red')
+      expect(preference.attributes['value']).to eq(0)
+      expect(preference.value).to eq('red')
+    end
+  end
+
+  describe '#definition' do
+    it 'returns the preference definition' do
+      expect(preference.definition).to be_kind_of(UserPreferences::PreferenceDefinition)
+    end
+  end
+
+  private
+
+  def stub_definition
+    preference.stub(:attributes).and_return({'value' => 1})
+    preference.stub(:value).and_return('white')
+    preference.stub(:permitted_values).and_return(['white'])
+  end
+end

data/spec/user_preferences_spec.rb

@@ -0,0 +1,44 @@
+require 'spec_helper'
+require 'yaml'
+
+describe UserPreferences do
+  it 'should be valid' do
+    expect(UserPreferences).to be_a(Module)
+  end
+
+  describe '.[]' do
+    it 'returns a preference definition instance for supplied category and name' do
+      result = UserPreferences[:food, :wine]
+      expect(result).to be_kind_of(UserPreferences::PreferenceDefinition)
+      expect(result.category).to eq(:food)
+      expect(result.name).to eq(:wine)
+      expect(result.default).to eq('red')
+    end
+
+    context "the category doesn't exist" do
+      it 'returns nil' do
+        expect(UserPreferences[:fashion, :hats]).to be_nil
+      end
+    end
+
+    context "the name doesn't exist" do
+      it 'returns nil' do
+        expect(UserPreferences[:food, :dressing]).to be_nil
+      end
+    end
+  end
+
+  describe '.defaults' do
+    it 'returns the defaults from definitions' do
+      expect_any_instance_of(UserPreferences::Defaults).to receive(:get)
+      UserPreferences.defaults(:food)
+    end
+  end
+
+  describe '.definitions' do
+    it 'returns the loaded preference yml' do
+      file = File.expand_path("../fixtures/user_preferences.yml", __FILE__)
+      expect(UserPreferences.definitions).to eq(YAML.load_file(file).with_indifferent_access)
+    end
+  end
+end

data/user_preferences.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'user_preferences/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "user_preferences"
+  spec.version       = UserPreferences::VERSION
+  spec.authors       = ["Andy Dust"]
+  spec.email         = ["adust@mubi.com"]
+  spec.summary       = "User preferences gem for Rails."
+  spec.description   = %Q{user_preference is a small library for setting and getting categorized user preferences.
+                      Supports both binary and multivalue preferences and default values. }
+  spec.homepage      = "http://github.com/mubi/user_preferences"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'activerecord', '>= 3.0'
+  spec.add_dependency 'activesupport', '>= 3.0'
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency 'rspec', '~> 2.14'
+  spec.add_development_dependency 'sqlite3', '~> 1.3'
+end

metadata

@@ -0,0 +1,167 @@
+--- !ruby/object:Gem::Specification
+name: user_preferences
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Andy Dust
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+description: ! "user_preference is a small library for setting and getting categorized
+  user preferences.\n                      Supports both binary and multivalue preferences
+  and default values. "
+email:
+- adust@mubi.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/user_preferences/install_generator.rb
+- lib/generators/user_preferences/templates/migration.rb
+- lib/generators/user_preferences/templates/user_preferences.yml
+- lib/user_preferences.rb
+- lib/user_preferences/api.rb
+- lib/user_preferences/defaults.rb
+- lib/user_preferences/has_preferences.rb
+- lib/user_preferences/preference.rb
+- lib/user_preferences/preference_definition.rb
+- lib/user_preferences/railtie.rb
+- lib/user_preferences/version.rb
+- spec/fixtures/user_preferences.yml
+- spec/migrations/001_create_users.rb
+- spec/migrations/002_create_preferences.rb
+- spec/spec_helper.rb
+- spec/user_preferences/api_spec.rb
+- spec/user_preferences/defaults_spec.rb
+- spec/user_preferences/has_preferences_spec.rb
+- spec/user_preferences/preference_definition_spec.rb
+- spec/user_preferences/preference_spec.rb
+- spec/user_preferences_spec.rb
+- user_preferences.gemspec
+homepage: http://github.com/mubi/user_preferences
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: User preferences gem for Rails.
+test_files:
+- spec/fixtures/user_preferences.yml
+- spec/migrations/001_create_users.rb
+- spec/migrations/002_create_preferences.rb
+- spec/spec_helper.rb
+- spec/user_preferences/api_spec.rb
+- spec/user_preferences/defaults_spec.rb
+- spec/user_preferences/has_preferences_spec.rb
+- spec/user_preferences/preference_definition_spec.rb
+- spec/user_preferences/preference_spec.rb
+- spec/user_preferences_spec.rb