cpython/Lib/distutils/fancy_getopt.py

312 lines
10 KiB
Python
Raw Normal View History

1999-03-22 10:52:19 -04:00
"""distutils.fancy_getopt
Wrapper around the standard getopt module that provides the following
additional features:
* short and long options are tied together
* options have help strings, so fancy_getopt could potentially
create a complete usage summary
* options set attributes of a passed-in object
"""
# created 1999/03/03, Greg Ward
2000-03-01 21:49:45 -04:00
__revision__ = "$Id$"
1999-03-22 10:52:19 -04:00
import sys, string, re
1999-03-22 10:52:19 -04:00
from types import *
import getopt
from distutils.errors import *
# Much like command_re in distutils.core, this is close to but not quite
# the same as a Python NAME -- except, in the spirit of most GNU
# utilities, we use '-' in place of '_'. (The spirit of LISP lives on!)
# The similarities to NAME are again not a coincidence...
longopt_pat = r'[a-zA-Z](?:[a-zA-Z0-9-]*)'
longopt_re = re.compile (r'^%s$' % longopt_pat)
# For recognizing "negative alias" options, eg. "quiet=!verbose"
neg_alias_re = re.compile ("^(%s)=!(%s)$" % (longopt_pat, longopt_pat))
1999-03-22 10:52:19 -04:00
# This is used to translate long options to legitimate Python identifiers
# (for use as attributes of some object).
longopt_xlate = string.maketrans ('-', '_')
def fancy_getopt (options, negative_opt, object, args):
1999-03-22 10:52:19 -04:00
# The 'options' table is a list of 3-tuples:
# (long_option, short_option, help_string)
# if an option takes an argument, its long_option should have '='
# appended; short_option should just be a single character, no ':' in
# any case. If a long_option doesn't have a corresponding
# short_option, short_option should be None. All option tuples must
# have long options.
# Build the short_opts string and long_opts list, remembering how
# the two are tied together
short_opts = [] # we'll join 'em when done
long_opts = []
short2long = {}
attr_name = {}
takes_arg = {}
for option in options:
try:
(long, short, help) = option
except ValueError:
raise DistutilsGetoptError, \
"invalid option tuple " + str (option)
1999-03-22 10:52:19 -04:00
# Type-check the option names
if type (long) is not StringType or len (long) < 2:
raise DistutilsGetoptError, \
"long option '%s' must be a string of length >= 2" % \
long
1999-03-22 10:52:19 -04:00
if (not ((short is None) or
(type (short) is StringType and len (short) == 1))):
raise DistutilsGetoptError, \
"short option '%s' must be None or string of length 1" % \
short
1999-03-22 10:52:19 -04:00
long_opts.append (long)
if long[-1] == '=': # option takes an argument?
if short: short = short + ':'
long = long[0:-1]
takes_arg[long] = 1
else:
# Is option is a "negative alias" for some other option (eg.
# "quiet" == "!verbose")?
alias_to = negative_opt.get(long)
if alias_to is not None:
if not takes_arg.has_key(alias_to) or takes_arg[alias_to]:
raise DistutilsGetoptError, \
("option '%s' is a negative alias for '%s', " +
"which either hasn't been defined yet " +
"or takes an argument") % (long, alias_to)
long_opts[-1] = long
takes_arg[long] = 0
else:
takes_arg[long] = 0
1999-03-22 10:52:19 -04:00
# Now enforce some bondage on the long option name, so we can later
# translate it to an attribute name in 'object'. Have to do this a
# bit late to make sure we've removed any trailing '='.
if not longopt_re.match (long):
raise DistutilsGetoptError, \
("invalid long option name '%s' " +
"(must be letters, numbers, hyphens only") % long
attr_name[long] = string.translate (long, longopt_xlate)
if short:
short_opts.append (short)
short2long[short[0]] = long
# end loop over 'options'
short_opts = string.join (short_opts)
try:
(opts, args) = getopt.getopt (args, short_opts, long_opts)
except getopt.error, msg:
raise DistutilsArgError, msg
for (opt, val) in opts:
if len (opt) == 2 and opt[0] == '-': # it's a short option
opt = short2long[opt[1]]
elif len (opt) > 2 and opt[0:2] == '--':
opt = opt[2:]
else:
raise RuntimeError, "getopt lies! (bad option string '%s')" % \
opt
attr = attr_name[opt]
if takes_arg[opt]:
setattr (object, attr, val)
else:
if val == '':
alias = negative_opt.get (opt)
if alias:
setattr (object, attr_name[alias], 0)
else:
setattr (object, attr, 1)
1999-03-22 10:52:19 -04:00
else:
raise RuntimeError, "getopt lies! (bad value '%s')" % value
# end loop over options found in 'args'
return args
# fancy_getopt()
WS_TRANS = string.maketrans (string.whitespace, ' ' * len (string.whitespace))
def wrap_text (text, width):
if text is None:
return []
if len (text) <= width:
return [text]
text = string.expandtabs (text)
text = string.translate (text, WS_TRANS)
chunks = re.split (r'( +|-+)', text)
chunks = filter (None, chunks) # ' - ' results in empty strings
lines = []
while chunks:
cur_line = [] # list of chunks (to-be-joined)
cur_len = 0 # length of current line
while chunks:
l = len (chunks[0])
if cur_len + l <= width: # can squeeze (at least) this chunk in
cur_line.append (chunks[0])
del chunks[0]
cur_len = cur_len + l
else: # this line is full
# drop last chunk if all space
if cur_line and cur_line[-1][0] == ' ':
del cur_line[-1]
break
if chunks: # any chunks left to process?
# if the current line is still empty, then we had a single
# chunk that's too big too fit on a line -- so we break
# down and break it up at the line width
if cur_len == 0:
cur_line.append (chunks[0][0:width])
chunks[0] = chunks[0][width:]
# all-whitespace chunks at the end of a line can be discarded
# (and we know from the re.split above that if a chunk has
# *any* whitespace, it is *all* whitespace)
if chunks[0][0] == ' ':
del chunks[0]
# and store this line in the list-of-all-lines -- as a single
# string, of course!
lines.append (string.join (cur_line, ''))
# while chunks
return lines
# wrap_text ()
def generate_help (options, header=None):
"""Generate help text (a list of strings, one per suggested line of
output) from an option table."""
# Blithely assume the option table is good: probably wouldn't call
# 'generate_help()' unless you've already called 'fancy_getopt()'.
# First pass: determine maximum length of long option names
max_opt = 0
for option in options:
long = option[0]
short = option[1]
l = len (long)
if long[-1] == '=':
l = l - 1
if short is not None:
l = l + 5 # " (-x)" where short == 'x'
if l > max_opt:
max_opt = l
opt_width = max_opt + 2 + 2 + 2 # room for indent + dashes + gutter
# Typical help block looks like this:
# --foo controls foonabulation
# Help block for longest option looks like this:
# --flimflam set the flim-flam level
# and with wrapped text:
# --flimflam set the flim-flam level (must be between
# 0 and 100, except on Tuesdays)
# Options with short names will have the short name shown (but
# it doesn't contribute to max_opt):
# --foo (-f) controls foonabulation
# If adding the short option would make the left column too wide,
# we push the explanation off to the next line
# --flimflam (-l)
# set the flim-flam level
# Important parameters:
# - 2 spaces before option block start lines
# - 2 dashes for each long option name
# - min. 2 spaces between option and explanation (gutter)
# - 5 characters (incl. space) for short option name
# Now generate lines of help text.
line_width = 78 # if 80 columns were good enough for
text_width = line_width - opt_width # Jesus, then 78 are good enough for me
big_indent = ' ' * opt_width
if header:
lines = [header]
else:
lines = ['Option summary:']
for (long,short,help) in options:
text = wrap_text (help, text_width)
if long[-1] == '=':
long = long[0:-1]
# Case 1: no short option at all (makes life easy)
if short is None:
if text:
lines.append (" --%-*s %s" % (max_opt, long, text[0]))
else:
lines.append (" --%-*s " % (max_opt, long))
for l in text[1:]:
lines.append (big_indent + l)
# Case 2: we have a short option, so we have to include it
# just after the long option
else:
opt_names = "%s (-%s)" % (long, short)
if text:
lines.append (" --%-*s %s" %
(max_opt, opt_names, text[0]))
else:
lines.append (" --%-*s" % opt_names)
# for loop over options
return lines
# generate_help ()
def print_help (options, file=None, header=None):
if file is None:
file = sys.stdout
for line in generate_help (options, header):
file.write (line + "\n")
# print_help ()
if __name__ == "__main__":
text = """\
Tra-la-la, supercalifragilisticexpialidocious.
How *do* you spell that odd word, anyways?
(Someone ask Mary -- she'll know [or she'll
say, "How should I know?"].)"""
for w in (10, 20, 30, 40):
print "width: %d" % w
print string.join (wrap_text (text, w), "\n")
print