Re: [ANN] Application-0.6.0

Great work, Jim!  Looks like very quick way to get started on
an script - bypassing the tediousness of option/arg parsing and
a documentation framework.

I have a few more comments:

* allow the definition of long_description to appear in
comments above the application class with all of the rdoc
formatting (you'll need to parse $0 with rdoc utilities).  I
think this gives a more ruby-like way of documenting scripts.

* make a certain set of options enabled by default: man page,
version, usage, etc.  That way all applications written in this
framework will immediately have this commonality.  And then
have a way for the application class to delete this
functionality if it isn't wanted for some strange reason.

* automatic usage generation (on your TODO already?).  You
should also allow a short description for the options and
arguments so that each option/arg will come out in a single
line.

* in your examples, show how the options are accessed by main.

This looks very similar to a package I wrote for perl years ago
(option/arg parsing, automatic usage, semi-automatic man page
handling).  On man pages for that package, I decided to
automatically generate POD (like rdoc comments) from the
option/arg description and then have programmer paste it in the
script and maintain it.  I believe the way you are doing it is
a more maintainable approach (i.e. when you add/change/delete
an option the man page is automatically updated), but the man
page formatting is not very flexible.  Probably a good
tradeoff.

--- Jim Freeze <[e-mail]> wrote:

> CommandLine - Application and OptionParser
> ==========================================
> Author: Jim Freeze
> Copyright 2005 Jim Freeze
> 
> ABOUT
> =====
> CommandLine is a tool that facilitates building command line
> applications and parsing the command line. Version 0.6.0
> supercedes OptionParser-0.5.0 since the option libs are now
> part
> of CommandLine. (I thought that maintianing two gems for 
> the option libraries would be confusing.)
> 
> CommandLine provides a convenient way to quickly develop
> a professional looking commandline application.
> The OptionParser provides efficient tools to add and
> handle options while still allowing your application to 
> handle just about any argument configuration you may need.
> 
> Probably the best way to describe how the tool works is
> with an example:
> (For now this email, and the source, is the only
> documentation
> for application. I would like to hear comments and
> make changes before getting to involved in a write-up.)
> 
> 
>   % cat app2.rb
>   #---------------------------------------------------
>   #!/usr/bin/env ruby
> 
>   require 'rubygems'
>   require 'commandline'
> 
>   #
>   # A minimum application
>   #
>   class App < CommandLine::Application
> 
>     def initialize
>       args 1
>       super
>     end
> 
>     def main
>     end
>   end#class App
>   #---------------------------------------------------
> 
>   % app2.rb  
>    Usage: app2.rb 
> 
>   % cat app5.rb 
>   #---------------------------------------------------
>   #!/usr/bin/env ruby
> 
>   begin
>     require 'commandline'
>   rescue LoadError
>     require 'rubygems'
>     retry
>   end
> 
>   class App < CommandLine::Application
> 
>     def initialize
>       version           "0.0.1"
>       author            "Author Name"
>       copyright         "Copyright (c) 2005, Jim Freeze"
>       synopsis          "[-dhV] param_file out_file"
>       short_description "A simple app example that takes two
> arguments."
>       long_description  "app5 is a simple application example
> that supports "+
>                         "three options and two commandline
> arguments."
> 
>       option :version
>       option :debug
>       option :help
> 
>       args   :param_file, :out_file
> 
>       super
>     end
> 
>     def main
>       puts "main called"
>       puts "@param_file = #{@param_file}"
>       puts "@out_file   = #{@out_file}"
>     end
>   end#class App
>   #---------------------------------------------------
> 
>   % app5.rb  
>    Usage: app5.rb [-dhV] param_file out_file
> 
>   % app5.rb -h
>   NAME
> 
>       app5.rb - A simple app example that takes two
> arguments.
> 
>   DESCRIPTION
> 
>       app5.rb is a simple application example that supports
> three options
>       and two commandline arguments.
> 
>   OPTIONS
> 
>       --version,-V
>           Displays application version.
> 
>       --debug,-d
>           Sets debug to true.
> 
>       --help,-h
>           Displays help page.
> 
>   AUTHOR:  Author Name
>   Copyright (c) 2005, Jim Freeze
> 
>   % app5.rb  f1 f2
>   main called
>   @param_file = f1
>   @out_file   = f2
> 
>   % cat app6.rb
>   #---------------------------------------------------
>   #!/usr/bin/env ruby
> 
>   begin
>     require 'commandline'
>   rescue LoadError
>     require 'rubygems'
>     retry
>   end
> 
>   #
>   # An application demonstrating customizing of canonical
> options
>   #
>   class App < CommandLine::Application
> 
>     def initialize
>       version           "0.0.1"
>       author            "Author Name"
>       copyright         "Copyright (c) 2005, Jim Freeze"
>       short_description "A simple app example that takes two
> arguments."
>       long_description  "This app is a simple application
> example that supports "+
>                         "three options and two commandline
> arguments."
> 
>       option :version, :names => %w(--version -v
> --notice-the-change-from-app5)
>       option :debug, :arity => [0,1], :arg_description =>
> "debug_level",
>              :opt_description => "Set debug level from 0 to
> 9."
>       option :help
> 
>       args   :param_file, :out_file
> 
>       super
>     end
> 
>     def main
>       puts "main called"
>       puts "@param_file = #{@param_file}"
>       puts "@out_file   = #{@out_file}"
>     end
>   end#class App
>   #---------------------------------------------------
> 
>   % app6.rb -h
>   NAME
> 
>       app6.rb - A simple app example that takes two
> arguments.
> 
>   DESCRIPTION
> 
>       This app is a simple application example that supports
> three
>       options and two commandline arguments.
> 
>   OPTIONS
> 
>       --version,-v,--notice-the-change-from-app5
>           Displays application version.
> 
>       --debug,-d debug_level
>           Set debug level from 0 to 9.
> 
>       --help,-h
>           Displays help page.
> 
>   AUTHOR:  Author Name
>   Copyright (c) 2005, Jim Freeze
> 
>   % cat app7.rb 
>   #---------------------------------------------------
>   #!/usr/bin/env ruby
> 
>   begin
>     require 'commandline'
>   rescue LoadError
>     require 'rubygems'
>     retry
>   end
> 
>   #
>   # An application demonstrating customizing of canonical
> options
>   #
>   class App < CommandLine::Application
> 
>     def initialize
>       version           "0.0.1"
>       author            "Author Name"
>       copyright         "Copyright (c) 2005, Jim Freeze"
>       short_description "A simple app example that takes two
> arguments."
>       long_description  "This app is a simple application
> example that "+
>                         "supports three options and two
> commandline "+
>                         "arguments."
> 
>       option :version, :names => %w(--version -v
> --notice-the-change-from-app5)
>       option :debug, :arity => [0,1], :arg_description =>
> "debug_level",
>              :opt_description => "Set debug level from 0 to
> 9."
>       option :help
> 
>       args   :param_file, :out_file
> 
>       super
>     end
> 
>     def main
>       puts "main called"
>       puts "@param_file = #{@param_file}"
>       puts "@out_file   = #{@out_file}"
>     end
>   end#class App
>   #---------------------------------------------------
> 
>   % app7.rb -h
>   NAME
> 
>       app7.rb - A simple app example that takes two
> arguments.
> 
>   DESCRIPTION
> 
>       This app is a simple application example that supports
> three
>       options and two commandline arguments.
> 
>   OPTIONS
> 
>       --version,-v,--notice-the-change-from-app5
>           Displays application version.
> 
>       --debug,-d debug_level
>           Set debug level from 0 to 9.
> 
>       --help,-h
>           Displays help page.
> 
>   AUTHOR:  Author Name
>   Copyright (c) 2005, Jim Freeze
> 
> TESTS
> =====
> Tests: 49
> Assertions: 215
> 
> 
> HISTORY
> =======
> After poking around in a few corporations, it was evident
> that
> option parsing was not well understood. Therefore, many
> inhouse
> tools were built that did not conform to any of the POSIX,
> Gnu or XTools
> option styles. CommandLine::OptionParser was developed so
> that
> new applications could be written that conformed to accepted
> standards,
> but non-standard option configurations could be handled as
> well
> to support legacy interfaces.
> 
> Once the option parsing was written, there was a need to
> streamline
> the repetitive tasks in setting up an application. The
> original
> boilerplate was simple, but after taking a few cues from
> rails, a significant amount of functionality was added to
> Application that make it a very useful tool yet simple to
> use.
> 
> More information and usage scenarios on OptionParser can be
> found at:
>     http://rubyforge.org/projects/optionparser/
> 
> DOWNLOAD & INSTALLATION
> =======================
> 
> Homepage:      http://rubyforge.org/projects/optionparser/
> Documentation: http://optionparser.rubyforge.org/
> Download:     
> http://rubyforge.org/frs/?group_id=632&release_id=2345
> 
> Dependencies:
> * None
> 
> Currently optionparser is only available as a rubygem.
> 
> Via RubyGems 
>   $ gem install -r CommandLine
> 
> All feedback is appreciated!
> 
> Installations not yet available
> ===============================
> # not in RPA yet
> Via RPA 
>   $ rpa install commandline
>   
> # this either
> The do-it-yourself way 
>   $ ruby setup.rb config
>   $ ruby setup.rb setup
>   $ ruby setup.rb install
>   
> # nor this
> The simplified do-it-yourself way 
>   $ rake install
> 
> 
> RELEASE NOTES
> =============
> 
> 0.6.0  06/24/2005
> * Refitted and renamed gem to CommandLine
> * Added application class
> * Application is all new with many features - includes
> features
>   suggested from the ARCTAN group - Eric Mahurin, Bassam El
> Abid 
>   and Matt Lawrence
> * TODO: Add automatic synopsis generation
> * TODO: Add CVS like parsing
>
---------------------------------------------------------------------
> 0.5.1  06/17/2005
> * Contains all planned features except CVS like command
> handling
> * Fixed loading path using gems. Is now loaded by:
>    require 'rubygems'
>    require 'commandline/optionparser'
> * Updated documentation
> 
>
---------------------------------------------------------------------
> 0.5.0  06/07/2005  
> * First public release
> 
> APPENDIX
> ========
> OPTION PARSER 
> =============
> CommandLine is a library for building applications 
> and parsing commandlines.
> 
> CommandLine::OptionParser is part of the CommandLine suite of
> tools and is used for command line parsing. The command line
> parser suite consists of classes CommandLine::Option, 
> CommandLine::OptionData and CommandLine::Application.
> 
> The parser supports POSIX, Gnu and XTools style parsing
> options. 
> It also provides flexibility to support <em>non standard</em>
> options. For example:
> 
> POSIX
> =====
> OptionParser.new Option.new(:posix, :names => "-f")
> 
> Gnu
> ===
> OptionParser.new Option.new(:names => %w[--file -f])
> 
> XTools
> ======
> OptionParser.new Option.new(:names => "-file")
> 
> User
> ====
> OptionParser.new(Option.new(
>    :names => %w(--file -file --files -files -f),
>    :arg_arity => [1,-1],
>    :arg_description => "file1 [file2, ...]"))
> 
> This last option prints:
> 
>  OPTIONS
> 
>      --file,-file,--files,-files,-f file1 [file2, ...]
> 
> 
> ACKNOWLEDGEMENTS
> ================
> This library contains code from:
> * Austin Ziegler - Text::Format
> * ?? - open4.rb - obtained from codeforthepeople
> -- 
> Jim Freeze
> 
> 



		
____________________________________________________ 
Yahoo! Sports 
Rekindle the Rivalries. Sign up for Fantasy Football 
http://football.fantasysports.yahoo.com