configfiles 0.0.2 → 0.1.0

data/README.rdoc

@@ -0,0 +1,18 @@
+=ConfigFiles
+
+A simple library to specify the format of configuration files and the 
+way to turn their data into Ruby objects. 
+
+Ruby1.9 centric. "Lazy" to some extent and as needed. 
+
+No write support: it's strongly sugested to use ERB or other 
+templating systems for that.
+
+A good example usage is found at http:/github.com/gderosa/dansguardian.rb .
+
+==Author
+
+Copyright 2010 Guido De Rosa
+
+License: same of Ruby.
+

data/lib/configfiles/extensions/enumerable.rb

@@ -0,0 +1,5 @@
+module Enumerable
+  def list_inspect(separator=', ')
+    map{|x| x.inspect}.join(separator)
+  end
+end

data/lib/configfiles.rb

@@ -1,110 +1,259 @@
 # Copyright 2010, Guido De Rosa <guido.derosa*vemarsas.it>
 # License: same of Ruby
 
+require 'facets/enumerable/defer'
 
+require 'configfiles/extensions/enumerable'
 
 module ConfigFiles
 
-  VERSION = '0.0.2'
-
-  module Parser
-    def self.read_file(path)
-      self.read File.open path
-    end
-  end
+  VERSION = '0.1.0'
 
+  # You should write a read(io) method,
+  # taking an IO object and returnig a key-value hash, where keys
+  # are symbols, and values are Strings or Enumerable yielding Strings 
+  #
+  # This result will be passed to YourConfigClass#load,
+  # where YourConfigClass inherits from ConfigFiles::Base
   class Base
 
-    class ArgumentError < ::ArgumentError; end
-    class RuntimeError < ::RuntimeError; end
-
-    @@parameters ||= {}
-    @@options ||= {}
-
-    # examples: 
-    #   on :unknown_parameter, :fail | :accept | :ignore
-    #   on :unknown_parameter, {|str| str.to_i}
-    #
-    def self.on(name, value=nil, &block)
-      if block
-        @@options[name] = block
-      elsif name == :unknown_parameter and value == :accept
-        @@options[name] = lambda {|x| x} 
-      else
-        @@options[name] = value
+    CIRCUMSTANCES       = [:unknown_parameter, :unknown_value]
+    PREDEFINED_ACTIONS  = [:accept, :ignore, :fail]
+
+    class ArgumentError           < ::ArgumentError;  end
+    class RuntimeError            < ::RuntimeError;   end
+    class NoKeyError              < ::NameError;      end
+    class ValidationFailed        < ::RuntimeError;   end
+    class AlreadyDefinedParameter < ::Exception;      end
+    class DefaultAlreadySet       < ::Exception;      end
+    
+    AlreadyDefinedDefault = DefaultAlreadySet
+
+    @@parameters  ||= {}
+    @@behavior    ||= {
+      :unknown_parameter => :ignore,
+      :unknown_value    => :fail  # when the converter is a Hash,
+                                  # whose keys represents a fixed set
+                                  # of allowed strings, and values represents
+                                  # their "meaning", tipically as a Symbol
+    }
+    @@validate    ||= lambda {|data| true} 
+
+    class << self
+
+      # Examples: 
+      #   on :unknown_parameter, :fail # or :accept, or :ignore
+      #   on :unknown_parameter, {|str| str.to_i}
+      #
+      # There's also :unknown_value, to specify behavior when the
+      # converter is an Hash and the value found if not among the
+      # hash keys. Usage is similar.
+      #
+      def on(circumstance, action=nil, &block)
+        actions       = PREDEFINED_ACTIONS
+        circumstances = CIRCUMSTANCES
+        unless circumstances.include? circumstance
+          raise ArgumentError, "Invalid circumstance: #{circumstance.inspect}. Allowed values are #{circumstances.list_inspect}."
+        end
+        if block
+          @@behavior[circumstance] = block
+        elsif actions.include? action
+          @@behavior[circumstance] = action
+        elsif action
+          raise ArgumentError, "Invalid action: #{action}. Allowed values are #{actions.list_inspect}."
+        else
+          return @@behavior[circumstance] 
+        end
       end
-    end
 
-    def self.option(name)
-      @@options[name]
-    end
+      # +circumstance+ must be an elements of +CIRCUMSTANCES+
+      #
+      # returns an elements of +PREDEFINED_ACTIONS+ or a user-defined Proc
+      def behavior_on(circumstance); on(circumstance); end
 
-    def self.parameter(name, converter=nil, &converter_block)
-      if converter
-        if converter_block
-          raise ArgumentError, 'you must either specify a symbol or a block'
-        elsif converter.is_a? Hash
-          converter_block = lambda {|x| converter[x]} # x is a String from conf file
-        else #Symbol
-          converter_block = lambda {|x| x.method(converter).call}
+      # Add a parameter.
+      #
+      #   # keep as is
+      #   parameter :myparam 
+      #
+      #   # convert to integer
+      #   parameter :myparam, :to_i
+      #
+      #   # do some computation
+      #   parameter :myparam do |str|
+      #     ... 
+      #     ...
+      #     my_result
+      #   end
+      #
+      #   # map a set of possible/admitted values; you may call the 
+      #   # class method +on+(:unknown_value) to customize behavior
+      #   parameter :myparam,
+      #     '1' => :my_first_option,
+      #     '2' => :my_second_one
+      #
+      def parameter(name, converter=nil, &converter_block)
+        if @@parameters[name] and @@parameters[name][:converter]
+          raise AlreadyDefinedParameter, "Already defined parameter \"#{name}\""
         end
-      else
-        converter_block ||= lambda {|x| x}  
+        if converter
+          if converter_block
+            raise ArgumentError, 'you must either specify a symbol or a block'
+          elsif converter.is_a? Hash
+
+            converter_block = lambda do |x| # x is a String from conf file 
+              if converter.keys.include? x
+                return converter[x] # returns from lambda, not from method 
+              elsif @@behavior[:unknown_value] == :fail
+                raise ArgumentError, "Invalid value \"#{x}\" for parameter \"#{name}\". Allowed values are #{converter.keys.list_inspect}."
+              elsif @@behavior[:unknown_value] == :accept
+                return x
+              end
+            end 
+
+          else #Symbol
+            converter_block = lambda {|x| x.method(converter).call}
+          end
+        else
+          converter_block ||= lambda {|x| x}  
+        end
+        @@parameters[name] ||= {} 
+        @@parameters[name][:converter] = converter_block
       end
-      @@parameters[name] = {
-        :converter  => converter_block
-      }
-    end
 
-    # A special kind of parameter, with a special kind of converter, which in turn
-    # converts an Enumerator of Strings into an Enumerator of custom objects. 
-    # Working with Enumerators instead of
-    # Arrays is the right thing to do when you deal with very long list of
-    # names, IP adresses, URIs etc. 
-    def self.enumerator(name, &block)
-      parameter name do |enum|
-        Enumerator.new do |yielder|
-          enum.each do |string|
-            yielder << block.call(string) 
+      # set default value of a parameter
+      def default(name, value)
+        if @@parameters[name] and @@parameters[name][:default]
+          raise DefaultAlreadySet, "Default for \"#{name}\" has been already set (to value: #{@@parameters[name][:default]})"
+        end
+        @@parameters[name] ||= {}
+        @@parameters[name][:default] = value
+      end
+
+      # A special kind of parameter, with a special kind of converter, 
+      # which in turn
+      # converts an Enumerable yielding Strings into an Enumerator of 
+      # custom objects. You may work with Enumerators instead of
+      # Arrays , which is the right thing to do when you deal with very 
+      # long list of names, IP adresses, URIs etc (lazy evaluation) .
+      def enumerator(name, converter=nil, &converter_block)
+        if block_given?
+          raise ArgumentError, 'you must either specify a symbol or a block' if
+              converter
+        else
+          if converter # converter may be :to_i etc.
+            converter_block = lambda {|x| x.method(converter).call} 
+          else
+            converter_block = lambda {|x| x}
           end
         end
+        #parameter name do |enumerable|
+        #  Enumerator.new do |yielder|
+        #    enumerable.each do |string|
+        #      yielder << converter_block.call(string) 
+        #    end
+        #  end
+        #end
+        #
+        # Use facets instead
+        parameter name do |enumerable|
+          enumerable.defer.map{|element| converter_block.call(element)} 
+        end
       end
-    end
 
-    def self.validate(&block)
-      @@validate = block
-    end
+      # Set validaion rules. For example, if parameter 'a' must be 
+      # smaller than 'b':
+      #
+      #   validate do |confdata|  
+      #     raise ValidationFailed, "no good!" unless
+      #         confdata[:a] <= confdata[:b] 
+      #   end
+      #
+      def validate(&block)
+        @@validate = block
+      end
 
-    attr_accessor :options, :data
+    end # class << self
 
     def initialize
-      @options = @@options.dup
       @data = {}
-      def @data.missing_method(id); @data[id]; end
     end
 
+    # Validate configuration object, according to what declared 
+    # with the class method 
     def validate
-      @@validate.call(@data)
+      @@validate.call(self) 
     end
 
+    # Load the Hash h onto the ConfigFiles object, carrying on conversions
+    # to Ruby objects, validation, and default actions
+    # if needed. h's keys are Symbols, h's values are typically Strings
+    # or Enumerables yielding Strings. See also ConfigFiles::Base.parameter
+    # and ConfigFiles::Base.on.
     def load(h)
+
       h.each_pair do |id, value|
-        if @@parameters[id][:converter]
+        if @@parameters[id] and @@parameters[id][:converter]
           @data[id] = @@parameters[id][:converter].call(value)
-        elsif @options[:unknown_parameter] == :fail
+        elsif @@behavior[:unknown_parameter] == :fail
           raise RuntimeError, "unknown parameter #{key}" # otherwise ignore
-        elsif @options[:unknown_parameter].respond_to? :call
-          block = @options[:unknown_parameter]
+        elsif @@behavior[:unknown_parameter] == :accept
+          @data[id] = value
+        elsif @@behavior[:unknown_parameter].respond_to? :call
+          block = @@behavior[:unknown_parameter]
           @data[id] = block.call value
         end
       end
+
+      # assign default values to the remaining params
+      @@parameters.each_pair do |name, h| 
+        if !@data[name] and @@parameters[name][:default]
+          @data[name] = @@parameters[name][:default]
+        end
+      end
+
+      @data.merge! deferred_data
+
       validate  
     end
 
-    def flush
-      @data = {}
+    # Like Hash#[], but more rigidly! Raise an Exception on unknown
+    # key, instead of returning nil.
+    def [](key)
+      if @data.keys.include? key
+        @data[key]
+      else
+        raise NoKeyError, "unknown key '#{key}' for #{self.class}"
+      end
     end
 
-  end
+    # Like Hash#[]=, but more rigidly! New keys are not created 
+    # automagically. You should have used ConfigFiles.parameter for that.
+    def []=(key, val)
+      if @data.keys.include? key
+        @data[key] = val
+      else
+        raise NoKeyError, "uknown key '#{key}' for #{self.class}"
+      end
+    end
+
+    # Like Hash#each, iterate over parameter names and values.
+    #   conf.each{|name, value| puts "#{name} is set to #{value}"}
+    def each(&blk) 
+      @data.each(&blk)
+    end
+
+    private
 
+    def deferred_data
+      results = {} 
+      @data.each do |k, v|
+        if v.is_a? Proc
+          results[k] = v.call(@data)
+        end
+      end
+      results
+    end
+
+  end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 2
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors: 
 - Guido De Rosa
@@ -14,28 +14,42 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-02 00:00:00 +02:00
+date: 2010-09-14 00:00:00 +02:00
 default_executable: 
-dependencies: []
-
-description: "A simple library to specify the format of configuration files and the way to turn them into Ruby objects. Ruby1.9 centric. It supports lazy lists. No write support: it's strongly sugested to use ERB or other templating systems for that."
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: facets
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: "A simple library to specify the format of configuration files and the way to turn them into Ruby objects. Ruby1.9 centric. Uses some lazy evaluation. No write support: it's strongly sugested to use ERB or other templating systems for that."
 email: guido.derosa@vemarsas.it
 executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.rdoc
 files: 
-- configfiles-example.rb
+- README.rdoc
 - lib/configfiles.rb
+- lib/configfiles/extensions/enumerable.rb
 has_rdoc: true
 homepage: http://github.com/gderosa/configfiles
 licenses: []
 
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --main
+- README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -60,6 +74,6 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: A simple library to specify the format of configuration files and the way to turn them into Ruby objects.
+summary: A simple library to specify the format of configuration files and the way to turn their data into Ruby objects.
 test_files: []
 

data/configfiles-example.rb

@@ -1,86 +0,0 @@
-$LOAD_PATH.unshift 'lib'
-
-require 'pp'
-require 'ipaddr'
-require 'configfiles'
-
-class MyConfig < ConfigFiles::Base
-
-  class MyException < Exception; end
-  class MyArgumentError < ArgumentError; end
-
-  # I find more rubystic defining a "conversion"
-  # rater than statically declaring classes ;)
-  parameter :par_integer, :to_i
-  parameter :par_str # no conversion needed
-  parameter :par_custom do |s|
-    s.length 
-  end
-
-  # receive an Enumerator from Parser, and turn into another Enumerator
-  #
-  # NOTE: Enumerable#map_enum would be cool ;-)
-  #
-  # TODO: use facets Enumerable#defer? Mmm, let's try to depend
-  # just on the std lib if possible...
-  #
-  enumerator :iplist do |ipstr| 
-    IPAddr.new(ipstr)
-  end
-
-  validate do |data| 
-    raise MyArgumentError if data[:par_custom] > 100
-    raise MyException unless data[:par_str] =~ /\S+/
-    # or you may use standard exceptions....
-    true
-  end
-
-end
-
-class MyKeyValueParser 
-
-  include ConfigFiles::Parser
-
-  def self.read(io, opt_h={}) 
-    h = {}
-    io.each_line do |line|
-      key_re    = '[\w\d_\-\.]+'
-      value_re  = '[\w\d_\-\.]+'
-      if line =~ /(#{key_re})\s*=\s*(#{value_re})/ 
-        h[$1.to_sym] = $2
-      end
-    end
-    return h
-  end
-end
-
-
-class MyListSlurper
-
-  include ConfigFiles::Parser
-
-  def self.read(io, opt_h={})
-    if block_given?
-      io.each_line do |line|
-        yield line.strip if line =~ /\S/
-      end
-    else
-      enum_for :read, io
-    end
-  end
-
-end
-
-
-
-c = MyConfig.new
-
-parse_result = MyKeyValueParser.read(File.open 'keyval.conf')
-
-c.load parse_result
-
-pp c
-
-
-
-