"""
Interfaces for FormEncode
"""

from protocols import Interface, Attribute

class IDeclarative(Interface):

    def __init__(**kw):
        """
        Instantiates this class with all the keywords being used to
        update the instance variables.
        """

    def __call__(**kw):
        """
        Returns a copy with all attributes using the given keywords,
        being updated.
        """


class IValidator(IDeclarative):

    messages = Attribute('A dictionary of messages (with formatting strings) for error responses', name='messages')
    protocols = Attribute('A list of protocols (strings) that this validator should work on', name='protocols')
    ifMissing = Attribute('If the source that this validator would handle is missing (e.g., a field that was not specified), use this value.  If Validator.NoDefault, then if the field is missing an exception should be raised.', name='ifMissing')
    repeating = Attribute('A boolean; this object accepts lists if true, subvalidators can be found in the validators attribute.', name='repeating')
    compound = Attribute('A boolean; this object has a dictionary of validators if this is true, subvalidators can be found in the field attribute (a dictionary).', name='compound')

    def toPython(value, state=None):
        """
        Convert `value` from its foreign representation to its Python
        representation.  `state` is for application-specific hooks.
        """

    def fromPython(value, state=None):
        """
        Convert `value` from its Python representation to the foreign
        representation.  `state` is for application-specific hooks.
        """

    def message(name, default):
        """
        Return the message (from the `messages` attribute) that goes
        with `name`, or return default if `name` not found `default`.
        """

class ISchema(IValidator):

    fields = Attribute('A dictionary of (field name: validator)', name='fields')

class IController(Interface):

    """
    Wrap `object` in a controller.  This controller knows how to get
    attributes and their values from the object, and how to set those
    attributes in the object.  A simple implementation could use
    __dict__ and setattr(), though in different contexts something
    more limited may be called for.

    Sophisticated controllers might also have sub-controllers for the
    object's attributes.

    An object may be a class, the attributes being defaults for the
    class, and setting the attributes may create a new instance.

    Typically controllers will be adaptable into validators, which
    will be used to when communicating to outside sources.  The
    controller may also be adaptable to an HTMLView for extra
    goodness.

    @@: Should mutable/immutable be explicit, or defined
    per-controller?
    """

    def attributes():
        """
        Return a dictionary of attributes associated with the object.
        """

    def copyWithAttributes(attrs):
        """
        Return a copy of the object with the given attributes.
        """

    def setAttributes(attrs):
        """
        Set the object with the attributes.  Return None.
        """

class IField(Interface):
    """
    Objects that represent HTML input widgets
    """

    static = Attribute('static', "Boolean; static fields cannot be edited.")
    hidden = Attribute('hidden', "Boolean; hidden fields are not shown.")
    validator = Attribute('validator', "Validator(s) associated with this field.")

    def html(request):
        """
        Return the HTML, using the given request.  `Field.html` is the
        typical implementation -- subclasses usually override
        `htmlInput`.
        """

    def htmlHidden(request):
        """
        Return the hidden representation of this field
        """

    def htmlStatic(request):
        """
        Return the static (uneditable) representation of this field.
        """

    def htmlInput(request):
        """
        Return the HTML for this field.
        """