configurability 1.0.0 → 1.0.1

data/ChangeLog

@@ -1,4 +1,43 @@
-4[tip]   4d7044641f87   2010-07-12 13:38 -0700   ged
+17[tip]   4bff6d5f7b6e   2010-08-08 10:26 -0700   ged
+  Added tag 1.0.1 for changeset e3605ccbe057
+
+16[1.0.1]   e3605ccbe057   2010-08-08 10:26 -0700   ged
+  Added signature for changeset 41bc1de0bf36
+
+15   41bc1de0bf36   2010-08-04 18:51 -0700   ged
+  More Configurability::Config work
+
+14   44db952eb824   2010-08-04 18:23 -0700   ged
+  More work on Configurability::Config
+
+13   2323bf260e7c   2010-08-04 16:28 -0700   ged
+  Finishing up Configurability::Config.
+
+12   9e0bab83afd5   2010-08-04 10:18 -0700   ged
+  Build system updates.
+
+11   cba63cef2f7f   2010-08-04 10:17 -0700   ged
+  Add an rspec shared behavior for testing classes with Configurability
+
+10   4ffdde3f7a2f   2010-07-16 16:55 -0700   ged
+  Adding a Configurability::Config class for YAML config loading.
+
+9   d225cef4269e   2010-07-16 16:54 -0700   ged
+  Updating README, project metadata, adding .irbrc
+
+8   9da882b82786   2010-07-16 16:53 -0700   ged
+  Version bump; debugging log
+
+7   ecf5d4565338   2010-07-12 15:52 -0700   ged
+  Added tag 1.0.0 for changeset 74b5dd9a89c9
+
+6[1.0.0]   74b5dd9a89c9   2010-07-12 15:52 -0700   ged
+  Added signature for changeset e0fef8dabba4
+
+5   e0fef8dabba4   2010-07-12 15:51 -0700   ged
+  README formatting, YARD tag fix.
+
+4   4d7044641f87   2010-07-12 13:38 -0700   ged
   Documentation, added a test for classname normalization.
 
 3   0b395dbf657f   2010-07-12 08:13 -0700   ged

data/README.md

@@ -10,6 +10,7 @@ configuration is split up and sent to the objects that will use it.
 To add configurability to a class, just require the library and extend
 the class:
 
+    require 'configurability'
     class User
         extend Configurability
     end
@@ -35,7 +36,12 @@ _section name_ as a `Symbol` or a `String`:
 
 The section name is based on an object's _config key_, which is the name of
 the object that is being extended with all non-word characters converted into
-underscores (`_`) by default.
+underscores (`_`) by default. It will also have any leading Ruby-style
+namespaces stripped, e.g.,
+
+            MyClass            -> :myclass
+            Acme::User         -> :user
+            "J. Random Hacker" -> :j_random_hacker
 
 If the object responds to the `#name` method, then the return value of that
 method is used to derive the name. If it doesn't have a `#name` method, the
@@ -82,13 +88,131 @@ a `#configure` method that takes the config section as an argument:
     class WebServer
         extend Configurability
 
+        config_key :webserver
+
         def self::configure( configsection )
             @default_bind_addr = configsection[:host]
             @default_port = configsection[:port]
         end
     end
 
-If you still want the `config` variable to be set, just `super` from your implementation; don't if you don't want it to be set.
+If you still want the `@config` variable to be set, just `super` from your implementation; don't if you don't want it to be set.
+
+
+## Configuration Objects
+
+Configurability also includes `Configurability::Config`, a fairly simple
+configuration object class that can be used to load a YAML configuration file,
+and then present both a Hash-like and a Struct-like interface for reading
+configuration sections and values; it's meant to be used in tandem with Configurability, but it's also useful on its own.
+
+Here's a quick example to demonstrate some of its features. Suppose you have a
+config file that looks like this:
+
+    --- 
+    database: 
+      development: 
+        adapter: sqlite3
+        database: db/dev.db
+        pool: 5
+        timeout: 5000
+      testing: 
+        adapter: sqlite3
+        database: db/testing.db
+        pool: 2
+        timeout: 5000
+      production: 
+        adapter: postgres
+        database: fixedassets
+        pool: 25
+        timeout: 50
+    ldap: 
+      uri: ldap://ldap.acme.com/dc=acme,dc=com
+      bind_dn: cn=web,dc=acme,dc=com
+      bind_pass: Mut@ge.Mix@ge
+    branding: 
+      header: "#333"
+      title: "#dedede"
+      anchor: "#9fc8d4"
+
+You can load this config like so:
+
+    require 'configurability/config'
+    config = Configurability::Config.load( 'examples/config.yml' )
+    # => #<Configurability::Config:0x1018a7c7016 loaded from 
+        examples/config.yml; 3 sections: database, ldap, branding>
+
+And then access it using struct-like methods:
+
+    config.database
+    # => #<Configurability::Config::Struct:101806fb816
+        {:development=>{:adapter=>"sqlite3", :database=>"db/dev.db", :pool=>5,
+        :timeout=>5000}, :testing=>{:adapter=>"sqlite3",
+        :database=>"db/testing.db", :pool=>2, :timeout=>5000},
+        :production=>{:adapter=>"postgres", :database=>"fixedassets",
+        :pool=>25, :timeout=>50}}>
+
+    config.database.development.adapter
+    # => "sqlite3"
+
+    config.ldap.uri
+    # => "ldap://ldap.acme.com/dc=acme,dc=com"
+
+    config.branding.title
+    # => "#dedede"
+
+or using a Hash-like interface using either `Symbol`s, `String`s, or a mix of
+both:
+
+    config[:branding][:title]
+    # => "#dedede"
+
+    config['branding']['header']
+    # => "#333"
+
+    config['branding'][:anchor]
+    # => "#9fc8d4"
+
+You can install it via the Configurability interface:
+
+    config.install
+
+Check to see if the file it was loaded from has changed since you
+loaded it:
+
+    config.changed?
+    # => false
+
+    # Simulate changing the file by manually changing its mtime
+    File.utime( Time.now, Time.now, config.path )
+    config.changed?
+    # => true
+
+If it has changed (or even if it hasn't), you can reload it, which automatically re-installs it via the Configurability interface:
+
+    config.reload
+
+You can make modifications via the same Struct- or Hash-like interfaces and write the modified config back out to the same file:
+
+    config.database.testing.adapter = 'mysql'
+    config[:database]['testing'].database = 't_fixedassets'
+
+then dump it to a YAML string:
+
+    config.dump
+	# => "--- \ndatabase: \n  development: \n    adapter: sqlite3\n   
+	 	database: db/dev.db\n    pool: 5\n    timeout: 5000\n  testing: \n   
+	 	adapter: mysql\n    database: t_fixedassets\n    pool: 2\n    timeout:
+	 	5000\n  production: \n    adapter: postgres\n    database:
+	 	fixedassets\n    pool: 25\n    timeout: 50\nldap: \n  uri:
+	 	ldap://ldap.acme.com/dc=acme,dc=com\n  bind_dn:
+	 	cn=web,dc=acme,dc=com\n  bind_pass: Mut@ge.Mix@ge\nbranding: \n 
+	 	header: \"#333\"\n  title: \"#dedede\"\n  anchor: \"#9fc8d4\"\n"
+
+or write it back to the file it was loaded from:
+
+	config.write
+
 
 
 ## Development

data/Rakefile

@@ -76,7 +76,7 @@ elsif VERSION_FILE.exist?
 	PKG_VERSION = VERSION_FILE.read[ /VERSION\s*=\s*['"](\d+\.\d+\.\d+)['"]/, 1 ]
 end
 
-PKG_VERSION = '0.0.0' unless defined?( PKG_VERSION )
+PKG_VERSION = '0.0.0' unless defined?( PKG_VERSION ) && !PKG_VERSION.nil?
 
 PKG_FILE_NAME = "#{PKG_NAME.downcase}-#{PKG_VERSION}"
 GEM_FILE_NAME = "#{PKG_FILE_NAME}.gem"
@@ -168,7 +168,7 @@ include RakefileHelpers
 
 # Set the build ID if the mercurial executable is available
 if hg = which( 'hg' )
-	id = IO.read('|-') or exec hg.to_s, 'id', '-n'
+	id = `#{hg} id -n`.chomp
 	PKG_BUILD = "pre%03d" % [(id.chomp[ /^[[:xdigit:]]+/ ] || '1')]
 else
 	PKG_BUILD = 'pre000'
@@ -237,7 +237,11 @@ GEMSPEC   = Gem::Specification.new do |gem|
 
 	gem.summary           = PKG_SUMMARY
 	gem.description       = [
-		"Configurability is mixin that allows you to add configurability to one or more classes, assign them each a section of the configuration, and then when the configuration is loaded, the class is given the section it requested.",
+		"Configurability is a mixin that allows you to add ",
+		"configurability to one or more classes, assign them ",
+		"each a section of the configuration, and then when ",
+		"the configuration is loaded, the class is given the ",
+		"section it requested.",
   	  ].join( "\n" )
 
 	gem.authors           = "Michael Granger"

data/lib/configurability/behavior.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+
+require 'configurability'
+require 'spec'
+
+share_examples_for "an object with Configurability" do
+
+	before( :each ) do
+		fail "this behavior expects the object under test to be in the @object " +
+		     "instance variable" unless defined?( @object )
+	end
+
+	it "is extended with Configurability" do
+		Configurability.configurable_objects.should include( @object )
+	end
+
+	it "has a Symbol config key" do
+		@object.config_key.should be_a( Symbol )
+	end
+
+	it "has a config key that is a reasonable section name" do
+		@object.config_key.to_s.should =~ /^[a-z][a-z0-9]*$/i
+	end
+
+end
+

data/lib/configurability/config.rb

@@ -0,0 +1,561 @@
+#!/usr/bin/env ruby
+
+require 'tmpdir'
+require 'pathname'
+require 'forwardable'
+require 'yaml'
+require 'logger'
+
+require 'configurability'
+
+# A configuration object class for systems with Configurability
+# 
+# @author Michael Granger <ged@FaerieMUD.org>
+# @author Mahlon E. Smith <mahlon@martini.nu>
+# 
+# This class also delegates some of its methods to the underlying struct:
+#
+# @see Configurability::Config::Struct#to_hash
+#      #to_hash (delegated to its internal Struct)
+# @see Configurability::Config::Struct#member?
+#      #member? (delegated to its internal Struct)
+# @see Configurability::Config::Struct#members
+#      #members (delegated to its internal Struct)
+# @see Configurability::Config::Struct#merge
+#      #merge (delegated to its internal Struct)
+# @see Configurability::Config::Struct#merge!
+#      #merge! (delegated to its internal Struct)
+# @see Configurability::Config::Struct#each
+#      #each (delegated to its internal Struct)
+# @see Configurability::Config::Struct#[]
+#      #[] (delegated to its internal Struct)
+# @see Configurability::Config::Struct#[]=
+#      #[]= (delegated to its internal Struct)
+# 
+class Configurability::Config
+	extend Forwardable
+
+
+	#############################################################
+	###	C L A S S   M E T H O D S
+	#############################################################
+
+	### Read and return a Configurability::Config object from the file at the given +path+.
+	### @param [String] path      the path to the config file
+	### @param [Hash]   defaults  a Hash of default config values which will be
+	###                           used if the config at +path+ doesn't override
+	###                           them.
+	### @param          block     passed through as the block argument to {#initialize}.
+	def self::load( path, defaults=nil, &block )
+		path = Pathname( path ).expand_path
+		source = path.read
+		Configurability.log.debug "Read %d bytes from %s" % [ source.length, path ]
+		return new( source, path, defaults, &block )
+	end
+
+
+	### Recursive hash-merge function. Used as the block argument to a Hash#merge.
+	### @param [Symbol]  key     the key that's in conflict
+	### @param [Object]  oldval  the value in the original Hash
+	### @param [Object]  newval  the value in the Hash being merged
+	def self::merge_complex_hashes( key, oldval, newval )
+		return oldval.merge( newval, &method(:merge_complex_hashes) ) if
+			oldval.is_a?( Hash ) && newval.is_a?( Hash )
+		return newval
+	end
+
+
+
+	#############################################################
+	###	I N S T A N C E   M E T H O D S
+	#############################################################
+
+	### Create a new Configurability::Config object. If the optional +source+ argument
+	### is specified, parse the config from it.
+	### 
+	### @param [String] source           the YAML source of the configuration
+	### @param [String, Pathname] path   the path to the config file (if loaded from a file)
+	### @param [Hash] defaults           a Hash containing default values which the loaded values
+	###                                  will be merged into.
+	### @yield  The block will be evaluated in the context of the config object after
+	###         the config is loaded, unless it accepts an argument, in which case the config
+	###         object is passed as the argument.
+	def initialize( source=nil, path=nil, defaults=nil, &block )
+
+		# Shift the hash parameter if it shows up as the path
+		if path.is_a?( Hash )
+			defaults = path
+			path = nil
+		end
+
+		# Make a deep copy of the defaults before loading so we don't modify
+		# the argument
+		@defaults     = Marshal.load( Marshal.dump(defaults) ) if defaults
+		@time_created = Time.now
+		@path         = path
+
+		if source
+			@struct = self.make_configstruct_from_source( source, @defaults )
+		else
+			@struct = Configurability::Config::Struct.new( @defaults )
+		end
+
+		if block
+			Configurability.log.debug "Block arity is: %p" % [ block.arity ]
+
+			# A block with an argument is called with the config as the argument
+			# instead of instance_evaled
+			case block.arity
+			when 0, -1  # 1.9 and 1.8, respectively
+				Configurability.log.debug "Instance evaling in the context of %p" % [ self ]
+				self.instance_eval( &block )
+			else
+				block.call( self )
+			end
+		end
+	end
+
+
+	######
+	public
+	######
+
+	# Define delegators to the inner data structure
+	def_delegators :@struct, :to_hash, :to_h, :member?, :members, :merge,
+		:merge!, :each, :[], :[]=
+
+	# @return [Configurability::Config::Struct] The underlying config data structure
+	attr_reader :struct
+
+	# @return [Time] The time the configuration was loaded
+	attr_accessor :time_created
+
+	# @return [Pathname] the path to the config file, if loaded from a file
+	attr_accessor :path
+
+
+	### Install this config object in any objects that have added
+	### Configurability.
+	def install
+		Configurability.configure_objects( self )
+	end
+
+
+	### Return the config object as a YAML hash
+	def dump
+		strhash = stringify_keys( self.to_h )
+		return YAML.dump( strhash )
+	end
+
+
+	### Write the configuration object using the specified name and any
+	### additional +args+.
+	def write( path=@path, *args )
+		raise ArgumentError,
+			"No name associated with this config." unless path
+		path.open( File::WRONLY|File::CREAT|File::TRUNC ) do |ofh|
+			ofh.print( self.dump )
+		end
+	end
+
+
+	### Returns +true+ for methods which can be autoloaded
+	def respond_to?( sym )
+		return true if @struct.member?( sym.to_s.sub(/(=|\?)$/, '').to_sym )
+		super
+	end
+
+
+	### Returns +true+ if the configuration has changed since it was last
+	### loaded, either by setting one of its members or changing the file
+	### from which it was loaded.
+	def changed?
+		return self.changed_reason ? true : false
+	end
+
+
+	### If the configuration has changed, return the reason. If it hasn't,
+	### returns nil.
+	def changed_reason
+		if @struct.dirty?
+			Configurability.log.debug "Changed_reason: struct was modified"
+			return "Struct was modified"
+		end
+
+		if self.path && self.is_older_than?( self.path )
+			Configurability.log.debug "Source file (%s) has changed." % [ self.path ]
+			return "Config source (%s) has been updated since %s" %
+				[ self.path, self.time_created ]
+		end
+
+		return nil
+	end
+
+
+	### Return +true+ if the specified +file+ is newer than the time the receiver
+	### was created.
+	def is_older_than?( path )
+		return false unless path.exist?
+		st = path.stat
+		Configurability.log.debug "File mtime is: %s, comparison time is: %s" %
+			[ st.mtime, @time_created ]
+		return st.mtime > @time_created
+	end
+
+
+	### Reload the configuration from the original source if it has
+	### changed. Returns +true+ if it was reloaded and +false+ otherwise.
+	### 
+	def reload
+		raise "can't reload from an in-memory source" unless self.path
+
+		if self.changed?
+			self.time_created = Time.now
+			source = self.path.read
+			@struct = self.make_configstruct_from_source( source, @defaults )
+
+			self.install
+			return true
+		else
+			return false
+		end
+	end
+
+
+	### Return a human-readable, compact representation of the configuration
+	### suitable for debugging.
+	def inspect
+		return "#<%s:0x%0x16 loaded from %s; %d sections: %s>" % [
+			self.class.name,
+			self.object_id * 2,
+			self.path ? self.path : "memory",
+			self.struct.members.length,
+			self.struct.members.join( ', ' )
+		]
+	end
+
+
+	#########
+	protected
+	#########
+
+
+	### Read in the specified +filename+ and return a config struct.
+	### @param [String]  source  the YAML source to be converted
+	### @return [Configurability::Config::Struct]  the converted config struct
+	def make_configstruct_from_source( source, defaults=nil )
+		defaults ||= {}
+		mergefunc = Configurability::Config.method( :merge_complex_hashes )
+		hash = YAML.load( source )
+		ihash = symbolify_keys( untaint_values(hash) )
+		mergedhash = defaults.merge( ihash, &mergefunc )
+
+		return Configurability::Config::Struct.new( mergedhash )
+	end
+
+
+	### Handle calls to struct-members
+	def method_missing( sym, *args )
+		key = sym.to_s.sub( /(=|\?)$/, '' ).to_sym
+
+		self.class.class_eval %{
+			def #{key}; @struct.#{key}; end
+			def #{key}=(arg); @struct.#{key} = arg; end
+			def #{key}?; @struct.#{key}?; end
+		}
+
+		return self.method( sym ).call( *args )
+	end
+
+
+	#######
+	private
+	#######
+
+	### Return a copy of the specified +hash+ with all of its values
+	### untainted.
+	def untaint_values( hash )
+		newhash = {}
+		hash.each do |key,val|
+			case val
+			when Hash
+				newhash[ key ] = untaint_values( hash[key] )
+
+			when Array
+				newval = val.collect {|v| v.dup.untaint}
+				newhash[ key ] = newval
+
+			when NilClass, TrueClass, FalseClass, Numeric, Symbol
+				newhash[ key ] = val
+
+			else
+				newval = val.dup
+				newval.untaint
+				newhash[ key ] = newval
+			end
+		end
+		return newhash
+	end
+
+
+	### Return a duplicate of the given +hash+ with its identifier-like keys
+	### transformed into symbols from whatever they were before.
+	def symbolify_keys( hash )
+		newhash = {}
+		hash.each do |key,val|
+			if val.is_a?( Hash )
+				newhash[ key.to_sym ] = symbolify_keys( val )
+			else
+				newhash[ key.to_sym ] = val
+			end
+		end
+
+		return newhash
+	end
+
+
+	### Return a version of the given +hash+ with its keys transformed
+	### into Strings from whatever they were before.
+	def stringify_keys( hash )
+		newhash = {}
+		hash.each do |key,val|
+			if val.is_a?( Hash )
+				newhash[ key.to_s ] = stringify_keys( val )
+			else
+				newhash[ key.to_s ] = val
+			end
+		end
+
+		return newhash
+	end
+
+
+
+	#############################################################
+	###	I N T E R I O R   C L A S S E S
+	#############################################################
+
+	### Hash-wrapper that allows struct-like accessor calls on nested
+	### hashes.
+	class Struct
+		extend Forwardable
+		include Enumerable
+
+		# Mask most of Kernel's methods away so they don't collide with
+		# config values.
+		Kernel.methods(false).each {|meth|
+			next unless method_defined?( meth )
+			next if /^(?:__|dup|object_id|inspect|class|raise|method_missing)/.match( meth )
+			undef_method( meth )
+		}
+
+
+		### Create a new ConfigStruct using the values from the given +hash+ if specified.
+		### @param [Hash] hash  a hash of config values
+		def initialize( hash=nil )
+			hash ||= {}
+			@hash = hash.dup
+			@dirty = false
+		end
+
+
+		######
+		public
+		######
+
+		# Forward some methods to the internal hash
+		def_delegators :@hash, :keys, :key?, :values, :value?, :length,
+		    :empty?, :clear, :each
+
+		# Let :each be called as :each_section, too
+		alias_method :each_section, :each
+
+
+		### Return the value associated with the specified +key+.
+		### @param [Symbol, String] key  the key of the value to return
+		### @return [Object] the value associated with +key+, or another
+		###                  Configurability::Config::ConfigStruct if +key+
+		###                  is a section name.
+		def []( key )
+			key = key.untaint.to_sym
+
+			# Create the config struct on the fly for subsections
+			if !@hash.key?( key )
+				@hash[ key ] = self.class.new
+			elsif @hash[ key ].is_a?( Hash )
+				@hash[ key ] = self.class.new( @hash[key] )
+			end
+
+			return @hash[ key ]
+		end
+
+
+		### Set the value associated with the specified +key+ to +value+.
+		### @param [Symbol, String] key    the key of the value to set
+		### @param [Object]         value  the value to set
+		def []=( key, value )
+			key = key.untaint.to_sym
+			self.mark_dirty if @hash[ key ] != value
+			@hash[ key ] = value
+		end
+
+
+		### Mark the struct has having been modified since its creation.
+		def mark_dirty
+			@dirty = true
+		end
+
+
+		### Returns +true+ if the ConfigStruct or any of its sub-structs
+		### have changed since it was created.
+		def dirty?
+			return true if @dirty
+			return true if @hash.values.find do |obj|
+				obj.respond_to?( :dirty? ) && obj.dirty?
+			end
+		end
+
+
+		### Return the receiver's values as a (possibly multi-dimensional)
+		### Hash with String keys.
+		def to_hash
+			rhash = {}
+			@hash.each {|k,v|
+				case v
+				when Configurability::Config::Struct
+					rhash[k] = v.to_h
+				when NilClass, FalseClass, TrueClass, Numeric
+					# No-op (can't dup)
+					rhash[k] = v
+				when Symbol
+					rhash[k] = v.to_s
+				else
+					rhash[k] = v.dup
+				end
+			}
+			return rhash
+		end
+		alias_method :to_h, :to_hash
+
+
+		### Return +true+ if the receiver responds to the given
+		### method. Overridden to grok autoloaded methods.
+		def respond_to?( sym, priv=false )
+			key = sym.to_s.sub( /(=|\?)$/, '' ).to_sym
+			return true if @hash.key?( key )
+			super
+		end
+
+
+		### Returns an Array of Symbols, one for each of the struct's members.
+		def members
+			return @hash.keys
+		end
+
+
+		### Returns +true+ if the given +name+ is the name of a member of
+		### the receiver.
+		def member?( name )
+			return @hash.key?( name.to_s.to_sym )
+		end
+
+
+		### Merge the specified +other+ object with this config struct. The
+		### +other+ object can be either a Hash, another Configurability::Config::Struct, or an
+		### Configurability::Config.
+		def merge!( other )
+			mergefunc = Configurability::Config.method( :merge_complex_hashes )
+
+			case other
+			when Hash
+				@hash = self.to_h.merge( other, &mergefunc )
+
+			when Configurability::Config::Struct
+				@hash = self.to_h.merge( other.to_h, &mergefunc )
+
+			when Configurability::Config
+				@hash = self.to_h.merge( other.struct.to_h, &mergefunc )
+
+			else
+				raise TypeError,
+					"Don't know how to merge with a %p" % other.class
+			end
+
+			# :TODO: Actually check to see if anything has changed?
+			@dirty = true
+
+			return self
+		end
+
+
+		### Return a new Configurability::Config::Struct which is the result of merging the
+		### receiver with the given +other+ object (a Hash or another
+		### Configurability::Config::Struct).
+		def merge( other )
+			self.dup.merge!( other )
+		end
+
+
+		### Return a human-readable representation of the Struct suitable for debugging.
+		def inspect
+			return "#<%s:%0x16 %p>" % [
+				self.class.name,
+				self.object_id * 2,
+				@hash,
+			]
+		end
+
+
+		#########
+		protected
+		#########
+
+		### Handle calls to key-methods
+		def method_missing( sym, *args )
+			key = sym.to_s.sub( /(=|\?)$/, '' ).to_sym
+
+			# Create new methods for this key
+			reader    = self.create_member_reader( key )
+			writer    = self.create_member_writer( key )
+			predicate = self.create_member_predicate( key )
+
+			# ...and install them
+			self.class.send( :define_method, key, &reader )
+			self.class.send( :define_method, "#{key}=", &writer )
+			self.class.send( :define_method, "#{key}?", &predicate )
+
+			# Now jump to the requested method in a way that won't come back through
+			# the proxy method if something didn't get defined
+			self.method( sym ).call( *args )
+		end
+
+
+		### Create a reader method for the specified +key+ and return it.
+		### @param [Symbol] key  the config key to create the reader method body for
+		### @return [Proc] the body of the new method
+		def create_member_reader( key )
+			return lambda { self[key] }
+		end
+
+
+		### Create a predicate method for the specified +key+ and return it.
+		### @param [Symbol] key  the config key to create the predicate method body for
+ 		### @return [Proc] the body of the new method
+		def create_member_predicate( key )
+			return lambda { self[key] ? true : false }
+		end
+
+
+		### Create a writer method for the specified +key+ and return it.
+		### @param [Symbol] key  the config key to create the writer method body for
+		### @return [Proc] the body of the new method
+		def create_member_writer( key )
+			return lambda {|val| self[key] = val }
+		end
+
+	end # class Struct
+
+end # class Configurability::Config
+
+# vim: set nosta noet ts=4 sw=4:
+

data/lib/configurability.rb

@@ -9,10 +9,10 @@ require 'yaml'
 module Configurability
 
 	# Library version constant
-	VERSION = '1.0.0'
+	VERSION = '1.0.1'
 
 	# Version-control revision constant
-	REVISION = %q$Revision: e0fef8dabba4 $
+	REVISION = %q$Revision: 9da882b82786 $
 
 	require 'configurability/logformatter.rb'
 
@@ -84,6 +84,9 @@ module Configurability
 	### +config_key+, the object's #configure method is called with +nil+ 
 	### instead.
 	def self::configure_objects( config )
+		self.log.debug "Splitting up config %p between %d objects with configurability." %
+			[ config, self.configurable_objects.length ]
+
 		self.configurable_objects.each do |obj|
 			section = obj.config_key.to_sym
 			self.log.debug "Configuring %p with the %p section of the config." %

data/rake/documentation.rb

@@ -53,6 +53,31 @@ begin
 	class YARD::RegistryStore; include YardGlobals; end
 	class YARD::Docstring; include YardGlobals; end
 	module YARD::Templates::Helpers::ModuleHelper; include YardGlobals; end
+
+	if vvec(RUBY_VERSION) >= vvec("1.9.1")
+		# Monkeypatched to allow more than two '#' characters at the beginning
+		# of the comment line.
+		# Patched from yard-0.5.8
+		require 'yard/parser/ruby/ruby_parser'
+		class YARD::Parser::Ruby::RipperParser < Ripper
+			def on_comment(comment)
+				$stderr.puts "Adding comment: %p" % [ comment ]
+				visit_ns_token(:comment, comment)
+
+				comment = comment.gsub(/^\#+\s{0,1}/, '').chomp
+				append_comment = @comments[lineno - 1]
+
+				if append_comment && @comments_last_column == column
+					@comments.delete(lineno - 1)
+					comment = append_comment + "\n" + comment
+				end
+
+				@comments[lineno] = comment
+				@comments_last_column = column
+			end
+		end # class YARD::Parser::Ruby::RipperParser
+	end
+
 	# </metamonkeypatch>
 
 	YARD_OPTIONS = [] unless defined?( YARD_OPTIONS )

data/rake/hg.rb

@@ -215,13 +215,20 @@ unless defined?( HG_DOTDIR )
 			paths = get_repo_paths()
 			if origin_url = paths['default']
 				ask_for_confirmation( "Pull and update from '#{origin_url}'?", false ) do
-					run 'hg', 'pull', '-u'
+					Rake::Task['hg:pull_without_confirmation'].invoke
 				end
 			else
 				trace "Skipping pull: No 'default' path."
 			end
 		end
 
+
+		desc "Pull and update without confirmation"
+		task :pull_without_confirmation do
+			run 'hg', 'pull', '-u'
+		end
+
+
 		desc "Check the current code in if tests pass"
 		task :checkin => ['hg:pull', 'hg:newfiles', 'test', COMMIT_MSG_FILE] do
 			targets = get_target_args()

data/spec/configurability/config_spec.rb

@@ -0,0 +1,311 @@
+#!/usr/bin/env ruby
+
+BEGIN {
+	require 'pathname'
+	basedir = Pathname.new( __FILE__ ).dirname.parent.parent
+
+	libdir = basedir + "lib"
+
+	$LOAD_PATH.unshift( libdir ) unless $LOAD_PATH.include?( libdir )
+}
+
+require 'tempfile'
+require 'logger'
+require 'fileutils'
+
+require 'spec'
+require 'spec/lib/helpers'
+
+require 'configurability/config'
+
+
+
+#####################################################################
+###	C O N T E X T S
+#####################################################################
+describe Configurability::Config do
+	include Configurability::SpecHelpers
+
+	TEST_CONFIG = %{
+	---
+	section:
+	  subsection:
+	    subsubsection: value
+	listsection:
+	  - list
+	  - values
+	  - are
+	  - neat
+	mergekey: Yep.
+	textsection: |-
+	  With some text as the value
+	  ...and another line.
+	}.gsub(/^\t/, '')
+
+
+	before( :all ) do
+		setup_logging( :fatal )
+	end
+
+	after( :all ) do
+		reset_logging()
+	end
+
+	it "can dump itself as YAML" do
+		Configurability::Config.new.dump.should == "--- {}\n\n"
+	end
+
+	it "returns nil as its change description" do
+		Configurability::Config.new.changed_reason.should be_nil()
+	end
+
+	it "autogenerates accessors for non-existant struct members" do
+		config = Configurability::Config.new
+		config.plugins.filestore.maxsize = 1024
+		config.plugins.filestore.maxsize.should == 1024
+	end
+
+	it "merges values loaded from the config with any defaults given" do
+		config = Configurability::Config.new( TEST_CONFIG, :defaultkey => "Oh yeah." )
+		config.defaultkey.should == "Oh yeah."
+	end
+
+	it "yields itself if a block is given at creation" do
+		yielded_self = nil
+		config = Configurability::Config.new { yielded_self = self }
+		yielded_self.should equal( config )
+	end
+
+	it "passes itself as the block argument if a block of arity 1 is given at creation" do
+		arg_self = nil
+		yielded_self = nil
+		config = Configurability::Config.new do |arg|
+			yielded_self = self
+			arg_self = arg
+		end
+		yielded_self.should_not equal( config )
+		arg_self.should equal( config )
+	end
+
+	it "supports both Symbols and Strings for Hash-like access" do
+		config = Configurability::Config.new( TEST_CONFIG )
+		config[:section]['subsection'][:subsubsection].should == 'value'
+	end
+
+
+	describe "created with in-memory YAML source" do
+
+		before(:each) do
+			@config = Configurability::Config.new( TEST_CONFIG )
+		end
+
+		it "responds to methods which are the same as struct members" do
+			@config.should respond_to( :section )
+			@config.section.should respond_to( :subsection )
+			@config.should_not respond_to( :pork_sausage )
+		end
+
+		it "contains values specified in the source" do
+			# section:
+			#   subsection:
+			#     subsubsection: value
+			@config.section.subsection.subsubsection.should == 'value'
+
+			# listsection:
+			#   - list
+			#   - values
+			#   - are
+			#   - neat
+			@config.listsection.should == %w[list values are neat]
+
+			# mergekey: Yep.
+			@config.mergekey.should == 'Yep.'
+
+			# textsection: |-
+			#   With some text as the value
+			#   ...and another line.
+			@config.textsection.should == "With some text as the value\n...and another line."
+		end
+
+		it "returns struct members as an Array of Symbols" do
+			@config.members.should be_an_instance_of( Array )
+			@config.members.should have_at_least( 4 ).things
+			@config.members.each do |member|
+				member.should be_an_instance_of( Symbol)
+			end
+		end
+
+		it "is able to iterate over sections" do
+			@config.each do |key, struct|
+				key.should be_an_instance_of( Symbol)
+			end
+		end
+
+		it "dumps values specified in the source" do
+			@config.dump.should =~ /^section:/
+			@config.dump.should =~ /^\s+subsection:/
+			@config.dump.should =~ /^\s+subsubsection:/
+			@config.dump.should =~ /^- list/
+		end
+
+		it "provides a human-readable description of itself when inspected" do
+			@config.inspect.should =~ /4 sections/i
+			@config.inspect.should =~ /mergekey/
+			@config.inspect.should =~ /textsection/
+			@config.inspect.should =~ /from memory/i
+		end
+
+		it "raises an exception when reloaded" do
+			expect {
+				@config.reload
+			}.to raise_exception( RuntimeError, /can't reload from an in-memory source/i )
+		end
+
+	end
+
+
+	# saving if changed since loaded
+	describe " whose internal values have been changed since loaded" do
+		before(:each) do
+			@config = Configurability::Config.new( TEST_CONFIG )
+			@config.section.subsection.anothersection = 11451
+		end
+
+
+		### Specifications
+		it "should report that it is changed" do
+			@config.changed?.should == true
+		end
+
+		it "should report that its internal struct was modified as the reason for the change" do
+			@config.changed_reason.should =~ /struct was modified/i
+		end
+
+	end
+
+
+	# loading from a file
+	describe " loaded from a file" do
+		before(:all) do
+			@tmpfile = Tempfile.new( 'test.conf', '.' )
+			@tmpfile.print( TEST_CONFIG )
+			@tmpfile.close
+		end
+
+		after(:all) do
+			@tmpfile.delete
+		end
+
+
+		before(:each) do
+			@config = Configurability::Config.load( @tmpfile.path )
+		end
+
+
+		### Specifications
+		it "remembers which file it was loaded from" do
+			@config.path.should == Pathname( @tmpfile.path ).expand_path
+		end
+
+		it "writes itself back to the same file by default" do
+			@config.port = 114411
+			@config.write
+			otherconfig = Configurability::Config.load( @tmpfile.path )
+
+			otherconfig.port.should == 114411
+		end
+
+		it "includes the name of the file in its inspect output" do
+			@config.inspect.should include( File.basename(@tmpfile.path) )
+		end
+
+		it "yields itself if a block is given at load-time" do
+			yielded_self = nil
+			config = Configurability::Config.load( @tmpfile.path ) do
+				yielded_self = self
+			end
+			yielded_self.should equal( config )
+		end
+
+		it "passes itself as the block argument if a block of arity 1 is given at load-time" do
+			arg_self = nil
+			yielded_self = nil
+			config = Configurability::Config.load( @tmpfile.path ) do |arg|
+				yielded_self = self
+				arg_self = arg
+			end
+			yielded_self.should_not equal( config )
+			arg_self.should equal( config )
+		end
+
+		it "doesn't re-read its source file if it hasn't changed" do
+			@config.path.should_not_receive( :read )
+			Configurability.should_not_receive( :configure_objects )
+			@config.reload.should be_false()
+		end
+	end
+
+
+	# reload if file changes
+	describe " whose file changes after loading" do
+		before(:all) do
+			@tmpfile = Tempfile.new( 'test.conf', '.' )
+			@tmpfile.print( TEST_CONFIG )
+			@tmpfile.close
+		end
+
+		after(:all) do
+			@tmpfile.delete
+		end
+
+
+		before(:each) do
+			old_date = Time.now - 3600
+			File.utime( old_date, old_date, @tmpfile.path )
+			@config = Configurability::Config.load( @tmpfile.path )
+			now = Time.now + 10
+			File.utime( now, now, @tmpfile.path )
+		end
+
+
+		### Specifications
+		it "reports that it is changed" do
+			@config.should be_changed
+		end
+
+		it "reports that its source was updated as the reason for the change" do
+			@config.changed_reason.should =~ /source.*updated/i
+		end
+
+		it "re-reads its file when reloaded" do
+			@config.path.should_receive( :read ).and_return( TEST_CONFIG )
+			Configurability.should_receive( :configure_objects ).with( @config )
+			@config.reload.should be_true()
+		end
+
+		it "reapplies its defaults when reloading" do
+			config = Configurability::Config.load( @tmpfile.path, :defaultskey => 8 )
+			config.reload
+			config.defaultskey.should == 8
+		end
+	end
+
+
+	# merging
+	describe " created by merging two other configs" do
+		before(:each) do
+			@config1 = Configurability::Config.new
+			@config2 = Configurability::Config.new( TEST_CONFIG )
+			@merged = @config1.merge( @config2 )
+		end
+
+
+		### Specifications
+		it "should contain values from both" do
+			@merged.mergekey.should == @config2.mergekey
+		end
+	end
+
+end
+
+# vim: set nosta noet ts=4 sw=4:

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 0
-  - 0
-  version: 1.0.0
+  - 1
+  version: 1.0.1
 platform: ruby
 authors: 
 - Michael Granger
@@ -14,11 +14,16 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-12 00:00:00 -07:00
+date: 2010-08-08 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
-description: Configurability is mixin that allows you to add configurability to one or more classes, assign them each a section of the configuration, and then when the configuration is loaded, the class is given the section it requested.
+description: |-
+  Configurability is a mixin that allows you to add 
+  configurability to one or more classes, assign them 
+  each a section of the configuration, and then when 
+  the configuration is loaded, the class is given the 
+  section it requested.
 email: 
 - ged@FaerieMUD.org
 executables: []
@@ -34,8 +39,11 @@ files:
 - ChangeLog
 - README.md
 - LICENSE
+- spec/configurability/config_spec.rb
 - spec/configurability_spec.rb
 - spec/lib/helpers.rb
+- lib/configurability/behavior.rb
+- lib/configurability/config.rb
 - lib/configurability/logformatter.rb
 - lib/configurability.rb
 - rake/191_compat.rb
@@ -86,5 +94,6 @@ signing_key:
 specification_version: 3
 summary: A configurability mixin for Ruby
 test_files: 
+- spec/configurability/config_spec.rb
 - spec/configurability_spec.rb
 - spec/lib/helpers.rb