main 2.5.0 → 2.6.0

data/README

@@ -5,8 +5,9 @@ SYNOPSIS
   a class factory and dsl for generating command line programs real quick
 
 URI
-  http://rubyforge.org/projects/codeforpeople/
   http://codeforpeople.com/lib/ruby/
+  http://rubyforge.org/projects/codeforpeople/
+  http://codeforpeople.rubyforge.org/svn/
 
 INSTALL
   gem install main
@@ -25,6 +26,7 @@ DESCRIPTION
     - parsing user defined ARGV and ENV
     - zero requirements for understanding the obtuse apis of *any* command
       line option parsers
+    - leather pants
 
   in short main.rb aims to drastically lower the barrier to writing uniform
   command line applications.
@@ -64,7 +66,7 @@ DESCRIPTION
       end
     }
 
-  which allows you a program called 'a.rb' to be invoked as
+  which allows a program, called 'a.rb', to be invoked as
 
     ruby a.rb install
 
@@ -252,7 +254,7 @@ SAMPLES
       b.rb
     
     SYNOPSIS
-      b.rb foo [options]+
+      b.rb foo foo foo [options]+
     
     PARAMETERS
       foo (3 -> int(foo)) 
@@ -357,7 +359,7 @@ SAMPLES
     
     PARAMETERS
       --foo=foo, -f (2 -> float(foo)) 
-      --bar=[bar], -b (1 ~> bool(bar=false)) 
+      --bar=[bar], -b (0 ~> bool(bar=false)) 
       --help, -h 
     
 
@@ -365,11 +367,130 @@ SAMPLES
 DOCS
   test/main.rb
 
-  vim -o lib/main.rb lib/main/*
+  find ./lib |xargs vim -o
 
   API section below
 
 HISTORY
+  2.6.0
+    - added 'mixin' feaature for storing, and later evaluating a block of
+      code.  the purpose of this is for use with modes where you want to keep
+      your code dry, but may not want to define something in the base class
+      for all to inherit.  'mixin' allows you to define the code to inherit
+      once and the selectively drop it in child classes (modes) on demand.
+      for example
+
+        Main {
+          mixin :foobar do
+            option 'foo'
+            option 'bar'
+          end
+
+          mode :install do
+            mixin :foobar
+          end
+
+          mode :uninstall do
+            mixin :foobar
+          end
+
+          mode :clean do
+          end
+        }
+
+    - mode definitions are now deferred to the end of the Main block, so you
+      can do this
+
+        Main {
+          mode 'a' do
+            mixin :foo
+          end
+
+          mode 'b' do
+            mixin :foo
+          end
+
+          def inherited_method
+            42
+          end
+
+          mixin 'foo' do
+            def another_inherited_method
+              'forty-two'
+            end
+          end
+        }
+
+    - added sanity check at end of paramter contruction
+
+    - improved auto usage generation when arity is used with arguments
+
+    - removed 'p' shortcut in paramerter dsl because it collided with
+      Kernel.p.  it's now called 'param'.  this method is availble *inside* a
+      parameter definition
+
+        option('foo', 'f'){
+          synopsis "arity = #{ param.arity }"
+        }
+      
+    - fixed bug where '--' did not signal the end of parameter parsing in a
+      getoptlong compliant way
+
+    - added (before/after)_parse_parameters, (before/after)_initialize, and
+      (before/after)_run hooks
+
+    - fixed bug where adding to usage via
+
+        usage['my_section'] = 'custom message'
+
+      totally horked the default auto generated usage message
+
+    - updated dependancies in gemspec.rb for attributes (~> 5.0.0) and
+      arrayfields (~> 4.3.0)
+
+    - check that client code defined run, iff not wrap_run! is called.  this is
+      so mains with a mode, but no run defined, still function correctly when 
+      passed a mode
+
+    - added new shortcut for creating accessors for parameters.  for example
+
+        option('foo'){
+          argument :required
+          cast :int
+          attr
+        }
+
+        def run
+          p foo ### this attr will return the parameter's *value*
+        end
+
+      a block can be passed to specify how to extract the value from the
+      parameter
+
+        argument('foo'){
+          optional
+          default 21 
+          cast :int
+          attr{|param| param.value * 2}
+        }
+
+        def run
+          p foo #=> 42 
+        end
+
+    - fixed bug where 'abort("message")' would print "message" twice on exit
+      if running under a nested mode (yes again - the fix in 2.4.0 wasn't
+      complete)
+
+    - added a time cast, which uses Time.parse
+
+        argument('login_time'){ cast :time }
+
+    - added a date cast, which uses Date.parse
+
+        argument('login_date'){ cast :date }
+    
+
   2.5.0
     - added 'examples', 'samples', and 'api' kewords to main dsl.  each
       keyword takes a list of strings which will be included in the help

data/TODO

@@ -0,0 +1,10 @@
+
+* clean up warnings under 'ruby -d'
+* error reporting weird for some errors
+
+===============================================================================
+X calls to abort sometimes lead to STDERR prining twice ;-(
+X main's' with modes, but no run do not operate properly - add default run w/wrap_run!
+X usage fubar when extra chunks are set
+X usage of arguments is fubar when negative arities are used
+X add sanity checks at parameter contruction completion

data/a.rb

@@ -1,24 +1,7 @@
 require 'main'
 
 Main {
-  option 'bar'
-
-  examples 'a', 'b'
-
-  api <<-txt
-    foobar
-    barfoo
-  txt
-
-  mode 'foo' do
-    option('bar'){ required }
-
-    def run
-      p params
-    end
-  end
-
-  def run 
-    p params
-  end
+  option('foo'){
+    examples
+  }
 }

data/gemspec.rb

@@ -25,7 +25,8 @@ Gem::Specification::new do |spec|
 
   spec.has_rdoc = File::exist? "doc" 
   spec.test_suite_file = "test/#{ lib }.rb" if File::directory? "test"
-  #spec.add_dependency 'lib', '>= version'
+  spec.add_dependency 'attributes', '>= 5.0.0'
+  spec.add_dependency 'arrayfields', '>= 4.3.0'
 
   spec.extensions << "extconf.rb" if File::exists? "extconf.rb"
 

data/install.rb

@@ -36,9 +36,11 @@ def install_rb(srcdir=nil, destdir=nil, mode=nil, bin=nil)
     next unless FileTest.file?(f)
     next if (f = f[srcdir.length+1..-1]) == nil
     next if (/CVS$/ =~ File.dirname(f))
+    next if (/\.svn/ =~ File.dirname(f))
     next if f =~ %r/\.lnk/
     next if f =~ %r/\.svn/
     next if f =~ %r/\.swp/
+    next if f =~ %r/\.svn/
     path.push f
     dir |= [File.dirname(f)]
   end

data/lib/main.rb

@@ -2,7 +2,7 @@ module Main
 #
 # top level constants
 #
-  Main::VERSION = '2.5.0' unless
+  Main::VERSION = '2.6.0' unless
     defined? Main::VERSION
   def self.version() Main::VERSION end
 
@@ -28,13 +28,13 @@ module Main
     42
   end
   begin
-    gem 'attributes', '~> 4.1.0'
+    gem 'attributes', '~> 5.0.0'
     require 'attributes'
   rescue Exception 
     require libdir + 'attributes'
   end
   begin
-    gem 'attributes', '~> 4.3.0'
+    gem 'arrayfields', '~> 4.3.0'
     require 'arrayfields'
   rescue Exception 
     require libdir + 'arrayfields'
@@ -45,6 +45,7 @@ module Main
   require libdir + 'stdext'
   require libdir + 'softspoken'
   require libdir + 'util'
+  require libdir + 'logger'
   require libdir + 'usage'
   require libdir + 'cast'
   require libdir + 'parameter'

data/lib/main/base.rb

@@ -21,7 +21,9 @@ module Main
                   end
 
                   pre_run
+                  before_run
                   self.class.const_get(:RUN).bind(self).call(*a, &b)
+                  after_run
                   post_run
 
                   finalize
@@ -66,13 +68,14 @@ module Main
         } 
       end
 
+    # attributes
       attribute( 'name' ){ File.basename $0 } 
       attribute( 'synopsis' ){ Usage.default_synopsis(self) }
       attribute( 'description' )
       attribute( 'usage' ){ Usage.default_usage self } 
       attribute( 'modes' ){ Mode.list }
+      attribute( 'mode_definitions' ){ Array.new }
       attribute( 'mode_name' ){ 'main' }
-      def mode_name=(value) @mode_name = Mode.new value end
       attribute( 'parent' ){ nil }
       attribute( 'children' ){ Set.new }
 
@@ -89,6 +92,21 @@ module Main
       attribute( 'exit_failure' ){ EXIT_FAILURE } 
       attribute( 'exit_warn' ){ EXIT_WARN } 
       inheritable_attribute( 'parameters' ){ Parameter::List[] }
+      inheritable_attribute( 'can_has_hash' ){ Hash.new }
+      inheritable_attribute( 'mixin_table' ){ Hash.new }
+
+    # override a few attributes
+      def mode_name=(value)
+        @mode_name = Mode.new value
+      end
+
+      def usage *argv, &block
+        usage! unless defined? @usage 
+        return @usage if argv.empty? and block.nil?
+        key, value, *ignored = argv
+        value = block.call if block
+        @usage[key.to_s] = value.to_s
+      end
 
       def create parent = Base, *a, &b
         Class.new parent do |child|
@@ -97,6 +115,15 @@ module Main
           child.context do
             child.class_eval &b if b
             child.default_options!
+            #child.wrap_run! unless child.const_defined?(:RUN)
+            mode_definitions.each do |name, block|
+              klass = 
+                create context do
+                  mode_name name.to_s
+                  module_eval &block if block
+                end
+              modes.add klass
+            end
           end
         end
       end
@@ -115,6 +142,14 @@ module Main
         end
       end
 
+      module ::Main
+        singleton_class{
+          def current
+            ::Main::Base.context
+          end
+        }
+      end
+
       def fully_qualified_mode
         list = []
         ancestors.each do |ancestor|
@@ -129,8 +164,10 @@ module Main
       def new(*a, &b)
         allocate.instance_eval do
           pre_initialize
+          before_initialize
           main_initialize *a, &b
           initialize
+          after_initialize
           post_initialize
           self
         end
@@ -167,14 +204,51 @@ module Main
       end
       alias_method 'env', 'environment'
 
+=begin
       def mode name, &b
         klass = 
           create context do
-            mode_name name
+            mode_name name.to_s
             module_eval &b if b
           end
         modes.add klass
       end
+=end
+
+      def mode name, &b
+        mode_definitions << [name, b]
+      end
+
+      def can_has ptype, *a, &b
+        key = a.map{|s| s.to_s}.sort_by{|s| -s.size }.first
+        can_has_hash.update key => [ptype, a, b]
+        key
+      end
+
+      def has key, *keys 
+        keys = [key, *keys].flatten.compact.map{|k| k.to_s}
+        keys.map do |key|
+          ptype, a, b = can_has_hash[key]
+          abort "yo - can *not* has #{ key.inspect }!?" unless(ptype and a and b)
+          send ptype, *a, &b
+          key
+        end
+      end
+
+      def mixin name, *names, &block
+        names = [name, *names].flatten.compact.map{|name| name.to_s}
+        if block
+          names.each do |name|
+            mixin_table[name] = block
+          end
+        else
+          names.each do |name|
+            module_eval &mixin_table[name]
+          end
+        end
+      end
+
+## TODO - for some reason these hork the usage!
 
       %w[ examples samples api ].each do |chunkname|
         module_eval <<-code
@@ -184,6 +258,8 @@ module Main
           end
         code
       end
+      alias_method 'example', 'examples'
+      alias_method 'sample', 'samples'
     end
     extend DSL
 
@@ -219,6 +295,7 @@ module Main
 =begin
 =end
     def pre_initialize() :hook end
+    def before_initialize() :hook end
     def main_initialize argv = ARGV, env = ENV, opts = {}
       @argv, @env, @opts = argv, env, opts
       setup_finalizers
@@ -227,6 +304,7 @@ module Main
       setup_logging
     end
     def initialize() :hook end
+    def after_initialize() :hook end
     def post_initialize() :hook end
 
     def setup_finalizers
@@ -253,7 +331,7 @@ module Main
     def logger= log
       unless(defined?(@logger) and @logger == log)
         case log 
-          when Logger
+          when ::Logger, Logger
             @logger = log
           when IO, StringIO
             @logger = Logger.new log 
@@ -320,6 +398,7 @@ module Main
     end
     
     def pre_parse_parameters() :hook end
+    def before_parse_parameters() :hook end
     def parse_parameters
       pre_parse_parameters
 
@@ -329,12 +408,15 @@ module Main
 
       post_parse_parameters
     end
+    def after_parse_parameters() :hook end
     def post_parse_parameters() :hook end
 
     def pre_run() :hook end
+    def before_run() :hook end
     def run
       raise NotImplementedError, 'run not defined'
     end
+    def after_run() :hook end
     def post_run() :hook end
 
     def mode_given?
@@ -380,7 +462,9 @@ module Main
         end
 
         if Softspoken === e or SystemExit === e
-          stderr.puts e.message unless(SystemExit === e and e.message.to_s == 'exit')
+          quiet = ((SystemExit === e and e.message.respond_to?('abort')) or # see main/stdext.rb
+                  (SystemExit === e and e.message == 'exit'))
+          stderr.puts e.message unless quiet
         else
           fatal{ e }
         end