gcloud 0.0.2 → 0.0.4

data/packages/gcutil-1.7.1/lib/python_gflags/gflags2man.py

@@ -0,0 +1,544 @@
+#!/usr/bin/env python
+
+# Copyright (c) 2006, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+"""gflags2man runs a Google flags base program and generates a man page.
+
+Run the program, parse the output, and then format that into a man
+page.
+
+Usage:
+  gflags2man <program> [program] ...
+"""
+
+# TODO(user): work with windows paths (\) as well as unix (/)
+
+# This may seem a bit of an end run, but it:  doesn't bloat flags, can
+# support python/java/C++, supports older executables, and can be
+# extended to other document formats.
+# Inspired by help2man.
+
+
+
+import os
+import re
+import sys
+import stat
+import time
+
+import gflags
+
+_VERSION = '0.1'
+
+
+def _GetDefaultDestDir():
+  home = os.environ.get('HOME', '')
+  homeman = os.path.join(home, 'man', 'man1')
+  if home and os.path.exists(homeman):
+    return homeman
+  else:
+    return os.environ.get('TMPDIR', '/tmp')
+
+FLAGS = gflags.FLAGS
+gflags.DEFINE_string('dest_dir', _GetDefaultDestDir(),
+                    'Directory to write resulting manpage to.'
+                    ' Specify \'-\' for stdout')
+gflags.DEFINE_string('help_flag', '--help',
+                    'Option to pass to target program in to get help')
+gflags.DEFINE_integer('v', 0, 'verbosity level to use for output')
+
+
+_MIN_VALID_USAGE_MSG = 9         # if fewer lines than this, help is suspect
+
+
+class Logging:
+  """A super-simple logging class"""
+  def error(self, msg): print >>sys.stderr, "ERROR: ", msg
+  def warn(self, msg): print >>sys.stderr, "WARNING: ", msg
+  def info(self, msg): print msg
+  def debug(self, msg): self.vlog(1, msg)
+  def vlog(self, level, msg):
+    if FLAGS.v >= level: print msg
+logging = Logging()
+class App:
+  def usage(self, shorthelp=0):
+    print >>sys.stderr, __doc__
+    print >>sys.stderr, "flags:"
+    print >>sys.stderr, str(FLAGS)
+  def run(self):
+    main(sys.argv)
+app = App()
+
+
+def GetRealPath(filename):
+  """Given an executable filename, find in the PATH or find absolute path.
+  Args:
+    filename  An executable filename (string)
+  Returns:
+    Absolute version of filename.
+    None if filename could not be found locally, absolutely, or in PATH
+  """
+  if os.path.isabs(filename):                # already absolute
+    return filename
+
+  if filename.startswith('./') or  filename.startswith('../'): # relative
+    return os.path.abspath(filename)
+
+  path = os.getenv('PATH', '')
+  for directory in path.split(':'):
+    tryname = os.path.join(directory, filename)
+    if os.path.exists(tryname):
+      if not os.path.isabs(directory):  # relative directory
+        return os.path.abspath(tryname)
+      return tryname
+  if os.path.exists(filename):
+    return os.path.abspath(filename)
+  return None                         # could not determine
+
+class Flag(object):
+  """The information about a single flag."""
+
+  def __init__(self, flag_desc, help):
+    """Create the flag object.
+    Args:
+      flag_desc  The command line forms this could take. (string)
+      help       The help text (string)
+    """
+    self.desc = flag_desc               # the command line forms
+    self.help = help                    # the help text
+    self.default = ''                   # default value
+    self.tips = ''                      # parsing/syntax tips
+
+
+class ProgramInfo(object):
+  """All the information gleaned from running a program with --help."""
+
+  # Match a module block start, for python scripts --help
+  # "goopy.logging:"
+  module_py_re = re.compile(r'(\S.+):$')
+  # match the start of a flag listing
+  # " -v,--verbosity:  Logging verbosity"
+  flag_py_re         = re.compile(r'\s+(-\S+):\s+(.*)$')
+  # "   (default: '0')"
+  flag_default_py_re = re.compile(r'\s+\(default:\s+\'(.*)\'\)$')
+  # "   (an integer)"
+  flag_tips_py_re    = re.compile(r'\s+\((.*)\)$')
+
+  # Match a module block start, for c++ programs --help
+  # "google/base/commandlineflags":
+  module_c_re = re.compile(r'\s+Flags from (\S.+):$')
+  # match the start of a flag listing
+  # " -v,--verbosity:  Logging verbosity"
+  flag_c_re         = re.compile(r'\s+(-\S+)\s+(.*)$')
+
+  # Match a module block start, for java programs --help
+  # "com.google.common.flags"
+  module_java_re = re.compile(r'\s+Flags for (\S.+):$')
+  # match the start of a flag listing
+  # " -v,--verbosity:  Logging verbosity"
+  flag_java_re         = re.compile(r'\s+(-\S+)\s+(.*)$')
+
+  def __init__(self, executable):
+    """Create object with executable.
+    Args:
+      executable  Program to execute (string)
+    """
+    self.long_name = executable
+    self.name = os.path.basename(executable)  # name
+    # Get name without extension (PAR files)
+    (self.short_name, self.ext) = os.path.splitext(self.name)
+    self.executable = GetRealPath(executable)  # name of the program
+    self.output = []          # output from the program.  List of lines.
+    self.desc = []            # top level description.  List of lines
+    self.modules = {}         # { section_name(string), [ flags ] }
+    self.module_list = []     # list of module names in their original order
+    self.date = time.localtime(time.time())   # default date info
+
+  def Run(self):
+    """Run it and collect output.
+
+    Returns:
+      1 (true)   If everything went well.
+      0 (false)  If there were problems.
+    """
+    if not self.executable:
+      logging.error('Could not locate "%s"' % self.long_name)
+      return 0
+
+    finfo = os.stat(self.executable)
+    self.date = time.localtime(finfo[stat.ST_MTIME])
+
+    logging.info('Running: %s %s </dev/null 2>&1'
+                 % (self.executable, FLAGS.help_flag))
+    # --help output is often routed to stderr, so we combine with stdout.
+    # Re-direct stdin to /dev/null to encourage programs that
+    # don't understand --help to exit.
+    (child_stdin, child_stdout_and_stderr) = os.popen4(
+      [self.executable, FLAGS.help_flag])
+    child_stdin.close()       # '</dev/null'
+    self.output = child_stdout_and_stderr.readlines()
+    child_stdout_and_stderr.close()
+    if len(self.output) < _MIN_VALID_USAGE_MSG:
+      logging.error('Error: "%s %s" returned only %d lines: %s'
+                    % (self.name, FLAGS.help_flag,
+                       len(self.output), self.output))
+      return 0
+    return 1
+
+  def Parse(self):
+    """Parse program output."""
+    (start_line, lang) = self.ParseDesc()
+    if start_line < 0:
+      return
+    if 'python' == lang:
+      self.ParsePythonFlags(start_line)
+    elif 'c' == lang:
+      self.ParseCFlags(start_line)
+    elif 'java' == lang:
+      self.ParseJavaFlags(start_line)
+
+  def ParseDesc(self, start_line=0):
+    """Parse the initial description.
+
+    This could be Python or C++.
+
+    Returns:
+      (start_line, lang_type)
+        start_line  Line to start parsing flags on (int)
+        lang_type   Either 'python' or 'c'
+       (-1, '')  if the flags start could not be found
+    """
+    exec_mod_start = self.executable + ':'
+
+    after_blank = 0
+    start_line = 0             # ignore the passed-in arg for now (?)
+    for start_line in range(start_line, len(self.output)): # collect top description
+      line = self.output[start_line].rstrip()
+      # Python flags start with 'flags:\n'
+      if ('flags:' == line
+          and len(self.output) > start_line+1
+          and '' == self.output[start_line+1].rstrip()):
+        start_line += 2
+        logging.debug('Flags start (python): %s' % line)
+        return (start_line, 'python')
+      # SWIG flags just have the module name followed by colon.
+      if exec_mod_start == line:
+        logging.debug('Flags start (swig): %s' % line)
+        return (start_line, 'python')
+      # C++ flags begin after a blank line and with a constant string
+      if after_blank and line.startswith('  Flags from '):
+        logging.debug('Flags start (c): %s' % line)
+        return (start_line, 'c')
+      # java flags begin with a constant string
+      if line == 'where flags are':
+        logging.debug('Flags start (java): %s' % line)
+        start_line += 2                        # skip "Standard flags:"
+        return (start_line, 'java')
+
+      logging.debug('Desc: %s' % line)
+      self.desc.append(line)
+      after_blank = (line == '')
+    else:
+      logging.warn('Never found the start of the flags section for "%s"!'
+                   % self.long_name)
+      return (-1, '')
+
+  def ParsePythonFlags(self, start_line=0):
+    """Parse python/swig style flags."""
+    modname = None                      # name of current module
+    modlist = []
+    flag = None
+    for line_num in range(start_line, len(self.output)): # collect flags
+      line = self.output[line_num].rstrip()
+      if not line:                      # blank
+        continue
+
+      mobj = self.module_py_re.match(line)
+      if mobj:                          # start of a new module
+        modname = mobj.group(1)
+        logging.debug('Module: %s' % line)
+        if flag:
+          modlist.append(flag)
+        self.module_list.append(modname)
+        self.modules.setdefault(modname, [])
+        modlist = self.modules[modname]
+        flag = None
+        continue
+
+      mobj = self.flag_py_re.match(line)
+      if mobj:                          # start of a new flag
+        if flag:
+          modlist.append(flag)
+        logging.debug('Flag: %s' % line)
+        flag = Flag(mobj.group(1),  mobj.group(2))
+        continue
+
+      if not flag:                    # continuation of a flag
+        logging.error('Flag info, but no current flag "%s"' % line)
+      mobj = self.flag_default_py_re.match(line)
+      if mobj:                          # (default: '...')
+        flag.default = mobj.group(1)
+        logging.debug('Fdef: %s' % line)
+        continue
+      mobj = self.flag_tips_py_re.match(line)
+      if mobj:                          # (tips)
+        flag.tips = mobj.group(1)
+        logging.debug('Ftip: %s' % line)
+        continue
+      if flag and flag.help:
+        flag.help += line              # multiflags tack on an extra line
+      else:
+        logging.info('Extra: %s' % line)
+    if flag:
+      modlist.append(flag)
+
+  def ParseCFlags(self, start_line=0):
+    """Parse C style flags."""
+    modname = None                      # name of current module
+    modlist = []
+    flag = None
+    for line_num in range(start_line, len(self.output)):  # collect flags
+      line = self.output[line_num].rstrip()
+      if not line:                      # blank lines terminate flags
+        if flag:                        # save last flag
+          modlist.append(flag)
+          flag = None
+        continue
+
+      mobj = self.module_c_re.match(line)
+      if mobj:                          # start of a new module
+        modname = mobj.group(1)
+        logging.debug('Module: %s' % line)
+        if flag:
+          modlist.append(flag)
+        self.module_list.append(modname)
+        self.modules.setdefault(modname, [])
+        modlist = self.modules[modname]
+        flag = None
+        continue
+
+      mobj = self.flag_c_re.match(line)
+      if mobj:                          # start of a new flag
+        if flag:                        # save last flag
+          modlist.append(flag)
+        logging.debug('Flag: %s' % line)
+        flag = Flag(mobj.group(1),  mobj.group(2))
+        continue
+
+      # append to flag help.  type and default are part of the main text
+      if flag:
+        flag.help += ' ' + line.strip()
+      else:
+        logging.info('Extra: %s' % line)
+    if flag:
+      modlist.append(flag)
+
+  def ParseJavaFlags(self, start_line=0):
+    """Parse Java style flags (com.google.common.flags)."""
+    # The java flags prints starts with a "Standard flags" "module"
+    # that doesn't follow the standard module syntax.
+    modname = 'Standard flags'          # name of current module
+    self.module_list.append(modname)
+    self.modules.setdefault(modname, [])
+    modlist = self.modules[modname]
+    flag = None
+
+    for line_num in range(start_line, len(self.output)): # collect flags
+      line = self.output[line_num].rstrip()
+      logging.vlog(2, 'Line: "%s"' % line)
+      if not line:                      # blank lines terminate module
+        if flag:                        # save last flag
+          modlist.append(flag)
+          flag = None
+        continue
+
+      mobj = self.module_java_re.match(line)
+      if mobj:                          # start of a new module
+        modname = mobj.group(1)
+        logging.debug('Module: %s' % line)
+        if flag:
+          modlist.append(flag)
+        self.module_list.append(modname)
+        self.modules.setdefault(modname, [])
+        modlist = self.modules[modname]
+        flag = None
+        continue
+
+      mobj = self.flag_java_re.match(line)
+      if mobj:                          # start of a new flag
+        if flag:                        # save last flag
+          modlist.append(flag)
+        logging.debug('Flag: %s' % line)
+        flag = Flag(mobj.group(1),  mobj.group(2))
+        continue
+
+      # append to flag help.  type and default are part of the main text
+      if flag:
+        flag.help += ' ' + line.strip()
+      else:
+        logging.info('Extra: %s' % line)
+    if flag:
+      modlist.append(flag)
+
+  def Filter(self):
+    """Filter parsed data to create derived fields."""
+    if not self.desc:
+      self.short_desc = ''
+      return
+
+    for i in range(len(self.desc)):   # replace full path with name
+      if self.desc[i].find(self.executable) >= 0:
+        self.desc[i] = self.desc[i].replace(self.executable, self.name)
+
+    self.short_desc = self.desc[0]
+    word_list = self.short_desc.split(' ')
+    all_names = [ self.name, self.short_name, ]
+    # Since the short_desc is always listed right after the name,
+    #  trim it from the short_desc
+    while word_list and (word_list[0] in all_names
+                         or word_list[0].lower() in all_names):
+      del word_list[0]
+      self.short_desc = ''              # signal need to reconstruct
+    if not self.short_desc and word_list:
+      self.short_desc = ' '.join(word_list)
+
+
+class GenerateDoc(object):
+  """Base class to output flags information."""
+
+  def __init__(self, proginfo, directory='.'):
+    """Create base object.
+    Args:
+      proginfo   A ProgramInfo object
+      directory  Directory to write output into
+    """
+    self.info = proginfo
+    self.dirname = directory
+
+  def Output(self):
+    """Output all sections of the page."""
+    self.Open()
+    self.Header()
+    self.Body()
+    self.Footer()
+
+  def Open(self): raise NotImplementedError    # define in subclass
+  def Header(self): raise NotImplementedError  # define in subclass
+  def Body(self): raise NotImplementedError    # define in subclass
+  def Footer(self): raise NotImplementedError  # define in subclass
+
+
+class GenerateMan(GenerateDoc):
+  """Output a man page."""
+
+  def __init__(self, proginfo, directory='.'):
+    """Create base object.
+    Args:
+      proginfo   A ProgramInfo object
+      directory  Directory to write output into
+    """
+    GenerateDoc.__init__(self, proginfo, directory)
+
+  def Open(self):
+    if self.dirname == '-':
+      logging.info('Writing to stdout')
+      self.fp = sys.stdout
+    else:
+      self.file_path = '%s.1' % os.path.join(self.dirname, self.info.name)
+      logging.info('Writing: %s' % self.file_path)
+      self.fp = open(self.file_path, 'w')
+
+  def Header(self):
+    self.fp.write(
+      '.\\" DO NOT MODIFY THIS FILE!  It was generated by gflags2man %s\n'
+      % _VERSION)
+    self.fp.write(
+      '.TH %s "1" "%s" "%s" "User Commands"\n'
+      % (self.info.name, time.strftime('%x', self.info.date), self.info.name))
+    self.fp.write(
+      '.SH NAME\n%s \\- %s\n' % (self.info.name, self.info.short_desc))
+    self.fp.write(
+      '.SH SYNOPSIS\n.B %s\n[\\fIFLAGS\\fR]...\n' % self.info.name)
+
+  def Body(self):
+    self.fp.write(
+      '.SH DESCRIPTION\n.\\" Add any additional description here\n.PP\n')
+    for ln in self.info.desc:
+      self.fp.write('%s\n' % ln)
+    self.fp.write(
+      '.SH OPTIONS\n')
+    # This shows flags in the original order
+    for modname in self.info.module_list:
+      if modname.find(self.info.executable) >= 0:
+        mod = modname.replace(self.info.executable, self.info.name)
+      else:
+        mod = modname
+      self.fp.write('\n.P\n.I %s\n' % mod)
+      for flag in self.info.modules[modname]:
+        help_string = flag.help
+        if flag.default or flag.tips:
+          help_string += '\n.br\n'
+        if flag.default:
+          help_string += '  (default: \'%s\')' % flag.default
+        if flag.tips:
+          help_string += '  (%s)' % flag.tips
+        self.fp.write(
+          '.TP\n%s\n%s\n' % (flag.desc, help_string))
+
+  def Footer(self):
+    self.fp.write(
+      '.SH COPYRIGHT\nCopyright \(co %s Google.\n'
+      % time.strftime('%Y', self.info.date))
+    self.fp.write('Gflags2man created this page from "%s %s" output.\n'
+                  % (self.info.name, FLAGS.help_flag))
+    self.fp.write('\nGflags2man was written by Dan Christian. '
+                  ' Note that the date on this'
+                  ' page is the modification date of %s.\n' % self.info.name)
+
+
+def main(argv):
+  argv = FLAGS(argv)           # handles help as well
+  if len(argv) <= 1:
+    app.usage(shorthelp=1)
+    return 1
+
+  for arg in argv[1:]:
+    prog = ProgramInfo(arg)
+    if not prog.Run():
+      continue
+    prog.Parse()
+    prog.Filter()
+    doc = GenerateMan(prog, FLAGS.dest_dir)
+    doc.Output()
+  return 0
+
+if __name__ == '__main__':
+  app.run()