#!/usr/bin/env python
"""
  document.py -- Simple script to generate manpages from C header
  files.  Looks for the following formatted C comments in the C header files:

  /*
   * Function: my_function - This is my function
   * Description: My function does the following things, in no particular 
   *              order: It eats, sleeps, and is merry
   * Input: arg1 - This argument is healthy
   *        arg2 - This argument is wealthy
   *        arg3 - This argument is wise
   * Output: arg4 - The location of the porridge
   *         arg5 - The location of the spider
   * Returns: -1 on error, 0 otherwise
   */

"""


import sys, os, getopt, string, re, time

QUIET = 0

def usage(argv0):
  print "%s [--help]" % argv0

class FuncDoc:
  def __init__ (self, name):
    self._name = name
    self._title = None
    self._desc = None
    self._args = None
    self._retr = None
    self._defn = None
    self._output = None
    self._other = ""

  def __repr__(self):
    out = []
    out.append("Name: %s" % self._name)
    if self._title is not None:
      out.append("Title: %s" % self._title)
    if self._desc is not None:
      out.append("Description: %s" % self._desc)
    if self._args is not None:
      out.append("Input: %s" % self._args)
    if self._output is not None:
      out.append("Output: %s" % self._output)
    if self._retr is not None:
      out.append("Returns: %s" % self._retr)
    if string.strip(self._other):
      out.append("Other: %s" % self._other)
    if self._defn is not None:
      out.append("Definition:")
      out.append(self._defn)
    return string.join(out, "\n")

class CParser:
  STATE_OTHER = 0
  STATE_COMT = 1
  STATE_FUNC = 2

  RE_C_comment = re.compile("/\*(.*)")
  RE_C_define = re.compile("\s*#\s*define (\S+) (.*)")
  RE_C_typedef = re.compile("typedef (\S+) (.*)")
  RE_C_func_def = re.compile("[^#]*(\S+)([ \*]+)(\S+)\s*\([^\)]*\);")
  RE_C_func_def_b = re.compile("[^#]*(\S+)([ \*]+)(\S+)\s*\([^\)]*")
  RE_C_func_com = re.compile("function:\s*(\S+)(.*)", re.IGNORECASE) 
  RE_C_desc_com = re.compile("description:\s*(.+)", re.IGNORECASE) 
  RE_C_args_com = re.compile("(arguments|input):\s*(.+)", re.IGNORECASE) 
  RE_C_retr_com = re.compile("(return|returns):\s*(.+)", re.IGNORECASE) 
  RE_C_out_com = re.compile("output:\s*(.+)", re.IGNORECASE)
  RE_C_other_com = re.compile("(\S+):\s*(.+)")
  RE_C_com_cont = re.compile("[ \*]*(.+)")

  def __init__ (self, filename):
    self._filename = filename
    self._funcs = {}

  def func (self, name):
    try:
      return self._funcs[name]
    except KeyError:
      f = FuncDoc(name)
      self._funcs[name] = f
      return f

  def go(self):
    try:
        fp = open(self._filename)
    except IOError:
        return
    state = CParser.STATE_OTHER
    f = None
    cont = None
    while 1:
      line = fp.readline()
      if not line: break
      if state == CParser.STATE_OTHER:
        m = CParser.RE_C_comment.search (line)
        if m:
          line = m.group(1)
          state = CParser.STATE_COMT
        else:
          m = CParser.RE_C_define.match(line)
          if m: continue
          m = CParser.RE_C_typedef.search(line)
          if m: continue
          m = CParser.RE_C_func_def.match(line)
          if m:
            func_name = m.group(3)
            f = self.func(func_name)
            f._defn = line
          else:
            m = CParser.RE_C_func_def_b.match(line)
            if m:
              state = CParser.STATE_FUNC
              func_name = m.group(3)
              f = self.func(func_name)
              f._defn = line
              continue
      if state == CParser.STATE_COMT:
        if string.find(line, "*/") != -1:
          state = CParser.STATE_OTHER
          continue
        m = CParser.RE_C_func_com.search(line)
        if m:
          cont = "func"
          f = self.func(m.group(1))
          f._title = m.group(2)
          continue
        m = CParser.RE_C_desc_com.search(line)
        if m:
          cont = "desc"
          f._desc = m.group(1)
          continue
        m = CParser.RE_C_args_com.search(line)
        if m:
          cont = "args"
          f._args = m.group(2)
          continue
        m = CParser.RE_C_retr_com.search(line)
        if m:
          cont = "retr"
          f._retr = m.group(2)
          continue
        m = CParser.RE_C_out_com.search(line)
        if m:
          cont = "out"
          f._output = m.group(1)
          continue
        m = CParser.RE_C_other_com.search(line)
        if not f: continue
        if m:
          cont = "other"
          f._other = f._other + "%s: %s" % (m.group(1), m.group(2))
          continue
        m = CParser.RE_C_com_cont.search(line)
        if m:
          if cont == "func":
            f._title = f._title + '\n' + m.group(1)
          elif cont == "desc":
            f._desc = f._desc + '\n'+ m.group(1)
          elif cont == "args":
            f._args = f._args + '\n' + m.group(1)
          elif cont == "retr":
            f._retr = f._retr + '\n' + m.group(1)
          elif cont == "out":
            f._output = f._output + '\n' + m.group(1)
          elif cont == "other":
            f._other = f._other + '\n' + m.group(1)
      elif state == CParser.STATE_FUNC:
        f._defn = f._defn+line
        if string.find(line, ");") != -1:
          state = CParser.STATE_OTHER

  def dump(self):
    for name in self._funcs.keys():
      # print name
      print "%s\n" % self._funcs[name]

  def dump_manpages(self, directory, owner):
    global QUIET
    date = time.strftime("%d %B %Y", time.localtime(time.time()))
    for name, f in self._funcs.items():
      if f._title is None and f._desc is None and f._args is None and f._retr is None:
        if not QUIET:
          sys.stderr.write('-W- No info for function "%s()"\n' % name)
        continue
      if f._defn is None:
        if not QUIET:
          sys.stderr.write('-W- No defn for function "%s()"\n' % name)
      fp = open("%s/%s.3" % (directory, name), "w")
      fp.write('.TH %s 3 "%s" "%s" "%s"\n\n' % (name, date, owner, self._filename))
      fp.write('.de Ss\n.sp\n.ft CW\n.nf\n..\n')
      fp.write('.de Se\n.fi\n.ft P\n.sp\n..\n')
      fp.write('.SH NAME\n')
      if f._title is None:
        fp.write('%s\n' % f._name)
      else:
        fp.write('%s %s\n' % (f._name, f._title))
      fp.write('.SH SYNOPSIS\n')
      fp.write('.Ss\n#include <%s>\n.Se\n' % self._filename)
      if f._defn:
        fp.write('.Ss\n%s\n.Se\n' % f._defn)
      else:
        fp.write('.Ss\n%s()\n.Se\n' % f._name)
      fp.write('\n')
      if f._args:
        fp.write('.SH ARGUMENTS\n')
        fp.write('%s\n\n' % string.replace(f._args, '\n', '\n.br\n'))
      if f._desc or string.strip(f._other):
        fp.write('.SH DESCRIPTION\n')
        if f._desc: fp.write('%s\n\n' % f._desc)
        if string.strip(f._other): fp.write('%s\n\n' % f._other)
      if f._output:
        fp.write('.SH "RETURN VALUE"\n')
        fp.write('%s\n\n' % string.replace(f._output, '\n', '\n.br\n'))
      fp.write('.SH "SEE ALSO"\n')
      fp.write('.BR %s\n' % string.join(self._funcs.keys(), ' "(3), "'))
      fp.close()

  def dump_hdf (self, directory, owner):
    global QUIET
    sys.path.insert (0, "../python")
    sys.path.insert (0, "python")
    import neo_cgi, neo_util
    hdf = neo_util.HDF()
    date = time.strftime("%d %B %Y", time.localtime(time.time()))
    if not self._funcs.items(): return
    for name, f in self._funcs.items():
      if f._title is None and f._desc is None and f._args is None and f._retr is None:
        if not QUIET:
          sys.stderr.write('-W- No info for function "%s()"\n' % name)
        continue
      if f._defn is None:
        if not QUIET:
          sys.stderr.write('-W- No defn for function "%s()"\n' % name)
      hdf.setValue ("Code.%s" % name, name)
      obj = hdf.getObj ("Code.%s" % name)
      obj.setValue ("Name", name)
      obj.setValue ("filename", self._filename)
      if f._title: obj.setValue ("Title", f._title)
      if f._defn: obj.setValue ("Define", neo_cgi.text2html(f._defn))
      if f._args: obj.setValue ("Args", neo_cgi.text2html(f._args))
      if f._desc: obj.setValue ("Desc", neo_cgi.text2html(f._desc))
      if string.strip(f._other): obj.setValue ("Other", neo_cgi.text2html(string.strip(f._other)))
      if f._output: obj.setValue ("Output", neo_cgi.text2html(f._output))
      n = 0
      for func in self._funcs.keys():
        obj.setValue ("related.%d" % n, func)
        n = n + 1

    fname = self._filename
    x = string.rindex (fname, "/")
    if x != -1: fname = fname[x+1:]
    x = string.rindex (fname, '.')
    if x != -1: fname = fname[:x]

    hdf.writeFile ("%s/%s.hdf" % (directory, fname))

def main(argv, environ):
  alist, args = getopt.getopt(argv[1:], "q", ["help", "outdir=", "owner=", "hdf"])

  outdir = "."
  owner = ""
  do_hdf = 0
  for (field, val) in alist:
    if field == "--help":
      usage (argv[0])
      return
    if field == "--outdir":
      outdir = val
    if field == "--owner":
      owner = val
    if field == "-q":
      global QUIET
      QUIET = 1
    if field == "--hdf":
      do_hdf = 1

  if args:
    for file in args:
      parser = CParser(file)
      parser.go()
      if not do_hdf:
        parser.dump_manpages(outdir, owner)
      else:
        parser.dump_hdf (outdir, owner)


if __name__ == "__main__":
  main (sys.argv, os.environ)