[Doc-SIG] More documentation

[Moshe Zadka]

Here is some more user testing -- the docstrings in getopt.py converted to
use my syntax, with the change I've made:

Now long args can have either the syntax

<something>::
	<something>

Or 
 
<something>:: <something>

The same way the Python interpreter allows. Note that although my official
escape character is '@', in all the tests I've never had to escape once!

in-defense-of-thesis-mode-ly y'rs, Z.

"""Parser for command line options.

This module helps scripts to parse the command line arguments in
[var sys.argv].  It supports the same conventions as the Unix 
[cfunction getopt()] function (including the special meanings of arguments of 
the form [code `-'] and [code `--']).  Long options similar to those supported 
by GNU software may be used as well via an optional third argument.  This 
module provides a single function and an exception:

Gerrit Holl <gerrit@nl.linux.org> moved the string-based exceptions
to class-based exceptions.

list::
    item:: [function getopt()] -- Parse command line options
    item:: 
        [exception GetoptError] -- exception (class) raised when 
        [function getopt()] detects a problem with the options.

exception name=GetoptError::
	An exception throws for incorrect options. It has a member
	[member opt], which is the option which triggered the exception.
"""

# Long option support added by Lars Wirzenius <liw@iki.fi>.

import string

class GetoptError(Exception):
    opt = ''
    msg = ''
    def __init__(self, *args):
        self.args = args
        if len(args) == 1:
            self.msg = args[0]
        elif len(args) == 2:
            self.msg = args[0]
            self.opt = args[1]

    def __str__(self):
        return self.msg

error = GetoptError # backward compatibility

def getopt(args, shortopts, longopts = []):
    """\
    Return the list of options and values used.

    arg name=args type=list::
        Arguments to be parsed. Note that the first argument
        is assumed to be a real argument, [emph not] the name of the program.

    arg name=shortopts type=string::
        Option letters the program recognizes that. Option that require
        an argument are followed by a colon ([code :]).
        Note that this is the same format the Unix [cfunction getopt()]
        uses.

    arg name=longopts type=list default=[code []]::
        Long options names which should be recognized. Options which require
        and argument should be followed by an equal sign ([code '=']).

        Note that the leading double hyphen ([code '--']) should [emph not]
        be included in the option name.

    return type=tuple::
        The return value consists of two elements:

        list::
            item:: 
                A list of [code (option, value)] pairs.
                The option appears as it appears on the command line: including
                a hyphen or double hyphen.
                Long and short options may be mixed.
            item:: 
                List of program arguments left after the options were stripped
                (this is a trailing slice of the first argument).
    """
<snipped actual code>


--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.