CommandLine - Application and OptionParser
==========================================
Author: Jim Freeze
Copyright 2005 Jim Freeze

DOCS: http://rubyforge.org/docman/view.php/632/232/posted-docs.index.html

Welcome to CommandLine

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.

CommandLine smartly handles the arguments passed on the commandline. For example, if your application accepts arguments, and none are given, it prints a usage statement. But, if your application accepts no arguments, CommandLine will happily run your application. CommandLine also handles a complex set of options through the OptionParser library, which is described below.

OptionParser is designed to be a flexible command line parser with a Ruby look and feel to it. OptionParser got its birth from the need for a parser that is standards compliant, yet flexible. OptionParser supports the standard command line styles of Unix, Gnu and X Toolkit, but also lets you break those rules.

OptionParser is not a port of a traditional command line parser, but it is written to meet the feature requirements of traditional command line parsers. When using it as a library, you should notice that it is expressive, supports Ruby’s blocks and lambda’s, and is sprinkled with a little bit of magic.

While the library can be used by itself, it is also designed to work with the CommandLine::Application class. These tools work together to facilitate the generation of a sophisticated (batch oriented) application user interface in a matter of minutes.

If you need a refresher on the traditional option parsing schemes, see "Traditional Option Parsing Schemes" below.


EXAMPLES
========

Probably the best way to describe how the tool works is
with some examples:

  % cat app.rb
  #---------------------------------------------------
  #!/usr/bin/env ruby

  require 'rubygems'
  require 'commandline'

  #
  # A minimum application
  #
  class App < CommandLine::Application
    def main
    end
  end#class App
  #---------------------------------------------------

  % app.rb  
   Usage: app.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         "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

      expected_args   :param_file, :out_file
    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         "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

      expected_args   :param_file, :out_file
    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         "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

      expected_args   :param_file, :out_file
    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: 81
Assertions: 310


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.7.9  11/05/2005
=== Additions
- Renamed gem to lowercase commandline
- Added replay command options
- Added CommandLine::Application_wo_AutoRun - no auto run set thru at_exit
- Added documentation for CommandLine::Application - instead of just README
- Changed :arg_arity to :arity in Option
- Add :required for use with :opt_found
- Added args accessor for @args - suggested by Esteban Manchado Velázquez
- Added opt() accessor for @option_data[]


HISTORY
=======
After poking around in a few corporations, it was evident that
option parsing was not well understood. Therefore, many inhouse
tools were built that did not conform to any of the POSIX, Gnu or XTools
option styles. CommandLine::OptionParser was developed so that
new applications could be written that conformed to accepted standards,
but non-standard option configurations could be handled as well
to support legacy interfaces.

Once the option parsing was written, there was a need to streamline
the repetitive tasks in setting up an application. The original
boilerplate was simple, but after taking a few cues from
rails, a significant amount of functionality was added to
Application that make it a very useful tool yet simple to use.

More information and usage scenarios on OptionParser can be found at:
    http://rubyforge.org/projects/optionparser/



ACKNOWLEDGEMENTS
================
This library contains code from:
* Austin Ziegler - Text::Format
* Ara - open4.rb - obtained from codeforthepeople