yacl 1.0.0

data/lib/yacl/define/cli/runner.rb

@@ -0,0 +1,82 @@
+module Yacl::Define::Cli
+  # Public: The Runner class is to be used by app developers as the entry point
+  # for the commandline programs. A class that inherits from Runner is what is
+  # placed in a bin/myapp file in the project structure.
+  #
+  # The Runner is configured with the Plan to use for loading the configuratin
+  # properties and when the plan is loaded, the properties are available via the
+  # #properties method.
+  #
+  # Example:
+  #
+  #   class MyApp::Runner < Yacl::Define::Cli::Runner
+  #     plan MyApp::Plan
+  #
+  #     def run
+  #       puts properties.database.server
+  #     end
+  #   end
+  #
+  # And in your 'bin/myapp-cli' file you would have:
+  #
+  #   # automatically populate with ARGV and ENV
+  #   MyApp::Runner.go
+  #
+  #   # or be explicit
+  #   MyApp::Runner.go( ARGV, ENV )
+  #
+  class Runner
+    class Error < ::Yacl::Error; end
+
+    # Public: Execute the Runner
+    #
+    # argv - The commandline args to use (default: ARGV)
+    # env  - The enviroment hash to use  (default: ENV )
+    #
+    # It is assumed that when this method exits, the program is over.
+    #
+    # Returns nothing.
+    def self.go( argv = ARGV, env = ENV )
+      r = self.new( argv, env )
+      r.run
+    end
+
+    # Public: Define the Plan associated with this Runner.
+    #
+    # plan - A class you define that inherits from Yacl::Define::Plan
+    #
+    # Returns: the plan class if it is set, nil otherwise.
+    def self.plan( *args )
+      @plan_klass = args.first unless args.empty?
+      return @plan_klass
+    end
+
+    # Internal: Initalize the Runner.
+    #
+    # argv - The commandline args to use (default: ARGV)
+    # env  - The enviroment hash to use  (default: ENV )
+    #
+    # This method should be avoided by end users, they should call #go instead.
+    def initialize( argv = ARGV, env = ENV )
+      raise Error, "No plan class specified in #{self.class}" unless self.class.plan
+      @plan = plan_klass.new( :argv => argv, :env => env )
+    end
+
+    # Public: Access the Properties instance that is created by the Plan. This
+    # is the fully realized Properties of the plan and should be considered
+    # read-only.
+    #
+    # Returns a Properties instance.
+    def properties
+      @plan.properties
+    end
+
+    # Internal: return the Plan class defined for this Runner class
+    #
+    # Returns a Plan class
+    def plan_klass
+      self.class.plan
+    end
+  end
+end
+

data/lib/yacl/define/defaults.rb

@@ -0,0 +1,58 @@
+module Yacl::Define
+  # Public: A base class for use in defining your application's default
+  # configuration properties.
+  #
+  # For the API purposes, classes that inherit from Defaults may behave as
+  # both Loader and Properties classes.
+  #
+  # Examples:
+  #
+  #   class MyDefaults < Yacl::Define::Defaults
+  #     default 'host.name', 'localhost'
+  #     default 'host.port', 4321
+  #   end
+  #
+  # Now you can use an instances of MyDefaults to find your defaults
+  #
+  #   d = MyDefaults.new
+  #   d.host.name               # => 'localhost'
+  class Defaults
+    class Error< ::Yacl::Error; end
+    extend Forwardable
+
+    # Internal: Create the instance of Properties that will be populated by
+    # calls to Properties::default.
+    #
+    # Returns: Properties
+    def self.properties
+      @properties ||= ::Yacl::Properties.new
+    end
+
+    # Public: Define a property and its value.
+    #
+    # name  - The String name of the property.
+    # value - The obj to be the default value for the given name.
+    #
+    # Returns nothing.
+    def self.default( name, value )
+      args = name.to_s.split('.')
+      args << value
+      properties.set( *args )
+    end
+
+    # Behave as if we are an instance of Properties
+    def_delegators :@properties, *Yacl::Properties.delegatable_methods
+
+    # Internal: Return the Properties so we behave like a Loader
+    attr_reader :properties
+
+    # Internal: Fake out being a Loader.
+    #
+    # This method is here to implement the LoaderAPI
+    #
+    # Returns nothing.
+    def initialize( opts = {} )
+      @properties = self.class.properties
+    end
+  end
+end

data/lib/yacl/define/plan.rb

@@ -0,0 +1,197 @@
+module Yacl::Define
+  # Public: The Plan is the order an method by which the Properties of your
+  # application are loaded and looked up. This is a base class from which you
+  # will define your Property lookups.
+  #
+  # Example:
+  #
+  #   class MyPlan < Yacl::Define::Plan
+  #     try MyApp::Cli::Parser
+  #     try Yacl::Loader::Env, :prefix => 'MY_APP'
+  #     try Yacl::Loader::YamlDir, :parameter => 'config.dir'
+  #     try MyApp::Defaults
+  #
+  #     on_error do |exception|
+  #       $stderr.puts "ERROR: #{exception}"
+  #       $stderr.puts "Try --help for help"
+  #       exit 1
+  #     end
+  #   end
+  #
+  # This creates a class MyPlan that when utilized by a Runner loads properties
+  # in the following cascading order:
+  #
+  # 1) Commandline is parsed and converted to Properties, these have the highest
+  #    priority
+  # 2) The environemtn variables are used, only those that start with 'MY_APP'
+  #    as the variable prefix. These have the 2nd higest priority
+  # 3) A configuration directory is loaded, using the 'config.dir' parameter
+  #    that comes from either (1) or (2). Properties found in this config dir
+  #    hve the 3rd highest priority
+  # 4) Built in defaults if the property is not found any any of the previous
+  #    locations.
+  #
+  class Plan
+    class Error < ::Yacl::Error; end
+
+    # Internal: An internal class used to encapsulate the individual items of
+    # the lookup plan.
+    class Item
+      # Internal: Create a new Item. Thiis is what is created from a call to
+      # Plan.try
+      def initialize( klass, options )
+        @loader_klass = klass
+        @options      = options
+      end
+
+      # Internal: load hte properties from the given Loader class
+      #
+      # Returns a Properties instance
+      def load_properties( params )
+        opt    = @options.merge( params )
+        loader = @loader_klass.new( opt )
+        loader.properties
+      end
+    end
+
+    class << self
+      # Public: Add the given Loader child class or Loader duck-type class to the
+      # definition of the Plan.
+      #
+      # klass   - A Class that implements the Loader API.
+      # options - A Hash that will be passed to klass.new() when the klass is
+      #           initialized
+      #
+      # Example:
+      #
+      #     try Yacl::Loader::YamlDir, :parameter => 'config.dir'
+      #
+      # Returns nothing.
+      def try( klass , options = {} )
+        items << Item.new( klass, options )
+      end
+
+      # Public: Define a callable to be invoked should an error happen while
+      # loading the properties of your application.
+      #
+      # callable - the Callable to be invoked.
+      #
+      # Example:
+      #
+      #   on_error( Proc.new{ fail "kaboom!" } )
+      #
+      #   on_error do
+      #     raise "Kaboom!"
+      #   end
+      #
+      # Return the callable if no parameters are given and the callable is
+      # defined.
+      #
+      # Raises an error if no parameters are given and the callable is NOT
+      # defined.
+      #
+      def on_error( callable = nil, &block )
+        if callable then
+          @on_error = callable
+        elsif block_given?
+          @on_error =  block
+        elsif defined? @on_error
+          return @on_error
+        else
+          raise Error, "on_error requires the use of a callable or a block"
+        end
+      end
+
+      # Internal: Test to see if this class has an on_error callable defined.
+      #
+      # Returns true or false if the on_error is defined.
+      def has_on_error?
+        defined? @on_error
+      end
+
+      # Internal: Return the array of Items that are used in the child class
+      # definition.
+      #
+      # Returns: an Array of Items
+      def items
+        @items ||= []
+      end
+    end
+
+    # Internal: Return the array of Items defined for this class
+    #
+    # Returns an Array of Items.
+    def items
+      self.class.items
+    end
+
+    # Public: Return the Properties instance that results from instantiating the
+    # Plan.
+    #
+    # Returns an Properties instance.
+    attr_reader :properties
+
+    # Public: Create a new instance of the Plan. This should be invoked via
+    # #super in a child class.
+    #
+    def initialize( params = {} )
+      initial_properties = params[:initial_properties] || Yacl::Properties.new
+      @properties = load_properties( initial_properties, params, items )
+    rescue Yacl::Error => ye
+      if self.class.has_on_error? then
+        self.class.on_error.call( ye )
+      else
+        raise ye
+      end
+    end
+
+    #######
+    private
+    #######
+
+    # Internal: Create the Proprites from an initial properties, a set of params
+    # and the list of Items in the class.
+    #
+    # initial_properties - a blank Properties, or an initialized Properties
+    #                      instance to use as the highest priority properties
+    # params             - A Hash that will be passed to each Item when it is
+    #                      loaded.
+    # items              - An Array of Item instances
+    #
+    # The properties are loaded in definitiaion order, that is the order they
+    # appear in the class definition. The initial properties are recalculated on
+    # each iteration as the next Properties may use some information from the
+    # previous Properties to load itself.
+    #
+    # The final Properties that is returned is a merging of all the loaded
+    # properties in reverse order from the bottom to the top. This results in
+    # the last Item defined with #try being the "bottom" property with the last
+    # priority. It may be overwritten by any of the Properties that are loaded
+    # from higher in the loader stack
+    #
+    # Returns a Properties instance.
+    def load_properties( initial_properties, params, items )
+      loaded_properties = [ initial_properties ]
+      items.each do |item|
+        properties_so_far = merge_properties( loaded_properties )
+        item_params       = params.merge( :properties => properties_so_far )
+        loaded_properties << item.load_properties( item_params )
+      end
+      return merge_properties( loaded_properties )
+    end
+
+    # Internal: Merge a list of Properties instances in the reverse order of the
+    # Array in which they exist
+    #
+    # properties_list - an Array of Properties
+    #
+    # Returns a Properties instances.
+    def merge_properties( properties_list )
+      props = ::Yacl::Properties.new
+      properties_list.reverse.each do |p|
+        props.merge!( p )
+      end
+      return props
+    end
+  end
+end

data/lib/yacl/loader.rb

@@ -0,0 +1,80 @@
+require 'pathname'
+module Yacl
+  # Loader - the base class of all Loaders. It defines the Loader API>
+  #
+  # The Loader API is:
+  #
+  #   1) The initializer method takes an Hash. This hash is stored in the
+  #      @options and is avaialble to all child clasess via the #options
+  #      method.
+  #
+  #   2) The #properties method takes no parameters and MUST return a Properties
+  #      instance
+  #
+  #   3) If the options passed into the initializer has a :reference_properites
+  #      key, its value is made available via the #reference_properties method.
+  #
+  # Loader also provides a couple of utility methods for use by child classes.
+  #
+  class Loader
+    class Error < ::Yacl::Error; end
+
+    # Internal: The options object this loader is associated with
+    attr_reader :options
+
+    # Create a new instance of the Loader
+    #
+    # opts - as Hash of options. Well known options are:
+    #        :properties - A Properties object
+    #        :path       - A directory/file path
+    #
+    def initialize( opts = {} )
+      @options = opts
+    end
+
+    # Internal:
+    #
+    # Load the properties according to the type of loader it is
+    #
+    # Returns: Properties
+    def properties
+      Properties.new
+    end
+
+    # Internal:
+    #
+    # The properties that are passed in to use should we need them while loading
+    #
+    # Returns: properties
+    def reference_properties
+      @options[:properties]
+    end
+
+    # Internal: Return param split on "."
+    #
+    # This will only be done if param is a String
+    #
+    # Returns an Array or param
+    def self.mapify_key( param )
+      return param unless param.kind_of?( String )
+      return param.split('.')
+    end
+
+    # Internal: Extract the value from :path and covert it to a Pathname
+    # If a :path key is found, then extract it and convert the value to a
+    # Pathname
+    #
+    # options - a Hash
+    # key     = the key to extract as a path (default: 'path')
+    #
+    # Returns a Pathname or nil.
+    def self.extract_path( options, key = 'path' )
+      ps = options[key.to_sym] || options[key.to_s]
+      return nil unless ps
+      return Pathname.new( ps )
+    end
+  end
+end
+require 'yacl/loader/env'
+require 'yacl/loader/yaml_file'
+require 'yacl/loader/yaml_dir'

data/lib/yacl/loader/env.rb

@@ -0,0 +1,103 @@
+class Yacl::Loader
+  # Env loads a Configuration object from a hash, generally this would be ENV.
+  #
+  # The keys in the hash may be filtered by a prefix. For instance if you had
+  # keys in the hash of :
+  #
+  #   MY_APP_OPTION_A => 'foo'
+  #   MY_APP_OPTION_B => 'bar'
+  #
+  # And you wanted to have those loaded so they were accessible as
+  # option.a and option.b you would use Loader::Env like:
+  #
+  # Example:
+  #
+  #   properties = Yacl::Loader::Env.new( ENV, 'MY_APP' ).properties
+  #   properties.option.a # => 'foo'
+  #   properties.option.b # => 'bar'
+  #
+  class Env < ::Yacl::Loader
+    class Error < ::Yacl::Loader::Error; end
+
+    # Create a new Env instance from the loaded options
+    #
+    # opts - a hash of options:
+    #        :env => The environment has to pass in (default: ENV). required.
+    #        :prefix => the prefix to strip off of each key in the :env hash. required.
+    #
+    def initialize( opts = {} )
+      super
+      @env    = @options.fetch( :env, ENV )
+      @prefix = @options.fetch( :prefix, nil )
+      raise Error, "No environment variable prefix is given" unless @prefix
+    end
+
+    # Public: return the Properties that are created from the environment hash.
+    #
+    # Returns a Properties instance
+    def properties
+      load_properties( @env, @prefix )
+    end
+
+    private
+
+    # Internal: given a hash, and a key prefix, convert the hash into a
+    # Properties instance.
+    #
+    # env    - a Hash of environment variables
+    # prefix - a String of indicated the prefix of keys in env that are to be
+    #          stripped off
+    def load_properties( env, prefix )
+      dot_env     = convert_to_dotted_keys( env )
+      dot_prefix  = to_property_path( prefix )
+      prefix_only = prefix_keys_only( dot_prefix, dot_env )
+      p           = Yacl::Properties.new( prefix_only )
+      p           = p.scoped_by( dot_prefix ) if dot_prefix
+      return p
+    end
+
+    # Internal: Return a new Hash that has only those key/values where the key
+    # is prefixed with the given prefix item.
+    #
+    # prefix - a string to compare against the keys of the hash
+    # hash   - the hash to return a subset from
+    #
+    # Returns a Hash.
+    def prefix_keys_only( prefix, hash)
+      only = {}
+      hash.each do |k,v|
+        only[k] = v if k =~ /#{prefix}/
+      end
+      return only
+    end
+
+    # Internal: Take the input Hash, convert all the keys to a dotted notation
+    # and return the new hash.
+    #
+    # The returnd hash will have keys that have been converted using
+    # #to_property_path
+    #
+    # hash - the hash to convert
+    #
+    # Returns a hash.
+    def convert_to_dotted_keys( hash )
+      converted = {}
+      hash.each do |k,v|
+        dot_k = to_property_path( k )
+        converted[dot_k] = v
+      end
+      return converted
+    end
+
+    # Internal: Convert the input String to a property style. The String is
+    # downcased and all _ are converted to .
+    #
+    # name - the String to convert
+    #
+    # Returns the converted String.
+    def to_property_path( name )
+      return nil unless name
+      name.downcase.gsub('_','.')
+    end
+  end
+end