"""
$RCSfile: interfaces.py,v $

Processor interfaces

Author: Philipp von Weitershausen <philikon@philikon.de>

$Id: interfaces.py,v 1.4 2005/09/06 02:08:59 arielpartners Exp $
"""

__cvstag__  = '$Name:  $'[6:-2]
__date__    = '$Date: 2005/09/06 02:08:59 $'[6:-2]
__version__ = '$Revision: 1.4 $'[10:-2]

from zope.interface  import Interface

class IProcessor(Interface):

    def setDebugLevel(level):
        """

        Set debug level from 0 to 3.
        0 = silent
        3 = extra verbose
        Debug messages go to Zope server log.

        """

class IDTDValidator(IProcessor):
    """
    ZopeXMLMethods DTD Validator public interface

    This class encapsulates an DTD Validator for use by
    ZopeXMLMethods.  IDTDValidator is the Interface implemented by a
    processor library.  Any library capable of validating XML via a
    DTD can be used, as long as an adaptor class is written that
    conforms to this interface.

    This is the first of many schema validator interfaces.  For
    example: XML-Schema, RelaxNG, Schematron, DTD.
    
    """

    def dtdValidationResultsString(xmlString, xmlURL):
        """
        Validate the passed in XML document against the
        DTD that it refers to in a DOCTYPE.
        """

    def isValidForDTD(xmlString, xmlURL):
        """
        Return boolean indicating whether passed in document is valid
        with respect to its DTD
        """

class IXPathProcessor(IProcessor):
    """
    ZopeXMLMethods XSLT Processor public interface

    This class encapsulates an XSLT Processor for use by
    ZopeXMLMethods.  IXSLTProcessor is the Interface implemented by a
    processor library.  Any library capable of processing XPath can be
    used, as long as an adaptor class is written that conforms to this
    interface.
    """

    def compile(expression):
        """
        Return compiled expression as IXPathExpression.  If a
        particular processing library does not provide the capability
        of compiling an expression, it may choose to implement
        IXPathExpression directly and have this method return an
        instance of itself (see SabPythProcessor.py).  Throws an exception
        if there are any errors.
        """

class IXPathExpression(Interface):
    """
    
    Interface for a compiled xpath expression.  This may be
    implemented either as a separate adaptor class that adapts a
    processor-native compiled xpath expression type, or directly by
    the parent adaptor class.
    
    """

    def evaluateString(xmlString, xmlURL, prettyPrint=0):
       "return result of xpath evaluation as string"

    def evaluateDOM(xmlNode, xmlURL):
       "return a list of DOM nodes matching xpath"

class IXSLTProcessor(IProcessor):
    """
    ZopeXMLMethods XSLT Processor public interface

    This class encapsulates an XSLT Processor for use by
    ZopeXMLMethods.  IXSLTProcessor is the Interface implemented by a
    processor library.  Any library capable of processing XSLT can be
    used, as long as an adaptor class is written that conforms to this
    interface.
    """

    def transform(xmlString, xmlURL, xsltString, xsltURL,
                  transformObject = None, xsltParams = {}, REQUEST = None):
        """
        Transforms the passed in XML into the required output (usually
        HTML) using the passed in XSLT.  Both the XML and XSLT strings
        should be well-formed.  Returns the output as a string.
        transformObject and REQUEST params may be used to acquire Zope
        content such as XSLT parameters and URN namespaces, if
        required.

        If anything goes wrong, it raises an Exception.
        """

class IProcessorRegistry(Interface):

    def prefer(processorType, processorName, exclusive=0):
        """
        For a given processor type, indicate a preference for one
        processor over another.  Set the 'exclusive' flag to indicate
        that no other choices should be offered, even if available.
        To change your preference, simply call this method again.
        
        Note: if the chosen processor is not available, this advice is
        simply ignored.  Why?  Imagine the case where you make a
        choice, then ZSync the object tree to another Zope instance in
        which this processor is not available!  We must recover
        gracefully from this (rather likely) scenario.
        """
    
    def register(processorType, processorName, processorClassName):
        "register a processor with the given name and classname"

    def names(processorType):
        """
        
        Return list of currently available processors of the given
        type.

        If an exclusive preference has been expressed, *and* the
        preferred processor is available, return only that.

        Call reload() first to ensure we pick up new processor
        libraries if we just got ZSynced to another Zope instance.

        """

    def item(processorType, processorName):
        """
        
        Obtain the object encapsulating the named processor of the
        given type, if it is available.

        Otherwise, return the defaultItem()
        
        """

    def defaultItem(processorType):
        """

        Obtain the object encapsulating the preferred processor of the
        given type, if it is available.

        Otherwise try all other processors in random order.

        Finally, give up if we don't have a single processor
        available.

        Call reload() first to ensure we pick up new processor
        libraries if we just got ZSynced to another Zope instance.
        
        """

    def defaultName(processorType):
        """
        
        Return the name of the default processor of the indicated
        type.  If a preference was indicated and it is available, return
        it.  Otherwise return the first one or None if there aren't
        any.

        """

# EOF interfaces.py