[ANN] CommandLine-0.7.10
Jim Freeze
==================
Author: Jim Freeze
WHAT
====
This is a quick update to CommandLine. The following changes were
made to OptionData and Application:
- Changed #opt to return @option_data
- OptionData objects now can respond to methods as well as []
Basically, this lets you access option data with a method call
as well as #[]. Since method names cannot start with a dash,
some may like this and some may not. I am curious about your opinions.
DOCS
====
http://rubyforge.org/docman/view.php/632/233/posted-docs.index.html
ABOUT
=====
CommandLine is a library that greatly simplifies the repetitive
process of building a command line user interface for your
applications. It's 'ruby-like' usage style streamlines application
development so that even applications with numerous configuration
options can be quickly put together. CommandLine automatically builds
friendly usage and help screens that are nicely formatted for the
user. No longer is starting an application a pain where you have to
copy boiler plate code (or a previous application) and retype
repetitive code to get an application started
EXAMPLE
=======
% cat app.rb
#---------------------------------------------------
#!/usr/bin/env ruby
require 'rubygems'
require 'commandline'
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 :debug, :arity => [0,1],
:arg_description => "debug_level",
:opt_description => "Set debug level from 0 to 9.",
:opt_found => get_args
option :version, :help
expected_args :param_file, :out_file
end
def main
#... code here
end
end#class App
#---------------------------------------------------
% app.rb -h
NAME
app.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
--debug,-d debug_level
Set debug level from 0 to 9.
--version,-v
Displays application version.
--help,-h
Displays help page.
AUTHOR: Author Name
Copyright (c) 2005, Jim Freeze
TESTS
=====
Tests: 82
Assertions: 319
DOWNLOAD & INSTALLATION
=======================
Homepage: http://rubyforge.org/projects/optionparser/
Documentation: http://rubyforge.org/docman/view.php/632/232/posted-docs.index.html
Download: http://rubyforge.org/frs/?group_id=632&release_id=2345
Dependencies:
* None
Currently CommandLine 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.7.10 11/06/2005
- Changed opt() to return @option_data
- OptionData objects now can respond to methods as well as []
== 0.7.9 11/05/2005
=== Additions
- Renamed gem to lowercase commandline
- Added replay command options
- Added CommandLine::Application_wo_AutoRun - no auto run set thru at_exit
- Added documentation for CommandLine::Application - instead of just README
- Changed :arg_arity to :arity in Option
- Add :required for use with :opt_found
- Added args accessor for @args - suggested by Esteban Manchado Velázquez
- Added opt() accessor for @option_data[]
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/
ACKNOWLEDGEMENTS
================
This library contains code from:
* Austin Ziegler - Text::Format
* Ara - open4.rb - obtained from codeforthepeople
--
--
Jim Freeze
Nathaniel S. H. Brown
Really cool tool!
Just tried it out with a simple "svn-add" script
(http://www.nshb.net/node/240) and it worked great. Was super quick to
implement such a simple script :)
Warmest regards,
Nathan.
--------------------------------------------------------------
Nathaniel S. H. Brown Toll Free 1.877.4.INIMIT
Inimit Innovations Phone 604.724.6624
www.inimit.com Fax 604.444.9942
Gavin Sinclair
>
> class App < CommandLine::Application
>
> def initialize
> version "0.0.1"
> author "Author Name"
> copyright "Copyright (c) 2005, Jim Freeze"
> All feedback is appreciated!
Two questions:
* I want to write an application that inherits a different class. Can
I still use this library?
* Does this interact in any way with the stdlib's 'optparse'
(OptionParser class)?
Thanks,
Gavin
Jim Freeze
On 11/7/05, Nathaniel S. H. Brown <ns...@inimit.com> wrote:
> Hey Jim,
>
> Really cool tool!
Thanks
> Just tried it out with a simple "svn-add" script
> (http://www.nshb.net/node/240) and it worked great. Was super quick to
> implement such a simple script :)
Great. Looks loke you made good use of it.
I may actually steal the svn util you wrote with it. :)
BTW, looks like you found a bug in my ANN doc.
The copyright description doesn't need the word 'Copyright (c)' in
the text any more. That is provided automatically.
Thanks
--
Jim Freeze
Jim Freeze
> Jim Freeze wrote:
> >
> > class App < CommandLine::Application
> >
> > def initialize
> > version "0.0.1"
> > author "Author Name"
> > copyright "Copyright (c) 2005, Jim Freeze"
# my bad here
> > [...]
>
> > All feedback is appreciated!
>
> Two questions:
>
> * I want to write an application that inherits a different class. Can
> I still use this library?
Good question. Can you give me an example.
When I created this there was much debate over whether
to make this a module or a class. IIRC, class was used
becuase it was thought that any mixed in functionality
should really go in its own class to have SOI. The app
class is really just to handle the interface with the user.
So, a standard app would look like so:
class MyApp < CommandLine::Application
def initialize
end
def main
# keep SOI
MyBigWorkingClass.new(@option_data)
end
end
> * Does this interact in any way with the stdlib's 'optparse'
> (OptionParser class)?
No. CommandLine has its own (more powerful) parser called
CommandLine::OptionParser.
--
Jim Freeze
Gavin Sinclair
> > * I want to write an application that inherits a different class. Can
> > I still use this library?
>
> Good question. Can you give me an example.
Say I have a company-specific application class (which I don't, but
let's pretend) called AcmeApp, which all applications are to inherit.
Say I also want to use your library. I'd like to see the option
parsing be independent of the application. Perhaps something like
this:
class AppOptions < CommandLine::OptionParser
author "Gavin Sinclair"
description "blah blah blah"
options :help, :debug
option :names => %w(--remove -R), # ...
expected_args :file
end
class App < AcmeApp
def App.run(args)
options = AppOptions.parse(args)
if options.debug
...
elsif options.remove
...
end
end
end
App.run(ARGV)
> When I created this there was much debate over whether
> to make this a module or a class. IIRC, class was used
> becuase it was thought that any mixed in functionality
> should really go in its own class to have SOI. The app
> class is really just to handle the interface with the user.
> So, a standard app would look like so:
>
> class MyApp < CommandLine::Application
> def initialize
> end
> def main
> # keep SOI
> MyBigWorkingClass.new(@option_data)
> end
> end
Oh I see...
A few small applications I'm working have a common base class. I'll
see if I can rearrange the code or otherwise get it working with the
CommandLine library. Otherwise I might have some more specific
suggestions.
Cheers,
Gavin
Jim Freeze
Your AppOptions is basically playing the role of the
Application class here. :)
The author, description, etc.. are methods of Application.
They add to the formatted output of OptionParser. All the
hard work is done by OptionParser.
You could use OptionParser similar to what you have above,
but you won't get the convenience of the Application wrappers,
unless of course you write your own.
That is originally why this project started out as OptionParser.
Then I started encapsulating some common scenarios, and
Application was born.
> Oh I see...
>
> A few small applications I'm working have a common base class. I'll
> see if I can rearrange the code or otherwise get it working with the
> CommandLine library. Otherwise I might have some more specific
> suggestions.
Yes. Your app class is just the interface to collect the arguments
from the command line. You should be able to keep the app
class completely separate. If not, I would be interesting in knowing
why to see if we need to adjust some things.
--
Jim Freeze