1 """ CommandLine - Get and parse command line options

     2 

     3     NOTE: This still is very much work in progress !!!

     4 

     5     Different version are likely to be incompatible.

     6 

     7     TODO:

     8 

     9     * Incorporate the changes made by (see Inbox)

    10     * Add number range option using srange()

    11 

    12 """

    13 

    14 __copyright__ = """\

    15 Copyright (c), 1997-2006, Marc-Andre Lemburg (mal@lemburg.com)

    16 Copyright (c), 2000-2006, eGenix.com Software GmbH (info@egenix.com)

    17 See the documentation for further information on copyrights,

    18 or contact the author. All Rights Reserved.

    19 """

    20 

    21 __version__ = '1.2'

    22 

    23 import sys, getopt, string, glob, os, re, exceptions, traceback

    24 

    25 ### Helpers

    26 

    27 def _getopt_flags(options):

    28 

    29     """ Convert the option list to a getopt flag string and long opt

    30         list

    31 

    32     """

    33     s = []

    34     l = []

    35     for o in options:

    36         if o.prefix == '-':

    37             # short option

    38             s.append(o.name)

    39             if o.takes_argument:

    40                 s.append(':')

    41         else:

    42             # long option

    43             if o.takes_argument:

    44                 l.append(o.name+'=')

    45             else:

    46                 l.append(o.name)

    47     return string.join(s,''),l

    48 

    49 def invisible_input(prompt='>>> '):

    50 

    51     """ Get raw input from a terminal without echoing the characters to

    52         the terminal, e.g. for password queries.

    53 

    54     """

    55     import getpass

    56     entry = getpass.getpass(prompt)

    57     if entry is None:

    58         raise KeyboardInterrupt

    59     return entry

    60 

    61 def fileopen(name, mode='wb', encoding=None):

    62 

    63     """ Open a file using mode.

    64 

    65         Default mode is 'wb' meaning to open the file for writing in

    66         binary mode. If encoding is given, I/O to and from the file is

    67         transparently encoded using the given encoding.

    68 

    69         Files opened for writing are chmod()ed to 0600.

    70 

    71     """

    72     if name == 'stdout':

    73         return sys.stdout

    74     elif name == 'stderr':

    75         return sys.stderr

    76     elif name == 'stdin':

    77         return sys.stdin

    78     else:

    79         if encoding is not None:

    80             import codecs

    81             f = codecs.open(name, mode, encoding)

    82         else:

    83             f = open(name, mode)

    84         if 'w' in mode:

    85             os.chmod(name, 0600)

    86         return f

    87 

    88 def option_dict(options):

    89 

    90     """ Return a dictionary mapping option names to Option instances.

    91     """

    92     d = {}

    93     for option in options:

    94         d[option.name] = option

    95     return d

    96 

    97 # Alias

    98 getpasswd = invisible_input

    99 

   100 _integerRE = re.compile('\s*(-?\d+)\s*$')

   101 _integerRangeRE = re.compile('\s*(-?\d+)\s*-\s*(-?\d+)\s*$')

   102 

   103 def srange(s,

   104 

   105            split=string.split,integer=_integerRE,

   106            integerRange=_integerRangeRE):

   107 

   108     """ Converts a textual representation of integer numbers and ranges

   109         to a Python list.

   110 

   111         Supported formats: 2,3,4,2-10,-1 - -3, 5 - -2

   112 

   113         Values are appended to the created list in the order specified

   114         in the string.

   115 

   116     """

   117     l = []

   118     append = l.append

   119     for entry in split(s,','):

   120         m = integer.match(entry)

   121         if m:

   122             append(int(m.groups()[0]))

   123             continue

   124         m = integerRange.match(entry)

   125         if m:

   126             start,end = map(int,m.groups())

   127             l[len(l):] = range(start,end+1)

   128     return l

   129 

   130 def abspath(path,

   131 

   132             expandvars=os.path.expandvars,expanduser=os.path.expanduser,

   133             join=os.path.join,getcwd=os.getcwd):

   134 

   135     """ Return the corresponding absolute path for path.

   136 

   137         path is expanded in the usual shell ways before

   138         joining it with the current working directory.

   139 

   140     """

   141     try:

   142         path = expandvars(path)

   143     except AttributeError:

   144         pass

   145     try:

   146         path = expanduser(path)

   147     except AttributeError:

   148         pass

   149     return join(getcwd(), path)

   150 

   151 ### Option classes

   152 

   153 class Option:

   154 

   155     """ Option base class. Takes no argument.

   156 

   157     """

   158     default = None

   159     helptext = ''

   160     prefix = '-'

   161     takes_argument = 0

   162     has_default = 0

   163     tab = 15

   164 

   165     def __init__(self,name,help=None):

   166 

   167         if not name[:1] == '-':

   168             raise TypeError,'option names must start with "-"'

   169         if name[1:2] == '-':

   170             self.prefix = '--'

   171             self.name = name[2:]

   172         else:

   173             self.name = name[1:]

   174         if help:

   175             self.help = help

   176 

   177     def __str__(self):

   178 

   179         o = self

   180         name = o.prefix + o.name

   181         if o.takes_argument:

   182             name = name + ' arg'

   183         if len(name) > self.tab:

   184             name = name + '\n' + ' ' * (self.tab + 1 + len(o.prefix))

   185         else:

   186             name = '%-*s ' % (self.tab, name)

   187         description = o.help

   188         if o.has_default:

   189             description = description + ' (%s)' % o.default

   190         return '%s %s' % (name, description)

   191 

   192 class ArgumentOption(Option):

   193 

   194     """ Option that takes an argument.

   195 

   196         An optional default argument can be given.

   197 

   198     """

   199     def __init__(self,name,help=None,default=None):

   200 

   201         # Basemethod

   202         Option.__init__(self,name,help)

   203 

   204         if default is not None:

   205             self.default = default

   206             self.has_default = 1

   207         self.takes_argument = 1

   208 

   209 class SwitchOption(Option):

   210 

   211     """ Options that can be on or off. Has an optional default value.

   212 

   213     """

   214     def __init__(self,name,help=None,default=None):

   215 

   216         # Basemethod

   217         Option.__init__(self,name,help)

   218 

   219         if default is not None:

   220             self.default = default

   221             self.has_default = 1

   222 

   223 ### Application baseclass

   224 

   225 class Application:

   226 

   227     """ Command line application interface with builtin argument

   228         parsing.

   229 

   230     """

   231     # Options the program accepts (Option instances)

   232     options = []

   233 

   234     # Standard settings; these are appended to options in __init__

   235     preset_options = [SwitchOption('-v',

   236                                    'generate verbose output'),

   237                       SwitchOption('-h',

   238                                    'show this help text'),

   239                       SwitchOption('--help',

   240                                    'show this help text'),

   241                       SwitchOption('--debug',

   242                                    'enable debugging'),

   243                       SwitchOption('--copyright',

   244                                    'show copyright'),

   245                       SwitchOption('--examples',

   246                                    'show examples of usage')]

   247 

   248     # The help layout looks like this:

   249     # [header]   - defaults to ''

   250     #

   251     # [synopsis] - formatted as '<self.name> %s' % self.synopsis

   252     #

   253     # options:

   254     # [options]  - formatted from self.options

   255     #

   256     # [version]  - formatted as 'Version:\n %s' % self.version, if given

   257     #

   258     # [about]    - defaults to ''

   259     #

   260     # Note: all fields that do not behave as template are formatted

   261     #       using the instances dictionary as substitution namespace,

   262     #       e.g. %(name)s will be replaced by the applications name.

   263     #

   264 

   265     # Header (default to program name)

   266     header = ''

   267 

   268     # Name (defaults to program name)

   269     name = ''

   270 

   271     # Synopsis (%(name)s is replaced by the program name)

   272     synopsis = '%(name)s [option] files...'

   273 

   274     # Version (optional)

   275     version = ''

   276 

   277     # General information printed after the possible options (optional)

   278     about = ''

   279 

   280     # Examples of usage to show when the --examples option is given (optional)

   281     examples = ''

   282 

   283     # Copyright to show

   284     copyright = __copyright__

   285 

   286     # Apply file globbing ?

   287     globbing = 1

   288 

   289     # Generate debug output ?

   290     debug = 0

   291 

   292     # Generate verbose output ?

   293     verbose = 0

   294 

   295     # Internal errors to catch

   296     InternalError = exceptions.Exception

   297 

   298     # Instance variables:

   299     values = None       # Dictionary of passed options (or default values)

   300                         # indexed by the options name, e.g. '-h'

   301     files = None        # List of passed filenames

   302     optionlist = None   # List of passed options

   303 

   304     def __init__(self,argv=None):

   305 

   306         # Setup application specs

   307         if argv is None:

   308             argv = sys.argv

   309         self.filename = os.path.split(argv[0])[1]

   310         if not self.name:

   311             self.name = os.path.split(self.filename)[1]

   312         else:

   313             self.name = self.name

   314         if not self.header:

   315             self.header = self.name

   316         else:

   317             self.header = self.header

   318 

   319         # Init .arguments list

   320         self.arguments = argv[1:]

   321 

   322         # Setup Option mapping

   323         self.option_map = option_dict(self.options)

   324 

   325         # Append preset options

   326         for option in self.preset_options:

   327             if not self.option_map.has_key(option.name):

   328                 self.add_option(option)

   329 

   330         # Init .files list

   331         self.files = []

   332 

   333         # Start Application

   334         try:

   335             # Process startup

   336             rc = self.startup()

   337             if rc is not None:

   338                 raise SystemExit,rc

   339 

   340             # Parse command line

   341             rc = self.parse()

   342             if rc is not None:

   343                 raise SystemExit,rc

   344 

   345             # Start application

   346             rc = self.main()

   347             if rc is None:

   348                 rc = 0

   349 

   350         except SystemExit,rc:

   351             pass

   352 

   353         except KeyboardInterrupt:

   354             print

   355             print '* User Break'

   356             print

   357             rc = 1

   358 

   359         except self.InternalError:

   360             print

   361             print '* Internal Error (use --debug to display the traceback)'

   362             if self.debug:

   363                 print

   364                 traceback.print_exc(20, sys.stdout)

   365             elif self.verbose:

   366                 print '  %s: %s' % sys.exc_info()[:2]

   367             print

   368             rc = 1

   369 

   370         raise SystemExit,rc

   371 

   372     def add_option(self, option):

   373 

   374         """ Add a new Option instance to the Application dynamically.

   375 

   376             Note that this has to be done *before* .parse() is being

   377             executed.

   378 

   379         """

   380         self.options.append(option)

   381         self.option_map[option.name] = option

   382 

   383     def startup(self):

   384 

   385         """ Set user defined instance variables.

   386 

   387             If this method returns anything other than None, the

   388             process is terminated with the return value as exit code.

   389 

   390         """

   391         return None

   392 

   393     def exit(self, rc=0):

   394 

   395         """ Exit the program.

   396 

   397             rc is used as exit code and passed back to the calling

   398             program. It defaults to 0 which usually means: OK.

   399 

   400         """

   401         raise SystemExit, rc

   402 

   403     def parse(self):

   404 

   405         """ Parse the command line and fill in self.values and self.files.

   406 

   407             After having parsed the options, the remaining command line

   408             arguments are interpreted as files and passed to .handle_files()

   409             for processing.

   410 

   411             As final step the option handlers are called in the order

   412             of the options given on the command line.

   413 

   414         """

   415         # Parse arguments

   416         self.values = values = {}

   417         for o in self.options:

   418             if o.has_default:

   419                 values[o.prefix+o.name] = o.default

   420             else:

   421                 values[o.prefix+o.name] = 0

   422         flags,lflags = _getopt_flags(self.options)

   423         try:

   424             optlist,files = getopt.getopt(self.arguments,flags,lflags)

   425             if self.globbing:

   426                 l = []

   427                 for f in files:

   428                     gf = glob.glob(f)

   429                     if not gf:

   430                         l.append(f)

   431                     else:

   432                         l[len(l):] = gf

   433                 files = l

   434             self.optionlist = optlist

   435             self.files = files + self.files

   436         except getopt.error,why:

   437             self.help(why)

   438             sys.exit(1)

   439 

   440         # Call file handler

   441         rc = self.handle_files(self.files)

   442         if rc is not None:

   443             sys.exit(rc)

   444 

   445         # Call option handlers

   446         for optionname, value in optlist:

   447 

   448             # Try to convert value to integer

   449             try:

   450                 value = string.atoi(value)

   451             except ValueError:

   452                 pass

   453 

   454             # Find handler and call it (or count the number of option

   455             # instances on the command line)

   456             handlername = 'handle' + string.replace(optionname, '-', '_')

   457             try:

   458                 handler = getattr(self, handlername)

   459             except AttributeError:

   460                 if value == '':

   461                     # count the number of occurances

   462                     if values.has_key(optionname):

   463                         values[optionname] = values[optionname] + 1

   464                     else:

   465                         values[optionname] = 1

   466                 else:

   467                     values[optionname] = value

   468             else:

   469                 rc = handler(value)

   470                 if rc is not None:

   471                     raise SystemExit, rc

   472 

   473         # Apply final file check (for backward compatibility)

   474         rc = self.check_files(self.files)

   475         if rc is not None:

   476             sys.exit(rc)

   477 

   478     def check_files(self,filelist):

   479 

   480         """ Apply some user defined checks on the files given in filelist.

   481 

   482             This may modify filelist in place. A typical application

   483             is checking that at least n files are given.

   484 

   485             If this method returns anything other than None, the

   486             process is terminated with the return value as exit code.

   487 

   488         """

   489         return None

   490 

   491     def help(self,note=''):

   492 

   493         self.print_header()

   494         if self.synopsis:

   495             print 'Synopsis:'

   496             # To remain backward compatible:

   497             try:

   498                 synopsis = self.synopsis % self.name

   499             except (NameError, KeyError, TypeError):

   500                 synopsis = self.synopsis % self.__dict__

   501             print ' ' + synopsis

   502         print

   503         self.print_options()

   504         if self.version:

   505             print 'Version:'

   506             print ' %s' % self.version

   507             print

   508         if self.about:

   509             print string.strip(self.about % self.__dict__)

   510             print

   511         if note:

   512             print '-'*72

   513             print 'Note:',note

   514             print

   515 

   516     def notice(self,note):

   517 

   518         print '-'*72

   519         print 'Note:',note

   520         print '-'*72

   521         print

   522 

   523     def print_header(self):

   524 

   525         print '-'*72

   526         print self.header % self.__dict__

   527         print '-'*72

   528         print

   529 

   530     def print_options(self):

   531 

   532         options = self.options

   533         print 'Options and default settings:'

   534         if not options:

   535             print '  None'

   536             return

   537         long = filter(lambda x: x.prefix == '--', options)

   538         short = filter(lambda x: x.prefix == '-', options)

   539         items = short + long

   540         for o in options:

   541             print ' ',o

   542         print

   543 

   544     #

   545     # Example handlers:

   546     #

   547     # If a handler returns anything other than None, processing stops

   548     # and the return value is passed to sys.exit() as argument.

   549     #

   550 

   551     # File handler

   552     def handle_files(self,files):

   553 

   554         """ This may process the files list in place.

   555         """

   556         return None

   557 

   558     # Short option handler

   559     def handle_h(self,arg):

   560 

   561         self.help()

   562         return 0

   563 

   564     def handle_v(self, value):

   565 

   566         """ Turn on verbose output.

   567         """

   568         self.verbose = 1

   569 

   570     # Handlers for long options have two underscores in their name

   571     def handle__help(self,arg):

   572 

   573         self.help()

   574         return 0

   575 

   576     def handle__debug(self,arg):

   577 

   578         self.debug = 1

   579         # We don't want to catch internal errors:

   580         self.InternalError = None

   581 

   582     def handle__copyright(self,arg):

   583 

   584         self.print_header()

   585         print string.strip(self.copyright % self.__dict__)

   586         print

   587         return 0

   588 

   589     def handle__examples(self,arg):

   590 

   591         self.print_header()

   592         if self.examples:

   593             print 'Examples:'

   594             print

   595             print string.strip(self.examples % self.__dict__)

   596             print

   597         else:

   598             print 'No examples available.'

   599             print

   600         return 0

   601 

   602     def main(self):

   603 

   604         """ Override this method as program entry point.

   605 

   606             The return value is passed to sys.exit() as argument.  If

   607             it is None, 0 is assumed (meaning OK). Unhandled

   608             exceptions are reported with exit status code 1 (see

   609             __init__ for further details).

   610 

   611         """

   612         return None

   613 

   614 # Alias

   615 CommandLine = Application

   616 

   617 def _test():

   618 

   619     class MyApplication(Application):

   620         header = 'Test Application'

   621         version = __version__

   622         options = [Option('-v','verbose')]

   623 

   624         def handle_v(self,arg):

   625             print 'VERBOSE, Yeah !'

   626 

   627     cmd = MyApplication()

   628     if not cmd.values['-h']:

   629         cmd.help()

   630     print 'files:',cmd.files

   631     print 'Bye...'

   632 

   633 if __name__ == '__main__':

   634     _test()