#!/usr/bin/python2.4
#
# Copyright 2006 Google Inc. All Rights Reserved.

"""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...
"""

# 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.

__author__ = 'dchristian@google.com (Dan Christian)'

import os
import re
import sys
import stat
import datetime
import subprocess

from google3.pyglib import app
from google3.pyglib import flags
from google3.pyglib import logging

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 '/tmp'

FLAGS = flags.FLAGS
flags.DEFINE_string('dest_dir', _GetDefaultDestDir(),
                    'Directory to write resulting manpage to.'
                    ' Specify \'-\' for stdout')
flags.DEFINE_string('help_flag', '--help',
                    'Option to pass to target program in to get help')

MIN_VALID_USAGE_MSG = 9            # minimum output likely to be valid
_version = '0.1'

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 '/' == filename[0]:                # 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 directory or '/' != directory[0]: # directory is relative
        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 gleened from running a program with --help."""

  # Match a module block start
  # google3.pyglib.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
  # google3/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
  # 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 = datetime.date.today()   # default date info

  def Run(self):
    """Run it and collect output.

    Returns:
      True   If everything went well.
      False  If there were problems.
    """
    if not self.executable:
      logging.error('Could not locate "%s"' % self.long_name)
      return False

    finfo = os.stat(self.executable)
    self.date = datetime.date.fromtimestamp(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 re-direct that to
    # stdout.  Re-direct stdin to /dev/null to encourage programs that
    # don't understand --help to exit.
    try:
      runstate = subprocess.Popen(
        [self.executable, FLAGS.help_flag],
        stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
        stdin=open('/dev/null', 'r'))
    except OSError, msg:
      logging.error('Error executing "%s": %s' % (self.name, msg))
      return False

    #read output progressively so the pipe doesn't fill up (fileutil).
    self.output = runstate.stdout.readlines()
    status = runstate.wait()
    logging.debug('Program exited with %s' % status)
    output = runstate.communicate()[0]
    if output:
      self.output = output.splitlines()
    if len(self.output) < MIN_VALID_USAGE_MSG:
      logging.error(
        'Error: "%s %s" returned %d and only %d lines: %s'
        % (self.name, FLAGS.help_flag, status, len(self.output), output))
      return False
    return True

  def Parse(self):
    """Parse program output."""
    cnt, lang = self.ParseDesc()
    if cnt < 0:
      return
    if 'python' == lang:
      self.ParsePythonFlags(cnt)
    elif 'c' == lang:
      self.ParseCFlags(cnt)
    elif 'java' == lang:
      self.ParseJavaFlags(cnt)

  def ParseDesc(self, cnt=0):
    """Parse the initial description.

    This could be Python or C++.

    Returns:
      (line_count, lang_type)
        line_count  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 = False
    cnt = 0
    for cnt in range(cnt, len(self.output)): # collect top description
      line = self.output[cnt].rstrip()
      # Python flags start with 'flags:\n'
      if ('flags:' == line
          and len(self.output) > cnt+1 and '' == self.output[cnt+1].rstrip()):
        cnt += 2
        logging.debug('Flags start (python): %s' % line)
        return (cnt, 'python')
      # SWIG flags just have the module name followed by colon.
      if exec_mod_start == line:
        logging.debug('Flags start (swig): %s' % line)
        return (cnt, '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 (cnt, 'c')
      # java flags begin with a constant string
      if line == 'where flags are':
        logging.debug('Flags start (java): %s' % line)
        cnt += 2                        # skip "Standard flags:"
        return (cnt, '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, cnt=0):
    """Parse python/swig style flags."""
    modname = None                      # name of current module
    flag = None
    for cnt in range(cnt, len(self.output)): # collect flags
      line = self.output[cnt].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, cnt=0):
    """Parse C style flags."""
    modname = None                      # name of current module
    flag = None
    for cnt in range(cnt, len(self.output)): # collect flags
      line = self.output[cnt].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, cnt=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 cnt in range(cnt, len(self.output)): # collect flags
      line = self.output[cnt].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 cnt in range(len(self.desc)):   # replace full path with name
      if self.desc[cnt].find(self.executable) >= 0:
        self.desc[cnt] = self.desc[cnt].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()


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, self.info.date.strftime('%x'), 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 = flag.help
        if flag.default or flag.tips:
          help += '\n.br\n'
        if flag.default:
          help += '  (default: \'%s\')' % flag.default
        if flag.tips:
          help += '  (%s)' % flag.tips
        self.fp.write(
          '.TP\n%s\n%s\n' % (flag.desc, help))

  def Footer(self):
    self.fp.write(
      '.SH COPYRIGHT\nCopyright \(co %s Google.\n'
      % self.info.date.strftime('%Y'))
    self.fp.write('Gflags2man.par created this page from "%s %s" output.\n'
                  % (self.info.name, FLAGS.help_flag))
    self.fp.write('\nGflags2man.par was written by Dan Christian'
                  ' (dchristian@google.com).  Note that the date on this'
                  ' page is the modification date of %s.\n' % self.info.name)


def main(argv):
  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()


if __name__ == '__main__':
  app.run()