kvc 0.0.1

data/History.txt

@@ -0,0 +1,5 @@
+=== 0.0.1 / 2009-04-01
+
+* 1 major enhancement
+
+  * Birthday!

data/Manifest.txt

@@ -0,0 +1,10 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+app/models/kvc/settings.rb
+lib/kvc.rb
+lib/kvc/settings_proxy.rb
+tasks/kvc_tasks.rake
+test/kvc_test.rb
+uninstall.rb

data/README.txt

@@ -0,0 +1,117 @@
+= KVC
+
+http://github.com/stephencelis/kvc
+
+
+== DESCRIPTION
+
+KVC (Key-Value Configuration) provides a powerful, transparent way to maintain
+mutable app settings in the database.
+
+
+== FEATURES/PROBLEMS
+
+* Transparent: no generators or migrations to run.
+* Powerful: quick access; automatic updates; scales quickly.
+
+For more rigidity/safety: http://github.com/stephencelis/acts_as_singleton
+
+
+== SYNOPSIS
+
+Need a mutable setting in the database? Just add it, KVC-style:
+
+  KVC.key = "value"
+
+
+You're set.
+
+Any value will do:
+
+  KVC.last_import = Time.zone.now
+
+
+However you do:
+
+  KVC.site_messages.unshift("Downtime expected at 0800.").pop
+
+
+Store related settings together in a hash to reduce queries:
+
+  KVC.homepage_settings = { ... }.with_indifferent_access
+  KVC.homepage_settings # => { ... }
+
+
+If need be, validate specific key values in an initializer:
+
+  # config/initializers/kvc_config.rb
+  KVC::Settings.config do
+    validates("password") { |value| value =~ /\d+/ }
+  end
+
+
+== REQUIREMENTS
+
+* Rails 2.3.2 or greater.
+
+
+== INSTALL
+
+=== As a gem
+
+Install:
+
+  % gem install stephencelis-kvc --source=http://gems.github.com
+
+
+And configure:
+
+  config.gem "stephencelis-kvc",
+    :lib => "kvc",
+    :source => "http://gems.github.com"
+
+
+=== As a plugin
+
+Install:
+
+  % script/plugin install git://github.com/stephencelis/kvc.git
+
+
+Or submodule:
+
+  % git submodule add git://github.com/stephencelis/kvc.git vendor/plugins/kvc
+
+
+=== Anything else?
+
+Just restart your server, and you should be good to go. The key-value table
+will migrate transparently when the model first loads.
+
+If you uninstall the plugin, you will be prompted to drop the table (to drop
+the table at any time, execute the "kvc:drop_table" Rake task).
+
+
+== LICENSE
+
+(The MIT License)
+
+(c) 2009-* Stephen Celis, stephen@stephencelis.com.
+
+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/Rakefile

@@ -0,0 +1,34 @@
+$: << File.dirname(__FILE__) + "/lib"
+require "rubygems"
+require "hoe"
+require "active_record"
+require "kvc"
+
+Hoe.new("kvc", KVC::VERSION) do |p|
+  p.developer("Stephen Celis", "stephen@stephencelis.com")
+  p.remote_rdoc_dir = ''
+end
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the KVC plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the kvc plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'KVC'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/app/models/kvc/settings.rb

@@ -0,0 +1,76 @@
+# KVC::Settings is a model rarely accessed like other Active Record models.
+# You can still fetch records from the database as in other models, but you
+# will more likely read and write records through the KVC namespace directly:
+#
+#   KVC.key = "value"
+#   # Creates #<KVC::Settings id: 1, key: "key", value: "---\n\"value\"">
+#   # Values are serialized to accommodate complex object storage.
+#
+#   KVC.key # => "value"
+#   # Fetches #<KVC::Settings id: 1, key: "key", value: "---\n\"value\"">
+class KVC::Settings < ActiveRecord::Base
+  # Do not raise exceptions on keys that don't exist.
+  @@strict_keys = false
+  cattr_accessor :strict_keys
+
+  @@validations = HashWithIndifferentAccess.new []
+  cattr_reader :validations
+  class << self
+    alias strict_keys? strict_keys
+
+    # Config takes a block for configuration. For now, this provides
+    # rudimentary validation. E.g.:
+    #
+    #   KVC::Settings.config do
+    #     validates("username") { |value| value.is_a? String }
+    #     validates("username") { |value| (2..16).include? value.to_s.length }
+    #   end
+    def config(&block)
+      Object.new.instance_eval do
+        def validates(*args, &proc)
+          @@validations[args] << proc
+        end
+        self
+      end.instance_eval(&block)
+    end
+  end
+
+  # Active Record does not automatically namespace tables.
+  set_table_name :kvc_settings
+
+  # Validate in case the unique index isn't enough.
+  validates_uniqueness_of :key
+
+  # Deserializes value from database.
+  def value
+    @value ||= YAML.load(read_attribute(:value))
+  end
+
+  # Serializes value for database.
+  def value=(input)
+    returning @value = input do
+      write_attribute :value, input.to_yaml
+    end
+  end
+
+  private
+
+  def validate
+    unless @@validations[key].map { |validation| validation.call(value) }.all?
+      errors.add_to_base "#{key} cannot be set to #{value}"
+    end
+  end
+
+  if !table_exists?
+    ActiveRecord::Schema.define do
+      create_table :kvc_settings do |t|
+        t.string :key
+        t.text :value
+
+        t.timestamps
+      end
+
+      add_index :kvc_settings, :key, :unique => true
+    end
+  end
+end

data/lib/kvc.rb

@@ -0,0 +1,65 @@
+# KVC (Key-Value Configuration) provides a powerful, transparent way to
+# maintain mutable app settings in the database.
+#
+#   KVC.key = "value" # Saves key-value pairing to a database record.
+#   KVC.key           # Retrieves the record and returns the "value".
+#
+# Use the index syntax to avoid conflicts with Module methods:
+#
+#   KVC.name = "Ruby Inside"
+#   KVC.name    # => "KVC" (Whoops.)
+#   KVC["name"] # => "Ruby Inside"
+#
+# Or set boolean methods (values are serialized, so booleans are fair game):
+#
+#   KVC["display_warning?"] = true
+#   KVC.display_warning? # => true
+#
+# Or get creative:
+#
+#   KVC["Chad's expensive guitar"] = Fender::Stratocaster.new(1957)
+# 
+# By default, nonexistent keys return +nil+ values, but you can be stricter if
+# you want to avoid typo-based bugs:
+#
+#   KVC.a_typo_could_occur?            # => nil
+#   KVC::Settings.strict_keys = true   #
+#   KVC.a_typo_could_occur?            # Raises NoMethodError.
+#
+# If you really need validations, define them in an initializer. E.g.:
+#
+#   # config/initializers/kvc_config.rb
+#   KVC::Settings.config do
+#     validates("password") { |value| value =~ /\d+/ }
+#   end
+#
+# Failed validations will raise <tt>ActiveRecord::RecordInvalid</tt>.
+module KVC
+  VERSION = "0.0.1"
+
+  class << self
+    private
+
+    # Handles the key-value magic.
+    def method_missing(method, *args, &block)
+      key = method.to_s
+      key.sub!(/^\[\](=?)$/) { "#{args.shift}#{$1}" }
+    
+      if key.sub!(/=$/) {} # Is it a writer method?
+        returning args.shift do |value|
+          setting = KVC::Settings.find_or_initialize_by_key(key)
+          setting.update_attributes!(:value => value)
+        end
+      elsif setting = KVC::Settings.find_by_key(key) # Is it a reader?
+        if args.present?
+          error_message = "wrong number of arguments (#{args.length} for 0)"
+          raise ArgumentError, error_message
+        end
+    
+        KVC::SettingsProxy.new(setting)
+      elsif args.present? || KVC::Settings.strict_keys?
+        raise NoMethodError
+      end
+    end
+  end
+end

data/lib/kvc/settings_proxy.rb

@@ -0,0 +1,27 @@
+# The KVC::SettingsProxy proxies to a KVC::Settings object's value. The proxy
+# ensures that when a value is modified, the Settings object is immediately
+# updated in the database.
+#
+# These proxies also provide access to the Settings object's timestamp
+# attributes.
+class KVC::SettingsProxy
+  undef_method *instance_methods.grep(/^(?!__|nil\?|send)/)
+
+  def initialize(setting)
+    @setting = setting
+  end
+
+  private
+
+  def method_missing(method, *args, &block)
+    return @setting.send(method) if [:created_at, :updated_at].include? method
+
+    return_value = @setting.value.send(method, *args, &block)
+    if @setting.value != YAML.load(@setting.read_attribute(:value))
+      @setting.update_attribute :value, @setting.value
+      return self # Allow for chaining.
+    end
+
+    return_value
+  end
+end

data/tasks/kvc_tasks.rake

@@ -0,0 +1,8 @@
+namespace :kvc do
+  desc "Drop the KVC::Settings table"
+  task :drop_table do
+    if KVC::Settings.table_exists?
+      ActiveRecord::Base.connection.drop_table :kvc_settings
+    end
+  end
+end

data/test/kvc_test.rb

@@ -0,0 +1,130 @@
+require 'test/unit'
+require 'rubygems'
+require 'active_record'
+require 'active_support'
+require 'active_support/test_case'
+
+$: << File.expand_path(File.dirname(__FILE__) + "/../lib") <<
+      File.expand_path(File.dirname(__FILE__) + "/../app/models")
+
+ActiveRecord::Base.establish_connection :adapter => 'sqlite3',
+                                        :dbfile => ':memory:'
+
+require "kvc"
+require "kvc/settings"
+require "kvc/settings_proxy"
+
+logger = Logger.new(STDOUT)
+
+class KVCTest < ActiveSupport::TestCase
+  teardown do
+    KVC::Settings.destroy_all
+  end
+
+  test "KVC::Settings table should exist" do
+    assert KVC::Settings.table_exists?
+  end
+
+  test "method_missing should re-raise if there are arguments" do
+    assert_raise NoMethodError do
+      KVC.this_should("not_work")
+    end
+  end
+
+  test "fake attributes should return nil if we're not being strict" do
+    assert_nil KVC.nonexistent_key
+  end
+
+  test "fake attributes should raise exception if we're being strict" do
+    begin
+      assert_equal false, KVC::Settings.strict_keys? # Avoid nil-check.
+      KVC::Settings.strict_keys = true
+      assert KVC::Settings.strict_keys?
+      assert_raise(NoMethodError) { KVC.nonexistent_key }
+    ensure
+      KVC::Settings.strict_keys = false
+    end
+  end
+
+  test "can set attributes" do
+    assert_difference "KVC::Settings.count" do
+      assert_nil KVC.favorite_food
+      assert_equal "popsicles", KVC.favorite_food = "popsicles"
+      assert_equal "popsicles", KVC.favorite_food
+    end
+  end
+
+  test "attributes should update if the changed" do
+    KVC.mutable_array = []
+    KVC.mutable_array << 1
+    assert_equal [1], KVC::Settings.find_by_key("mutable_array").value
+
+    KVC.mutable_string = ""
+    KVC.mutable_string << "change"
+    assert_equal "change", KVC::Settings.find_by_key("mutable_string").value
+    KVC.mutable_string.sub!(/ch/) { "r" }
+    assert_equal "range", KVC::Settings.find_by_key("mutable_string").value
+  end
+
+  test "attribute changes should chain" do
+    KVC.mutable_array = [1, 2, 3]
+    (KVC.mutable_array << 4).shift
+    assert_equal [2, 3, 4], KVC.mutable_array
+  end
+
+  test "attributes should serialize and deserialize" do
+    type = KVC::Settings.columns.find { |column| column.name == "key" }.type
+    assert_equal :string, type
+
+    KVC.favorite_year = 1984
+    assert_kind_of Integer, KVC.favorite_year
+  end
+
+  test "can set attributes with whitespace and symbols" do
+    assert KVC["uses_git?"] = true
+    assert KVC.uses_git?
+
+    assert KVC["Nonstandard, but a fine time :)"] = Time.now
+    assert_instance_of Time, KVC["Nonstandard, but a fine time :)"]
+  end
+
+  test "should have access to created_at and updated_at via proxy" do
+    KVC.apples = [:braeburn, :granny_smith, :fuji, :macintosh]
+    apples = KVC.apples
+    assert_instance_of Time, apples.created_at
+    assert_equal apples.created_at, apples.updated_at
+  end
+
+  test "brackets and equals should not necessarily clash" do
+    KVC["[]=''"] = "upside-down cookie monster"
+    assert_equal "upside-down cookie monster", KVC["[]=''"]
+  end
+
+  test "cannot create duplicate attributes" do
+    KVC.unique = true
+    assert_no_difference "KVC::Settings.count" do
+      KVC::Settings.create :key => "unique", :value => true
+
+      assert_raise ActiveRecord::StatementInvalid do
+        try_again = KVC::Settings.new :key => "unique", :value => true
+        try_again.save_without_validation
+      end
+    end
+  end
+
+  test "validations should raise exceptions when invalid" do
+    begin
+      KVC::Settings.config do
+        validates("password") { |value| value =~ /\d+/ }
+      end
+      assert_raise ActiveRecord::RecordInvalid do
+        KVC.password = "password"
+      end
+      assert_nothing_raised do
+        KVC.password = "password1"
+      end
+    ensure
+      KVC::Settings.validations["password"] = []
+    end
+  end
+end

data/uninstall.rb

@@ -0,0 +1,9 @@
+require Rails.root.join("config", "environment")
+
+if KVC::Settings.table_exists?
+  print "Also drop the KVC table? [yN] "
+  if STDIN.gets.chomp =~ /^y)/i
+    ActiveRecord::Base.connection.drop_table :kvc_settings
+    puts "Successfully dropped KVC::Settings."
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: kvc
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Stephen Celis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-03 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.11.0
+    version: 
+description: KVC (Key-Value Configuration) provides a powerful, transparent way to maintain mutable app settings in the database.
+email: 
+- stephen@stephencelis.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- Manifest.txt
+- README.txt
+- Rakefile
+- app/models/kvc/settings.rb
+- lib/kvc.rb
+- lib/kvc/settings_proxy.rb
+- tasks/kvc_tasks.rake
+- test/kvc_test.rb
+- uninstall.rb
+has_rdoc: true
+homepage: http://github.com/stephencelis/kvc
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: kvc
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: KVC (Key-Value Configuration) provides a powerful, transparent way to maintain mutable app settings in the database.
+test_files: []
+