yacl 1.0.0

data/example/myapp-simple/config/database.yml

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

data/example/myapp-simple/config/host.yml

@@ -0,0 +1,2 @@
+port: 4321
+address: 0.0.0.0

data/example/myapp-simple/config/pipeline.yml

@@ -0,0 +1 @@
+dir: /tmp/foo/bar

data/example/myapp-simple/lib/myapp.rb

@@ -0,0 +1,53 @@
+require 'yacl'
+module MyApp
+  # This is a simplier version of 'myapp' example where we use a DSL instead of
+  # explicit classes. Under hte covers, this creats classes that do the same as
+  # the explicit version.
+  #
+  # For simpler cases where you want to put all of this together this may make
+  # more sense.
+  class Application < ::Yacl::Simple
+
+    # This defines a MyApp::Application::Defaults class. This class is also
+    # available via MyApp::Application.defaults
+    defaults do
+      default 'archive.uri'    , 'http://archive.example.com'
+      default 'messaging.uri'  , 'kestrel://messaging1.example.com:2229/'
+      default 'messaging.queue', 'pending'
+      default 'system'         , 'main'
+      default 'timelimit'      , '10'
+    end
+
+    # This defines a MyApp::Application::Parser class. This class is also
+    # available via MyApp::Application.parser
+    parser do
+      banner "myapp [options]+"
+      opt 'pipeline.dir', :long => 'pipeline-dir', :short => 'd', :description => "The pipeline directory we are using", :cast => :string
+      opt 'config.dir'  , :long => 'config-dir',   :short => 'c', :description => "The directory to load configuration from", :cast => :string
+      opt 'timelimit'   , :long => 'time-limit',   :short => 't', :description => "The amount of time to run for", :cast => :integer
+      opt 'system'      , :long => 'system',       :short => 's', :description => "The system setting", :cast => :string
+      opt 'debug'       , :long => 'debug',        :sortt => 'D', :description => "Turn on debugging", :cast => :boolean
+    end
+
+    # This defines a MyApp::Application::Plan class. This class is also
+    # available via MyApp::Application.plan
+    plan do
+      try MyApp::Application.parser
+      try Yacl::Loader::Env, :prefix => 'MY_APP'
+      try Yacl::Loader::YamlDir, :parameter => 'config.dir'
+      try MyApp::Application.defaults
+
+      on_error do |exception|
+        $stderr.puts "ERROR: #{exception}"
+        $stderr.puts "Try --help for help"
+        exit 1
+      end
+    end
+
+    # This is the method that will be run when it is executed on the
+    # commandline.
+    def run
+      puts properties.map.inspect
+    end
+  end
+end

data/example/myapp/bin/myapp

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+# load path munging so the example works from a git checkout, do not do this
+# in your program
+$: << File.expand_path( "../../../../lib", __FILE__ ) # yacl library
+$: << File.expand_path( "../../lib", __FILE__ )       # lib dir of this sample app
+require 'rubygems'
+
+#------------------------------------------------------------------------------
+# This would be the top level commandline entry point for your program. Feel
+# free to have multiple of them if that is what your situation requires.
+#------------------------------------------------------------------------------
+
+require 'myapp'
+require 'myapp/cli'
+
+MyApp::Cli::Runner.go( ARGV, ENV )

data/example/myapp/bin/myapp-job

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+#------------------------------------------------------------------------------
+# This would be a top-level entrypoint into your system that was not commandline
+# based. Think loaded by some other framework. Maybe a Torquebox Job or a
+# Resqueue Job or something that was more static.
+#------------------------------------------------------------------------------
+
+require 'myapp'
+MyApp::Job::ForSomething.new( "pipeline.dir" => "/over/there" )

data/example/myapp/config/database.yml

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

data/example/myapp/config/httpserver.yml

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

data/example/myapp/config/pipeline.yml

@@ -0,0 +1 @@
+dir: /tmp/foo/bar

data/example/myapp/lib/myapp.rb

@@ -0,0 +1,6 @@
+# Top level namespace of your application
+module MyApp
+  VERSION = "1.0.0"
+end
+require 'myapp/defaults'
+require 'myapp/job'

data/example/myapp/lib/myapp/cli.rb

@@ -0,0 +1,92 @@
+require 'myapp/defaults'
+module MyApp
+  # In this example I am encapsulating everything that has to do with a
+  # commandline program within the Cli module. For this example, there is one
+  # and only one commandline program.
+  module Cli
+
+    # The Commandline options for our program. This maps the commandline
+    # options, given in the :long and :short style for consistency in
+    # commandline functionalyt to their property names which have a dotten
+    # notation and make property access consistent throughout the program.
+    #
+    # These Options are to be used by the Parser class.
+    class Options < Yacl::Define::Cli::Options
+      opt 'pipeline.dir', :long => 'pipeline-dir', :short => 'd', :description => "The pipeline directory we are using", :cast => :string
+      opt 'config.dir'  , :long => 'config-dir',   :short => 'c', :description => "The directory to load configuration from", :cast => :string
+      opt 'timelimit'   , :long => 'time-limit',   :short => 't', :description => "The amount of time to run for", :cast => :integer
+      opt 'system'      , :long => 'system',       :short => 's', :description => "The system setting", :cast => :string
+      opt 'debug'       , :long => 'debug',        :sortt => 'D', :description => "Turn on debugging", :cast => :boolean
+     end
+
+    # The Parser class. This is kept explicitly separate from the Options class
+    # so that, you may, if you like use whatever commadnline parser
+    # library/program you whish. By default this library will automatically use
+    # trollop and generate a commandline for you from it. If you whish to use
+    # another commandline library, you may define your own Parser class.
+    #
+    # Use Yacl::Define::Cli::Parser as a template for how you would like to do
+    # your work. YOu can probably get by with inheriting from
+    # Yacl::Define::Cli::Parser and overwriting the #delegate_parser and #parse
+    # methods.
+    class Parser < Yacl::Define::Cli::Parser
+      banner "myapp [options]+"
+      options MyApp::Cli::Options
+    end
+
+    # The Plan class, this defines the order of loading of your properties and the
+    # order of resolution of when looking up a property. The property Loaders
+    # are loaded in the defined order below, and that is their priority. For
+    # example the 'config.dir' property may be defiend in the Parser and the
+    # Environment, and in this case if it has a value in the Env but not the
+    # Parser the Env value will take precidence. If there is a value in the
+    # Parser though, that will be the value used.
+    #
+    # In this case, since we know that this plan has a commandline, we're
+    # catching any load errors and printing out to stderr on a failure. If this
+    # perhaps was used in a non-commandline situation the on_error block could
+    # do something completely different.
+    class Plan < Yacl::Define::Plan
+
+      # 1) parse the commandline and load properties from the mapping of the
+      # commandline to the property names.
+      try MyApp::Cli::Parser
+
+      # 2) using the environment and only those environment variables that
+      # start with MY_APP load additional properties.
+      try Yacl::Loader::Env, :prefix => 'MY_APP'
+
+      # 3) using the config.dir value, which is probably set via the
+      # --config-dir parser option, or via the MY_APP_CONFIG_DIR environment
+      # variable laod up some more properties.
+      try Yacl::Loader::YamlDir, :parameter => 'config.dir'
+
+      # 4) if a property is not found in any of the previous locations, then use
+      # the defaults. And if it is not in the defaults, then we will return nil
+      try MyApp::Defaults
+
+      # If an error happens while attempting to load the properties the print a
+      # message on stderr and exit the program.
+      on_error do |exception|
+        $stderr.puts "ERROR: #{exception}"
+        $stderr.puts "Try --help for help"
+        exit 1
+      end
+    end
+
+    # The Runner class, this is what is instantiated in the bin script and
+    # invoked from the commandline. It uses the Plan and a #run method you
+    # define to take actione.
+    #
+    # In this particular case, it just prints out the properties.
+    class Runner < ::Yacl::Define::Cli::Runner
+      plan MyApp::Cli::Plan
+
+      def run
+        p = properties
+        puts p.map.inspect
+      end
+    end
+
+  end
+end

data/example/myapp/lib/myapp/defaults.rb

@@ -0,0 +1,28 @@
+require 'yacl'
+module MyApp
+  # The core defaults of your system. Not all of your default properties need to
+  # be defined. It is your choice what is defined and what isn't. Think of these
+  # as the hardcoded defaults that if the property is not overwritte by
+  # something else in the system, then it will fall back to this. 
+  #
+  # Sensible Defaults in other words.
+  #
+  # Possible ways of using these:
+  #
+  #   - Have different Defaults for development/test/production
+  #   - Use this for things that are hardly ever overwritten
+  #   - global defaults that are common across many sub-components.
+  #
+  # It would be perfectly reasonable to have different classes defined for
+  # different things. Different commandline applications, or entrypoints into
+  # the library etc.
+  class Defaults < Yacl::Define::Defaults
+    default 'archive.uri'    , 'http://archive.example.com'
+    default 'messaging.uri'  , 'kestrel://messaging1.example.com:2229/'
+    default 'messaging.queue', 'pending'
+    default 'system'         , 'main'
+    default 'timelimit'      , '10'
+  end
+end
+
+

data/example/myapp/lib/myapp/job.rb

@@ -0,0 +1,56 @@
+require 'myapp/defaults'
+module MyApp
+  # In this case we are assuming that the application is not part of a
+  # commandline program and it may be used from some other library and it still
+  # needs to load its config from some location.
+  #
+  # This could be the case of :
+  #   - Resque or some other background job system
+  #   - Part of a torquebox configuration
+  #   - embedded in some other library
+  module Job
+
+    # We have a plan just as we did with the commandline one, but without the
+    # commandline parser.
+    class Plan < Yacl::Define::Plan
+      # First try to load properties from the environment variables that start
+      # with MY_PREFIX
+      try Yacl::Loader::Env, :prefix => 'MY_APP'
+
+      # Next we will load from an explicit directory.
+      try Yacl::Loader::YamlDir, :path => File.expand_path( "../../../config", __FILE__ )
+
+      # And finally we will use the built in defaults
+      try MyApp::Defaults
+
+      # On an error we just print to stderr saying that we do not know what is
+      # going on. We could re-reise the exception, or just let it naturally
+      # percolate up if we wanted something else to handle it.
+      on_error do |exception|
+        $stderr.puts exception
+        $stderr.puts exception.backtrace.join("\n")
+      end
+    end
+
+    # In this situation we have a class that needs to use the plan and do
+    # something with it. Instead of having a commandline program, this is the
+    # clasee that serves as the interface between our code and someone elses
+    # code.
+    class ForSomething
+
+      # We will take a hash here so that the external program can explicitly
+      # pass in as set of initial properties and have them bee the most highly
+      # prioritiezed values in the plan stack.
+      #
+      # We also explictly use the Plan here, and do not assume that there is a
+      # runner.
+      def initialize( params )
+        p = Yacl::Properties.new( params )
+        plan = Job::Plan.new( :initial_properties => p )
+        puts plan.properties.map.inspect
+      end
+    end
+  end
+end
+
+

data/lib/yacl.rb

@@ -0,0 +1,12 @@
+# Yacl is Your Application Configuration Library.
+#
+# See the README
+module Yacl
+  # The Current Version of the library
+  VERSION = "1.0.0"
+  class Error < ::StandardError; end
+end
+require 'yacl/properties'
+require 'yacl/loader'
+require 'yacl/define'
+require 'yacl/simple'

data/lib/yacl/define.rb

@@ -0,0 +1,9 @@
+module Yacl
+  # Define is the namespace underwhich lives those classes an end user will
+  # inherit from to create their own classes.
+  module Define
+  end
+end
+require 'yacl/define/defaults'
+require 'yacl/define/cli'
+require 'yacl/define/plan'

data/lib/yacl/define/cli.rb

@@ -0,0 +1,7 @@
+module Yacl::Define
+  module Cli
+  end
+end
+require 'yacl/define/cli/options'
+require 'yacl/define/cli/parser'
+require 'yacl/define/cli/runner'

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

@@ -0,0 +1,97 @@
+module Yacl::Define::Cli
+
+  # Internal: Encapsulation of all the elements pertaining to a single
+  # commandline option.
+  Option = Struct.new( :property_name, :long, :short, :description, :cast)
+
+  # Public: Inherit from Cli::Options to define your the mapping between your
+  # application properties and commandline switches.
+  #
+  # The class you create from here is to be used in conjuction with a class you
+  # create that is a child class of Cli::Parser.
+  #
+  # Example:
+  #
+  #   class MyOptions < ::Yacl::Define::Cli::Options
+  #     opt 'log.level', :long => 'log-level', :short => 'l', :description => "Logging Level", :cast => :string
+  #     opt 'config.dir',:long => 'config-dir', :short => 'c', :description => "Configuration directory", :cast => :string
+  #   end
+  #
+  #   o = MyOptions.new( 'log-level' => 'debug', 'config-dir' => '/tmp/foo' )
+  #   o.properties # => Properties instance with 'log.level' => debug and 'config.dir' => '/tmp/foo'
+  #
+  class Options < ::Yacl::Loader
+
+    # Internal: access to the defined list of options
+    #
+    # Returns the Array of options
+    def self.opt_list
+      @opt_list ||= []
+    end
+
+    # Public: Declare a property and its corresponding commandline options.
+    #
+    # name   - The property name as a String
+    # params - The Hash options to accompany the property name (default: {})
+    #          :long        - The long commandline option. Without leading dashes
+    #          :short       - The short commandline option. Without leading dashes
+    #          :description - The text description of this commandline option
+    #          :cast        - What to cast the value of the commandline option
+    #                         to. This can be one of: :integer, :float, :string,
+    #                         :boolean
+    #
+    # Examples:
+    #
+    #   opt 'app.thing.one', :long => 'thing-one', :short => 't', :description => "Thing One", :cast => :string
+    #
+    # Returns nothing.
+    def self.opt(name, params = {} )
+      opt_list << Option.new( name, params[:long], params[:short], params[:description ], params[:cast] )
+    end
+
+    # Public: Load the Properties from the options that were passed to the
+    # initializer.
+    #
+    # Returns a Properties instance.
+    def properties
+      load_properties( @options )
+    end
+
+    # Public: yield each defined Option in this class to the caller
+    #
+    # Yields the Option instance of the iteration.
+    #
+    # Returns nothing.
+    def each
+      opt_list.each do |o|
+        yield o
+      end
+    end
+
+    # Internal: Return the list of defined options for this Class.
+    #
+    # Returns an Array of Option instances
+    def opt_list
+      self.class.opt_list
+    end
+
+    # Internal: convert the given hash of long options into a Properties
+    # instance using the defined options.
+    #
+    # It is assumed that the commandline has already been parsed and that the
+    # hash passed in is the long options that were parsed out of the
+    # commandline.
+    #
+    # hash - a Hash of long options and their values.
+    #
+    # Returns a Properties instance
+    def load_properties( hash )
+      prop_hash = {}
+      opt_list.each do |o|
+        next unless hash.has_key?( o.long )
+        prop_hash[o.property_name] = hash[o.long]
+      end
+      return Yacl::Properties.new( prop_hash )
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+require 'trollop'
+module Yacl::Define::Cli
+  # Public: Parser is a Loader that uses a Cli::Options class and the Trollop
+  # parser to convert commandline options into a Properties instance. It is to
+  # be inherited from so you can have your own parser per commandline program in
+  # your application suite.
+  #
+  # Example:
+  #
+  #   class MyOptions < ::Yacl::Define::Cli::Options
+  #     opt 'log.level', :long => 'log-level', :short => 'l', :description => "Logging Level", :cast => :string
+  #     opt 'config.dir',:long => 'config-dir', :short => 'c', :description => "Configuration directory", :cast => :string
+  #   end
+  #
+  #   class MyParser < ::Yacl::Define::Cli::Parser
+  #     banner "Usage: myapp [options]+"
+  #     options MyOptions
+  #   end
+  #
+  #   p = MyParser.new( :argv => ARGV )
+  #   p.properties #=> a Properties instance
+  #
+  class Parser < ::Yacl::Loader
+
+    # Public: Define the options Class that is be used by this Parser, or return
+    # the existin Class if it is already defined.
+    #
+    # klass - A Class that is a child class of Cli::Options.
+    #
+    # Returns the current options Class.
+    def self.options( *args )
+      @options_klass ||= args.first unless args.empty?
+      return @options_klass
+    end
+
+    # Public: Set or retrieve the banner text.
+    #
+    # text - A String to be displayed as part of the help text.
+    #
+    # Returns the value set, or the default value if one is not set.
+    def self.banner( *args )
+      @banner = args.first unless args.empty?
+      @banner ||= "Usage  :  #{File.basename($0)} [options]+\nOptions:"
+    end
+
+    # Public: Define a commandline option for this Parser.
+    # Using 'opt' over options will dynamically create a child class of Options
+    # for use by this class
+    def self.opt( *args )
+      options( Class.new( Yacl::Define::Cli::Options ) )
+      options.opt( *args )
+    end
+
+    # Create a new Parser instance
+    #
+    # opts - The hash of options for this Loader
+    #        :argv - The commandline options passed to the Parser.
+    #        other options as per the Loader class.
+    #
+    def initialize( opts = {} )
+      super
+      @argv = opts[:argv] || []
+    end
+
+    # Public: Retrive the class level banner text.
+    #
+    # Returns the String banner text
+    def banner
+      self.class.banner
+    end
+
+    # Public: Return the Properties instance that is created by parsing the
+    # commandline options.
+    #
+    # Nil values from possible defaults from the commandline parser are
+    # filtered out before being merged onto the options.
+    #
+    # Returns a Properties instance.
+    def properties
+      h = {}
+      parse( @argv ).each do |k,v|
+        h[k] = v unless v.nil?
+      end
+      o = options_klass.new( h )
+      o.properties
+    end
+
+    private
+
+    # Internal: Return the class level value stored in Parser#options
+    #
+    # Returns a Class
+    def options_klass
+      self.class.options
+    end
+
+    def delegate_parser
+      Trollop::Parser.new( options_klass.new, self.banner ) do |trollop_options, banner_text|
+        text banner_text
+        trollop_options.each do |x|
+          opt x.long, x.description, :type => x.cast
+        end
+      end
+    end
+
+    def parse( argv )
+      Trollop::with_standard_exception_handling( delegate_parser ) do
+        delegate_parser.parse( argv )
+      end
+    end
+  end
+end