Blinking snake

Getargs.py

Constellation band

HTML Documentation for getargs.py.

This is the official documentation for getargs.py, a command-line argument-parsing module for Python.

MODULE: getargs

Generalized option handling for Python programs.

USAGE

    from getargs import *
  1. Set the variable 'progname' to sys.argv[0];
  2. define any functions you may need in the arglist;
  3. create an argument list of the form:
        arglist=(
            ('i',0,"An integer argument",None),
            ('f',0.0,"A Float argument",3.14159),
            ...
        )
  4. Instantiate a class arguments variable:
            xarg=arguments('-',arglist)
  5. Call the xarg.getargs() method:
            progname,sys.argv=xarg.getargs(sys.argv)
  6. To query an option, use the value()method:
            if xarg.value('i')!=None:
                do something. ...
  7. 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

Arglist fields are:

(key,type,docstring,value,mode )

where:

SINGLE LETTER OPTIONS

Single letter options that take arguments (non-boolean) may do so in one of two ways, either immediately following the keyletter ('-i29') or following a space ('-i 29'). The choice is the user’s, not the programmer’s. Single letter options of the autoincrementing variety have a default value of 0. Each repetition of the keyletter in the option arguments increments the flag value by one. "-i" has a value of 1, while "-iiii" has a value of 4, for example.

LONG OPTIONS

Long options that take arguments (non-boolean) may do so in one of two ways, either separated by a space ('-integer 29') or separated by a separator character, by default the '=' sign ('-integer=29'). Again, the choice is left to the user, not the programmer. Autoincrementing long options are not supported.

LIST AND TUPLE ARGUMENTS

Options that require list or tuple arguments need such an argument in the form of a list, which probably needs to be quoted. By default, the list has the form

            'a b c d e f'

but by using the setsep() method the programmer can have it be of the form

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

for example.

ORDER OF OPTIONS

The order of options is not significant. You cannot tell if one option has been set on the command line before another; this should not be a problem.

CASE

The case of options is significant; 'i' and 'I' are different options, and so are '-integer' and '-Integer' (and also '-inTegeR'). However, on long options, the user only needs to provide sufficient information in order to set or toggle an option. The matching algorithm searches for whatever substring the user provides; if the substring matches more than one option, then it looks first for an exact match. Failing that, it will match the longest option name it can for the substring provided. I.e., if there are two options -h and -help, and the user types '-he', then the option matched will be -help.

FILE OPTIONS

The type of these is determined by matching against the value 'nofile', which is defined to be the same as the value returned by 'open("/dev/null","r")'; if users are on a PC or on a Mac, they won’t have "/dev/null", so "nul" is used instead.

DETERMINING IF AN OPTION HAS APPEARED ON THE COMMAND LINE

If the programmer provides a default value other than None, then there is no way to tell if the option appeared on the command line. However, if the default value is None, then the value() method will return non-None if and only if the user put it in the command line. This even works for boolean options, since the only way for one to be set this way is in the arglist; all other methods set the value to either 0 or 1. Autoincrementing options will have the value 0 if they did not appear on the command line.

VARIABLES

The only variables in the getargs module are 'nofile', which is used only to find the type of file options, and VERSION, which can be found below.

FUNCTIONS

Functions provided by the getargs module are:

nofunc() Provided to find the type of function options.
isnumber() Used to determine if a string can be converted into an integer; the string can contain only digits or '-' or '+'.
islong() Same as isnumber(), except the string can also contain the letter 'L'.
isfloat() The string contains digits, a period, signs or the letters 'e' or 'E'.
manpage() Returns the __doc__ attribute for the getargs module.

CLASS

The only class provided by getargs is class arguments.

METHODS

The methods provided by the arguments class are:

HISTORICAL NOTE

I first built a version of getargs in C many years ago, but I no longer support the C version; I never released it because I was never satisfied with it, and because it was much too delicate for public performance. Also, because it was written in C (not C++), it could be very complicated to use. The Python version cures all those problems, although I recognize that it’s probably more complicated than some people would like. I’m always open to simplification suggestions.

BUGS AND SPECIAL CONSIDERATIONS

Functions referred to in arglist must be defined before the arglist. The program name (progname) must be defined (as in "progname = sys.argv[ 0 ]") before you can use it in any function referred to in the arglist. Such functions are called as soon as they are found in the command line.

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 . Report any infelicitous grammar or language errors in this __doc__ attribute or HTML page to the same place.

Thank you for using getargs.

COPYRIGHT

Copyright 1994-2007 by Ivan Van Laningham.
All rights reserved.
License granted to anyone for non-commercial use, as long as this copyright notice and the author’s name are included in any modifications, and such modifications are reported to the author for consideration in future releases.

VERSION

Version 1.3,  12.19.6.11.6  13 Kimi  14 Yax  G1  11:11:01

EXAMPLE

Here’s a complete test program in Python:

#!/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

You can download getargs.py, testarg.py and this file, getargs.html at:

Previous Page
Table of Contents
Next Page

Main web site:  http://www.pauahtun.org

Valid HTML 4.01 Transitional