| #!/usr/bin/env python |
| # |
| # Copyright (c) 2007, 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(csilvers): 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. |
| |
| __author__ = 'Dan Christian' |
| |
| import os |
| import re |
| import sys |
| import stat |
| import time |
| import subprocess |
| |
| 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() |
| |
| |
| 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 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 0 |
| |
| # 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 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: |
| print >>sys.stderr, __doc__ |
| print >>sys.stderr, "flags:" |
| print >>sys.stderr, str(FLAGS) |
| 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__': |
| main(sys.argv) |
