shelldocs.py

#!/usr/bin/python
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import os
import re
import sys
import string
from optparse import OptionParser

asflicense='''
<!---
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
-->
'''

def docstrip(key,string):
  string=re.sub("^## @%s " % key ,"",string)
  string=string.lstrip()
  string=string.rstrip()
  return string

def toc(list):
  tocout=[]
  header=()
  for i in list:
    if header != i.getinter():
      header=i.getinter()
      line="  * %s\n" % (i.headerbuild())
      tocout.append(line)
    line="    * [%s](#%s)\n" % (i.getname().replace("_","\_"),i.getname())
    tocout.append(line)
  return tocout

class ShellFunction:
  def __init__(self):
    self.reset()

  def __cmp__(self,other):
    if (self.audience == other.audience):
      if (self.stability == other.stability):
        if (self.replaceb == other.replaceb):
          return(cmp(self.name,other.name))
        else:
          if (self.replaceb == "Yes"):
            return -1
          else:
            return 1
      else:
          if (self.stability == "Stable"):
            return -1
          else:
            return 1
    else:
      if (self.audience == "Public"):
        return -1
      else:
        return 1

  def reset(self):
    self.name=None
    self.audience=None
    self.stability=None
    self.replaceb=None
    self.returnt=None
    self.desc=None
    self.params=None

  def setname(self,text):
    definition=text.split();
    self.name=definition[1]

  def getname(self):
    if (self.name is None):
      return "None"
    else:
      return self.name

  def setaudience(self,text):
    self.audience=docstrip("audience",text)
    self.audience=self.audience.capitalize()

  def getaudience(self):
    if (self.audience is None):
      return "None"
    else:
      return self.audience

  def setstability(self,text):
    self.stability=docstrip("stability",text)
    self.stability=self.stability.capitalize()

  def getstability(self):
    if (self.stability is None):
      return "None"
    else:
      return self.stability

  def setreplace(self,text):
    self.replaceb=docstrip("replaceable",text)
    self.replaceb=self.replaceb.capitalize()

  def getreplace(self):
    if self.replaceb == "Yes":
      return self.replaceb
    else:
      return "No"

  def getinter(self):
    return ((self.getaudience(), self.getstability(), self.getreplace()))

  def addreturn(self,text):
    if (self.returnt is None):
      self.returnt = []
    self.returnt.append(docstrip("return",text))

  def getreturn(self):
    if (self.returnt is None):
      return "Nothing"
    else:
      return "\n\n".join(self.returnt)

  def adddesc(self,text):
    if (self.desc is None):
      self.desc = []
    self.desc.append(docstrip("description",text))

  def getdesc(self):
    if (self.desc is None):
      return "None"
    else:
      return " ".join(self.desc)

  def addparam(self,text):
    if (self.params is None):
      self.params = []
    self.params.append(docstrip("param",text))

  def getparams(self):
    if (self.params is None):
      return ""
    else:
      return " ".join(self.params)

  def getusage(self):
    line="%s %s" % (self.name, self.getparams())
    return line.rstrip()

  def headerbuild(self):
    if self.getreplace() == "Yes":
      replacetext="Replaceable"
    else:
      replacetext="Not Replaceable"
    line="%s/%s/%s" % (self.getaudience(), self.getstability(), replacetext)
    return(line)

  def getdocpage(self):
    line="### `%s`\n\n"\
         "* Synopsis\n\n"\
         "```\n%s\n"\
         "```\n\n" \
         "* Description\n\n" \
         "%s\n\n" \
         "* Returns\n\n" \
         "%s\n\n" \
         "| Classification | Level |\n" \
         "| :--- | :--- |\n" \
         "| Audience | %s |\n" \
         "| Stability | %s |\n" \
         "| Replaceable | %s |\n\n" \
         % (self.getname(),
            self.getusage(),
            self.getdesc(),
            self.getreturn(),
            self.getaudience(),
            self.getstability(),
            self.getreplace())
    return line

  def lint(self):
    getfuncs = {
        "audience"    : self.getaudience,
        "stability"   : self.getstability,
        "replaceable" : self.getreplace,
    }
    validvalues = {
        "audience"    : ("Public", "Private"),
        "stability"   : ("Stable", "Evolving"),
        "replaceable" : ("Yes", "No"),
    }
    messages = []
    for attr in ("audience", "stability", "replaceable"):
      value = getfuncs[attr]()
      if value == "None":
        messages.append("ERROR: function %s has no @%s" % (self.getname(), attr.lower()))
      elif value not in validvalues[attr]:
        validvalue = "|".join(v.lower() for v in validvalues[attr])
        messages.append("ERROR: function %s has invalid value (%s) for @%s (%s)" %
                        (self.getname(), value.lower(), attr.lower(), validvalue))
    return "\n".join(messages)

  def __str__(self):
    line="{%s %s %s %s}" \
      % (self.getname(),
         self.getaudience(),
         self.getstability(),
         self.getreplace())
    return line

def main():
  parser=OptionParser(usage="usage: %prog [--skipprnorep] --output OUTFILE --input INFILE [--input INFILE ...]")
  parser.add_option("-o","--output", dest="outfile",
     action="store", type="string",
     help="file to create", metavar="OUTFILE")
  parser.add_option("-i","--input", dest="infile",
     action="append", type="string",
     help="file to read", metavar="INFILE")
  parser.add_option("--skipprnorep", dest="skipprnorep",
     action="store_true", help="Skip Private & Not Replaceable")
  parser.add_option("--lint", dest="lint",
                    action="store_true", help="Enable lint mode")
  parser.add_option("-V", "--version", dest="release_version", action="store_true", default=False,
                    help="display version information for shelldocs and exit.")

  (options, args)=parser.parse_args()

  if options.release_version:
    with open(os.path.join(os.path.dirname(__file__), "../VERSION"), 'r') as ver_file:
      print ver_file.read()
    sys.exit(0)

  if options.infile is None:
    parser.error("At least one input file needs to be supplied")
  elif options.outfile is None and options.lint is None:
    parser.error("At least one of output file and lint mode needs to be specified")

  allfuncs = []
  try:
    for filename in options.infile:
      with open(filename,"r") as shellcode:
        funcdef = ShellFunction()
        for line in shellcode:
          if line.startswith('## @description'):
            funcdef.adddesc(line)
          elif line.startswith('## @audience'):
            funcdef.setaudience(line)
          elif line.startswith('## @stability'):
            funcdef.setstability(line)
          elif line.startswith('## @replaceable'):
            funcdef.setreplace(line)
          elif line.startswith('## @param'):
            funcdef.addparam(line)
          elif line.startswith('## @return'):
            funcdef.addreturn(line)
          elif line.startswith('function'):
            funcdef.setname(line)
            if options.skipprnorep and \
              funcdef.getaudience() == "Private" and \
              funcdef.getreplace() == "No":
                 pass
            else:
              allfuncs.append(funcdef)
            funcdef = ShellFunction()
  except IOError, err:
    print >> sys.stderr, "ERROR: Failed to read from file: %s. Aborting." % err.filename
    sys.exit(1)

  allfuncs = sorted(allfuncs)

  if options.lint:
    for funcs in allfuncs:
      message = funcs.lint()
      if 0 < len(message):
        print message

  if options.outfile is not None:
    with open(options.outfile, "w") as outfile:
      outfile.write(asflicense)
      for line in toc(allfuncs):
         outfile.write(line)
      outfile.write("\n------\n\n")

      header = []
      for funcs in allfuncs:
        if header != funcs.getinter():
          header = funcs.getinter()
          line = "## %s\n" % (funcs.headerbuild())
          outfile.write(line)
        outfile.write(funcs.getdocpage())

if __name__ == "__main__":
  main()