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:
% 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: rubyforge.org/projects/optionparser/ Documentation: optionparser.rubyforge.org/ Download: rubyforge.org/frs/?group_id=632&release_id=2345
Dependencies:
-
None
Currently optionparser is only available as a rubygem.
Via RubyGems
$ gem install -r CommandLine
All feedback is appreciated!
Installations not yet available
# not in RPA yet Via RPA
$ rpa install commandline
# this either The do-it-yourself way
$ ruby setup.rb config
$ ruby setup.rb setup
$ ruby setup.rb install
# nor this The simplified do-it-yourself way
$ rake install
RELEASE NOTES
0.6.0 06/24/2005
-
Refitted and renamed gem to CommandLine
-
Added application class
-
Application is all new with many features - includes features suggested from the ARCTAN group - Eric Mahurin, Bassam El Abid and Matt Lawrence
-
TODO: Add automatic synopsis generation
-
TODO: Add CVS like parsing
0.5.1 06/17/2005
-
Contains all planned features except CVS like command handling
-
Fixed loading path using gems. Is now loaded by:
require 'rubygems' require 'commandline/optionparser' -
Updated documentation
0.5.0 06/07/2005
-
First public release
APPENDIX
OPTION PARSER
CommandLine is a library for building applications and parsing commandlines.
CommandLine::OptionParser is part of the CommandLine suite of tools and is used for command line parsing. The command line parser suite consists of classes CommandLine::Option, CommandLine::OptionData and CommandLine::Application.
The parser supports POSIX, Gnu and XTools style parsing options. It also provides flexibility to support non standard options. For example:
POSIX
OptionParser.new Option.new(:posix, :names => “-f”)
Gnu
OptionParser.new Option.new(:names => %w[–file -f])
XTools
OptionParser.new Option.new(:names => “-file”)
User
OptionParser.new(Option.new(
:names => %w(--file -file --files -files -f),
:arg_arity => [1,-1],
:arg_description => "file1 [file2, ...]"))
This last option prints:
OPTIONS
--file,-file,--files,-files,-f file1 [file2, ...]
ACKNOWLEDGEMENTS
This library contains code from:
-
Austin Ziegler - Text::Format
-
?? - open4.rb - obtained from codeforthepeople