Asp Forum - [ANN] Application-0.6.0

Jim Freeze

6/24/2005 6:53:00 PM

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/opt...

DOWNLOAD & INSTALLATION
=======================

Homepage: http://rubyforge.org/projects/opt...
Documentation: http://optionparser.ruby...
Download: http://rubyforge.org/frs/?group_id=632&relea...

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

21 Answers

Austin Ziegler

6/24/2005 7:26:00 PM

On 6/24/05, Jim Freeze <jim@freeze.org> wrote:
> * Austin Ziegler - Text::Format

I'd probably be a good idea for me to release Text::Format 1.0, then,
wouldn't it? You could probably just use the Text::Format gem, then.

> * ?? - open4.rb - obtained from codeforthepeople

Ara does codeforpeople.

-austin
--
Austin Ziegler * halostatue@gmail.com
* Alternate: austin@halostatue.ca

Eric Mahurin

6/24/2005 7:41:00 PM

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 <jim@freeze.org> 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/opt...
>
> DOWNLOAD & INSTALLATION
> =======================
>
> Homepage: http://rubyforge.org/projects/opt...
> Documentation: http://optionparser.ruby...
> Download:
> http://rubyforge.org/frs/?group_id=632&relea...
>
> 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...

Jim Freeze

6/24/2005 7:51:00 PM

* Austin Ziegler <halostatue@gmail.com> [2005-06-25 04:26:29 +0900]:

> On 6/24/05, Jim Freeze <jim@freeze.org> wrote:
> > * Austin Ziegler - Text::Format

> I'd probably be a good idea for me to release Text::Format 1.0, then,
> wouldn't it? You could probably just use the Text::Format gem, then.

Austin, you take hints so well. :)
Right now it is just embedded in the commandline search path,
but it is done in a way that I can pull it at any time and
add a gem dependency.

> > * ?? - open4.rb - obtained from codeforthepeople
> Ara does codeforpeople.

Thanks

--
Jim Freeze

Jim Freeze

6/24/2005 8:04:00 PM

* Eric Mahurin <eric_mahurin@yahoo.com> [2005-06-25 04:41:16 +0900]:

> 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.

Thanks

> 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.

I take patches. ;)
If this is supported, how do you suggest handling the existance of
both long_description and rdoc.

> * 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.

Hmm, haven't thought about that, but sounds reasonable.
If I follow the rails framework, then this would be a
scaffold. However, I have not mentioned what is behind curtain
#3, but I can tell you it is something that will generate
a project directory structure and an application skeleton.
This skeleton (scaffold in rails speak) could just include
them as they are done now.

Would this be ok or do you still think there should be
implicit options that a user must delete?

> * 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.

This is already supported. Here are the rules:

-x Single character options desc. goes on same line.

--x Double dash and single character options desc. goes on the same line.

---x
Triple dash and single character desc. goes on the next
line.

--y Double dash and single character options description that wraps to
the next line.

You usually only see this for POSIX options.

> * 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.

What about adding a #to_rdoc so the app can document itself?

--
Jim Freeze

Eric Mahurin

6/24/2005 8:35:00 PM

--- Jim Freeze <jim@freeze.org> wrote:

> > 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.
>
> I take patches. ;)

sorry, busy with my own ruby coding right now...

> If this is supported, how do you suggest handling the
> existance of
> both long_description and rdoc.

If you figure out how to get this working, maybe
long_description would be obsolete. For any reasonable size
script, embedding the long_description where it is now would
probably create too much clutter. Putting it in comments using
rdoc formatting would seem to make more sense.

> > * 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.
>
> Hmm, haven't thought about that, but sounds reasonable.
> If I follow the rails framework, then this would be a
> scaffold. However, I have not mentioned what is behind
> curtain
> #3, but I can tell you it is something that will generate
> a project directory structure and an application skeleton.
> This skeleton (scaffold in rails speak) could just include
> them as they are done now.
>
> Would this be ok or do you still think there should be
> implicit options that a user must delete?

Since I have no knowledge of rails and don't know what's behind
curtain #3, I don't know what you are talking about.

> > * 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.
>
> This is already supported. Here are the rules:
>
> -x Single character options desc. goes on same line.
>
> --x Double dash and single character options desc. goes
> on the same line.
>
> ---x
> Triple dash and single character desc. goes on the
> next
> line.
>
> --y Double dash and single character options description
> that wraps to
> the next line.
>
> You usually only see this for POSIX options.

What I meant was that you should have short description for the
usage and a long description for the man page. For example,
compare gzip -h (usage) vs. man gzip (full docs). One has a
few words per option and the other a full paragraph per option.

> > * 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.
>
> What about adding a #to_rdoc so the app can document itself?
>
> --
> Jim Freeze
>
>

__________________________________
Yahoo! Mail
Stay connected, organized, and protected. Take the tour:
http://tour.mail.yahoo.com/mai...

Jim Weirich

6/24/2005 8:59:00 PM

On Friday 24 June 2005 04:04 pm, Jim Freeze wrote:
> > * 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.
>
> Hmm, haven't thought about that, but sounds reasonable.

One way to handle this is to provide a CommandLine::BasicApplication with no
defaults and also CommandLine::Application with the mentioned goodies. This
allows people to fall back to a bare bones version with little effort.

Another approach is to provide additional functionality in modules (or
something module-like). Include a module and get several related features.

--
-- Jim Weirich jim@weirichhouse.org http://onest...
-----------------------------------------------------------------
"Beware of bugs in the above code; I have only proved it correct,
not tried it." -- Donald Knuth (in a memo to Peter van Emde Boas)

Eric Mahurin

6/24/2005 9:15:00 PM

--- Jim Weirich <jim@weirichhouse.org> wrote:

> On Friday 24 June 2005 04:04 pm, Jim Freeze wrote:
> > > * 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.
> >
> > Hmm, haven't thought about that, but sounds reasonable.
>
> One way to handle this is to provide a
> CommandLine::BasicApplication with no
> defaults and also CommandLine::Application with the mentioned
> goodies. This
> allows people to fall back to a bare bones version with
> little effort.
>
> Another approach is to provide additional functionality in
> modules (or
> something module-like). Include a module and get several
> related features.

That sounds like the right way to do it.
CommandLine::Application would be a derived class of
CommandLine::BasicApplication and most applications would be
derived from CommandLine::Application to get the goodies.

The reason I ask for this is that it is sometimes frustrating
to simply get usage. It varies from -u, -usage, -h, -help,
--help, etc. If an app has required options/args, it usually
is not a problem, but when nothing is required, it may take a
while to figure out how the get the usage. Having a standard
for these goodies would be a good thing.

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

Jim Freeze

6/24/2005 10:31:00 PM

* Jim Weirich <jim@weirichhouse.org> [2005-06-25 05:58:51 +0900]:

> On Friday 24 June 2005 04:04 pm, Jim Freeze wrote:
> > > * 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.
> >
> > Hmm, haven't thought about that, but sounds reasonable.
>
> One way to handle this is to provide a CommandLine::BasicApplication with no
> defaults and also CommandLine::Application with the mentioned goodies. This
> allows people to fall back to a bare bones version with little effort.
>
> Another approach is to provide additional functionality in modules (or
> something module-like). Include a module and get several related features.

Both are good suggestions. Thanks.
Using that, I would make the following equivalent:

class App < CommandLine::BasicApplication
standard_options
end

class App < CommandLine::Application
end

The is nice because I don't have to figure out a way to
let the user remove options.

--
Jim Freeze

Jim Freeze

6/24/2005 10:39:00 PM

* Eric Mahurin <eric_mahurin@yahoo.com> [2005-06-25 05:34:48 +0900]:

> > I take patches. ;)
>
> sorry, busy with my own ruby coding right now...
Yeah, aren't we all. :)

> > Hmm, haven't thought about that, but sounds reasonable.
> > If I follow the rails framework, then this would be a
> > scaffold. However, I have not mentioned what is behind
> > curtain
> > #3, but I can tell you it is something that will generate
> > a project directory structure and an application skeleton.
> > This skeleton (scaffold in rails speak) could just include
> > them as they are done now.
> >
> > Would this be ok or do you still think there should be
> > implicit options that a user must delete?
>
> Since I have no knowledge of rails and don't know what's behind
> curtain #3, I don't know what you are talking about.

Eric, you're reading too fast. I told you what was behind curtain #3. ;)
But, this may be a mute point if we use Jim Weirich's idea.

> What I meant was that you should have short description for the
> usage and a long description for the man page. For example,
> compare gzip -h (usage) vs. man gzip (full docs). One has a
> few words per option and the other a full paragraph per option.

Yes, but that seems like going overboard. What I mean is that
seems like it could get busy quick. I suppose one way to clean
that up would be to use the std description for both #usage
and #man, but if they define a description for #man, then
use it.

So, how about something like:

option :names => "--my-option",
:opt_description => "this is used in usage (and maybe man)",
:arg_description => "the_argument",
# use text below in man page if they exist
:man_opt_description => "this is a longer description "+
"indended for the man page.",
:man_arg_description => "do_we_really_need_this_for_arg?"

--
Jim Freeze

Jim Freeze

6/24/2005 10:47:00 PM

* Eric Mahurin <eric_mahurin@yahoo.com> [2005-06-25 06:14:49 +0900]:

> The reason I ask for this is that it is sometimes frustrating
> to simply get usage. It varies from -u, -usage, -h, -help,
> --help, etc. If an app has required options/args, it usually
> is not a problem, but when nothing is required, it may take a
> while to figure out how the get the usage. Having a standard
> for these goodies would be a good thing.

CommandLine::Application does the same thing.
For an application that takes arguments, when it sees
none, it takes that as a que to print the usage.
If it does not expect any arguments, it won't print
the usage and the user has to guess. I don't know
of any way around this.

But, you bring up a good point. Consider a std app:

% app
Usage: app [-dhv] file

That's it. That's all you get. What is -h? What is -d? or -v?

I used to print the man page instead of the usage, but that
got long. Now I'm thinking that the usage statement should
be more clear. We need a short description and some kind of
way to at least know how to get more info. Seems like there
should be a way to add the description of selected options
to the usage statement.

What do you think?

--
Jim Freeze

comp.lang.ruby

[ANN] Application-0.6.0

Jim Freeze

Austin Ziegler

Eric Mahurin

Jim Freeze

Jim Freeze

Eric Mahurin

Jim Weirich

Eric Mahurin

Jim Freeze

Jim Freeze

Jim Freeze

x Login to ForumsZone