configurability 3.0.0.pre20161130174408 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ea686c0c69488500b5a99766adb8d47a71415a7d
-  data.tar.gz: 22c502b78fe24a6c29c0b7e2f24a556cf15bb4a1
+  metadata.gz: e5b8b9694625491f3e546adeaccceb6c954d5ec3
+  data.tar.gz: b9d69f613e03aeb99cec8c0a4d38f7dc5ba85d15
 SHA512:
-  metadata.gz: fa983d829f75746d680966e050c1f7ef76e826439c7892deca3715397f75984cfce0017cc68419d9155fdfee13dad38ad242e096319704383c3600ebd9d8e78f
-  data.tar.gz: e285d94730abc2a40cbc7200136c3bdaf22d359f9185f47072f584576aeb5f094a4b5b1f4449166f804f9a5a2832eb5a17ead825d05ebad56d08d01cf081409d
+  metadata.gz: e2cf44e75c61f75d701d72733a417e837d179b7c948cac985107ba212cf6df689f1fc62b6cb96d2e8c0e41f32a6c3324006970903254f1423a9cd7d1a7dc746e
+  data.tar.gz: 11fff4eb97457b4bd3ee7c0dfc4a38c95c09b403e5cefd4822692c03ef1ec99239061165eef28ff8aea8b5f3eb523420577a58fcc09e81bc468a1fdb52e67481

checksums.yaml.gz.sig

@@ -0,0 +1,2 @@
+Bv�;ب<��C�㇕��|�v�l���>rH2˖C�@�\4�x�[�"��@4��'�m63�ƚ<���\f�+CWa��`���&E�+$R��#
+��,l��'�Z����@U��̩4��l9J�[�Õ�&��Jʐ�E߁�Y��eR��ej�2C���S��Z����G�<�|B�d�3f^���vo���.D������''�����lk�T.t��i>�w�J����J�˽�C��O��s�4+���W0����}�1զ[l�؇{|�a�0?��%�Q��%α���Rj���-2���@3�ꐨg����/X��q��Ϳo뙶/N���>���j˓}�b�5��l3��<��L9�o,�so�>7/�a��N.

data/History.md

@@ -2,7 +2,9 @@
 
 Enhancement:
 
-- Add hierarchical config keys.
+- Add hierarchical config keys
+- Add a DSL for setting up settings and defaults
+- Add a better default #configure method
 
 
 == v2.2.2 [2016-09-28] Michael Granger <ged@FaerieMUD.org>

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2010-2016 Michael Granger and Mahlon E. Smith
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Manifest.txt

@@ -7,6 +7,7 @@ Rakefile
 bin/configurability
 examples/basicconfig.rb
 examples/config.yml
+examples/readme.rb
 lib/configurability.rb
 lib/configurability/behavior.rb
 lib/configurability/config.rb

data/README.md

@@ -16,92 +16,180 @@ github
 
 ## Description
 
-Configurability is a unified, unintrusive, assume-nothing configuration system
+Configurability is a unified, non-intrusive, assume-nothing configuration system
 for Ruby. It lets you keep the configuration for multiple objects in a single
 config file, load the file when it's convenient for you, and distribute the
 configuration when you're ready, sending it everywhere it needs to go with a
 single action.
 
 
-
 ## Installation
 
     gem install configurability
 
 
+## Example
+
+    # user.rb
+    require 'configurability'
+    
+    class User
+        extend Configurability
+
+        configurability( :users ) do
+            setting :min_password_length, default: 6
+        end
+
+    end
+
+
+    # config.yml
+    users:
+      min_password_length: 12
+
+In pry:
+
+    [1] pry(main)> require 'user'
+    => true
+    [2] pry(main)> User.min_password_length
+    => 6
+    [3] pry(main)> config = Configurability::Config.load( "config.yml" )
+    => #<Configurability::Config:0x7fd99a0f635816 loaded from config.yml ...>
+    [4] pry(main)> config.install
+    => [Loggability, User]
+    [5] pry(main)> User.min_password_length
+    => 12
+
+
 ## Usage
 
-To add configurability to a class, just require the library and extend
-the class:
+To add Configurability to your module or class, just `extend` it and declare
+some settings:
 
     require 'configurability'
-    class User
+    class Database
         extend Configurability
+
+        configurability( :db ) do
+            setting :url, default: 'sqlite:/'
+            setting :user
+            setting :password
+        end
     end
 
-Or, add it to a instance:
+This sets up the class to use the `db` config key, and adds attributes for the
+three subkey settings under it (with getters and setters) to the class. It also
+adds a `configure` class method that will set whichever of the settings are
+passed to it, defaulting the `url` to the provided value if it's not given.
+
+If your config file (e.g., `config.yml`) looks like this:
+
+    --
+    db:
+        url: 'postgres:/acme'
+        user: tim
+        password: "pXVvVY,YjWNRRi[yPWx4"
+
+You can configure the `Database` class (and all other objects extended with
+Configurability) with it like so:
+
+    require 'configurability/config'
+    
+    config = Configurability::Config.load( 'config.yml' )
+    Configurability.configure_objects( config )
+
+After this happens you can access the configuration values like this:
+
+    Database.url
+    # => "postgres:/acme"
+    Database.user
+    # => "tim"
+    Database.password
+    # => "pXVvVY,YjWNRRi[yPWx4"
+
+
+### More Details
+
+Configurability is implemented using `Module#extend`, so there's very little
+magic going on. Every object (including Class and Module objects) that is
+extended with Configurability is registered in an Array of objects that will be
+configured when the config is loaded.
+
+You extend a Class, of course, as in the above example:
+
+    class MyClass
+        extend Configurabtility
+    end
+
+But you can also add it to individual instances of objects to configure them
+separately:
 
     user = User.new
     user.extend( Configurability )
 
-Later, when you've loaded the configuration, can can call
+When you call:
 
     Configurability.configure_objects( config )
 
-and the `config` will be spliced up and sent to all the objects that have
-been extended with it. `Configurability` expects the configuration to be 
-broken up into a number of sections, each of which is accessible via either
-a method with the _section name_ or the index operator (`#[]`) that takes the 
-_section name_ as a `Symbol` or a `String`:
+the specified `config` will be spliced up and sent to all the objects that have
+been registered. `Configurability` expects the configuration to be broken
+up into a number of sections, each of which is accessible via either a method
+with the _section name_ or the index operator (`#[]`) that takes the _section
+name_ as a `Symbol` or a `String`:
 
     config.section_name
     config[:section_name]
     config['section_name']
 
-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. It will also have any leading Ruby-style
+The section name is based on an object's _config key_, which is the argument
+you specify when declaring your settings. If you don't provide one, it defaults
+to the name of the object that is being extended with all non-word characters
+converted into underscores (`_`). It will also have any leading Ruby-style
 namespaces stripped, e.g.,
 
-            MyClass            -> :myclass
-            Acme::User         -> :user
-            "J. Random Hacker" -> :j_random_hacker
+    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
 name of its `Class` will be used instead. If its class is anonymous, then
 the object's config key will be `:anonymous`.
 
-When the configuration is loaded, an instance variable called `@config` is set
-to the appropriate section of the config object for each object that has
-been extended with Configurability.
+When the configuration is loaded, any attribute writers that correspond with
+keys of the config will be called with the configured values, and an instance
+variable called `@config` is set to the appropriate section of the config.
 
 As you add more objects to your configuration, it may be useful to group
 related sections together. You can specify that your object's configuration
-is part of a group by prepending the name of the group to your config key
-separated by a double underscore (`__`)
+is part of a group by specifying a config key with either a dot if it's a String or a double underscore if it's a Symbol. E.g.,
+
+    # Read from the `db` subsection of `myapp`
+    configurability( 'myapp.db' )
+
+    # Same thing, but with a symbol:
+    configurability( :myapp__db )
 
 
 ## Customization
 
-The default behavior above is just provided as a reasonable default; it is
-expected that you'll want to customize at least one or two things about
-how configuration is handled in your objects.
+The default behavior above is just provided as a reasonable default; you may
+want to customize one or two things about how configuration is handled in your
+objects.
 
 
 ### Setting a Custom Config Key
 
-The first thing you might want to do is change the config section that
-corresponds to your object. You can do that by declaring a different
-config key, either using a declarative method:
+If you want to customize the config key without calling `configurability` you
+can do that by declaring it with the `config_key` method:
 
     class OutputFormatter
         extend Configurability
         config_key :format
     end
 
-or by overriding the `#config_key` method and returning the desired value
-as a Symbol:
+or by overriding the `#config_key` method youtself and returning the desired
+value as a Symbol:
 
     class User
         extend Configurability
@@ -121,9 +209,9 @@ a `#configure` method that takes the config section as an argument:
 
         config_key :webserver
 
-        def self::configure( configsection )
-            @default_bind_addr = configsection[:host]
-            @default_port = configsection[:port]
+        def self::configure( config )
+            @default_bind_addr = config[:host]
+            @default_port = config[:port]
         end
     end
 
@@ -142,28 +230,28 @@ 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: 
+    ---
+    database:
+      development:
         adapter: sqlite3
         database: db/dev.db
         pool: 5
         timeout: 5000
-      testing: 
+      testing:
         adapter: sqlite3
         database: db/testing.db
         pool: 2
         timeout: 5000
-      production: 
+      production:
         adapter: postgres
         database: fixedassets
         pool: 25
         timeout: 50
-    ldap: 
+    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: 
+    branding:
       header: "#333"
       title: "#dedede"
       anchor: "#9fc8d4"
@@ -172,7 +260,7 @@ You can load this config like so:
 
     require 'configurability/config'
     config = Configurability::Config.load( 'examples/config.yml' )
-    # => #<Configurability::Config:0x1018a7c7016 loaded from 
+    # => #<Configurability::Config:0x1018a7c7016 loaded from
         examples/config.yml; 3 sections: database, ldap, branding>
 
 And then access it using struct-like methods:
@@ -206,12 +294,17 @@ both:
     config['branding'][:anchor]
     # => "#9fc8d4"
 
-You can install it via the Configurability interface:
+You can install it (i.e., configure your objects) via the Configurability
+interface:
 
     config.install
 
-Check to see if the file it was loaded from has changed since you
-loaded it:
+If you change the values in the config object, they won't propagate
+automatically; you'll need to call `#install` on it again to send the changes to
+the objects being configured.
+
+You can check to see if the file the config was loaded from has changed since
+you loaded it:
 
     config.changed?
     # => false
@@ -222,7 +315,7 @@ loaded it:
     # => true
 
 If it has changed (or even if it hasn't), you can reload it, which
-automatically re-installs it via the Configurability interface:
+automatically re-installs it via the Configurability interface if it has:
 
     config.reload
 
@@ -235,36 +328,43 @@ write the modified config back out to the same file:
 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"
+    # => "--- \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
+    config.write
+
+Note that this is just using `YAML.dump`, so any comments, ordering, or other
+nice formatting you have in your config file will be clobbered if you rewrite
+it.
 
 
 ## Configuration Defaults
 
 It's a good idea to provide a set of reasonable defaults for any configured
-object. Configurability provides a `defaults` method that will look for a constant
-called either `DEFAULT_CONFIG` or `CONFIG_DEFAULTS` on each object extended with
-Configurability, and will return a dup of the value of this constant if it does.
+object. The defaults for all settings are added to extended Classes and Modules
+as a constant named `CONFIG_DEFAULTS`. You can, of course set this constant
+yourself as well.
 
-You can also override `defaults` yourself if you wish to provide them via something
-other than a constant.
+Configurability provides a `defaults` method that will return the hash of
+settings and their default values from the `CONFIG_DEFAULTS` constant. You can
+also override the `defaults` method yourself (and super to the original) if you
+wish to do something different.
 
 There are also a couple of useful functions built on top of this method:
 
 gather_defaults
-: You can fetch a Hash of the default config values of all objects that have been extended 
-  with Configurability by calling `Configurabilty.gather_defaults`. You can also pass an
-  object that responds to `#merge!` to the method to merge the defaults into an existing
+: You can fetch a Hash of the default config values of all objects that have
+  been extended with Configurability by calling
+  `Configurabilty.gather_defaults`. You can also pass an object that responds
+  to `#merge!` to the method to merge the defaults into an existing
   config.
 
 default_config
@@ -276,9 +376,9 @@ default_config
 ## Development
 
 You can submit bug reports, suggestions, clone it with Mercurial, and
-read more about future plans at 
-{the project page}[http://bitbucket.org/ged/configurability]. If you 
-prefer Git, there is also a 
+read more about future plans at
+{the project page}[http://bitbucket.org/ged/configurability]. If you
+prefer Git, there is also a
 {Github mirror}[https://github.com/ged/configurability].
 
 After checking out the source, run:

data/examples/config.yml

@@ -23,3 +23,5 @@ branding:
   header: "#333"
   title: "#dedede"
   anchor: "#9fc8d4"
+users:
+  min_password_length: 12

data/examples/readme.rb

@@ -0,0 +1,14 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'configurability'
+
+class User
+    extend Configurability
+
+    configurability( :users ) do
+        setting :min_password_length, default: 6
+    end
+end
+
+

data/lib/configurability.rb

@@ -3,12 +3,7 @@
 require 'loggability'
 require 'yaml'
 
-# A configuration mixin for Ruby classes.
-#
-# == Author/s
-#
-# * Michael Granger <ged@FaerieMUD.org>
-#
+# A unified, unintrusive, assume-nothing configuration system for Ruby
 module Configurability
 	extend Loggability
 
@@ -21,7 +16,7 @@ module Configurability
 	VERSION = '3.0.0'
 
 	# Version-control revision constant
-	REVISION = %q$Revision: 5d62053ab7f8 $
+	REVISION = %q$Revision: f363eb5811b9 $
 
 	require 'configurability/deferred_config'
 
@@ -35,10 +30,6 @@ module Configurability
 	### The loaded config (if there is one)
 	@loaded_config = nil
 
-	### The hash of configuration calls that have already taken place -- the keys are
-	### Method objects for the configure methods of the configured objects, and the values
-	### are the config section it was called with
-	@configured = Hash.new( false )
 
 	class << self
 
@@ -48,9 +39,6 @@ module Configurability
 		# the loaded configuration (after ::configure_objects has been called at least once)
 		attr_accessor :loaded_config
 
-		# the hash of configure methods => config sections which have already been installed
-		attr_reader :configured
-
 	end
 
 
@@ -121,7 +109,6 @@ module Configurability
 	### If a configuration has been loaded (via {#configure_objects}), clear it.
 	def self::reset
 		self.loaded_config = nil
-		self.configured.clear
 	end
 
 
@@ -205,6 +192,12 @@ module Configurability
 	end
 
 
+	### Return the specified +key+ normalized into a valid Symbol config key.
+	def self::normalize_config_key( key )
+		return key.to_s.gsub( /\./, '__' ).to_sym
+	end
+
+
 	### Gather the default configuration in a Configurability::Config object and return it.
 	def self::default_config
 		return self.gather_defaults( Configurability::Config.new )
@@ -230,7 +223,7 @@ module Configurability
 	### Set the config key of the object.
 	def config_key=( sym )
 		Configurability.configurable_objects |= [ self ]
-		@config_key = normalize_config_key( sym )
+		@config_key = Configurability.normalize_config_key( sym )
 	end
 
 
@@ -279,12 +272,6 @@ module Configurability
 	end
 
 
-	### Return the specified +key+ normalized into a valid Symbol config key.
-	def normalize_config_key( key )
-		return key.to_s.gsub( /\./, '__' ).to_sym
-	end
-
-
 	#
 	# :section: Configuration settings block
 	#
@@ -322,7 +309,7 @@ module Configurability
 	### The default implementation of the method called by ::gather_defaults when
 	### gathering configuration defaults. This method expects either a
 	### +DEFAULT_CONFIG+ or a +CONFIG_DEFAULTS+ constant to contain the configuration
-	### defaults, and will just return the +fallback+ value if neither exists. 
+	### defaults, and will just return the +fallback+ value if neither exists.
 	def defaults( fallback=nil )
 
 		return fallback unless respond_to?( :const_defined? )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: configurability
 version: !ruby/object:Gem::Version
-  version: 3.0.0.pre20161130174408
+  version: 3.0.0
 platform: ruby
 authors:
 - Michael Granger
@@ -36,7 +36,7 @@ cert_chain:
   w8aNA5re5+Rt/Vvjxj5AcEnZnZiz5x959NaddQocX32Z1unHw44pzRNUur1GInfW
   p4vpx2kUSFSAGjtCbDGTNV2AH8w9OU4xEmNz8c5lyoA=
   -----END CERTIFICATE-----
-date: 2016-12-01 00:00:00.000000000 Z
+date: 2016-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -151,7 +151,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.15'
 description: |-
-  Configurability is a unified, unintrusive, assume-nothing configuration system
+  Configurability is a unified, non-intrusive, assume-nothing configuration system
   for Ruby. It lets you keep the configuration for multiple objects in a single
   config file, load the file when it's convenient for you, and distribute the
   configuration when you're ready, sending it everywhere it needs to go with a
@@ -169,12 +169,14 @@ extra_rdoc_files:
 files:
 - ChangeLog
 - History.md
+- LICENSE
 - Manifest.txt
 - README.md
 - Rakefile
 - bin/configurability
 - examples/basicconfig.rb
 - examples/config.yml
+- examples/readme.rb
 - lib/configurability.rb
 - lib/configurability/behavior.rb
 - lib/configurability/config.rb
@@ -201,14 +203,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
-summary: Configurability is a unified, unintrusive, assume-nothing configuration system
-  for Ruby
+summary: Configurability is a unified, non-intrusive, assume-nothing configuration
+  system for Ruby
 test_files: []