[ANN] CommandLine-0.7.10

[Jim Freeze]

CommandLine-0.7.10
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
Author: Jim Freeze

WHAT
=3D=3D=3D=3D
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
=3D=3D=3D=3D
=09http://rubyforge.org/docman/view.php/632/233/posted-docs.index.html

ABOUT
=3D=3D=3D=3D=3D
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
=3D=3D=3D=3D=3D=3D=3D

% 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 =3D> [0,1],
=09=09=09=09 :arg_description =3D> "debug_level",
pt_description =3D> "Set debug level from 0 to 9.",
=09=09=09=09 pt_found =3D> get_args
option :version, :help

expected_args aram_file, ut_file
end

def main
=09=09#... 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
=3D=3D=3D=3D=3D
Tests: 82
Assertions: 319


DOWNLOAD & INSTALLATION
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

Homepage: http://rubyforge.org/projects/optionparser/
Documentation: http://rubyforge.org/docman/view.php/632/232/posted-docs.ind=
ex.html
Download: http://rubyforge.org/frs/?group_id=3D632&release_id=3D2345

Dependencies:
* None

Currently CommandLine is only available as a rubygem.

Via RubyGems
$ gem install -r commandline

All feedback is appreciated!

Installations not yet available
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D
# 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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
=3D=3D 0.7.10 11/06/2005
- Changed opt() to return @option_data
- OptionData objects now can respond to methods as well as []

=3D=3D 0.7.9 11/05/2005
=3D=3D=3D 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 pt_found
- Added args accessor for @args - suggested by Esteban Manchado Vel=E1zquez
- Added opt() accessor for @option_data[]


HISTORY
=3D=3D=3D=3D=3D=3D=3D
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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
This library contains code from:
* Austin Ziegler - Text::Format
* Ara - open4.rb - obtained from codeforthepeople

 

[Nathaniel S. H. Brown]

Hey Jim,

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
=20

-----Original Message-----
From: (e-mail address removed) [mailto:[email protected]] On=20
Behalf Of Jim Freeze
Sent: November 6, 2005 3:35 PM
To: ruby-talk ML
Subject: [ANN] CommandLine-0.7.10
=20
CommandLine-0.7.10
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
Author: Jim Freeze
=20
WHAT
=3D=3D=3D=3D
This is a quick update to CommandLine. The following changes=20
were made to OptionData and Application:
- Changed #opt to return @option_data
- OptionData objects now can respond to methods as well as []
=20
Basically, this lets you access option data with a method=20
call as well as #[]. Since method names cannot start with a=20
dash, some may like this and some may not. I am curious about=20
your opinions.
=20
DOCS
=3D=3D=3D=3D
=09
http://rubyforge.org/docman/view.php/632/233/posted-docs.index.html
=20
ABOUT
=3D=3D=3D=3D=3D
CommandLine is a library that greatly simplifies the=20
repetitive process of building a command line user interface=20
for your applications. It's 'ruby-like' usage style=20
streamlines application development so that even applications=20
with numerous configuration options can be quickly put=20
together. CommandLine automatically builds friendly usage and=20
help screens that are nicely formatted for the user. No=20
longer is starting an application a pain where you have to=20
copy boiler plate code (or a previous application) and retype=20
repetitive code to get an application started
=20
EXAMPLE
=3D=3D=3D=3D=3D=3D=3D
=20
% cat app.rb
#---------------------------------------------------
#!/usr/bin/env ruby
=20
require 'rubygems'
require 'commandline'
=20
class App < CommandLine::Application
=20
def initialize
version "0.0.1"
author "Author Name"
copyright "Copyright (c) 2005, Jim Freeze"
short_description "A simple app example that takes two=20
arguments."
long_description "This app is a simple application=20
example that "+
"supports three options and two commandline "+
"arguments."
=20
option :debug, :arity =3D> [0,1],
:arg_description =3D> "debug_level",
pt_description =3D> "Set debug level from 0 to 9.",
pt_found =3D> get_args
option :version, :help
=20
expected_args aram_file, ut_file
end
=20
def main
#... code here
end
end#class App
#---------------------------------------------------
=20
% app.rb -h
NAME
=20
app.rb - A simple app example that takes two arguments.
=20
DESCRIPTION
=20
This app is a simple application example that supports three
options and two commandline arguments.
=20
OPTIONS
=20
--debug,-d debug_level
Set debug level from 0 to 9.
=20
--version,-v
Displays application version.
=20
--help,-h
Displays help page.
=20
AUTHOR: Author Name
Copyright (c) 2005, Jim Freeze
=20
TESTS
=3D=3D=3D=3D=3D
Tests: 82
Assertions: 319
=20
=20
DOWNLOAD & INSTALLATION
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
=20
Homepage: http://rubyforge.org/projects/optionparser/
Documentation:=20
http://rubyforge.org/docman/view.php/632/232/posted-docs.index.html
Download: = http://rubyforge.org/frs/?group_id=3D632&release_id=3D2345
=20
Dependencies:
* None
=20
Currently CommandLine is only available as a rubygem.
=20
Via RubyGems
$ gem install -r commandline
=20
All feedback is appreciated!
=20
Installations not yet available
= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D
# not in RPA yet
Via RPA
$ rpa install commandline
=20
# this either
The do-it-yourself way
$ ruby setup.rb config
$ ruby setup.rb setup
$ ruby setup.rb install
=20
# nor this
The simplified do-it-yourself way
$ rake install
=20
=20
RELEASE NOTES
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
=3D=3D 0.7.10 11/06/2005
- Changed opt() to return @option_data
- OptionData objects now can respond to methods as well as []
=20
=3D=3D 0.7.9 11/05/2005
=3D=3D=3D Additions
- Renamed gem to lowercase commandline
- Added replay command options
- Added CommandLine::Application_wo_AutoRun - no auto run set=20
thru at_exit
- Added documentation for CommandLine::Application - instead=20
of just README
- Changed :arg_arity to :arity in Option
- Add :required for use with pt_found
- Added args accessor for @args - suggested by Esteban=20
Manchado Vel=E1zquez
- Added opt() accessor for @option_data[]
=20
=20
HISTORY
=3D=3D=3D=3D=3D=3D=3D
After poking around in a few corporations, it was evident=20
that option parsing was not well understood. Therefore, many=20
inhouse tools were built that did not conform to any of the=20
POSIX, Gnu or XTools option styles. CommandLine::OptionParser=20
was developed so that new applications could be written that=20
conformed to accepted standards, but non-standard option=20
configurations could be handled as well to support legacy interfaces.
=20
Once the option parsing was written, there was a need to=20
streamline the repetitive tasks in setting up an application.=20
The original boilerplate was simple, but after taking a few=20
cues from rails, a significant amount of functionality was=20
added to Application that make it a very useful tool yet=20
simple to use.
=20
More information and usage scenarios on OptionParser can be found at:
http://rubyforge.org/projects/optionparser/
=20
=20
ACKNOWLEDGEMENTS
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
This library contains code from:
* Austin Ziegler - Text::Format
* Ara - open4.rb - obtained from codeforthepeople

 

[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]

Hi Nathaniel

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]

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

 

[Gavin Sinclair]

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]

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 =3D> %w(--remove -R), # ...
expected_args :file
end

class App < AcmeApp
def App.run(args)
options =3D AppOptions.parse(args)
if options.debug
...
elsif options.remove
...
end
end
end

App.run(ARGV)

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.