configtoolkit 1.0.7 → 1.1.0

data/FAQ.txt

@@ -0,0 +1,55 @@
+=== Why can't I use a normal Ruby Array rather than a ConstrainedArray in my configuration's specification?
+You can, but you probably don't want to.  Actually, underneath, the
+ConfigToolkit converts Array parameters into ConstrainedArray parameters with
+no constraints (<code>ConstrainedArray.new(Object, nil, nil)</code>).
+If you do this and therefore don't specify an element class constraint
+for the array, the ConfigToolkit will accept *any* value for an element
+of the array.  If this really is what you want, then go wild!
+
+=== When are the parameter values of a configuration class validated?
+Every time a parameter's setter is called, the new value is validated
+against the parameter's specification in order to ensure that it is
+of the proper class (or can be converted to the proper class) *before* the
+parameter is set.  In addition, if a custom validation block was specified
+for the paramater, then this is called with the new value *before*
+the paramter is set.  Since all parameter values loaded from a file (during
+the load method) are set with parameter setters, all values loaded from
+a file receive this validation.
+
+In addition, after a load operation and before a dump operation, the
+configuration is checked in order to ensure that all required parameters have
+been set.  If an optional parameter is found that has not been set, then
+it is set with its associated default value.  Finally, the validate_all_values
+method is called if it exists.
+
+The above ensures that parameters are set with only valid values, and that
+the configuration as a whole is valid right after load and right before
+dump operations.
+
+=== How/why does the ConfigToolkit convert parameter values from Strings to other classes?
+Relatively complex languages like YAML support typed data.  Simple
+configuration formats like key/value pairs, however, do not support typed data;
+every parameter value is read as a String.  Since the ConfigToolkit *knows* the
+specified class of a parameter value, however, it can attempt to convert the
+String to the specified class.  Unfortunately, Ruby does not have a standard
+way to convert Strings to other classes (whereas it does have a standard way to
+convert classes into Strings, the to_s method).  So, the ConfigToolkit does
+the best that it can and provides this conversion for the most common
+types:
+* Integers
+* Floats
+* Booleans
+* Symbols
+* Pathnames
+* URIs
+This support hopefully should cover 99.9% of parameters.  If you think that
+additional types should be supported, either particular standard types or
+arbitrary types via some kind of extension mechanism, please feel free to
+request the enhancement.
+
+=== What kind of nesting is supported by the ConfigToolkit?
+ConfigToolkit::BaseConfig child classes can be nested as parameters
+within other ConfigToolkit::BaseConfig child classes arbitrarily deep.  In
+addition, one can have ConfigToolkit::ConstrainedArray parameters with
+ConfigToolkit::BaseConfig element classes (an array of configuration objects
+as a parameter).

data/History.txt

@@ -1,3 +1,6 @@
+=== 1.1.0 / 2008-05-14
+Finish the README.txt; this is the first production release!
+
 === 1.0.7 / 2008-05-13
 Finish the code comments and code cleanup.
 

data/Manifest.txt

@@ -3,6 +3,7 @@ LICENSE
 README.txt
 History.txt
 Rakefile
+FAQ.txt
 lib/configtoolkit.rb
 lib/configtoolkit/baseconfig.rb
 lib/configtoolkit/toolkit.rb

data/README.txt

@@ -1,27 +1,75 @@
 = configtoolkit
 
-* http://configtoolkit.rubyforge.org/
+Project Page: http://rubyforge.org/projects/configtoolkit/
 
 == DESCRIPTION:
 
 This package makes sourcing information from configuration files robust
 and easy!  It:
-* Allows programmers to specify the type of data that should be returned
+* Allows programmers to specify the type of data that should be loaded
   from a configuration file.  The toolkit automatically will validate
   the file's data against this specification when loading the file, ensuring
-  that the specifications always are met and saving the programmer the tedious
-  chore of writing validation code.
-* Allows programmers to easily programatically create and dump new
-  configuration files.
+  that the specification always is obeyed and saving the programmer the
+  tedious chore of writing validation code.
+* Automagically generates parameter accessor methods, an equality operator,
+  and a to_s method from the configuration's specification.
+* Allows programmers to create configuration files,
+  easily and programatically.
 * Provides classes that can load from and dump to different kinds of
-  configuration files, including YAML configuration files.
-
-== FEATURES/PROBLEMS:
+  configuration files.
+* Is very extensible, allowing the engine to be used with custom format
+  configuration files and with custom data validation rules.
+
+== FEATURES:
+
+* The ConfigToolkit allows programmers to define a new configuration class by
+  specifying the parameters that are included in the configuration.  A
+  parameter specification consists of the class of the parameter's values,
+  whether or not the paramater is required, and a default value if the
+  parameter is not required.
+* Getter and setter methods automatically are added to a new configuration
+  class for each specified parameter.
+* An equality operator exists for each configuration class that
+  determines equality based on whether all parameter values are equal.
+* A to_s method that produces very pretty output exists for each
+  configuration class.
+* Programmers can specify custom validation blocks for each parameter, in
+  order to enforce specifications not directly supported by the engine.
+* Programmers can define a method in a configuration class that will be
+  called in order to enforce relationships between the values of different
+  parameters.
+* Programmers can create custom reader and writer classes in order to
+  load from and dump to (respectively) configuration file formats not
+  directly supported by the ConfigToolkit.
+* Configuration classes can be nested to any depth within each other.
+* Configuration classes have first class support for Array configuration
+  parameters.  Constraints can be specified for a given Array parameter that
+  will ensure that all elements of a value are of a
+  specified class and that there are a specified number of elements in
+  a value.
+* The ConfigToolkit supports multiple configurations stored
+  in a single file; it is able to distinguish that different configurations
+  within a file belong to different configuration objects.  For example,
+  "production" and "test" configuration information can live within the
+  same configuration file and can be loaded into separate configuration
+  instances.
+* A reader class to read YAML configuration files is included in the
+  Configtoolkit.
+* A writer class to dump YAML configuration files is included in the
+  Configtoolkit.
+* The ConfigToolkit includes a full unit testing suite.
+* The ConfigToolkit code has detailed comments.
+
+== PROBLEMS:
 
 None (known).
 
 == SYNOPSIS:
 
+This is a sample configuration class:
+  require 'rubygems'
+  require 'configtoolkit'
+
   class MachineConfig < ConfigToolkit::BaseConfig
     add_required_param(:name, String)
 
@@ -48,12 +96,121 @@ None (known).
     end
   end
 
-  This code creates a configuration class for a company's servers.  The
-  programmer specifies each of the parameters (the parameter's type, whether
-  the parameter is required, and a default value if the parameter is optional).
+This code creates a configuration class for a company's servers.  The
+programmer specifies each of the parameters (the parameter's class, whether
+the parameter is required, and a default value if the parameter is optional).
+
+The programmer also specifies a method (<code>validate_all_values</code>)
+that enforces an invariant between multiple parameters.  This will be called
+by the ConfigToolkit at the end of a load or at the start of a dump operation.
+
+A custom validation block is specified for the <code>num_cpus</code> parameter;
+the ConfigToolkit engine does not have direct support for
+checking specifications like "the value must be greater than zero", but these
+conditions easily can be added by the programmer.  Such blocks are
+called by the engine before the configuration parameter is set to the new
+value and are executed in the context of the configuration class instance.
+If there is a problem with the new value, the block should call
+<code>ConfigToolkit::BaseConfig#raise_error</code>.
+
+A ConfigToolkit::Boolean class is specified for the
+<code>behind_firewall</code> and <code>contains_sensitive_data</code>
+parameters.  Ruby does not have a standard boolean
+class (although it does have TrueClass and FalseClass, for boolean values), and
+so the ConfigToolkit provides a marker class for boolean values.  The value
+of a parameter specified with ConfigToolkit::Boolean either is true or false.
+
+A <code>ConfigToolkit::ConstrainedArray.new(URI, 2, 3)</code> class is
+specified for the <code>addresses</code> parameter.  A
+ConfigToolkit::ConstrainedArray class simply specifies that the
+parameter value will be an Array that obeys the
+constraints contained in the ConfigToolkit::ConstrainedArray.  In this
+case, the constraints ensure that all Array elements are of class URI,
+that the Array has at least two elements, and that the Array has at most
+three elements.
+
+The following machines.yaml file contains two MachineConfig configurations:
+  name: apple
+  architecture: powerpc
+  os: AIX
+  num_cpus: 32
+  behind_firewall: no
+  contains_sensitive_data: no
+  addresses:
+    - http://default.designingpatterns.com
+    - http://apple.designingpatterns.com
+
+  production:
+    tokyo:
+      name: orange
+      architecture: ultrasparc
+      os: Solaris
+      num_cpus: 64
+      contains_sensitive_data: yes
+      addresses:
+        - http://production.designingpatterns.com
+        - http://orange.designingpatterns.com
+
+The first configuration in the file:
+  name: apple
+  architecture: powerpc
+  os: AIX
+  num_cpus: 32
+  behind_firewall: no
+  contains_sensitive_data: no
+  addresses:
+    - http://default.designingpatterns.com
+    - http://apple.designingpatterns.com
+can be loaded into a MachineConfig instance like this:
+  require 'rubygems'
+  require 'configtoolkit'
+  require 'configtoolkit/yamlreader'
+
+  config = MachineConfig.load(ConfigToolkit::YAMLReader.new("machines.yaml"))
+
+The second configuration:
+  production:
+    tokyo:
+      name: orange
+      architecture: ultrasparc
+      os: Solaris
+      num_cpus: 64
+      contains_sensitive_data: yes
+      addresses:
+        - http://production.designingpatterns.com
+        - http://orange.designingpatterns.com
+can be loaded by specifying a "containing object" in the load call.
+A containing object simply is an object in a configuration file within
+which a config object is stored.  In this case, the containing
+object is "production.tokyo".  So:
+  require 'rubygems'
+  require 'configtoolkit'
+  require 'configtoolkit/yamlreader'
+
+  config = MachineConfig.load(ConfigToolkit::YAMLReader.new("machines.yaml"), "production.tokyo")
+will load the second configuration in machines.yaml.
+
+A MachineConfig instance can be dumped like this:
+  require 'rubygems'
+  require 'configtoolkit'
+  require 'configtoolkit/yamlreader'
+  require 'configtoolkit/yamlwriter'
+
+  config = MachineConfig.load(ConfigToolkit::YAMLReader.new("machines.yaml"))  
+  config.dump(ConfigToolkit::YAMLWriter.new("apple.yaml", true))
+
+This will produce the following apple.yaml:
+  --- 
+  name: apple
+  contains_sensitive_data: false
+  addresses: 
+  - http://default.designingpatterns.com
+  - http://apple.designingpatterns.com
+  os: AIX
+  architecture: powerpc
+  num_cpus: 32
+  behind_firewall: false
 
-  The programmer also specifies a method (validate_all_valus) that enforces
-  an invariant between multiple parameters.
 == REQUIREMENTS:
 
 Hoe is required, but only for running the tests.
@@ -62,6 +219,20 @@ Hoe is required, but only for running the tests.
 
 sudo gem install configtoolkit
 
+== AUTHORS:
+
+Designing Patterns: http://www.designingpatterns.com
+
+Share and Enjoy!
+
+== SUPPORT
+
+Please post questions, concerns, or requests for enhancement to the forums on
+the project page.  Alternatively, direct contact information for
+Designing Patterns can be found on the project page for this gem.
+Please discuss any enhancements with the authors (Designing Patterns)
+before doing any work.
+
 == LICENSE:
 
 See LICENSE, at the root of the distribution.

data/Rakefile

@@ -7,8 +7,8 @@ require 'hoe'
 
 $stderr = STDERR
 
-Hoe.new('configtoolkit', "1.0.7") do |p|
-  p.remote_rdoc_dir = 'rdoc'
+Hoe.new('configtoolkit', "1.1.0") do |p|
+  p.remote_rdoc_dir = ''
   p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
 end
 

data/lib/configtoolkit/baseconfig.rb

@@ -195,6 +195,15 @@ class BaseConfig
     @param_spec_list.push(param_spec)
     @param_spec_lookup_table[name] = param_spec
 
+    #
+    # Convert Array value classes into ConstrainedArrays with
+    # no constraints.  This makes supporting Arrays much easier, since
+    # they can share a code base with ConstrainedArrays.
+    #
+    if(value_class == Array)
+      value_class = ConstrainedArray.new(Object, nil, nil)
+    end
+
     #
     # Define the getter and setter methods with a string passed to
     # class_eval rather than a block, so as to avoid the need to access

data/test/readerwritertest.rb

@@ -8,8 +8,7 @@ require 'uri'
 
 class SampleSecondNestedConfig < ConfigToolkit::BaseConfig
   add_required_param(:req_second_nested_pathname, Pathname)
-  add_required_param(:req_second_nested_array,
-                     ConfigToolkit::ConstrainedArray.new(Integer, 2, 2))
+  add_required_param(:req_second_nested_array, Array)
 end
 
 class SampleNestedConfig < ConfigToolkit::BaseConfig

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: configtoolkit
 version: !ruby/object:Gem::Version 
-  version: 1.0.7
+  version: 1.1.0
 platform: ruby
 authors: 
 - DesigningPatterns
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-05-14 00:00:00 -04:00
+date: 2008-05-15 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -21,7 +21,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 1.5.1
     version: 
-description: "This package makes sourcing information from configuration files robust and easy!  It: * Allows programmers to specify the type of data that should be returned from a configuration file.  The toolkit automatically will validate the file's data against this specification when loading the file, ensuring that the specifications always are met and saving the programmer the tedious chore of writing validation code. * Allows programmers to easily programatically create and dump new configuration files. * Provides classes that can load from and dump to different kinds of configuration files, including YAML configuration files."
+description: "This package makes sourcing information from configuration files robust and easy!  It: * Allows programmers to specify the type of data that should be loaded from a configuration file.  The toolkit automatically will validate the file's data against this specification when loading the file, ensuring that the specification always is obeyed and saving the programmer the tedious chore of writing validation code. * Automagically generates parameter accessor methods, an equality operator, and a to_s method from the configuration's specification. * Allows programmers to create configuration files, easily and programatically. * Provides classes that can load from and dump to different kinds of configuration files. * Is very extensible, allowing the engine to be used with custom format configuration files and with custom data validation rules."
 email: 
 - technical.inquiries@designingpatterns.com
 executables: []
@@ -32,12 +32,14 @@ extra_rdoc_files:
 - Manifest.txt
 - README.txt
 - History.txt
+- FAQ.txt
 files: 
 - Manifest.txt
 - LICENSE
 - README.txt
 - History.txt
 - Rakefile
+- FAQ.txt
 - lib/configtoolkit.rb
 - lib/configtoolkit/baseconfig.rb
 - lib/configtoolkit/toolkit.rb
@@ -56,7 +58,7 @@ files:
 - test/sample.standard_yaml_classes.yaml
 - test/webserver.yaml
 has_rdoc: true
-homepage: http://configtoolkit.rubyforge.org/
+homepage: "Project Page: http://rubyforge.org/projects/configtoolkit/"
 post_install_message: 
 rdoc_options: 
 - --main
@@ -81,7 +83,7 @@ rubyforge_project: configtoolkit
 rubygems_version: 1.0.1
 signing_key: 
 specification_version: 2
-summary: "This package makes sourcing information from configuration files robust and easy!  It: * Allows programmers to specify the type of data that should be returned from a configuration file"
+summary: "This package makes sourcing information from configuration files robust and easy!  It: * Allows programmers to specify the type of data that should be loaded from a configuration file"
 test_files: 
 - test/test_baseconfig.rb
 - test/test_yaml.rb