Optik 1.5.3
===========

Optik is a powerful, flexible, extensible, easy-to-use command-line
parsing library for Python.  Using Optik, you can add intelligent,
sophisticated handling of command-line options to your scripts with very
little overhead.

Here's an example of using Optik to add some command-line options to a
simple script:

  from optik import OptionParser
  [...]
  parser = OptionParser()
  parser.add_option("-f", "--file", dest="filename",
                    help="write report to FILE", metavar="FILE")
  parser.add_option("-q", "--quiet",
                    action="store_false", dest="verbose", default=True,
                    help="don't print status messages to stdout")

  (options, args) = parser.parse_args()

With these few lines of code, users of your script can now do the
"usual thing" on the command-line:

  <yourscript> -f outfile --quiet
  <yourscript> -qfoutfile
  <yourscript> --file=outfile -q
  <yourscript> --quiet --file outfile

all of which result in the 'options' object looking like this:

  options.filename == "outfile"
  options.verbose == 0

Even niftier, users can run one of

  <yourscript> -h
  <yourscript> --help

and Optik will print out a brief summary of your script's options:

  usage: <yourscript> [options]

  options:
    -h, --help            show this help message and exit
    -f FILE, --file=FILE  write report to FILE
    -q, --quiet           don't print status messages to stdout

That's just a taste of the flexibility Optik gives you in parsing your
command-line.  See the documentation included in the package for
details.


REQUIREMENTS & INSTALLATION
---------------------------
        
Optik requires Python 2.0 or greater.

Installing Optik is easy; just use the standard incantion for installing
Python modules:

  python setup.py install

As of Python 2.3, Optik is included in the Python standard library as
'optparse'.  Generally, you don't need to install Optik if you're using
Python 2.3 or later: you can just import from 'optparse' instead of
'optik'.  You only need to install Optik separately, and import from
'optparse', if you want to use features from a more recent version of
Optik than was included with the Python version you are using.  A rough
guide:

  Python 2.3    included      Optik 1.4.1 plus a few small bug fixes
  Python 2.4    included      Optik 1.5a2
  Python 2.5    will include  Optik 1.5.3


TESTING
-------

Optik comes with a fairly extensive test suite.  To run the test suite,
execute these commands (before or after installing Optik):

  python setup.py build
  python test/test_optik.py


DOCUMENTATION
-------------

Optik comes with several documents, all in the doc/ subdirectory:

  * tao.html       philosophy and background; if you're not sure what the
                   difference between an argument and an option is, read this

  * tutorial.html  basic guide to using Optik in your programs

  * reference.html a detailed reference guide to almost all of Optik's
                   features

  * callbacks.html how to define callback options and write the callback
                   functions that go with them

  * extending.html information on extending Optik (eg. how to add new
                   actions and types)

You can also find these documents online:

  http://www.gerg.ca/software/optik/doc/current/
  http://optik.sourceforge.net/doc/current/

Additionally, the examples/ subdirectory demonstrates various ways to
extend Optik.


MAILING LISTS
-------------

The optik-users@lists.sourceforge.net list exists for general discussion
of Optik.  To join or view the list archive, visit

  http://lists.sourceforge.net/lists/listinfo/optik-users

General questions about Optik should be addressed to the list:

  optik-users@lists.sourceforge.net

(Currently, you must be subscribed to the list to post.  Sorry for the
inconvenience, but it's necessary to keep spam from overwhelming actual
discussion.)


AUTHOR, COPYRIGHT, AVAILABILITY
-------------------------------

The latest version of Optik can be found at
  http://optik.sourceforge.net/

Optik was written by Greg Ward <gward@python.net> with
contributions by (in no particular order):

  David Goodger
  Matthew Mueller
  Terrel Shumway
  Johannes Gijsbers
  Andrea 'fwyzard' Bocci

Copyright (c) 2001-2006 Gregory P. Ward.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
    
  * Neither the name of the author nor the names of its
    contributors may be used to endorse or promote products derived from
    this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
