| #!/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) |
