[ANN] Application-0.6.0

[Jim_Freeze2 (Jim Freeze)]

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

[Austin_Ziegler5 (Austin Ziegler)]

* 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

···

On 6/24/05, Jim Freeze <jim@freeze.org> wrote:
--
Austin Ziegler * halostatue@gmail.com
               * Alternate: austin@halostatue.ca

[Eric_Mahurin1 (Eric Mahurin)]

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

Yahoo Fantasy Football

[Levin_Alexander1 (Levin Alexander)]

Great! However, arguments with options do not seem to work correctly

$ cat testapp.rb
#!/usr/bin/env ruby
require 'rubygems'
require 'commandline'

# A minimum application
class App < CommandLine::Application
   def initialize
     option :debug, :arity => [1,1],
            :opt_description => "Set debug level from 0 to 9"

     args :file1, :file2
     super
   end
end #class App

$ ./testapp.rb --debug 2 file1 file2
Exception `CommandLine::Application::ArgumentError' at /usr/lib/ruby/gems/1.8/gems/CommandLine-0.6.0/lib/commandline/application.rb:87 - Too many arguments. Found 3 but expected 2.
  Usage: testapp.rb
ERROR: Too many arguments. Found 3 but expected 2.
  Usage: testapp.rb

···

Jim Freeze <jim@freeze.org> wrote:

CommandLine - Application and OptionParser

--
-Levin

[YANAGAWA_Kazuhisa]

Just curious but Subject says the released library is Application
while the announcement says that is CommandLine. Which is which?

# Yes, I believe CommandLine is one. This is just a reminder.

···

--
kjana@dm4lab.to June 25, 2005
It is comparison that makes men happy or miserable.

[Jim_Freeze2 (Jim Freeze)]

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

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

···

On 6/24/05, Jim Freeze <jim@freeze.org> wrote:

--
Jim Freeze

[Jim_Freeze2 (Jim Freeze)]

* 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

[Jim_Freeze2 (Jim Freeze)]

* YANAGAWA Kazuhisa <kjana@dm4lab.to> [2005-06-25 14:14:08 +0900]:

Just curious but Subject says the released library is Application
while the announcement says that is CommandLine. Which is which?

# Yes, I believe CommandLine is one. This is just a reminder.

I used the basename for the release, i.e, Application, but the
full name is

  CommandLine::Application

and it contains the additional libraries:

  CommandLine::Option
  CommandLine::OptionParser
  CommandLine::OptionData

Does that help. Do I need to change something to make it more clear?

···

--
Jim Freeze

[Jim_Freeze2 (Jim Freeze)]

* Levin Alexander <levin@grundeis.net> [2005-06-25 13:53:17 +0900]:

Great! However, arguments with options do not seem to work correctly

$ cat testapp.rb
#!/usr/bin/env ruby
require 'rubygems'
require 'commandline'

# A minimum application
class App < CommandLine::Application
  def initialize
    option :debug, :arity => [1,1],
           :opt_description => "Set debug level from 0 to 9"

    args :file1, :file2

Here, you are telling the app to expect two arguments.

    super
  end
end #class App

$ ./testapp.rb --debug 2 file1 file2

This results in:

  @file1 #=> "2"
  @file2 #=> "file1"

  file2 #=> error

Can you tell me how you expected the app to respond?

···

Jim Freeze <jim@freeze.org> wrote:

Exception `CommandLine::Application::ArgumentError' at
/usr/lib/ruby/gems/1.8/gems/CommandLine-0.6.0/lib/commandline/application.rb:87
- Too many arguments. Found 3 but expected 2.
Usage: testapp.rb
ERROR: Too many arguments. Found 3 but expected 2.
Usage: testapp.rb

--
Jim Freeze

[Eric_Mahurin1 (Eric Mahurin)]

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

···

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

> * 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/mailtour.html

[Jim_Weirich1 (Jim Weirich)]

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.

···

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.

--
-- Jim Weirich jim@weirichhouse.org http://onestepback.org
-----------------------------------------------------------------
"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)

[Levin_Alexander1 (Levin Alexander)]

    option :debug, :arity => [1,1],
           :opt_description => "Set debug level from 0 to 9"

    args :file1, :file2

Here, you are telling the app to expect two arguments.

I thought that /option/ defines the possible arguments and /args/ defined which of these are required.

I expected ths:

option :debug, :arity => [1,1]

to be a definition of the (optional) argument "--debug", which consumes exactly one parameter.

$ ./testapp.rb --debug 2 file1 file2

This results in:

  @file1 #=> "2"
  @file2 #=> "file1"

  file2 #=> error

Can you tell me how you expected the app to respond?

$ ./testapp.rb --debug 2 file1 file2

@debug #=> "2"
@file1 #=> "file1"
@file2 #=> "file2"

How is your example app6.rb supposed to work?

···

Jim Freeze <jim@freeze.org> wrote:

--
/Levin

[Eric_Mahurin1 (Eric Mahurin)]

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.

···

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

____________________________________________________
Yahoo! Sports
Rekindle the Rivalries. Sign up for Fantasy Football

Yahoo Fantasy Football

[Jim_Freeze2 (Jim Freeze)]

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

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

···

On Friday 24 June 2005 04:04 pm, Jim Freeze wrote:

--
Jim Freeze

[Jim_Freeze2 (Jim Freeze)]

* 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_Freeze2 (Jim Freeze)]

* Levin Alexander <levin@grundeis.net> [2005-06-28 13:01:17 +0900]:

>> option :debug, :arity => [1,1],
>> :opt_description => "Set debug level from 0 to 9"
>>
>> args :file1, :file2
>
>Here, you are telling the app to expect two arguments.

I thought that /option/ defines the possible arguments and /args/ defined
which of these are required.

I expected ths:
> option :debug, :arity => [1,1]

to be a definition of the (optional) argument "--debug", which consumes
exactly one parameter.

Instead of :arity, you want :arg_arity. When I originally wrote this,
I wrote OptionParser first, so the ;arg_arity was to let the user
know that they were specifying the arity for the arguments that
applied to the option. But in this context, it could be construed
to be the arity is for the arguments to the application.
Maybe this should be changed to:

  option :debug, :arity => [1,1]
or
  option :debug, :opt_arity => [1,1]

I think I like the first best.

>>$ ./testapp.rb --debug 2 file1 file2
>
>This results in:
>
> @file1 #=> "2"
> @file2 #=> "file1"
>
> file2 #=> error
>
>Can you tell me how you expected the app to respond?

$ ./testapp.rb --debug 2 file1 file2

@debug #=> "2"
@file1 #=> "file1"
@file2 #=> "file2"

Your little example also got me thinking that the arguments
to the application should be like those to the options--they
should be able to take arguments. Maybe something like:

  args :number { |arg| arg.to_f }
  args :file1 { |arg| raise if File.exists(arg) }

or just the regular

  args :number, :file

What do you think?

···

Jim Freeze <jim@freeze.org> wrote:

--
Jim Freeze

[Jim_Freeze2 (Jim Freeze)]

* 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

[Eric_Mahurin1 (Eric Mahurin)]

perfect!

···

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

> 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?"

____________________________________________________
Yahoo! Sports
Rekindle the Rivalries. Sign up for Fantasy Football

Yahoo Fantasy Football

[Levin_Alexander1 (Levin Alexander)]

  option :debug, :arity => [1,1]

That would be my favourite. What about:

   option :example {
     names %w(--example -e)
     arity [1,1]
     opt_description "Option Description"
   }

$ ./testapp.rb --debug 2 file1 file2

@debug #=> "2"

I just realized that this does not work. How can I access option arguments from my Application? Maybe there should be a Hash, like:

   arg[:example] #=> "2"
   arg[:foo] #=> ["bar", "baz"]
   arg[:not_given] #=> nil

... "arg" is probably not the best name

@file1 #=> "file1"
@file2 #=> "file2"

Btw, what is the difference between:
   :opt_found => Proc.new {|a,b| puts a,b}
   # works, prints
   # #<CommandLine::Option:0xb7d724a0>
   # -t
and:
   :opt_found => lambda {|a,b| puts a,b}
   # does not work, prints
   # ERROR: wrong number of arguments (3 for 2)

Your little example also got me thinking that the arguments
to the application should be like those to the options--they
should be able to take arguments. Maybe something like:

  args :number { |arg| arg.to_f }
  args :file1 { |arg| raise if File.exists(arg) }

Yes, that would be quite useful. You should also support:

   args :arity_2 { |arg1, arg2| ... }

···

Jim Freeze <jim@freeze.org> wrote:

--
-Levin

[Mark_Probert]

Hi ..

For an application that takes arguments, when it sees
none, it takes that as a que to print the usage.

Many of my scripts have just optional arguments, like

  $ foo
  $ foo -g # debugging, rather than -d
  $ foo -f bar.txt

Perhaps having a global switch like

  CommandLine::Application::NO_ARGS_OK

or a different base class where no arguments is ok,

  CommandLine::BasicApp

might work.

···

On Friday 24 June 2005 15:46, Jim Freeze wrote:

--
-mark. (probertm at acm dot org)