main 0.0.2 → 2.0.0

data/README

@@ -2,18 +2,34 @@ NAME
   main.rb
 
 SYNOPSIS
-  a class factory and dsl for generating real main programs real quick
+  a class factory and dsl for generating command line programs real quick
 
 URI
   http://rubyforge.org/projects/codeforpeople/
   http://codeforpeople.com/lib/ruby/
 
 INSTALL
-  $sudo gem install main
+  gem install main
 
 DESCRIPTION
-  main.rb is a library which simplifies and unifies the details of creating
-  command line programs.  for instance, this program
+  main.rb features the following:
+
+    - unification of option, argument, keyword, and environment parameter
+      parsing
+    - auto generation of usage and help messages
+    - support for mode/sub-commands
+    - io redirection support
+    - logging hooks using ruby's built-in logging mechanism
+    - intelligent error handling and exit codes 
+    - use as dsl or library for building Main objects
+    - parsing user defined ARGV and ENV
+    - zero requirements for understanding the obtuse apis of *any* command
+      line option parsers
+
+  in short main.rb aims to drastically lower the barrier to writing uniform
+  command line applications.
+
+  for instance, this program
 
     require 'main'
 
@@ -29,10 +45,34 @@ DESCRIPTION
     }
 
   sets up a program which requires one argument, 'bar', and which may accept one
-  command line switch, '--foo' in addition to the single option which is always
-  accepted and handled appropriately: '--help', '-h'.
+  command line switch, '--foo' in addition to the single option/mode which is always
+  accepted and handled appropriately: 'help', '--help', '-h'.  for the most
+  part main.rb stays out of your command line namespace but insists that your
+  application has at least a help mode/option.
+
+  main.rb supports sub-commands in a very simple way
+
+    require 'main'
+
+    Main {
+      mode 'install' do
+        def run() puts 'installing...' end
+      end
+
+      mode 'uninstall' do
+        def run() puts 'uninstalling...' end
+      end
+    }
+
+  which allows you a program called 'a.rb' to be invoked as
 
-  for simple programs this is a real time saver but it's for more complex
+    ruby a.rb install
+
+  and
+
+    ruby a.rb uninstall
+
+  for simple programs main.rb is a real time saver but it's for more complex
   applications where main.rb's unification of parameter parsing, class
   configuration dsl, and auto-generation of usage messages can really streamline
   command line application development.  for example the following 'a.rb'
@@ -173,10 +213,9 @@ SAMPLES
       a.rb foo [options]+
     
     PARAMETERS
-      * foo [ 1 -> int(foo) ] 
+      foo (1 -> int(foo)) 
           the foo param 
-      
-      * --help, -h 
+      --help, -h 
     
 
 
@@ -216,10 +255,9 @@ SAMPLES
       b.rb foo [options]+
     
     PARAMETERS
-      * foo [ 3 -> int(foo) ] 
+      foo (3 -> int(foo)) 
           the foo param 
-      
-      * --help, -h 
+      --help, -h 
     
 
 
@@ -265,11 +303,9 @@ SAMPLES
       c.rb foo=foo [bar=bar] [options]+
     
     PARAMETERS
-      * foo=foo [ 2 -> float(foo) ] 
-      
-      * bar=bar [ 1 ~> bool(bar) ] 
-      
-      * --help, -h 
+      foo=foo (2 -> float(foo)) 
+      bar=bar (1 ~> bool(bar)) 
+      --help, -h 
     
 
 
@@ -320,22 +356,45 @@ SAMPLES
       d.rb --foo=foo [options]+
     
     PARAMETERS
-      * --foo=foo, -f [ 2 -> float(foo) ] 
-      
-      * --bar=[bar], -b [ 1 ~> bool(bar=false) ] 
-      
-      * --help, -h 
+      --foo=foo, -f (2 -> float(foo)) 
+      --bar=[bar], -b (1 ~> bool(bar=false)) 
+      --help, -h 
     
 
 
 DOCS
   test/main.rb
 
-  find lib|xargs -n1 vi -R
+  vim -o lib/main.rb lib/main/*
 
   API section below
 
 HISTORY
+  2.0.0
+    - removed need for proxy.rb via Main::Base.wrap_run!
+    - added error handling hooks for parameter parsing
+    - bundled arrayfields, attributes, and pervasives although gems are tried
+      first
+    - softened error messages for parameter parsing errors: certain classes of
+      errors are now 'softspoken' and print only the message, not the entire
+      stacktrace, to stderr.  much nicer for users.  this is configurable.
+    - added subcommand/mode support
+    - added support for user defined exception handling on top level
+      exceptions/exits
+    - added support for negative arity.  this users ruby's own arity
+      semantics, for example:
+      
+        lambda{|*a|}.arity     == -1
+        lambda{|a,*b|}.arity   == -2
+        lambda{|a,b,*c|}.arity == -3
+        ...
+
+      in otherwords parameters now support 'zero or more', 'one or more' ...
+      'n or more' argument semantics
+
+  1.0.0
+    - some improved usage messages from jeremy hinegardner
+
   0.0.2
     - removed dependancy on attributes/arrayfields.  main now has zero gem
       dependancies.
@@ -442,6 +501,57 @@ API
       my own usage message
     txt
 
+  ###########################################################################
+  #                         MODE API                                        #
+  ###########################################################################
+  #
+  # modes are class factories that inherit from their parent class.  they can
+  # be nested *arbitrarily* deep.  usage messages are tailored for each mode.
+  # modes are, for the most part, independant classes but parameters are
+  # always a superset of the parent class - a mode accepts all of it's parents
+  # paramters *plus* and additional ones
+  # 
+    option 'inherited-option'
+    argument 'inherited-argument'
+
+    mode 'install' do
+      option 'force' do
+        description 'clobber existing installation'
+      end
+
+      def run
+        inherited_method()
+        puts 'installing...'
+      end
+
+      mode 'docs' do
+        description 'installs the docs'
+
+        def run
+          puts 'installing docs...'
+        end
+      end
+    end
+
+    mode 'un-install' do
+      option 'force' do
+        description 'remove even if dependancies exist'
+      end
+
+      def run
+        inherited_method()
+        puts 'un-installing...'
+      end
+    end
+
+    def run
+      puts 'no mode yo?'
+    end
+
+    def inherited_method
+      puts 'superclass_method...'
+    end
+
 
   ###########################################################################
   #                         PARAMETER API                                   #
@@ -497,7 +607,8 @@ API
       description 'a long description of foo'
     #
     # arity - indicates how many times the parameter should appear on the
-    # command line.  the default is one.
+    # command line.  the default is one.  negative arities are supported and
+    # follow the same rules as ruby methods/procs.
     #
       arity 2
     #

data/README.tmpl

@@ -2,18 +2,34 @@ NAME
   main.rb
 
 SYNOPSIS
-  a class factory and dsl for generating real main programs real quick
+  a class factory and dsl for generating command line programs real quick
 
 URI
   http://rubyforge.org/projects/codeforpeople/
   http://codeforpeople.com/lib/ruby/
 
 INSTALL
-  $sudo gem install main
+  gem install main
 
 DESCRIPTION
-  main.rb is a library which simplifies and unifies the details of creating
-  command line programs.  for instance, this program
+  main.rb features the following:
+
+    - unification of option, argument, keyword, and environment parameter
+      parsing
+    - auto generation of usage and help messages
+    - support for mode/sub-commands
+    - io redirection support
+    - logging hooks using ruby's built-in logging mechanism
+    - intelligent error handling and exit codes 
+    - use as dsl or library for building Main objects
+    - parsing user defined ARGV and ENV
+    - zero requirements for understanding the obtuse apis of *any* command
+      line option parsers
+
+  in short main.rb aims to drastically lower the barrier to writing uniform
+  command line applications.
+
+  for instance, this program
 
     require 'main'
 
@@ -29,10 +45,34 @@ DESCRIPTION
     }
 
   sets up a program which requires one argument, 'bar', and which may accept one
-  command line switch, '--foo' in addition to the single option which is always
-  accepted and handled appropriately: '--help', '-h'.
+  command line switch, '--foo' in addition to the single option/mode which is always
+  accepted and handled appropriately: 'help', '--help', '-h'.  for the most
+  part main.rb stays out of your command line namespace but insists that your
+  application has at least a help mode/option.
+
+  main.rb supports sub-commands in a very simple way
+
+    require 'main'
 
-  for simple programs this is a real time saver but it's for more complex
+    Main {
+      mode 'install' do
+        def run() puts 'installing...' end
+      end
+
+      mode 'uninstall' do
+        def run() puts 'uninstalling...' end
+      end
+    }
+
+  which allows you a program called 'a.rb' to be invoked as
+
+    ruby a.rb install
+
+  and
+
+    ruby a.rb uninstall
+
+  for simple programs main.rb is a real time saver but it's for more complex
   applications where main.rb's unification of parameter parsing, class
   configuration dsl, and auto-generation of usage messages can really streamline
   command line application development.  for example the following 'a.rb'
@@ -141,11 +181,36 @@ SAMPLES
 DOCS
   test/main.rb
 
-  find lib|xargs -n1 vi -R
+  vim -o lib/main.rb lib/main/*
 
   API section below
 
 HISTORY
+  2.0.0
+    - removed need for proxy.rb via Main::Base.wrap_run!
+    - added error handling hooks for parameter parsing
+    - bundled arrayfields, attributes, and pervasives although gems are tried
+      first
+    - softened error messages for parameter parsing errors: certain classes of
+      errors are now 'softspoken' and print only the message, not the entire
+      stacktrace, to stderr.  much nicer for users.  this is configurable.
+    - added subcommand/mode support
+    - added support for user defined exception handling on top level
+      exceptions/exits
+    - added support for negative arity.  this users ruby's own arity
+      semantics, for example:
+      
+        lambda{|*a|}.arity     == -1
+        lambda{|a,*b|}.arity   == -2
+        lambda{|a,b,*c|}.arity == -3
+        ...
+
+      in otherwords parameters now support 'zero or more', 'one or more' ...
+      'n or more' argument semantics
+
+  1.0.0
+    - some improved usage messages from jeremy hinegardner
+
   0.0.2
     - removed dependancy on attributes/arrayfields.  main now has zero gem
       dependancies.
@@ -252,6 +317,57 @@ API
       my own usage message
     txt
 
+  ###########################################################################
+  #                         MODE API                                        #
+  ###########################################################################
+  #
+  # modes are class factories that inherit from their parent class.  they can
+  # be nested *arbitrarily* deep.  usage messages are tailored for each mode.
+  # modes are, for the most part, independant classes but parameters are
+  # always a superset of the parent class - a mode accepts all of it's parents
+  # paramters *plus* and additional ones
+  # 
+    option 'inherited-option'
+    argument 'inherited-argument'
+
+    mode 'install' do
+      option 'force' do
+        description 'clobber existing installation'
+      end
+
+      def run
+        inherited_method()
+        puts 'installing...'
+      end
+
+      mode 'docs' do
+        description 'installs the docs'
+
+        def run
+          puts 'installing docs...'
+        end
+      end
+    end
+
+    mode 'un-install' do
+      option 'force' do
+        description 'remove even if dependancies exist'
+      end
+
+      def run
+        inherited_method()
+        puts 'un-installing...'
+      end
+    end
+
+    def run
+      puts 'no mode yo?'
+    end
+
+    def inherited_method
+      puts 'superclass_method...'
+    end
+
 
   ###########################################################################
   #                         PARAMETER API                                   #
@@ -307,7 +423,8 @@ API
       description 'a long description of foo'
     #
     # arity - indicates how many times the parameter should appear on the
-    # command line.  the default is one.
+    # command line.  the default is one.  negative arities are supported and
+    # follow the same rules as ruby methods/procs.
     #
       arity 2
     #

data/TODO

@@ -0,0 +1,2 @@
+* error handling for parameter parsing - callback hooks 
+* mode handling 

data/a.rb

@@ -0,0 +1,26 @@
+require 'main'
+
+main(){
+  argument('foo'){
+    arity -1
+  }
+
+  mode 'a' do
+    argument('bar'){
+      arity -1
+    }
+    run { 
+      foobar
+      puts 'a' 
+    }
+  end
+
+  run { 
+      foobar
+    puts 'no mode' 
+  }
+
+  def foobar
+    puts :foobar
+  end
+}

data/gemspec.rb

@@ -22,6 +22,6 @@ Gem::Specification::new do |spec|
   spec.extensions << "extconf.rb" if File::exists? "extconf.rb"
 
   spec.author = "Ara T. Howard"
-  spec.email = "ara.t.howard@noaa.gov"
+  spec.email = "ara.t.howard@gmail.com"
   spec.homepage = "http://codeforpeople.com/lib/ruby/#{ lib }/"
 end