configtoolkit 1.2.0 → 2.0.0

data/examples/key_value_example.dump.cfg

@@ -0,0 +1,5 @@
+production.www.num_cpus : 64
+production.www.behind_firewall : true
+production.www.os : {version <<-->> 10.0, name <<-->> Solaris}
+production.www.addresses : [http://www.designingpatterns.com, http://tokyo.designingpatterns.com]
+production.www.contains_sensitive_data : true

data/examples/key_value_example.normal1.cfg

@@ -0,0 +1,20 @@
+#
+# 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]
+############################################################
+
+#
+# Include a second configuration from a different file.
+# Note that the path to the second file is relative to
+# *this* file (they are in the same directory).
+#
+*include key_value_example.normal2.cfg

data/examples/key_value_example.normal2.cfg

@@ -0,0 +1,15 @@
+#
+# This file contains MachineConfig configurations
+# (see examples/machineconfig.rb for the configuration's specification).
+#
+
+############################################################
+# Second configuration (nested in the production.www
+# containing object).  Note how all of the keys are prefixed
+# with production.www in order to indicate that they are
+# within the production.www containing object.
+production.www.num_cpus = 64
+production.www.os = {name => Solaris, version => 10.0}
+production.www.contains_sensitive_data = yes
+production.www.addresses = [http://www.designingpatterns.com, http://tokyo.designingpatterns.com]
+############################################################

data/examples/key_value_example.rb

@@ -0,0 +1,72 @@
+#!/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/keyvaluereader'
+require 'configtoolkit/keyvaluewriter'
+
+#
+# The key-value format used by this file is the default format.
+#
+NORMAL_CONFIGURATION_FILE = 
+  File.expand_path_relative_to_caller("key_value_example.normal1.cfg")
+
+#
+# The first configuration has no containing object name.
+#
+reader = ConfigToolkit::KeyValueReader.new(NORMAL_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 is contained in a different
+# file that the first file includes.
+#
+reader = ConfigToolkit::KeyValueReader.new(NORMAL_CONFIGURATION_FILE)
+second_config = MachineConfig.load(reader, "production.www")
+print("The second config:\n#{second_config}\n")
+
+#
+# Configure a new, admittedly wacky, key-value format.
+# Note how the block passed to the constructor initializes
+# only a few of the KeyValueConfig parameters; the other
+# parameters will be assigned their default values.
+#
+key_value_config = ConfigToolkit::KeyValueConfig.new() do |config|
+  config.key_value_delimiter = ":"
+  config.comment_line_prefix = ";"
+  config.hash_key_value_delimiter = "<<-->>"
+end
+
+#
+# Read the first configuration from a file containing it in the new
+# format.
+#
+WACKY_CONFIGURATION_FILE = 
+  File.expand_path_relative_to_caller("key_value_example.wacky.cfg")
+reader = ConfigToolkit::KeyValueReader.new(WACKY_CONFIGURATION_FILE,
+                                           key_value_config)
+first_config = MachineConfig.load(reader)
+print("The first config sourced from a different key-value format:\n")
+print("#{first_config}\n")
+
+#
+# Write second_config in the new format to a string stream, the contents
+# of which will be printed.
+#
+string_stream = StringIO.new()
+writer = ConfigToolkit::KeyValueWriter.new(string_stream, key_value_config)
+second_config.dump(writer)
+print("The second configuration dumped to a new key-value file format:\n")
+print("#{string_stream.string}")

data/examples/key_value_example.wacky.cfg

@@ -0,0 +1,13 @@
+;
+; This file contains MachineConfig configurations
+; (see examples/machineconfig.rb for the configuration's specification).
+;
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+; First configuration, but with a wacky format
+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]
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

data/examples/load_example.rb

@@ -0,0 +1,32 @@
+#!/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'
+
+CONFIGURATION_FILE = File.expand_path_relative_to_caller("load_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.
+#
+reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+second_config = MachineConfig.load(reader, "production.www")
+print("The second config:\n#{second_config}\n")

data/examples/load_example.yaml

@@ -0,0 +1,34 @@
+#
+# 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 is a containing object
+production:
+# production.www is a containing object
+  www:
+############################################################
+# Second configuration (nested in the production.www
+# containing object)
+    num_cpus: 64
+    os:
+      name: Solaris
+      version: 10.0
+    contains_sensitive_data: yes
+    addresses:
+      - http://www.designingpatterns.com
+      - http://tokyo.designingpatterns.com
+############################################################

data/examples/load_group_example.rb

@@ -0,0 +1,28 @@
+#!/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'
+
+CONFIGURATION_FILE =
+ File.expand_path_relative_to_caller("load_group_example.yaml")
+
+#
+# The group of configurations is under the db_cluster containing
+# object name.
+#
+reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+configs = MachineConfig.load_group(reader, "db_cluster")
+configs.each do |name, config|
+  print "The #{name} configuration:\n#{config}\n"
+end

data/examples/load_group_example.yaml

@@ -0,0 +1,33 @@
+#
+# This file contains MachineConfig configurations
+# (see examples/machineconfig.rb for the configuration's specification).
+#
+
+db_cluster:
+  db1:
+    num_cpus: 16
+    os:
+      name: Solaris
+      version: 10.0
+    contains_sensitive_data: yes
+    behind_firewall: yes
+    addresses:
+      - http://db1.designingpatterns.com
+  db2:
+    num_cpus: 12
+    os:
+      name: AIX
+      version: 5.3
+    contains_sensitive_data: yes
+    behind_firewall: yes
+    addresses:
+      - http://db2.designingpatterns.com
+  db3:
+    num_cpus: 24
+    os:
+      name: Solaris
+      version: 10.0
+    contains_sensitive_data: yes
+    behind_firewall: yes
+    addresses:
+      - http://db3.designingpatterns.com

data/examples/machineconfig.rb

@@ -0,0 +1,77 @@
+require 'rubygems'
+require 'configtoolkit'
+
+require 'uri'
+
+#
+# This configuration class is nested within MachineConfig (below).
+# All configuration classes must descend from ConfigToolkit::BaseConfig.
+#
+class OSConfig < ConfigToolkit::BaseConfig
+  add_required_param(:name, String)
+  add_required_param(:version, Float)
+end
+
+#
+# This configuration class is used in all of the example programs.
+# Since it is a configuration class, it descends from
+# ConfigToolkit::BaseConfig.
+#
+class MachineConfig < ConfigToolkit::BaseConfig
+  #
+  # This is a required parameter with extra user-specified validation
+  # (that :num_cpus > 0 must be true)
+  #
+  add_required_param(:num_cpus, Integer) do |value|
+    if(value <= 0)
+      raise_error("num_cpus must be greater than zero")
+    end
+  end
+
+  #
+  # This required parameter is itself a BaseConfig instance; BaseConfig
+  # instances can be nested within each other.
+  #
+  add_required_param(:os, OSConfig)
+  
+  #
+  # This is a required boolean parameter.  Note that Ruby does not
+  # have a boolean type (it has a TrueClass and a FalseClass), so use
+  # a marker class (ConfigToolkit::Boolean) to indicate that
+  # the parameter will have boolean values (true and false).
+  # Boolean values can be written as "true"/"false" or as
+  # "yes"/"no" in configuration files.
+  #
+  add_required_param(:contains_sensitive_data, ConfigToolkit::Boolean)
+
+  #
+  # The behind_firewall parameter is optional and has a default value of
+  # true, which means that it will be set to the true if not explicitly set
+  # by a configuration file.
+  #
+  add_optional_param(:behind_firewall, ConfigToolkit::Boolean, true)
+
+  #
+  # The primary_contact parameter is optional and has no default value, which
+  # means that it will be absent if not explicitly set by a configuration file.
+  #
+  add_optional_param(:primary_contact, String)
+  
+  #
+  # This parameter's values are guaranteed to be Arrays with URI elements.
+  #
+  add_required_param(:addresses, ConfigToolkit::ConstrainedArray.new(URI))
+
+  #
+  # This method is called by load() after loading values for
+  # all parameters from a specified configuration and can enforce
+  # constraints between different parameters.  In this case, this method
+  # ensures that all machines containing sensitive data are behind
+  # the firewall.
+  #
+  def validate_all_values
+    if(contains_sensitive_data && !behind_firewall)
+      raise_error("only machines behind firewalls can contain sensitive data")
+    end
+  end
+end

data/examples/ruby_example.rb

@@ -0,0 +1,32 @@
+#!/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")

data/examples/ruby_example.rcfg

@@ -0,0 +1,52 @@
+#
+# 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")
+                                  ]

data/examples/usage_example.rb

@@ -0,0 +1,93 @@
+#!/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'
+
+#
+# If new() is passed a block, the block *must* initialize all
+# required parameters (otherwise a ConfigToolkit::Error will
+# be thrown).  Optional parameters to not need to be
+# explicitly initialized, however.  If a default value was
+# specified for an uninitialized optional parameter, the 
+# optional parameter will be set to the default value after
+# the block (the behind_firewall parameter is an example of this below);
+# otherwise, the default value will have no value
+# (the primary_contact parameter is an example of this below).
+#
+config = MachineConfig.new() do |config|
+  config.num_cpus = 8
+  config.os = OSConfig.new() do |os_config|
+    os_config.name = "Solaris"
+    os_config.version = 10.0
+  end
+  config.contains_sensitive_data = true
+  config.addresses = [URI("http://www.designingpatterns.com"),
+                      URI("http://jackfruit.designingpatterns.com")]
+end
+
+#
+# Note in the output that the behind_firewall parameter is true, its
+# default value, because it was not initialized in the block above.
+# Also note that the primary_contact parameter is not present.
+#
+print "Config after initialization:\n#{config}\n"
+
+#
+# Each parameter has a predicate method (automatically generated by
+# add_required_param or add_optional_param) that returns whether or not
+# the parameter has a value.
+#
+if(!config.primary_contact?)
+  #
+  # This will be printed...
+  #
+  print "Optional primary_contact parameter is NOT set!\n"
+end
+
+#
+# Each parameter has getter and setter accessor methods (automatically
+# generated by add_required_param or add_optional_param), just like
+# "normal" attributes.
+#
+config.primary_contact = "Tony"
+print("primary_contact parameter set to: #{config.primary_contact}\n")
+
+if(config.primary_contact?)
+  #
+  # This will be printed...
+  #
+  print "Optional primary_contact parameter is now IS set!\n\n"
+end
+
+#
+# Note in the output that the primary_contact parameter *now* is present.
+#
+print "Config after setting optional primary_contact parameter:\n#{config}\n"
+
+#
+# Each optional parameter has a clear method (automatically generated by
+# add_optional_param) that deletes the parameter's value.
+#
+config.clear_primary_contact()
+
+if(!config.primary_contact?)
+  #
+  # This will be printed...
+  #
+  print "Optional primary_contact parameter has been deleted!\n\n"
+end
+
+#
+# Note in the output that the primary_contact parameter once again
+# is absent.
+#
+print "Config after deleting the primary_contact parameter:\n#{config}\n"