#!/usr/bin/python
#
# Generates a DocBook section documenting all PLCAPI methods on
# stdout.
#
# Mark Huang <mlhuang@cs.princeton.edu>
# Copyright (C) 2006 The Trustees of Princeton University
#
# $Id$
#

import xml.dom.minidom
from xml.dom.minidom import Element, Text
import codecs

from PLC.Method import *
import DocBookLocal
import groups

# xml.dom.minidom.Text.writexml adds surrounding whitespace to textual
# data when pretty-printing. Override this behavior.
class TrimText(Text):
    """text"""
    def __init__(self, text = None):
        self.data = unicode(text)

    def writexml(self, writer, indent="", addindent="", newl=""):
        Text.writexml(self, writer, "", "", "")

class TrimTextElement(Element):
    """<tagName>text</tagName>"""
    def __init__(self, tagName, text = None):
        Element.__init__(self, tagName)
        if text is not None:
            self.appendChild(TrimText(text))

    def writexml(self, writer, indent="", addindent="", newl=""):
        writer.write(indent)
        Element.writexml(self, writer, "", "", "")
        writer.write(newl)

class simpleElement(TrimTextElement): pass

class paraElement(simpleElement):
    """<para>text</para>"""
    def __init__(self, text = None):
        simpleElement.__init__(self, 'para', text)

class blockquoteElement(Element):
    """<blockquote><para>text...</para><para>...text</para></blockquote>"""
    def __init__(self, text = None):
        Element.__init__(self, 'blockquote')
        if text is not None:
            # Split on blank lines
            lines = [line.strip() for line in text.strip().split("\n")]
            lines = "\n".join(lines)
            paragraphs = lines.split("\n\n")

            for paragraph in paragraphs:
                self.appendChild(paraElement(paragraph))

def param_type(param):
    """Return the XML-RPC type of a parameter."""
    if isinstance(param, Mixed) and len(param):
        subtypes = [param_type(subparam) for subparam in param]
        return " or ".join(subtypes)
    elif isinstance(param, (list, tuple, set)) and len(param):
        return "array of " + " or ".join([param_type(subparam) for subparam in param])
    else:
        return xmlrpc_type(python_type(param))

class paramElement(Element):
    """An optionally named parameter."""
    def __init__(self, name, param):
        # <listitem>
        Element.__init__(self, 'listitem')

        description = Element('para')

        if name:
            description.appendChild(simpleElement('parameter', name))
            description.appendChild(TrimText(": "))

        description.appendChild(TrimText(param_type(param)))

        if isinstance(param, (list, tuple, set)) and len(param) == 1:
            param = param[0]

        if isinstance(param, Parameter):
            description.appendChild(TrimText(", " + param.doc))
            param = param.type

        self.appendChild(description)

        if isinstance(param, dict):
            itemizedlist = Element('itemizedlist')
            self.appendChild(itemizedlist)
            for name, subparam in param.iteritems():
                itemizedlist.appendChild(paramElement(name, subparam))

        elif isinstance(param, (list, tuple, set)) and len(param):
            itemizedlist = Element('itemizedlist')
            self.appendChild(itemizedlist)
            for subparam in param:
                itemizedlist.appendChild(paramElement(None, subparam))


def get_method_doc(func):

    method = func.name

    if func.status == "deprecated":
        return

    (min_args, max_args, defaults) = func.args()

    section = Element('section')
    section.setAttribute('id', func.name)
    section.appendChild(simpleElement('title', func.name))

    prototype = "%s (%s)" % (method, ", ".join(max_args))
    para = paraElement('Prototype:')
    para.appendChild(blockquoteElement(prototype))
    section.appendChild(para)

    para = paraElement('Description:')
    para.appendChild(blockquoteElement(func.__doc__))
    section.appendChild(para)

    para = paraElement('Allowed Roles:')
    para.appendChild(blockquoteElement(", ".join(func.roles)))
    section.appendChild(para)

    section.appendChild(paraElement('Parameters:'))
    params = Element('itemizedlist')
    if func.accepts:
        for name, param, default in zip(max_args, func.accepts, defaults):
            params.appendChild(paramElement(name, param))
    else:
        listitem = Element('listitem')
        listitem.appendChild(paraElement('None'))
        params.appendChild(listitem)
    section.appendChild(params)

    section.appendChild(paraElement('Returns:'))
    returns = Element('itemizedlist')
    returns.appendChild(paramElement(None, func.returns))
    section.appendChild(returns)

    #print section.toprettyxml(encoding = "UTF-8")
    return section


def get_section(fields, field_list = None):
    if not field_list:
	field_list = fields.keys()
	field_list.sort()

    for field in field_list:
	value = fields[field]
	section = Element('section')
	section.setAttribute('id', field.title())
	section.appendChild(simpleElement('title', field.title()))
	# if list of methods, append method docs
	# else if dict, make a new section group
        if isinstance(value, dict):
	    section.appendChild(get_section(value))
	elif isinstance(value, list):
	    methods = DocBookLocal.get_func_list(value)
	    for method in methods:
		method_doc = get_method_doc(method)
	        section.appendChild(method_doc)   	      

    return section
 	
# write full list of methods to Methods.xml
#api_func_list = DocBookLocal.get_func_list()
#methods_xml = file('Methods.xml',  'w')
#for func in api_func_list:
#    section = get_method_doc(func)
#    if section:		
#        methods_xml.write(section)
#methods_xml.close()

# write methods grouped into interfaces
interfaces = ['Registry_Interface', 'Management_Interface', 'Slice_Interface']
for interface in interfaces:
    interface_file = file(interface+'.xml', 'w')
    interface_methods = groups.interfaces[interface]
    section =  get_section(interface_methods, ['public', 'admin'])
    if section:    
	interface_file.write(section.toprettyxml(encoding = "UTF-8"))
    interface_file.close()