markevans-configurable 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Mark Evans
+
+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.markdown

@@ -0,0 +1,50 @@
+Configurable
+============
+This is just a simple module which provides an object with a nice API for configuring it.
+
+The best explanation is with an example.
+Here we configure the `ImageProcessor` class.
+
+First declare which attributes we want to be configurable.
+
+    class ImageProcessor
+    
+      extend Configurable
+      
+      configurable_attr :processing_lib         # defaults to nil
+      configurable_attr :default_format, 'png'  # defaults to 'png'
+
+      # ...other stuff...
+
+    end
+
+Then we can configure them as we need
+
+    ImageProcessor.configure do |c|
+      c.processing_lib = 'imagemagick'
+    end
+
+Note that we can NOT configure the ImageProcessor by just saying `ImageProcessor.processing_lib = 'imagemagick'`, the only way is via the `configure` method.
+
+We can see what the configuration is at any time like so:
+
+    ImageProcessor.configuration   # {:processing_lib => 'imagemagick', :default_format => 'png'}
+
+
+Why not just use attr_accessors?
+------------------------------
+It's more of a conceptual win really. By limiting the configuration of these attributes to the `configure` method, the user knows that they are dealing with the configuration of the object.
+Also we are able to view the configuration with `ImageProcessor.configuration` because we've kept them separate from other accessor methods.
+
+Why not just use a `ImageProcessor.config` hash?
+----------------------------------------------
+Because after configuring an object, the rest of the code shouldn't care whether an attribute had to be configured or not (whereas it would using `ImageProcessor.config[:processing_lib]`).
+This way we can decide later that an attribute should actually be configurable, and this is transparent to the rest of the code.
+
+Install
+--------
+Usual way for github gems.
+
+Copyright
+--------
+Copyright (c) 2009 Mark Evans. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "configurable"
+    gem.summary = "Simple module for making your class configurable"
+    gem.email = "mark@new-bamboo.co.uk"
+    gem.homepage = "http://github.com/markevans/configurable"
+    gem.authors = ["Mark Evans"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Configurable #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/configurable.gemspec

@@ -0,0 +1,45 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{configurable}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Mark Evans"]
+  s.date = %q{2009-07-01}
+  s.email = %q{mark@new-bamboo.co.uk}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "configurable.gemspec",
+     "lib/configurable.rb",
+     "spec/configurable_spec.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/markevans/configurable}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{Simple module for making your class configurable}
+  s.test_files = [
+    "spec/configurable_spec.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/configurable.rb

@@ -0,0 +1,42 @@
+module Configurable
+  
+  # Exceptions
+  class NothingToConfigure < StandardError; end
+  class BadConfigAttribute < StandardError; end
+  
+  def configure(&blk)
+    raise NothingToConfigure, "You called configure but there are no configurable attributes" if configuration_hash.empty?
+    config_attributes = configuration_hash.keys
+    struct_class = Struct.new(*config_attributes)
+    struct = struct_class.new(*configuration_hash.values)
+    begin
+      yield(struct)
+    rescue NoMethodError => e
+      raise BadConfigAttribute, "You tried to configure using '#{e.name}',  but the valid config attributes are #{config_attributes.map{|a| %('#{a}') }.sort.join(', ')}"
+    end
+    struct.each_pair{|k,v| configuration_hash[k] = v }
+  end
+  
+  def configuration
+    configuration_hash.dup
+  end
+  
+  private
+  
+  def configurable_attr attribute, default=nil
+    configuration_hash[attribute] = default
+    class << self
+      self # Get the singleton class of the extended object
+    end.class_eval do
+      # Define the reader on the extended object
+      define_method(attribute) do
+        configuration_hash[attribute]
+      end
+    end
+  end
+  
+  def configuration_hash
+    @configuration_hash ||= {}
+  end
+  
+end

data/spec/configurable_spec.rb

@@ -0,0 +1,76 @@
+require 'spec'
+require File.dirname(__FILE__) + '/../lib/configurable'
+
+describe Configurable do
+
+  before(:each) do
+    class Car
+      extend Configurable
+      configurable_attr :colour
+      configurable_attr :top_speed, 216
+      def self.other_thing=(thing); end
+    end    
+  end
+
+  describe "setup" do
+    it "should provide attr_readers for configurable attributes" do
+      Car.should respond_to(:colour)
+    end
+
+    it "should not provide attr_writers for configurable attributes" do
+      Car.should_not respond_to(:colour=)
+    end
+
+    it "should set default values for configurable attributes" do
+      Car.top_speed.should == 216
+    end
+
+    it "should set the default as nil if not specified" do
+      Car.colour.should be_nil
+    end
+    
+    it "should allow specifying configurable attrs as strings" do
+      class Bike
+        extend Configurable
+        configurable_attr 'colour', 'rude'
+      end
+      Bike.colour.should == 'rude'
+    end
+  end
+
+  
+  describe "configuring" do
+    it "should raise an error if there are no configurable attributes" do
+      class None; extend Configurable; end
+      lambda {
+        None.configure{|c|}
+      }.should raise_error(Configurable::NothingToConfigure)
+    end
+    
+    it "should allow you to change values" do
+      Car.configure do |c|
+        c.colour = 'red'
+      end
+      Car.colour.should == 'red'
+    end
+    
+    it "should not allow you to call other methods on the object via the configuration" do
+      lambda{
+        Car.configure do |c|
+          c.other_thing = 5
+        end
+      }.should raise_error(Configurable::BadConfigAttribute)
+    end
+  end
+  
+  describe "getting configuration" do
+    it "should return the configuration as a hash" do
+      Car.configuration.should == {:colour => nil, :top_speed => 216}
+    end
+    it "should not allow you to change the configuration via the hash" do
+      Car.configuration[:top_speed] = 555
+      Car.top_speed.should == 216
+    end
+  end
+
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: markevans-configurable
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Mark Evans
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-01 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: mark@new-bamboo.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- configurable.gemspec
+- lib/configurable.rb
+- spec/configurable_spec.rb
+has_rdoc: true
+homepage: http://github.com/markevans/configurable
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Simple module for making your class configurable
+test_files: 
+- spec/configurable_spec.rb