HTML Documentation for getargs.py.

MODULE: getargs

USAGE

    from getargs import *

• Set the variable 'progname' to sys.argv[0];
• define any functions you may need in the arglist;
• create an argument list of the form

    arglist = (
        ( 'i', 0, "An integer argument", None ),
        ( 'f', 0.0, "A Float argument", 3.14159 ),
        ...
    )

• Instantiate a class arguments variable:

        xarg = arguments ( '-', arglist )

• Call the xarg.getargs() method:

        progname, sys.argv = xarg.getargs ( sys.argv )

• To query an option, use the value() method:

        if xarg.value ( 'i' ) != None :
            do something. ...

Boolean options have only two possible values, 1 or 0; if two or more options are mutually exclusive, it is the programmer's responisibility to see that the exclusivity is maintained, using the setvalue() method:

        if xarg.value ( 'j' ) :
            xarg.setvalue ( 'g', 0 )

ARGLIST FIELDS

( key, type, docstring, value, mode )

where:

• key = A single letter or a fullword used to find the option in sys.argv
• type = one of:
• None == A boolean option; these keys take no arguments;
• 0j == Autoincrementing flag; -i gives value 1, -iii gives value 3, etc.
• 0 == Requires an integer argument;
• 0L == Requires a long integer argument (may end in 'L';
• 0.0 == Requires a floating point argument; integer, but not long, strings are converted into floats;
• nofile = Requires a filename argument, or one of "stdin", "stdout" or "stderr";
• nofunc = Value must be a valid function; takes no arguments;
• () == Requires a list of arguments, usually of the form 'a b c d e', which is returned as a tuple
• [] == Requires a list of arguments, usually of the form 'a b c d e', which is returned as a list
• docstring = String that represents the hint the user sees, as in:

"Print a help message and exit"
• value = The default value; if this is not provided, None will be used.
• mode = Used for file options only; provides the second argument to open(); defaults to "r".

SINGLE LETTER OPTIONS

LONG OPTIONS

LIST AND TUPLE ARGUMENTS

            'a b c d e f'

            'a,b,c,d,e,f'

ORDER OF OPTIONS

CASE

FILE OPTIONS

DETERMINING IF AN OPTION HAS APPEARED ON THE COMMAND LINE

VARIABLES

FUNCTIONS

CLASS

METHODS

• __init__ ( self, c = '-', a = ( ) ) : where

c = switch character for options. a = an arglist as defined above.
• __del__ ( self ) :

closes any open files.
• __repr__ ( self ) :

Returns a string that can be used to display short help to the user.
• options ( self ) :

Returns a string of option letters or option words, suitably separated if need be, for use in a "Usage" message.
• argtype ( self, let ) :

Returns a string representing the argument type expected by the option. This can be one of:
• "#" for integers and longs;
• "*" for autoincrementers;
• "#.#" for floats;
• "" for filenames for file options;
• "" for lists and tuples;
• "" for everything else.
This method is used in __repr__.
• has_key ( self, let ) :

Returns 1 if the option key let was defined in the arglist, or 0 if it has not.
• additem ( self, let, typ, str, v = None, mode = "r" ) :

Adds a new option and fields to an existing arguments class variable, where:
• let = The option letter or word;
• type = the type (0, 0L, etc.)
• v = default value;
• mode = second argument to open().
Used internally; you shouldn't ordinarily need to use this.
• type ( self, let ) :

Returns either the type of option ("", etc.) or None if there is no such option.
• value ( self, let ) :

Returns either the value of the option (0, 49L, etc.) or None if there is no such option.
• mode ( self, let ) :

Returns either the mode to be used in opening the file or None if there is no such option.
• file ( self, let ) :

If there is no such option, returns None. Otherwise, returns the filename, the mode, and the file pointer (fname,mode,fp); the file pointer is either None, in which case the open() method needs to be called, or an already open file pointer which may be used directly.
• open ( self, let ) :

If this is a file option and the option exists, performs an open() on the filename using the stored mode. Returns None if the option doesn't exist or if open() returns None.
• close ( self, let ) :

If this is a valid option and the file pointer is open, fflushes it and closes it. There is no return value. Automatically called by the __del__ method, so you don't always need to do this.
• docstring ( self, let ) :

Returns the docstring, if there is one and if let is a valid option.
• len ( self ) :

Returns the number of options currently defined.
• keys ( self ) :

Returns a _sorted_ list of the options. If there are no options currently defined, returns None.
• longest ( self ) :

Returns 0 or the len() of the longest option string.
• longestargtype ( self ) :

Returns 0 or the len() of the longest argtype string used by the current set of options.
• switchchar ( self ) :

Returns the switch character, which is '-' by default.
• setswitch ( self, let ) :

Sets the switch character (the option lead-in character) to let: on PCs, for example, you could set this to '/'.
• sepchar ( self ) :

Returns the list separator character, which is ' ' by default.
• setsep ( self, c ) :

Sets the list separator character to c; a good alternate for this might be ','.
• parenchar ( self ) :

Returns the character used to separate option letters or words from their docstrings when building the __repr__ string.
• setsep ( self, c ) :

Sets the option separator character to c; for example, setting this to ']' would result in

                    -h] Help

instead of

                    -h) Help

• eqchar ( self ) :

Returns the character that separates long options from their values, which is set to '=' by default.
• seteq ( self, c ) :

Sets the long option value separator character to c; it's not a good idea to set this to ' '.
• setvalue ( self, c, v ) :

If c is a valid option, this method checks the type of v with the required type of c. The value indicated by v may not be None. Attempting to set an improper value prints an error message and otherwise does nothing.
• setargs ( self, list ) :

If list is a list of the form ( ( let, type, docstring, ... ), ... ), then setargs() runs through the outer list and uses the elements of the inner lists as parameters to the additem() method.
• matchlongarg ( self, m ) :

It's better not to use this; it's used internally by the getargs() method, where the context is set correctly. What it does is look through all the options to see if it can make a match with m; not all characters have to match exactly. If m is 'long', for example, and there are options 'l', 'lo' and 'longest', then matchlongarg() will return 'longest' as its best choice. The return value can then be used as an option key in, say, setvalue().
• getargs ( self, argv ) :

This is the interface between the option list (well, actually a dictionary of dictionaries) and the program's command line. The proper way to use this method is (for example):

                    xarg = arguments ( '-', arglist )
                    progname, sys.argv = xarg.getargs ( sys.argv )

After which sys.argv[ 0 ] and all options between argv[ 0 ] and the first non-option argument will be consumed, leaving the program responsible for any remaining command-line parameters. Values of any of the options that were consumed may be obtained through the value() method.

HISTORICAL NOTE

BUGS AND SPECIAL CONSIDERATIONS

There's no way to specify complex numbers on the command line, and no complex argument type.  This will eventually be remedied.

While there is no way to tell if any option has been set before any other option, the parser does proceed in a linear manner; i.e., "-out foo -help" would actually set the "-out" value "foo" before the "-help" function was called. Not that there's much utility in that.

Report any bugs found to ivanlan@callware.com. Report any infelicitous grammar or language errors in this __doc__ attribute or HTML page to the same place.

Thank you for using getargs.

COPYRIGHT

VERSION

EXAMPLE

#!/usr/local/bin/python

#
# Copyright 1999
# by Ivan Van Laningham
# All Rights Reserved.
#

import sys
import os 
import time
import math
import string

from getargs import *


if __name__ == "__main__" :
    progname = sys.argv[ 0 ]

    def printversion ( l = 0 ) :
        print "Version 1.%s" % ( l )

    def man ( l = 0 ) :
        print manpage ( )
        sys.exit ( 0 )

    def helpPig ( l = 0 ) :
        print "%s:  Usage %s any old gunk" % ( progname, xarg.options ( ) )
        print xarg,
        print "I'm Porky Pig"
        sys.exit ( 0 )

    def helpHog ( l = 0 ) :
        print xarg,
        print "I'm a HAWG!"

    arglist = ( ( 'v', nofunc,    "Function (print version)", printversion ),
        ( 'M', nofunc, "Man page", man ),
        ( '-manual', nofunc, "Man page", man ),
        ( 'i', 0, "Integer", None ),
        ( 'f', 0.0, "Float", None ),
        ( '+snorgle', "", "A Fubar String", None ),
        ( 'tuple', ( ), "Nameless tuple", None ),
        ( 'q', None, "None test", None ),
        ( 'list', [ ], "Nameless list", None ),
        ( 'h', nofunc, "Help", helpPig ),
        ( 'hogs', nofunc, "Help", helpHog ),
        ( 'qln', 0L, "Funky Long", None ),
        ( '-longarg', None, "Boolean long argument" ), # Adding leading - provides --longarg syntax. ...
        ( '-output', nofile, "the output file", "/tmp/dogbone" ),
        ( '-longest', None, "Boolean long argument" ), # Adding leading - provides --longarg syntax. ...
        ( '-longerlongerandlonger', 0, "Integer long argument", None ), # Adding leading - provides --longarg syntax. ...
    )
    xarg = arguments ( '-', arglist )
    progname, sys.argv = xarg.getargs ( sys.argv )
    helpHog ( )

    q = xarg.keys ( )
    for ii in q :
        print ii, xarg.value ( ii )
    
    o = 0
    for n in range ( len ( sys.argv ) ) :
        print o, sys.argv[ n ]
        o = o + 1

AVAILABILITY

• ftp://www.pauahtun.org/pub/getargspy.zip.