#!/usr/bin/python

# -*- coding: UTF-8 -*-

# vim: set ai ts=8 sts=0 sw=8 tw=0 noexpandtab:

# Copyright 2009 Gentoo Foundation

# Distributed under the terms of the GNU General Public Licence v2

# Authors:

#	Daniel Solano Gómez <gentoo@sattvik.com>

# Maintainer: Gentoo Java Herd <java@gentoo.org>

# Python based XML modifier

from xml.sax.saxutils import XMLGenerator

import sys

"""

This program is designed to manipulate any <javadoc> elements in an Ant build.xml document.  It 

strips any 'link' or 'linkoffline' attributes from any <javadoc> elements it finds, and adds 

<link> subelements corresponding to the options specified on the command line.

"""

class JavadocRewriter:

	"""

	Main class that drives all of the rewriting magic.

	"""

	EXIT_CODE_OK=0

	EXIT_CODE_WARN=1

	EXIT_CODE_ERROR=2

	__version__ = "$Revision: 1.1 $"[11:-2]

	files=None

	options=None

	exitCode=EXIT_CODE_OK

	processor=None

	def main(self,args):

		self.parseArguments(args)

		self.checkOptions()

		self.doMainWork()

		return self.exitCode

	def parseArguments(self,args):

		from optparse import OptionParser

		parser=OptionParser(

				version=self.getVersion(),

				usage=self.getUsage(),

				description=self.getDescription())

		parser.add_option("-b","--backup",

				action="store_true",dest="backup",

				help="Back up files that are being processed")

		parser.add_option("-l","--link",

				action="append",type="string",dest="links",

				metavar="URI",

				help="Add online link to URI, which may be an absolute URL or a relative "

				"file name")

		parser.add_option("-o","--link-offline",

				action="append",type="string",nargs=2,dest="offlineLinks",

				metavar="URI PKG_DIR",

				help="Add offline link to URI using package-list file in directory PKG_DIR")

		(self.options, self.files)=parser.parse_args(args)

	def getVersion(self):

		version ="Gentoo Ant Javadoc Rewriter "+self.__version__+"\n"

		version+="Copyright (c) 2009 Gentoo Foundation\n"

		version+="Distributed under the terms of the GNU General Public Lincense v2\n"

		version+="Please contact the Gentoo Java Team <java@gentoo.org> with problems."

		return version

	def getDescription(self):

		desc ="This program is designed to manipulate any <javadoc> elements in an Ant "

		desc+="build.xml document.  It strips any 'link' or 'linkoffline' attributes from any "

		desc+="<javadoc> elements it finds, and adds <link> subelements corresponding to the "

		desc+="options specified on the command line."

		return desc

	def getUsage(self):

		usage =self.getVersion()+"\n"

		usage+="\n"

		usage+="usage: %prog [-vh] [-l URI] [-o URI PKG_DIR] [-f FILE]"

		return usage

	def checkOptions(self):

		self.checkMissingLinks()

	def checkMissingLinks(self):

		if self.options.links == None and self.options.offlineLinks == None:

			self.doWarning("You have not specified any links")

	def doWarning(self,msg):

		self.setExitCode(self.EXIT_CODE_WARN)

		self.printMsg("Warning: %s" % msg)

	def setExitCode(self,code):

		# only allow exit code to be made more severe

		if self.exitCode<code:

			self.exitCode=code

	def printMsg(self,msg):

		print >> sys.stderr, "%s\n" % msg

	def doMainWork(self):

		self.initProcessor()

		self.processFiles()

	def initProcessor(self):

		self.processor=JavadocProcessor(

				self.options.links,

				self.options.offlineLinks)

	def processFiles(self):

		if len(self.files) == 0:

			self.processStdin()

		else:

			self.processFileList(self.files)

	def processStdin(self):

		self.processor.parse(sys.stdin)

		self.processor.write(sys.stdout)

	def processFileList(self,fileList):

		for fileName in fileList:

			self.processFile(fileName)

	def processFile(self,fileName):

		if fileName == '-':

			self.processStdin()

			return

		if self.options.backup:

			self.doBackup(fileName)

		self.readAndParse(fileName)

		self.writeParsedOutput(fileName)

	def doBackup(self,fileName):

		from shutil import copy2

		copy2(fileName,fileName+".jhbk")

	def readAndParse(self,fileName):

		with open(fileName,"r") as file:

			self.processor.parse(file)

	def writeParsedOutput(self,fileName):

		with open(fileName,"w") as file:

			self.processor.write(file)

class JavadocProcessor(XMLGenerator):

	"""

	The class that does the heavy duty work of rewriting a build.xml document.  It may be reused

	multiple times with subsequent calls to parse().

	"""

	def __init__(self,links=[],offlineLinks=[]):

		import StringIO

		self.buffer=StringIO.StringIO()

		self.links=links

		self.offlineLinks=offlineLinks

		self.inJavadocElement=0

		XMLGenerator.__init__(self,self.buffer,'UTF-8')

	def __str__(self):

		str ="JavadocProcessor: "

		str+=self.getLinkString();

                str+=self.getOfflineLinkString();

		return str

	def getLinkString(self):

		return self.getListString("link",self.links)

	def getOfflineLinkString(self):

		return self.getListString("link offline",self.offlineLinks)

	def getListString(self,name,list):

		str=""

		for item in list or []:

			str+="\n  {0}: {1}".format(name,item)

		return str

		self.parseInput(inStream)

		self.writeOutput(outFile)

		self.resetBuffer()

	def parse(self,inFile):

		"""

		Parse the XML in inFile and store the results in memory.

		"""

		from xml.sax import parse

		parse(inFile,self)

		self.writeUtf8(u'\n')

	def write(self,outFile):

		"""

		Write the stored results to outStream and reset the memory buffer.

		"""

		outFile.write(self.buffer.getvalue())

		self.resetBuffer()

	def resetBuffer(self):

		self.buffer.truncate(0)

	def writeUtf8(self,str):

		self.buffer.write(str.encode('UTF-8'))

	# SAX methods

	def startElement(self,name,attrs):

		if self.inJavadocElement:

			self.dropLinkStartElements(name,attrs)

		else:

			self.lookForJavadocStartElements(name,attrs)

	def endElement(self,name):

		if self.inJavadocElement:

			self.dropLinkEndElements(name)

		else:

			self.lookForJavadocEndElement(name)

	def dropLinkStartElements(self,name,attrs):

		if name.lower() != u'link':

			XMLGenerator.startElement(self,name,attrs)

	def lookForJavadocStartElements(self,name,attrs):

		if name.lower() == u'javadoc':

			self.processJavadocElement(attrs)

		else:

			XMLGenerator.startElement(self,name,attrs)

	def processJavadocElement(self,attrs):

		self.inJavadocElement+=1

		newAttrs=self.processJavadocAttributes(attrs)

		self.renderElement(u'javadoc',newAttrs)

		self.renderLinks()

		self.renderOfflineLinks()

	def processJavadocAttributes(self,attrs):

		newAttrs=dict(attrs)

		for name in newAttrs.keys():

			self.processJavadocAttribute(newAttrs,name)

		return newAttrs

	def processJavadocAttribute(self,attrs,name):

		if name.lower() == u'link' or name.lower() == u'linkoffline':

			attrs.pop(name)

	def renderElement(self,name,attrs,closeElement=False):

		self.writeUtf8(u"<%s" % name)

		self.renderAttributes(attrs)

		if closeElement:

			self.writeUtf8("/")

		self.writeUtf8(">\n")

	def renderAttributes(self,attrs):

		for (name, value) in attrs.items():

			self.renderAttribute(name,value)

	def renderAttribute(self,name,value):

		from xml.sax.saxutils import quoteattr

		self.writeUtf8(" %s=%s" % ( name, quoteattr(value) ))

	def renderLinks(self):

		for link in self.links or []:

			self.renderLink(link)

	def renderLink(self,link,attrs=dict()):

		attrs[u'href']=link;

		self.renderElement(u'link',attrs,True)

	def renderOfflineLinks(self):

		for (link, packagelistLoc) in self.offlineLinks or []:

			self.renderOfflineLink(link,packagelistLoc)

	def renderOfflineLink(self,link,packagelistLoc):

		attrs=dict()

		attrs[u'offline']=u'true'

		attrs[u'packagelistLoc']=packagelistLoc

		self.renderLink(link,attrs)

	def dropLinkEndElements(self,name):

		if name.lower() != u'link':

			XMLGenerator.endElement(self,name)

	def lookForJavadocEndElement(self,name):

		if name.lower() == u'javadoc':

			self.inJavadocElement-=1

		XMLGenerator.endElement(self,name)

if __name__ == '__main__':

	rewriter=JavadocRewriter()

	sys.exit(rewriter.main(sys.argv[1:]))