configtoolkit 1.2.0 → 2.0.0

data/Rakefile

@@ -1,13 +1,11 @@
 # -*- ruby -*-
 
-$LOAD_PATH.unshift("lib")
-
 require 'rubygems'
 require 'hoe'
 
-$stderr = STDERR
-
-Hoe.new('configtoolkit', "1.2.0") do |p|
+Hoe.new('configtoolkit', "2.0.0") do |p|
+  p.extra_deps << ['relative', '>= 1.0.0']
+  p.extra_deps << ['assertions', '>= 1.0.0']
   p.remote_rdoc_dir = ''
   p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
 end

data/Ruby.txt

@@ -0,0 +1,172 @@
+== RUBY CONFIGURATION FILES:
+What could be better than configuring Ruby programs with Ruby
+configuration files, harnessing the full power of Ruby for
+configuration?  The ConfigToolkit::RubyReader supports a Ruby
+configuration file format that allows configurations to leverage the
+expressiveness of the Ruby language in a way that's more natural than
+programatically initializing the configuration (via the
+ConfigToolkit::HashReader, for instance).
+
+Ruby configuration files essentially are key-value configuration files
+parsed by the Ruby interpreter; they allow the full Ruby language to
+be used while building up a configuration.  Parameters are specified
+by +config.param_name+ or +config.containing_object.param_name+.  They
+can be assigned to and, after assignment, used in other expressions.
+If a name first is referred to with a setter (i.e., +age+ in
+<code>config.first.second.age = 5</code>), then the name is assumed to
+be a parameter name.  If a name first is referred to with a getter
+(i.e., +first+ and +second+ in <code>config.first.second.age =
+5</code>), then the name is assumed to be an object name (either a
+containing or a nested configuration object).  Objects cannot be set
+(i.e., <code>config.first.second = 2</code> is illegal).  Parameter
+values, once set, can be referenced in later expressions.
+
+No +RubyWriter+ class is provided, since the strength of the format is
+supporting dynamic expressions that calculate configuration values,
+and any configuration file output by a writer only could consist of
+static expressions.
+
+== EXAMPLE:
+This is a Ruby configuration file:
+======+examples/ruby_example.rcfg+:
+ #
+ # This file contains MachineConfig configurations
+ # (see examples/machineconfig.rb for the configuration's specification).
+ #
+ 
+ require 'uri'
+ 
+ config.num_cpus = 32
+ 
+ #
+ # Note how the members of the nested OSConfig
+ # can be set by first referring to "os" and then to the
+ # desired member (i.e., config.os.name).  config.os
+ # also could have been set with a Hash (see below
+ # for an example).
+ #
+ config.os.name = "AIX"
+ config.os.version = 5.3
+ 
+ config.behind_firewall = false
+ 
+ #
+ # Notice how the behind_firewall value can be referenced
+ # in the contains_sensitive_data value assignment, since
+ # it was set above.
+ #
+ config.contains_sensitive_data = config.behind_firewall
+ config.addresses = [
+                     URI("http://default.designingpatterns.com"),
+                     URI("http://apple.designingpatterns.com")
+                    ]
+ 
+ #
+ # A trivial example of using a Ruby expression to calculate
+ # a parameter value.
+ #
+ config.production.www.num_cpus = 32 + 16 + 8 + 4 + 2 + 1 + 1
+ 
+ #
+ # Note that here the nested OSConfig is being set with a Hash (the
+ # configuration above sets the OSConfig parameters individually).
+ #
+ config.production.www.os = {
+   :name => "Solaris",
+   :version => 10.0
+ }
+ 
+ config.production.www.contains_sensitive_data = true
+ config.production.www.addresses = [
+                                    URI("http://www.designingpatterns.com"),
+                                    URI("http://tokyo.designingpatterns.com")
+                                   ]
+
+This program loads the two configurations in the file:
+======+examples/ruby_example.rb+:
+ #!/usr/bin/env ruby
+ 
+ #
+ # These example programs use the 'relative' gem in order to
+ # express paths relative to __FILE__ cleanly, allowing them to be run from
+ # any directory.  In particular, they use the require_relative
+ # method to load examples/machineconfig.rb and
+ # File.expand_path_relative_to_caller in order to refer to
+ # configuration files within the examples directory.
+ #
+ require 'rubygems'
+ require 'relative'
+ require_relative 'machineconfig'
+ 
+ require 'configtoolkit/rubyreader'
+ 
+ CONFIGURATION_FILE = File.expand_path_relative_to_caller("ruby_example.rcfg")
+ 
+ #
+ # The first configuration has no containing object name.
+ #
+ reader = ConfigToolkit::RubyReader.new(CONFIGURATION_FILE)
+ first_config = MachineConfig.load(reader)
+ print("The first config:\n#{first_config}\n")
+ 
+ #
+ # The second configuration has "production.www" as a containing
+ # object name.
+ #
+ reader = ConfigToolkit::RubyReader.new(CONFIGURATION_FILE)
+ second_config = MachineConfig.load(reader, "production.www")
+ print("The second config:\n#{second_config}\n")
+
+When run, it produces the following output:
+======The output of <code>examples/ruby_example.rb</code>:
+ The first config:
+ {
+     os                     : {
+         name   : AIX
+         version: 5.3
+     }
+     behind_firewall        : false
+     num_cpus               : 32
+     addresses              : [
+         http://default.designingpatterns.com,
+         http://apple.designingpatterns.com
+     ]
+     contains_sensitive_data: false
+ }
+ 
+ The second config:
+ production.www: {
+     os                     : {
+         name   : Solaris
+         version: 10.0
+     }
+     behind_firewall        : true
+     num_cpus               : 64
+     addresses              : [
+         http://www.designingpatterns.com,
+         http://tokyo.designingpatterns.com
+     ]
+     contains_sensitive_data: true
+ }
+ 
+
+
+== FUTURE DIRECTIONS:
+The Ruby configuration language could be improved in several ways.  Firstly,
+it could provide better support for arrays.  For instance, the following
+configuration file is invalid right now:
+ config.array_param[0] = 3
+In the future, the parser automatically could detect that +array_param+ is
+an array and allow array elements to be set.
+
+In addition, the following configuration file also is invalid right now:
+ config.array_param = []
+ config.array_param[0].fixnum_param = 3
+ config.array_param[0].string_param = "hello"
+That is, array elements could support object notation.  Right now, this would
+have to be written with Hashes:
+ config.array_param = []
+ config.array_param[0] = {:fixnum_param => 3, :string_param => "hello"}
+
+We would love feedback and suggestions from the community about future
+directions for this configuration language!

data/YAML.txt

@@ -0,0 +1,188 @@
+== YAML CONFIGURATION FILES:
+YAML is a clean, flexible data representation language that easily can
+represent complicated configurations.  It natively supports simple
+types (integers, floats, strings, booleans), and, since Ruby supports
+serialization of objects to YAML, Ruby's YAML library supports
+representing objects of virtually any type in YAML.  Support for YAML
+is available for many programming languages, making it attractive for
+configurations that must be read by several different languages.
+
+The ConfigToolkit::YAMLReader and ConfigToolkit::YAMLWriter allow
+configurations to be loaded from and dumped to YAML files.
+
+== EXAMPLE:
+The parameter values in YAML configuration files can be native YAML
+types (strings, integers, floats, booleans, etc.) and also can be
+serialized Ruby classes.  The following configuration file
+demonstrates this:
+======+examples/yaml_example.yaml+:
+ #
+ # This file contains MachineConfig configurations
+ # (see examples/machineconfig.rb for the configuration's specification).
+ #
+ 
+ ############################################################
+ # First configuration
+ num_cpus: 32
+ os:
+   name: AIX
+   version: 5.3
+ behind_firewall: no
+ contains_sensitive_data: no
+ addresses:
+   - http://default.designingpatterns.com
+   - http://apple.designingpatterns.com
+ ############################################################
+ 
+ production:
+ ############################################################
+ # Second configuration (nested in the production.www
+ # containing object).  Note that the elements of the
+ # addresses parameter array are expressed
+ # not as strings, as in the first configuration, but rather
+ # as serialized Ruby URI instances.  The YAMLReader class
+ # can read both, and the YAMLWriter class can
+ # output values of either only YAML native types or of serialized Ruby
+ # classes.
+   www:
+     contains_sensitive_data: true
+     addresses: 
+     - !ruby/object:URI::HTTP 
+       fragment: 
+       host: www.designingpatterns.com
+       opaque: 
+       password: 
+       path: ""
+       port: 80
+       query: 
+       registry: 
+       scheme: http
+       user: 
+     - !ruby/object:URI::HTTP 
+       fragment: 
+       host: tokyo.designingpatterns.com
+       opaque: 
+       password: 
+       path: ""
+       port: 80
+       query: 
+       registry: 
+       scheme: http
+       user: 
+     os: 
+       name: Solaris
+       version: 10.0
+     num_cpus: 64
+     behind_firewall: true
+ ############################################################
+
+The first configuration is written with only native YAML types
+while the second configuration is written with serialized Ruby URI
+classes (the +addresses+ parameter).  If the YAML file is to be read
+by multiple languages, then only native YAML types should be used in
+the file; FAQ.txt discusses how the ConfigToolkit converts YAML
+strings to some Ruby types (Pathnames, URIs, Symbols, etc.).  The following
+program shows how this example YAML configuration file can be loaded,
+and how a configuration can be written as a YAML file:
+======+examples/yaml_example.rb+:
+ #!/usr/bin/env ruby
+ 
+ #
+ # These example programs use the 'relative' gem in order to
+ # express paths relative to __FILE__ cleanly, allowing them to be run from
+ # any directory.  In particular, they use the require_relative
+ # method to load examples/machineconfig.rb and
+ # File.expand_path_relative_to_caller in order to refer to
+ # configuration files within the examples directory.
+ #
+ require 'rubygems'
+ require 'relative'
+ require_relative 'machineconfig'
+ 
+ require 'configtoolkit/yamlreader'
+ require 'configtoolkit/yamlwriter'
+ 
+ CONFIGURATION_FILE = File.expand_path_relative_to_caller("yaml_example.yaml")
+ 
+ #
+ # The first configuration has no containing object name.
+ #
+ reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ first_config = MachineConfig.load(reader)
+ print("The first config:\n#{first_config}\n")
+ 
+ #
+ # The second configuration has "production.www" as a containing
+ # object name.  Note that the second configuration
+ # reprents the URI elements of the addresses parameter array
+ # as Ruby URI classes, leveraging Ruby's ability to unserialize
+ # objects from YAML.
+ #
+ reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ second_config = MachineConfig.load(reader, "production.www")
+ print("The second config:\n#{second_config}\n")
+ 
+ #
+ # Write second_config to a string stream, which then is written to
+ # stdout.  Pass true as the second argument to new in order to specify that
+ # the writer only should write native YAML types (Strings, integers, floats,
+ # booleans, etc.).
+ #
+ string_stream = StringIO.new()
+ writer = ConfigToolkit::YAMLWriter.new(string_stream, true)
+ second_config.dump(writer)
+ print("The second configuration written in YAML with native YAML types:\n")
+ print("#{string_stream.string}")
+
+Note that the ConfigToolkit::YAMLWriter can dump parameter values with only
+native YAML types or with serialized Ruby classes, depending on the second
+argument passed to the ConfigToolkit::YAMLWriter.new method.  If a
+ConfigToolkit::YAMLWriter is instructed to use only native YAML types to
+express parameter values, it will use the +to_s+ method to convert all
+parameter values that are not of a native YAML type to strings.  When run, the
+program produces:
+======The output of <code>examples/yaml_example.rb</code>:
+ The first config:
+ {
+     num_cpus               : 32
+     addresses              : [
+         http://default.designingpatterns.com,
+         http://apple.designingpatterns.com
+     ]
+     contains_sensitive_data: false
+     os                     : {
+         version: 5.3
+         name   : AIX
+     }
+     behind_firewall        : false
+ }
+ 
+ The second config:
+ production.www: {
+     num_cpus               : 64
+     addresses              : [
+         http://www.designingpatterns.com,
+         http://tokyo.designingpatterns.com
+     ]
+     contains_sensitive_data: true
+     os                     : {
+         version: 10.0
+         name   : Solaris
+     }
+     behind_firewall        : true
+ }
+ 
+ The second configuration written in YAML with native YAML types:
+ --- 
+ production: 
+   www: 
+     addresses: 
+     - http://www.designingpatterns.com
+     - http://tokyo.designingpatterns.com
+     os: 
+       name: Solaris
+       version: 10.0
+     behind_firewall: true
+     num_cpus: 64
+     contains_sensitive_data: true
+

data/examples/hash_example.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+#
+# These example programs use the 'relative' gem in order to
+# express paths relative to __FILE__ cleanly, allowing them to be run from
+# any directory.  In particular, they use the require_relative
+# method to load examples/machineconfig.rb and
+# File.expand_path_relative_to_caller in order to refer to
+# configuration files within the examples directory.
+#
+require 'rubygems'
+require 'relative'
+require_relative 'machineconfig'
+
+require 'configtoolkit/hashreader'
+require 'configtoolkit/hashwriter'
+
+#
+# The first configuration has no containing object name.
+#
+config_hash = {
+  :num_cpus => 32,
+  :os => {
+    :name => "AIX",
+    :version => 5.3
+  },
+  :behind_firewall => false,
+  :contains_sensitive_data => false,
+  :addresses => [
+                 URI("http://default.designingpatterns.com"),
+                 URI("http://apple.designingpatterns.com")
+                ]
+}
+reader = ConfigToolkit::HashReader.new(config_hash)
+first_config = MachineConfig.load(reader)
+print("The first config:\n#{first_config}\n")
+
+#
+# The second configuration has "production.www" as a containing
+# object name and therefore the configuration is mapped to by
+# :www in a Hash, which in turn is mapped to by :production
+# in a containing Hash.
+#
+config_hash = {
+  :production => {
+    :www => {
+      :num_cpus => 64,
+      :os => {
+        :name => "Solaris",
+        :version => 10.0
+      },
+      :contains_sensitive_data => true,
+      :addresses => [
+                     URI("http://www.designingpatterns.com"),
+                     URI("http://tokyo.designingpatterns.com")
+                    ]
+    }
+  }
+}
+reader = ConfigToolkit::HashReader.new(config_hash)
+second_config = MachineConfig.load(reader, "production.www")
+print("The second config:\n#{second_config}\n")
+
+#
+# After the call to dump, the config_hash instance member of the HashWriter
+# instance contains the Hash representation of second_config.
+#
+writer = ConfigToolkit::HashWriter.new()
+second_config.dump(writer)
+print("The Hash dumped from the second config:\n")
+print("#{writer.config_hash.inspect}\n")