##
 #
 # A scriptable configuration file is a configuration file that is
 # actually a Ruby script.  Or maybe it's a Ruby script that's really a
 # configuration file in disguise.  Either way, this is a powerful
 # combination.
 #
 # The ScriptableConfig class is used to evaluate a Ruby script and
 # generate a data structure that holds the configuration information
 # contained in the Ruby script.  The format for such a Ruby script looks
 # like this:
 #
 # <tt>
 #   section_name {
 #     option_name parameter
 #     another_var_name another_param
 #   }
 # </tt>
 #
 # All configuration elements are set through method calls (in the above
 # example, section_name and option_name are actually method calls --
 # remember that parens are optional in Ruby).  Options are set through
 # methods that take parameters; sections are created through methods
 # that take a block as a parameter.
 #
 # Every ScriptableConfig object is created with a template that
 # describes which configuration options and sections are valid.  This
 # template is a Hash that maps the name of the option/section to a
 # factory that creates configuration elements.
 #
 # There are a few basic types of standard elements: Option, Section, and
 # SectionTable.  Read the class-specific documentation for more
 # information about each.  It is possible to create user-defined element
 # types; see the source for an example of how to do this.
 #
 # Example:
 #
 # <tt>
 #  module ConfigTemplate
 #    extend ScriptableConfig::Template
 #    Tmpl = {
 #      :foo => Option(),
 #      :bar => Option(RequireType(String)),
 #      :point => SectionTable ({
 #        :x => Option(RequireType(Numeric)),
 #        :y => Option(RequireType(Numberic))
 #      })
 #    }
 #  end
 #  c = Config.new(ConfigTemplate::Tmpl)
 #  c.read_file("config.rb")
 #  c.validate()
 # </tt>
 #
 class ScriptableConfig
 public
   ##
   # The Template module holds the standard configuration templates.
   #
   module Template
     ##
     # Specifies a configuration option.  Configuration options are
     # standard Ruby objects, and are set in the configuration file by
     # calling a method, e.g.:
     #
     # <tt>
     #   magic_number 42
     # </tt>
     #
     # Produces a key-value pair:
     #
     # <tt>
     #   :magic_number => 42
     # </tt>
     #
     # (this key-value pair will be part of a Hash or other structure
     # when the configuration file is read)
     #
     # The validator is a proc that does a sanity check on the object.
     # The default is nil, which means no validation.
     #
     def Option(validator=nil)
       return OptionFactory.new(validator)
     end
     module_function :Option
 
     ##
     # RequireType returns a proc that checks an object to make sure it
     # is the given type.  It can be used to generate a validator for an
     # option.
     #
     def RequireType(type)
       return proc { |obj| 
         if not obj.kind_of?(type) then
           raise TypeError, "Expecting #{type}; got #{obj.class}"
         end
       }
     end
 
     ##
     # Specifies a configuration section.  Configuration sections are
     # Hashes mapping an option name to a configuration element.  They
     # are set in the configuration file by passing a block to a method,
     # e.g.:
     #
     # <tt>
     #   server_info {
     #     name "httpd"
     #     listen_port 80
     #     listen_address Socket::INADDR_ANY
     #   }
     # </tt>
     #
     # Produces a key-value pair where the value is a Hash:
     #
     # <tt>
     #   :server_info => {
     #     :name => "http",
     #     :listen_port => 80,
     #     :listen_address => Socket::INADDR_INY
     #   }
     #
     def Section(template)
       return SectionFactory.new(template)
     end
     module_function :Section
 
     ##
     # Specifies a table of configuration sections.  A section table is a
     # Hash of configuration sections.  For example:
     #
     # <tt>
     #   interface("eth0") {
     #     address "192.168.1.1"
     #     firewall_enabled false
     #   }
     #   interface("eth1") {
     #     address "10.0.0.0"
     #     firewall_enabled true
     #   }
     # </tt>
     #
     # Produces:
     #
     # <tt>
     #   :interface => {
     #     :eth0 => {
     #       :address => "192.168.1.1",
     #       :firewall_enabeld => false
     #     },
     #     eth1 => {
     #       :address => "10.0.0.0",
     #       :firewall_enabled => true
     #     }
     #   }
     # </tt>
     #
     def SectionTable(template)
       return SectionTableFactory.new(template)
     end
     module_function :SectionTable
   end
 
   class AlreadyExists < StandardError; end
   class InvalidOption < StandardError; end
   class OptionUnset < StandardError; end
 
   ##
   # Create a new ScriptableConfig, using the provided template.
   #
   def initialize(template)
     @template = template
     @reader = SectionReader.new(template)
   end
 
   ##
   # Read the specified configuration file.  The resulting configuration
   # is a Hash, mapping names to a configuration elements, and can be
   # accessed with the config() method.  The 
   #
   def read_file(filename)
     File.open(filename) do |input|
       read_str(input.read, filename)
     end
   end
 
   ##
   # Read str as if it were a configuration file.
   #
   def read_str(str, filename=nil)
     filename ,= caller[0].split(':') if not filename
     @reader.instance_eval(str, filename)
   end
 
   ##
   # Return the configuration read by read_file() or read_str().
   #
   def config
     return @reader.members
   end
 
   ##
   # Return a string representation of the current configuration.
   #
   def to_s
     s = "#{self.class.name} {\n"
     @template.each do |k, v|
       s << INDENT_STR << k.to_s << " => "
       s << v.stringify(@reader.members[k], 2) << "\n"
     end
     s << "}\n"
     return s
   end
 
   ##
   #
   # Returns true if a configuration is valid (all required fields are
   # set), or raises an exception if the configuration is invalid.
   #
   # Most errors will be caught when the configuration file is read, but
   # those errors that are not will be caught here.
   #
   def validate
     @template.each do |k, v|
       obj = @reader.members.fetch(k) do
         raise OptionUnset, "Unset: #{k} (#{v.class})"
       end
       v.validate(obj, k)
     end
     return true
   end
 
 private
   ##
   # An OptionFactory creates options.  An option can be any Ruby object.
   #
   class OptionFactory
     def initialize(validator)
       @validator = validator
     end
 
     def create(orig, *args, &block)
       raise AlreadyExists, "Option already set" if orig
       raise ArgumentError, "Cannot pass block to option" if block
       @validator.call(*args) if @validator
       return args.size == 1 ? args[0] : args
     end
 
     def stringify(obj, indent)
       return obj.inspect
     end
 
     def validate(obj, name)
       return true
     end
   end
 
 
   ##
   # A SectionReader is a helper class that is used to read a section.
   #
   class SectionReader
     attr_reader :members
 
     def initialize(template)
       @template = template
       @members = {}
     end
 
     def method_missing(m, *args, &block)
       if @template[m] then
         @members[m] = @template[m].create(@members[m], *args, &block)
       else
         raise InvalidOption, "No such configuration option #{m}"
       end
     end
   end
 
   ##
   # A SectionFactory creates sections (which, presently, are Hashes).
   #
   class SectionFactory
     def initialize(template)
       @template = template
     end
 
     def create(orig, &block)
       raise AlreadyExists, "Section already created" if orig
       section_reader = SectionReader.new(@template)
       section_reader.instance_eval(&block)
       return section_reader.members
     end
 
     def stringify(section, indent)
       s = "{\n"
       section.each do |k, v|
         s << INDENT_STR * indent << k.to_s << " => "
         s << @template[k].stringify(v, indent + 1) << "\n"
       end
       s << INDENT_STR * (indent - 1) << "}"
       return s
     end
 
     def validate(section, name)
       @template.each do |k, v|
         obj = section.fetch(k) do
           raise OptionUnset, "Unset: #{name}:#{k} (#{v.class})"
         end
         v.validate(obj, "#{name}:#{k}")
       end
       return true
     end
   end
 
   ##
   # A SectionTableFactory creates tables (hashes) of sections.
   #
   class SectionTableFactory
     def initialize(template)
       @template = template
       @section_factory = SectionFactory.new(template)
     end
 
     def create(orig, item, &block)
       table = orig || Hash.new
       section = @section_factory.create(nil, &block)
       table[item] = section
       return table
     end
 
     def stringify(table, indent)
       s = "{\n"
       table.each do |section_id, section|
         s << INDENT_STR * indent << section_id.to_s << " => "
         s << @section_factory.stringify(section, indent + 1) << "\n"
       end
       s << INDENT_STR * (indent - 1) << "}"
       return s
     end
 
     def validate(table, name)
       table.each do |section_id, section|
         @section_factory.validate(section, "#{name}(#{section_id})")
       end
       return true
     end
   end
 
   INDENT_STR = "  "
 end
 
 if __FILE__ == $0 then
   module ConfigTemplate
     extend ScriptableConfig::Template
     Tmpl = {
       :foo => Option(),
       :bar => Option(RequireType(String)),
       :point => SectionTable ({
         :x => Option(RequireType(Fixnum)),
         :y => Option(RequireType(Fixnum))
       })
     }
   end
   c = ScriptableConfig.new(ConfigTemplate::Tmpl)
   c.read_file("config.rb")
   c.validate()
   puts c
 end