From: Eric Mahurin Date: 2005-06-25T04:41:16+09:00 Subject: 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 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 non standard > 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