yacl 1.0.0

data/lib/yacl/loader/yaml_dir.rb

@@ -0,0 +1,137 @@
+require 'yacl/loader/yaml_file'
+class Yacl::Loader
+  # YamlDir uses a directory of yaml files to load a Properties instance.
+  # It does so as if the entire directory were one big yaml file.
+  #
+  # Examples:
+  #
+  # Given the following directory structure -
+  #
+  #   ./config
+  #   ├── database.yml
+  #   ├── httpserver.yml
+  #   └── pipeline.yml
+  #
+  # And Creating a YamlDir instance -
+  #
+  #   yd    = YamlDir.new( :path => "./config" )
+  #
+  # Then you will have propertes like these.
+  #
+  #   props = yd.properties
+  #
+  #   props.dataabase.adapter # => postgre
+  #   props.httpserver.port   # => 80
+  #
+  # You may also create a YamlDir and have it use the propety from a Properites
+  # instance to indicate the directory to load from.
+  #
+  #   other_props.config.dir   # => ./config
+  #
+  #   yd = YamlDir.new( :properties => other_props, :parameter => 'config.dir' )
+  #
+  #   props = yd.properties
+  #   props.dataabase.adapter # => postgre
+  #   props.httpserver.port   # => 80
+  #
+  # This latter approach use what is used when incorparting a commandline option
+  # of a configuration directory within a Plan and the loading of the
+  # configuration directory after the pipeline is parsed.
+  #
+  #   class MyPlan < ::Yacl::Define::Plan
+  #     try MyApp::Cli::Parser
+  #     try Yacl::Loader::YamlDir, :parameter => 'config.dir'
+  #   end
+  #
+  # Since this use of YamlDir is part of a Plan, the Plan will pass in the
+  # Properties accumulated so far to YamlDir
+  #
+  class YamlDir < ::Yacl::Loader
+    class Error < ::Yacl::Loader::Error; end
+
+    # Public: Create a new instance of YamlDir
+    #
+    # opts - A Hash of options
+    #        :path       - The filesystem path to the directory to load
+    #        :properties - A Properties instance to use in conjunction with
+    #                      :parameter
+    #        :pararmeter - The parameter to look up within the Properties that
+    #                      passed in with :properites in order to populate
+    #                      :path
+    #        :scope      - Scope the loded Properties by this value and only
+    #                      return that subset from #properties
+    #
+    def initialize( opt = {} )
+      super
+      @path      = YamlDir.extract_path( options )
+      @parameter = YamlDir.mapify_key( options[:parameter] )
+
+      if (not @path) and (reference_properties and @parameter) then
+        value = reference_properties.get( *@parameter )
+        @path = Pathname.new( value ) if value
+      end
+
+      @scope     = options[:scope]
+      YamlDir.validate_directory( @path )
+    end
+
+    # Public: Return the Properites that are described by the this YamlDir
+    # instance
+    #
+    # Returns a Properties instance
+    def properties
+      YamlDir.validate_and_load_properties( @path, @scope )
+    end
+
+    class << self
+
+      # Internal: Validate the directory and then load the properties.
+      #
+      # dirname - The directory from which to load properties
+      # scope   - Apply the given scope to the loaded properties
+      #
+      # Returns a Properties instance.
+      def validate_and_load_properties( dirname , scope = nil )
+        validate_directory( dirname )
+        YamlDir.load_properties( dirname, scope )
+      end
+
+      # Internal: Validate the given directory.
+      #
+      # path - the Pathname to check.
+      #
+      # 1) make sure it is not nil
+      # 2) make sure that it exists
+      # 3) make sure that it is a directory
+      #
+      # Raise an error if any of the above fail
+      #
+      # Returns nothing.
+      def validate_directory( path )
+        raise Error, "No directory specified" unless path
+        raise Error, "#{path} does not exist" unless path.exist?
+        raise Error, "#{path} is not a directory" unless path.directory?
+      end
+
+      # Interal: Load the proprerties scoped by the given scope
+      #
+      # dirname - The directory from which to load properties
+      # scope   - Apply the given scope to the loaded properties
+      #
+      # Returns a Properties instance.
+      def load_properties( dirname, scope )
+        p = Yacl::Properties.new
+        Dir.glob( File.join( dirname, '*.yml') ).each do |config_fname|
+          file_properties = Yacl::Loader::YamlFile.new( :path => config_fname ).properties
+          namespace       = File.basename( config_fname, ".yml" )
+          file_properties.each do |k,v|
+            args = [ namespace, k ].flatten
+            args << v
+            p.set( *args )
+          end
+        end
+        return p
+      end
+    end
+  end
+end

data/lib/yacl/loader/yaml_file.rb

@@ -0,0 +1,102 @@
+require 'yaml'
+class Yacl::Loader
+  # YamlFile loads a Properites instance from a single yaml file.
+  #
+  # Examples:
+  #
+  #   yd = YamlFile.new( :filename => "./config/database.yml" )
+  #   props = yd.properties
+  #   props.adapter #=> 'postgres'
+  #
+  # You may also create a YamlFile and have it use the propety from a Properites
+  # instance to indicate the directory to load from.
+  #
+  #   other_props.config.file # => ./config/database.yml
+  #
+  #   yd = YamFile.new( :properties => other_props, :parameter => 'config.file' )
+  #
+  #   props = yd.properties
+  #   props.adapter # => postgre
+  #
+  class YamlFile < ::Yacl::Loader
+    class Error < ::Yacl::Loader::Error; end
+
+    def initialize( opts = {} )
+      super
+      @path      = YamlFile.extract_path( options )
+      @scope     = options.fetch( :scope, nil )
+      @parameter = YamlFile.mapify_key( options[:parameter] )
+
+      if (not @path) and (reference_properties and @parameter) then
+        @path = Pathname.new( reference_properties.get( *@parameter ) )
+      end
+
+
+      YamlFile.validate_file( @path )
+    end
+
+    def properties
+      YamlFile.validate_and_load_properties( @path, @scope )
+    end
+
+    class << self
+      # Internal: load a Properties from the given filename.
+      #
+      # filename - The name of the yaml file to load
+      # scope    - scope the loaded Properties by the given scope
+      #
+      # Returns a Properties instance.
+      def validate_and_load_properties( filename, scope = nil )
+        validate_file( filename )
+        YamlFile.load_properties( filename, scope )
+      end
+
+      # Internal: Validate that the give Pathname is a valid, readable file
+      #
+      # path - the Patname we are going to check
+      #
+      # Validates:
+      #
+      # 1) that path has a value
+      # 1) that the path exists
+      # 2) that the path is readable
+      #
+      # Raises an error if either of the above failes
+      def validate_file( path )
+        raise Error, "No path specified" unless path
+        raise Error, "#{path} does not exist" unless path.exist?
+        raise Error, "#{path} is not readable" unless path.readable?
+      end
+
+      # Internal: load a Properties from the given filename.
+      #
+      # filename - The name of the yaml file to load
+      # scope    - scope the loaded Properties by the given scope
+      #
+      # Returns a Properties instance.
+      def load_properties( filename, scope )
+        loaded = ::YAML.load_file( filename )
+        raise Error, "#{filename} does not contain a top level hash" unless loaded.kind_of?( Hash )
+
+        p = Yacl::Properties.new( loaded )
+        return scoped( p, scope, filename )
+      end
+
+      # Internal: scope the given Properties that are loaded from the given
+      # filename.
+      #
+      # p        - The Properties to scope by scope
+      # scope    - The scope to apply to p
+      # filename - The filename from which Properties was loaded
+      #
+      # Raises Error if the scope does not exist
+      #
+      # Returns a new Properties instance.
+      def scoped( p, scope, filename )
+        return p unless scope
+        raise Error, "#{filename} does not contain a top level scope of '#{scope}'. Options are #{p.scopes.join(", ")}" unless p.has_scope?( scope )
+        return p.scoped_by( scope )
+      end
+    end
+  end
+end

data/lib/yacl/properties.rb

@@ -0,0 +1,144 @@
+require 'forwardable'
+require 'set'
+require 'map'
+
+module Yacl
+  # Properties is a wrapper around keys and values that are part of a
+  # Configuration. This is just the keys and the values, it does not tie it to
+  # where the data comes from.
+  #
+  # The properties interface is a limited subset of the Hash interface.
+  #
+  # Properties may also be accessed via a dotted method call location
+  #
+  # Example:
+  #
+  #   p = Properties.new(  'my.a' => 'foo', 'my.b' => 'bar' )
+  #   p.my.a #=> 'foo'
+  #   p.my.b #=> 'bar'
+  #   p.my   #=> Properties
+  #
+  #
+  class Properties
+    extend Forwardable
+
+    # Internal: returns the list of methods to delegate to the internal Map
+    # instance
+    #
+    # Returns an Array of method names
+    def self.delegating_to_map
+      [ :set, :get, :fetch, :store, :delete, :clear, :[], :[]=, :has?, :has_key?, :each, :length, :keys, :method_missing ]
+    end
+
+    # Internal: Returns the list of methods that may be delegated to a
+    # Properties instance.
+    #
+    # Returns an Array of method names
+    def self.delegatable_methods
+      delegating_to_map + [ :scoped_by, :scopes, :has_scope? ]
+    end
+
+    # Internal: Delegate methods to the internal Map instance
+    def_delegators :@map, *Properties.delegating_to_map
+
+    # Internal: used only for merging
+    #
+    # Returns the internal Map instances
+    attr_reader :map
+
+    # Create a new Properites
+    #
+    # initial - A Hash or Map that is used as the initial values of the
+    #           Properites
+    #
+    def initialize( initial = {} )
+      @map = Map.new
+      expanded_keys( initial ) do |k,v|
+        k << v
+        @map.set( *k )
+      end
+    end
+
+    # Public: Mereg another Properties instance on top of this one, overwriting
+    # any commaon key/values.
+    #
+    # This is a destructive operation on this Properties instance.
+    #
+    # other - The Properties instance to lay on top of this one.
+    #
+    # Returns nothing
+    def merge!( other )
+      @map.merge!( other.map )
+    end
+
+    # Public: Return a new Properties that is a subset of the properties with the first
+    # prefix removed.
+    #
+    # scope - the scope under which to use
+    #
+    # Returns a new Properties object
+    def scoped_by( *scope )
+      scope = scope.length == 1 ? scope.first : scope
+      sub_map = @map.get( expand_key( scope ) ) || {}
+      Properties.new( sub_map )
+    end
+
+    # Public: List the knownn scops, i.e. top level keys, of the current
+    # Properitess.
+    #
+    # Returns an Array
+    def scopes
+      scope_names.to_a.sort
+    end
+
+    # Public: Return true or false if the Properites instance has the given
+    # scope.
+    #
+    # Returns true or false.
+    def has_scope?( scope )
+      scope_names.include?( scope )
+    end
+
+    private
+
+    # Internal: The list of all scope names
+    #
+    # Returns an Array of Strings
+    def scope_names
+      keys.map { |k| k.to_s }
+    end
+
+    # Internal: Expand the hash into an Array including the multi-value key and
+    # the value.
+    #
+    # hash - the Hash to convert to an array of arrays.
+    #
+    # Yields the Array of the currenty key and the value
+    #
+    # Returns nothing.
+    def expanded_keys( hash )
+      hash.each do |k,v|
+        ek = expand_key( k )
+        yield ek, v unless ek.empty?
+      end
+    end
+
+    # Internal: Convert the given key into an Array key suitable for use with
+    # Map.set
+    #
+    # key - the Key
+    #
+    # Retursn an Array
+    def expand_key( key )
+      ek = case key
+      when Array
+        key
+      when /\./
+        key.split(".")
+      else
+        [ key ]
+      end
+      ek.select { |k| k.to_s.strip.length > 0 }
+    end
+  end
+end

data/lib/yacl/simple.rb

@@ -0,0 +1,52 @@
+module Yacl
+  class Simple < ::Yacl::Define::Cli::Runner
+    class << self
+      # Public: Create a child class of Yacl::Define::Defaults
+      #
+      # block - an optional block will be evaluated in the context of the
+      #         created class.
+      #
+      # The child class is created once, and the block is evaluated once.
+      # Further class to this method will result in returning the already
+      # defined class.
+      def defaults( &block )
+        nested_class( 'Defaults', Yacl::Define::Defaults, &block )
+      end
+
+      # Public: Creates a child class of Yacl::Define::Cli::Parser
+      #
+      # block - an optional block will be evaluated in the context of the
+      #         created class.
+      #
+      # The child class is created once, and the block is evaluated once.
+      # Further class to this method will result in returning the already
+      # defined class.
+      def parser( &block )
+        nested_class( 'Parser', Yacl::Define::Cli::Parser, &block )
+      end
+
+      # Public: Creates a child class of Yacl::Define::Plan
+      #
+      # block - an optional block will be evaluated in the context of the
+      #         created class.
+      #
+      # The child class is created once, and the block is evaluated once.
+      # Further class to this method will result in returning the already
+      # defined class.
+      def plan( &block )
+        nested_class( 'Plan', Yacl::Define::Plan, &block )
+      end
+
+      # Internal: Define a class that is a nested class of the module
+      def nested_class( name, parent, &block )
+        unless const_defined?( name ) then
+          klass = Class.new( parent )
+          klass.class_eval( &block ) if block_given?
+          const_set( name , klass )
+        end
+        return const_get( name )
+      end
+
+    end
+  end
+end

data/spec/data/yaml_dir/database.yml

@@ -0,0 +1,8 @@
+adapter: postgres
+host: 127.0.0.1
+username: myusername
+password: mypassword
+subpart:
+  foo: bar
+  baz: wibble
+

data/spec/data/yaml_dir/httpserver.yml

@@ -0,0 +1,3 @@
+port: 4321
+bind: tcp://0.0.0.0
+docroot: /usr/local/www/htdocs