app-ctx 0.1.2

data/README

@@ -0,0 +1,109 @@
+
+    Application Context
+
+    Every application needs configuration and app-ctx provides a concise way of
+    doing it.
+
+    For all applications (you are not a mouseclicker, are u?), once in a while
+    you need to supply some configuration values to overrule the built-in
+    defaults. The app-ctx gem does unify and organize built-in constants,
+    config files and commandline option with a clearly defined priority, from
+    low to high:
+
+        - procedural: App::Config#set_default_values
+        - default values YAML file from next to the $0 script
+        - user supplied configuration file, eg.: --config=/tmp/foo.yml
+        - command line options and flags: --foo --bar=foo
+
+    But for your application it is of no interesst from where the values are
+    coming: command line option: "--port=1234", a user configuration file or
+    from the applications built-in default values. Therefor +app-ctx+ combines
+    value settings from various sources into a single configuration hash.
+
+    basically you have two ways to use it:
+
+        require 'app-ctx' # of course,and than...
+
+    1. closures (see examples/run_with_block.rb) 
+
+        App::ctx.run do |context| ... end
+
+    or 2. with a mainclass(see examples/run_with_class.rb)
+
+        App::ctx.run YourClassHere
+
+    The context object provides:
+
+       values:          the combined key and value settings
+       argv:            remaining argument(not the options) of the command line
+       defaults_path:   full path to the defaults file
+
+    for the second case(with a mainclass) an application instance of this class
+    is created. The first argument is than taken as method name and executed,
+    again with a context oject provided: 
+
+        prompt: ruby example/run_with_class show 
+
+    will result in the :show method beeing called:
+
+        context = Config.new...
+        ...
+        app = Simple.new...
+        app.show(context)
+
+
+    Conversions
+
+    Commandline options are strings only, but sometimes you need strongly typed
+    primitive values. +app-ctx+ does automatically convert integer and float
+    values, see "examples/conversions.rb" for:
+
+        prompt: ./examples/conversions.rb             
+        {:i=>23, :f=>3.14}
+        typeof 'i': Fixnum
+        typeof 'f': Float
+        prompt: ./examples/conversions.rb -i=17 -f=2.12
+        {:i=>17, :f=>2.12}
+        typeof 'i': Fixnum
+        typeof 'f': Float
+        prompt: ./examples/conversions.rb -i=i -f=f
+        {:i=>"i", :f=>"f"}
+        typeof 'i': String
+        typeof 'f': String
+
+
+    Flags/Boolean values
+    
+    Flags(options without values) are converted to boolean values, see
+    examples/boolean.rb:
+
+        dluesebrink dl-mbook ruby/app-ctx: r examples/boolean.rb 
+        {:bool=>false}
+        typeof 'bool': FalseClass
+        dluesebrink dl-mbook ruby/app-ctx: r examples/boolean.rb  --bool
+        {:bool=>true}
+        typeof 'bool': TrueClass
+
+
+    Ruby Conversions
+    
+    When Fixnum, Float and boolean conversion are not enough, as a last resort,
+    you can use ruby code directly for evaluation of option values. Replacing
+    '=' with ':' results in assigning the ruby evaluation value to the key, see
+    examples/ruby_conv.rb:
+
+        prompt: examples/ruby_conv.rb
+        {:r=>1..10, :a=>[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]}
+        typeof 'r': Range
+        typeof 'a': Array
+        prompt: ./examples/ruby_conv.rb -r:2..3 -a:'(-1..1).to_a'
+        {:r=>2..3, :a=>[-1, 0, 1]}
+        typeof 'r': Range
+        typeof 'a': Array
+        prompt: ./examples/ruby_conv.rb -r:2..3 -a:\(-1..1\).to_a
+        {:r=>2..3, :a=>[-1, 0, 1]}
+        typeof 'r': Range
+        typeof 'a': Array
+
+
+# vim: set tw=80 syntax=txt nosmartindent:

data/lib/app-ctx.rb

@@ -0,0 +1,228 @@
+
+require 'yaml'
+require 'rdoc/usage'
+
+require 'app-ctx/dlog'
+
+module App
+
+    # the priority of configuation settings is:
+    #   1. command line options
+    #   2. configuration from custom file, eg.: --config=/tmp/foo.yml
+    #   3. built-in default values from yaml file next to $0 script
+    class Config
+
+        include DL::LoggerMixin
+
+        attr_reader :values, :argv, :defaults_path
+
+        # params are :argv and :defaults_path which are defaulting to ARGV and
+        # the applications defaults which are loaded from a yaml file next to
+        # the '$0' application script.
+        def initialize params = {}
+            params = {
+                :argv           => ARGV, 
+                :defaults_path  => App.config_path($0)
+            }.update(params)
+
+            @argv = params[:argv]
+            @defaults_path = params[:defaults_path] 
+            
+            load_config_file(@defaults_path)
+            @values, @argv = parse_command_line @argv
+        end
+
+        # programatic way to define the default values other then from defaults
+        # file. 
+        def set_default_values defaults
+            @values = defaults.merge(@values)
+        end
+
+
+        def to_s
+         <<-EOT
+        args : #{argv.inspect}
+      values : #{values.inspect}
+    defaults : '#{defaults_path}'
+ user config : '#{values[:config]}'
+            EOT
+        end
+        
+        # overwrite current configuration with values from file
+        #
+        def load_config_file cpath
+            @values ||= {}
+            if File.exists? cpath = File.expand_path(cpath)
+                begin
+                    @values.update YAML.load_file(cpath)
+                    info "loaded(#{cpath})"
+                    debug "config values: #{@values.inspect}"
+                rescue => e
+                    warn "failed to load: #{cpath}", e
+                end
+            else
+                debug "no such config file: #{cpath}"
+            end
+        end
+
+        # methods below are related to option parsing and are used only at
+        # object creastions time from the c'tor
+        private
+
+        # overide default configuration with command line arguments.
+        #   --flag          becomes [ :flag => true]
+        #   --option=value  becomes [ :option => "value"]
+        #   --int=1         becomes [ :int => 1]
+        #   --float=2.3     becomes [ :float => 2.3]
+        #   --txt="foo bar" becomes [ :txt => "foo bar"]
+        #
+        #   --list:(1..10)  becomes [ :list => (1..10) ]
+        def parse_command_line argv
+            c = {}
+            argv = argv.clone.delete_if do |a|
+                #if m = /^--(\w+)(=(.+))?$/.match(a)
+                if m = /^(-(\w)|--(\w\w+))(=(.+))?$/.match(a)
+                    debug "#{m.to_a.inspect}" if m
+                    val = parse_arg m[5]
+                    key = m[2] || m[3]
+                    c[key.to_sym] = val
+
+                # eval as ruby snippet
+                elsif m = /^(-(\w)|--(\w\w+)):(.+)$/.match(a)
+                    debug "#{m.to_a.inspect}" if m
+                    val = eval m[4]
+                    key = m[2] || m[3]
+                    c[key.to_sym] = val
+                end
+            end
+            debug "command line options: #{c.inspect}"
+
+            # overload "--config=..." file before command line options
+            if cpath = c[:config]
+                if file_config = load_config_file(cpath)
+                    c = file_config.update(c)
+                else
+                    warn "configuration file not found: '#{cpath}'"
+                end
+            end
+
+            #[@values.dup.update(c), av]
+            @values.update(c)
+            [@values, argv]
+        end
+
+        def parse_arg val
+            return true unless val # options are booleans
+            Integer(val) rescue Float(val) rescue parse_string(val)
+        end
+
+        def parse_string s
+            if s.match %r{^['"].*['"]$}
+                s[1..-2]
+            else
+                s
+            end
+        end
+    end
+
+    class Container
+
+        Messages = {
+            :no_entrypoint  => <<-'EOM'
+
+    ::app-ctx:: 
+
+ -> sorry, your main class (#{clazz}) seems not to have a default
+ -> 'application_main' entrypoint and no method argument was given, so i don't
+ -> know what to do.
+
+    thank you, good bye and have a nice day
+
+        EOM
+        }
+
+        def inform message_id, binding
+            m = Messages[message_id]
+            puts eval("\"#{m}\"", binding)
+        end
+
+        def initialize context
+            @context = context
+        end
+
+        def execute clazz = nil
+
+            if block_given?
+                warn "attached block takes precedence over class!" if clazz
+                return yield(@context)
+            end
+
+            # create applicaton instance with or without context c'tor (this is
+            # IoC: Constructor Dependency Injection)
+            app = clazz.new(@context) rescue clazz.new
+
+            setter_injection app, @context
+
+            begin 
+                # first try the default entry point
+                app.application_main @context
+
+            rescue NoMethodError => e
+                if app.respond_to? :application_main
+                    DL.logger.error "failed invokation", e
+                else
+                    if 0 == @context.argv.length 
+                        inform :no_entrypoint, binding()
+                        RDoc::usage
+                        return
+                    else
+                        # one or more args  =>  first arg is method with rest
+                        # as params
+                        begin
+                            op = @context.argv.shift
+                            app.send(op, @context)
+                        rescue => e
+                            DL.logger.error "oops: #{e}", e
+                        end
+                    end
+                end
+            end
+
+            app # the created application instance
+        end
+
+        # IoC setter dependency injection:
+        # try all context keys as setter class 
+        def setter_injection obj, context
+            # try setters for keys from context(this is IoC: Setter dependency
+            # injection)
+            context.values.each do |key, value| 
+                #p "#{key} #{value}"
+                begin
+                    obj.send("#{key}=", value) 
+                rescue NoMethodError
+                    #ntdh
+                end
+            end
+        end
+        private :setter_injection
+    end
+
+    class << self
+        def run params = {}, &block
+            # create application container from command line context
+            container = Container.new(Config.new(params))
+            if block_given? 
+                container.execute {|context| block.call(context) }
+            else
+                container.execute params[:class]
+            end
+        end
+
+        def config_path app_path
+            defaults_path = File.expand_path(app_path)
+            ext = File.extname(defaults_path)
+            defaults_path.sub((ext == "" && /$/ || /#{ext}$/), ".yml")
+        end
+    end
+end

data/lib/app-ctx/dlog.rb

@@ -0,0 +1,164 @@
+# once (shamelessly) stolen(for testing(and squeezed)) from rails...
+# now degenerated beyong comprehension
+# awaiting a major refactoring to get a managble configuration...
+
+module DL
+    
+    AllLoggersByPrefix = {} # list of all loggers 
+
+    class Logger 
+
+        LevelMetrics = {
+            :fatal  => 0.0,
+            :error  => 1.0,
+            :warn   => 2.0,
+            :info   => 3.0,
+            :debug  => 4.0,
+        }
+
+        # XXX das mit diesem config kram ist alles noch ziemlicher mist...
+        DefaultLogger = {
+            :prefix         => "???",
+            :out            => $stderr,
+            :fmt            => "%c %23s  %s%s\n", # "%c %-13s: %s%s\n",
+            #:include_levels => /^(fatal|error|warn|info)/i, # no debug
+            :include_levels => nil, # all inclusive
+            #:exclude_levels => nil,
+            :exclude_levels => /^debug/i, # no debug on default 
+            :quiet          => false,
+            :level          => 3.0, 
+        }
+        Config = {
+            :default    => DefaultLogger,
+        }
+
+        attr_accessor :prefix, :out, :fmt, :include_levels, :exclude_levels
+        attr_accessor :quiet, :level
+
+        def initialize prefix, config = DefaultLogger
+            @nesting_level = 0
+            @config = DefaultLogger.dup
+            @config[:prefix] = prefix
+            configure config
+        end
+
+        def configure settings
+            @config.update(settings)
+            @prefix         = @config[:prefix]
+            @out            = @config[:out]
+            @fmt            = @config[:fmt]
+            @include_levels = @config[:include_levels]
+            @exclude_levels = @config[:exclude_levels]
+            @quiet          = @config[:quiet]         
+            @level          = @config[:level]
+        end
+
+        def self.[] prefix
+            self.get prefix
+        end
+
+        def log(status, message, exception, &block)
+            unless quiet
+                #return "excluded" if exclude_levels and exclude_levels.match(status)
+                #if include_levels and !include_levels.match(status)
+                #    return "not included"
+                #end
+                msg = @fmt % [status[0], prefix, '  ' * @nesting_level, message]
+                @out.print(msg)
+                if exception
+                    callstack = exception.backtrace
+                    @out.print " !! #{exception}\n\t#{callstack.join("\n\t")}\n"
+                    begin
+                        reason = exception.reason
+                        callstack = reason.backtrace
+                        txt = "#{reason}\n\t#{callstack.join("\n\t")}\n"
+                        @out.print "(Cause)>> #{txt}"
+                    rescue 
+                        # noop
+                    end
+                end
+            end
+            indent(&block) if block_given?
+        end
+
+        def flush
+            @out.flush
+        end
+
+        def indent(&block)
+            @nesting_level += 1
+            if block_given?
+                begin
+                    block.call
+                ensure
+                    outdent
+                end
+            end
+        end
+
+        def outdent
+            @nesting_level -= 1
+            if block_given?
+                begin
+                    block.call
+                ensure
+                    indent
+                end
+            end
+        end
+
+        private
+        def method_missing(method, *args, &block)
+            message, execption = args
+            if LevelMetrics[method.to_sym] <= level
+                log(method.to_s.upcase, message, execption, &block)
+            end
+        end
+    end
+
+    def self.logger(prefix = $0, out = $stdout)
+        prefix = self.find_prefix(prefix)
+        unless log = AllLoggersByPrefix[prefix]
+            c = Logger::Config[prefix] || {}
+            #c[:fmt] = "%c %23s  %s%s\n"
+            log = (AllLoggersByPrefix[prefix] = Logger.new(prefix, c))
+        end
+        log
+    end
+
+    def self.find_prefix prefix
+        raise "nil prefix not yet implemented!" unless prefix
+        return prefix if prefix.kind_of? String
+        return prefix.name if prefix.kind_of? Class
+        return prefix.name if prefix.kind_of? Module
+        return prefix.class.name
+    end
+
+    module LoggerMixin
+        def logger 
+            @dl_class_logger ||= DL.logger(self) # class logger
+        end
+
+        def debug *args
+            logger.debug *args
+        end
+        def info *args
+            logger.info *args
+        end
+        def warn *args
+            logger.warn *args
+        end
+        def error *args
+            logger.error *args
+        end
+        def fatal *args
+            logger.fatal *args
+        end
+        def log_level
+            logger.level
+        end
+        def set_log_level level
+            logger.level= level
+        end
+    end
+end

data/test/t_app-ctx.rb

@@ -0,0 +1,199 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'pp'
+
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'app-ctx'
+
+class AppModuleTest < Test::Unit::TestCase
+
+    class With_application_main
+        attr_reader :context
+        attr_accessor :baroque
+        # application_main is the default catch-all entry point for app-ctx
+        def application_main context
+            puts "#{self}: #{context.inspect}"
+            @context = context
+        end
+    end
+    def test_default_entry_point
+        puts "\n --> #{self.name}"
+        argv = ["-f", "--foo=bar", "--baroque=gaga", "arg1", "arg2"]
+        app = App::run :class => With_application_main, :argv => argv
+        assert_not_nil app
+        assert_equal With_application_main, app.class
+        assert_not_nil app.context
+        assert_equal({:f=>true, :foo=>"bar", :baroque =>"gaga"}, app.context.values)
+        assert_equal ["arg1", "arg2"], app.context.argv
+        assert_equal "gaga", app.baroque
+    end
+
+    class ArgumentEntryPoint
+        attr_reader :context
+        def entrypoint context
+            puts "#{self}: #{context.inspect}"
+            @context = context
+        end
+    end
+    def test_run_without_point
+        puts "\n --> #{self.name}"
+        argv = ["-f", "--foo=bar", "entrypoint", "first_method_arg"]
+        app = App::run :class => ArgumentEntryPoint, :argv => argv
+        assert_not_nil app
+        assert_equal ArgumentEntryPoint, app.class
+        assert_not_nil app.context
+        assert_equal({:f=>true, :foo=>"bar"}, app.context.values)
+        assert_equal ["first_method_arg"], app.context.argv
+    end
+
+end
+
+class AppConfigTest < Test::Unit::TestCase
+
+    include App
+
+    def test_config_block
+        puts "\n --> #{self.name}"
+        App::Config.new do |context| 
+            puts "--------------->context: #{context.inspect}"
+            assert_not_nil context
+            assert_equal({}, context.values)
+        end
+
+        App::Config.new :argv=>["-f", "--foo=bar", "arg1", "arg2"] do |context| 
+            puts "--------------->context: #{context.inspect}"
+            assert_not_nil context
+            assert_equal({:f=>true, :foo=>"bar"}, context.values)
+            assert_equal ["arg1", "arg2"], context.argv
+        end
+    end
+
+    def test_load_config_file 
+        puts "\n --> #{self.name}"
+        c = App::Config.new
+        # config file does not exist:w
+        c.load_config_file File.join(File.dirname($0), "no-such-file")
+        assert_equal({}, c.values)
+
+        # load configuration from file
+        c.load_config_file File.join(File.dirname($0), "config-1.yml")
+        assert_equal({
+            :f=>3.21, :i=>17, :empty_hash=>{}, :assoc=>{:key=>"foo"}
+        }, c.values)
+
+        # config overloading
+        c.load_config_file File.join(File.dirname($0), "config-2.yml")
+        assert_equal({
+            :f=>3.21, :i=>17, :empty_hash=>{}, 
+            :assoc=>{:key=>"bar"}, :f2=>-3.21
+        }, c.values)
+    end
+
+    def test_configure_defaults 
+        puts "\n --> #{self.name}"
+        c = App::Config.new
+        assert_equal ARGV, c.argv
+        assert_equal({}, c.values)
+
+        # find the default values config file next to the $0 script
+        assert_equal File.expand_path($0).sub(/.rb$/, ".yml"), c.defaults_path
+    end
+
+    def test_config_path
+        puts "\n --> #{self.name}"
+
+        cpath = App.config_path "foo.bar"
+        assert_not_nil cpath
+        assert_equal File.expand_path(File.join(".", "foo.yml")), cpath
+
+        cpath = App.config_path "/tmp/foo.rb.rb"
+        assert_not_nil cpath
+        assert_equal File.expand_path(File.join("/", "tmp", "foo.rb.yml")), cpath
+
+        # XXX this might fail on windows??
+        cpath = App.config_path "~/foo.bar"
+        assert_not_nil cpath
+        assert_equal File.expand_path(File.join("~", "foo.yml")), cpath
+    end
+
+    def test_parse_ruby_options
+        puts "\n --> #{self.name}"
+
+        c = Config.new :argv => ["--list:(1..10).to_a"]
+        cfg, av = c.values, c.argv
+        assert_equal({:list => (1..10).to_a}, cfg)
+
+        c = Config.new :argv => ["--list:(1..10)"]
+        cfg, av = c.values, c.argv
+        assert_equal({:list => (1..10)}, cfg)
+        assert cfg[:list].kind_of?(Range)
+    end
+
+    def test_parse_command_line_options
+        puts "\n --> #{self.name}"
+
+        c = Config.new :argv => []
+        cfg, av = c.values, c.argv
+        assert_equal({}, cfg)
+        assert_equal [], av
+
+        c = Config.new :argv => ["-a"]
+        cfg, av = c.values, c.argv
+        assert cfg[:a]
+        assert ! cfg[:b]
+    end
+
+    def test_parse_command_line_int_float_flags
+        puts "\n --> #{self.name}"
+
+        c = Config.new :argv => ["-a", "--int=5", "--float=2.34"]
+        cfg, av = c.values, c.argv
+        assert_equal({:a=>true,:int=>5, :float=>2.34}, cfg)
+        assert_equal [], av
+    end
+
+    def test_various_string_values
+        puts "\n --> #{self.name}"
+
+        c = Config.new :argv => ["xxx"]
+        cfg, av = c.values, c.argv
+        assert_equal ["xxx"], av
+        assert_equal({}, cfg)
+
+        c = Config.new :argv => ["foo", "bar"]
+        cfg, av = c.values, c.argv
+        assert_equal({}, cfg)
+        assert_equal ["foo", "bar"], av
+
+        c = Config.new :argv => ["--foo", "bar"]
+        cfg, av = c.values, c.argv
+        assert_equal({:foo=>true}, cfg)
+        assert_equal ["bar"], av
+
+        c = Config.new :argv => ["foo", "--bar"]
+        cfg, av = c.values, c.argv
+        assert_equal({:bar=>true}, cfg)
+        assert_equal ["foo"], av
+
+        c = Config.new :argv => ["--key=val", "foo"]
+        cfg, av = c.values, c.argv
+        assert_equal({:key=>'val'}, cfg)
+        assert_equal ["foo"], av
+
+        c = Config.new :argv => ["--key=val", "--key=ooo"]
+        cfg, av = c.values, c.argv
+        assert_equal({:key=>'ooo'}, cfg)
+        assert_equal [], av
+
+        c = Config.new :argv => ["-a='foo bar'", '-b="bar foo"']
+        cfg, av = c.values, c.argv
+        assert_equal [], av
+        assert_equal({:a=>"foo bar", :b=>"bar foo"}, cfg)
+
+        c = Config.new :argv => ["--aa='foo bar'", '--bb="bar foo"']
+        cfg, av = c.values, c.argv
+        assert_equal [], av
+        assert_equal({:aa=>"foo bar", :bb=>"bar foo"}, cfg)
+    end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: app-ctx
+version: !ruby/object:Gem::Version 
+  version: 0.1.2
+date: 2006-09-18 00:00:00 +02:00
+summary: command line application startup and config context
+require_paths: 
+- lib
+email: dirk.luesebrink@idmedia.com
+homepage: http://www.idmedia.com/
+rubyforge_project: 
+description: 
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Dirk Luesebrink
+files: 
+- lib/app-ctx.rb
+- lib/app-ctx/dlog.rb
+- test/t_app-ctx.rb
+- README
+test_files: 
+- test/t_app-ctx.rb
+rdoc_options: 
+- --main
+- README
+extra_rdoc_files: 
+- README
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+