########################################################################
# File name: fields.py
# This file is part of: aioxmpp
#
# LICENSE
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this program.  If not, see
# <http://www.gnu.org/licenses/>.
#
########################################################################
import abc
import collections
import copy

import aioxmpp.xso as xso

from . import xso as forms_xso


descriptor_ns = "{jabber:x:data}field"


FIELD_DOCSTRING_TEMPLATE = """
``{field_type.value}`` field ``{var}``

{label}
"""


class BoundField(metaclass=abc.ABCMeta):
    """
    Abstract base class for objects returned by the field descriptors.

    :param field: field descriptor to bind
    :type field: :class:`AbstractField`
    :param instance: form instance to bind to
    :type instance: :class:`object`

    :class:`BoundField` instances represent the connection between the field
    descriptors present at a form *class* and the *instance* of that class.

    They store of course the value of the field for the specific instance, but
    also possible instance-specific overrides for the metadata attributes
    :attr:`desc`, :attr:`label` and :attr:`required` (and possibly
    :attr:`.BoundOptionsField.options`). By default, these attributes return
    the same value as set on the corresponding `field`, but the attributes can
    be set to different values, which only affects the single form instance.

    The use case is to fill these fields with the information obtained from a
    :class:`.Data` XSO when creating a form with :meth:`.Form.from_xso`: it
    allows the fields to behave exactly like the sender specified.

    Deep-copying a :class:`BoundField` deepcopies all attributes, except the
    :attr:`field` and :attr:`instance` attributes. See also :meth:`clone_for`
    for copying a bound field for a new `instance`.

    Subclass overview:

    .. autosummary::

       BoundSingleValueField
       BoundMultiValueField
       BoundSelectField
       BoundMultiSelectField

    Binding relationship:

    .. autoattribute:: field

    .. attribute:: instance

       The `instance` as passed to the constructor.

    Field metadata attributes:

    .. autoattribute:: desc

    .. autoattribute:: label

    .. autoattribute:: required

    Helper methods:

    .. automethod:: clone_for

    The following methods must be implemented by base classes.

    .. automethod:: load

    .. automethod:: render

    """

    def __init__(self, field, instance):
        super().__init__()
        self._field = field
        self.instance = instance

    @property
    def field(self):
        """
        The field which is bound to the :attr:`instance`.
        """
        return self._field

    def __repr__(self):
        return "<bound {!r} for {!r} at 0x{:x}>".format(
            self._field,
            self.instance,
            id(self),
        )

    def __deepcopy__(self, memo):
        result = copy.copy(self)
        for k, v in self.__dict__.items():
            if k == "_field" or k == "instance":
                continue
            setattr(result, k, copy.deepcopy(v, memo))
        return result

    @property
    def desc(self):
        """
        .. seealso::

           :attr:`.Field.desc`
              for a full description of the ``desc`` semantics.
        """

        try:
            return self._desc
        except AttributeError:
            return self._field.desc

    @desc.setter
    def desc(self, value):
        self._desc = value

    @property
    def label(self):
        """
        .. seealso::

           :attr:`.Field.label`
              for a full description of the ``label`` semantics.
        """
        try:
            return self._label
        except AttributeError:
            return self._field.label

    @label.setter
    def label(self, value):
        self._label = value

    @property
    def required(self):
        """
        .. seealso::

           :attr:`.Field.required`
              for a full description of the ``required`` semantics.
        """
        try:
            return self._required
        except AttributeError:
            return self._field.required

    @required.setter
    def required(self, value):
        self._required = value

    def clone_for(self, other_instance, memo=None):
        """
        Clone this bound field for another instance, possibly during a
        :func:`~copy.deepcopy` operation.

        :param other_instance: Another form instance to which the newly created
                               bound field shall be bound.
        :type other_instance: :class:`object`
        :param memo: Optional deepcopy-memo (see :mod:`copy` for details)

        If this is called during a deepcopy operation, passing the `memo` helps
        preserving and preventing loops. This method is essentially a
        deepcopy-operation, with a modification of the :attr:`instance`
        afterwards.
        """

        if memo is None:
            result = copy.deepcopy(self)
        else:
            result = copy.deepcopy(self, memo)
        result.instance = other_instance
        return result

    @abc.abstractmethod
    def load(self, field_xso):
        """
        Load the field information from a data field.

        :param field_xso: XSO describing the field.
        :type field_xso: :class:`~.Field`

        This loads the current value, description, label and possibly options
        from the `field_xso`, shadowing the information from the declaration of
        the field on the class.

        This method is must be overriden and is thus marked abstract. However,
        when called from a subclass, it loads the :attr:`desc`, :attr:`label`
        and :attr:`required` from the given `field_xso`. Subclasses are
        supposed to implement a mechansim to load options and/or values from
        the `field_xso` and then call this implementation through
        :func:`super`.
        """
        if field_xso.desc:
            self._desc = field_xso.desc

        if field_xso.label:
            self._label = field_xso.label

        self._required = field_xso.required

    @abc.abstractmethod
    def render(self, *, use_local_metadata=True):
        """
        Return a :class:`~.Field` containing the values and metadata set in the
        field.

        :param use_local_metadata: if true, the description, label and required
                                   metadata can be sourced from the field
                                   descriptor associated with this bound field.
        :type use_local_metadata: :class:`bool`
        :return: A new :class:`~.Field` instance.

        The returned object uses the values accessible through this object;
        that means, any values set for e.g. :attr:`desc` take precedence over
        the values declared at the class level. If `use_local_metadata` is
        false, values declared at the class level are not used if no local
        values are declared. This is useful when generating a reply to a form
        received by a peer, as it avoids sending a modified form.

        This method is must be overriden and is thus marked abstract. However,
        when called from a subclass, it creates the :class:`~.Field` instance
        and initialises its :attr:`~.Field.var`, :attr:`~.Field.type_`,
        :attr:`~.Field.desc`, :attr:`~.Field.required` and
        :attr:`~.Field.label` attributes and returns the result. Subclasses are
        supposed to override this method, call the base implementation through
        :func:`super` to obtain the :class:`~.Field` instance and then fill in
        the values and/or options.
        """

        result = forms_xso.Field(
            var=self.field.var,
            type_=self.field.FIELD_TYPE,
        )

        if use_local_metadata:
            result.desc = self.desc
            result.label = self.label
            result.required = self.required
        else:
            try:
                result.desc = self._desc
            except AttributeError:
                pass

            try:
                result.label = self._label
            except AttributeError:
                pass

            try:
                result.required = self._required
            except AttributeError:
                pass

        return result


class BoundSingleValueField(BoundField):
    """
    A bound field which has only a single value at any time. Only the first
    value is parsed when loading data from a :class:`~.Field` XSO. When writing
    data to a :class:`~.Field` XSO, :data:`None` is treated as the absence of
    any value; every other value is serialised through the
    :attr:`~.AbstractField.type_` of the field.

    .. seealso::

       :class:`BoundField`
          for a description of the arguments.

    This bound field is used by :class:`TextSingle`, :class:`TextPrivate` and
    :class:`JIDSingle`.

    .. autoattribute:: value
    """

    @property
    def value(self):
        """
        The current value of the field. If no value is set when this attribute
        is accessed for reading, the :meth:`default` of the field is invoked
        and the result is set and returned as value.

        Only values which pass through :meth:`~.AbstractCDataType.coerce` of
        the :attr:`~.AbstractField.type_` of the field can be set. To
        revert the :attr:`value` to its default, use the ``del`` operator.
        """
        try:
            return self._value
        except AttributeError:
            # call through to field
            self._value = self._field.default()
            return self._value

    @value.setter
    def value(self, value):
        self._value = self._field.type_.coerce(value)

    @value.deleter
    def value(self):
        try:
            del self._value
        except AttributeError:
            pass

    def load(self, field_xso):
        try:
            value = field_xso.values[0]
        except IndexError:
            value = self._field.default()
        else:
            value = self._field.type_.parse(value)

        self._value = value

        super().load(field_xso)

    def render(self, **kwargs):
        result = super().render(**kwargs)

        try:
            value = self._value
        except AttributeError:
            value = self._field.default()

        if value is None:
            return result

        result.values[:] = [
            self.field.type_.format(value)
        ]

        return result


class BoundMultiValueField(BoundField):
    """
    A bound field which can have multiple values.

    .. seealso::

       :class:`BoundField`
          for a description of the arguments.

    This bound field is used by :class:`TextMulti` and :class:`JIDMulti`.

    .. autoattribute:: value
    """

    @property
    def value(self):
        """
        A tuple of values. This attribute can be set with any iterable; the
        iterable is then evaluated into a tuple and stored at the bound field.

        Whenever values are written to this attribute, they are passed through
        the :meth:`~.AbstractCDataType.coerce` method of the
        :attr:`~.AbstractField.type_` of the field. To revert the
        :attr:`value` to its default, use the ``del`` operator.
        """
        try:
            return self._value
        except AttributeError:
            self.value = self._field.default()
            return self._value

    @value.setter
    def value(self, values):
        coerce = self._field.type_.coerce
        self._value = tuple(
            coerce(v)
            for v in values
        )

    @value.deleter
    def value(self):
        try:
            del self._value
        except AttributeError:
            pass

    def load(self, field_xso):
        self._value = tuple(
            self._field.type_.parse(v)
            for v in field_xso.values
        )

        super().load(field_xso)

    def render(self, **kwargs):
        result = super().render(**kwargs)
        result.values[:] = (
            self.field.type_.format(v)
            for v in self._value
        )
        return result


class BoundOptionsField(BoundField):
    """
    This is an intermediate base class used to implement bound fields for
    fields which have options from which one or more values must be chosen.

    .. seealso::

       :class:`BoundField`
          for a description of the arguments.

    When the field is loaded from a :class:`~.Field` XSO, the options are also
    loaded from there and thus shadow the options defined at the `field`. This
    may come to a surprise of code expecting a specific set of options.

    Subclass overview:

    .. autosummary::

       BoundSelectField
       BoundMultiSelectField

    .. autoattribute:: options
    """

    @property
    def options(self):
        """
        This is a :class:`collections.OrderedDict` which maps option keys to
        their labels. The keys are used as the values of the field; the labels
        are human-readable text for display.

        This attribute can be written with any object which is compatible with
        the dict-constructor. The order is preserved if a sequence of key-value
        pairs is used.

        When writing the attribute, the keys are checked against the
        :meth:`~.AbstractCDataType.coerce` method of the
        :attr:`~.AbstractField.type_` of the field. To make the :attr:`options`
        attribute identical to the :attr:`~.AbstractField.options` attribute,
        use the ``del`` operator.

        .. warning::

           This attribute is mutable, however, mutating it directly may have
           unexpected side effects:

           * If the attribute has not been set before, you will actually be
             mutating the :class:`~.AbstractChoiceField.options` attributes
             value.

             This may be changed in the future by copying more eagerly.

           * The type checking cannot take place when keys are added by direct
             mutation of the dictionary. This means that errors will be delayed
             until the actual serialisation of the data form, which may be a
             confusing thing to debug.

           Relying on the above behaviour or any other behaviour induced by
           directly mutating the value returned by this attribute is **not
           recommended**. Changes to this behaviour are *not* considered
           breaking changes and will be done without the usual deprecation.
        """
        try:
            return self._options
        except AttributeError:
            return self.field.options

    @options.setter
    def options(self, value):
        iterator = (value.items()
                    if isinstance(value, collections.abc.Mapping)
                    else value)
        self._options = collections.OrderedDict(
            (self.field.type_.coerce(k), v)
            for k, v in iterator
        )

    @options.deleter
    def options(self):
        try:
            del self._options
        except AttributeError:
            pass

    def load(self, field_xso):
        self._options = collections.OrderedDict(
            field_xso.options
        )
        super().load(field_xso)

    def render(self, **kwargs):
        format_ = self._field.type_.format
        field_xso = super().render(**kwargs)
        field_xso.options.update(
            (format_(k), v)
            for k, v in self.options.items()
        )
        return field_xso


class BoundSelectField(BoundOptionsField):
    """
    Bound field carrying one value out of a set of options.

    .. seealso::

       :class:`BoundField`
          for a description of the arguments.
       :attr:`BoundOptionsField.options`
          for semantics and behaviour of the ``options`` attribute

    .. autoattribute:: value

    """

    @property
    def value(self):
        """
        The current value of the field. If no value is set when this attribute
        is accessed for reading, the :meth:`default` of the field is invoked
        and the result is set and returned as value.

        Only values contained in the :attr:`~.BoundOptionsField.options` can be
        set, other values are rejected with a :class:`ValueError`. To revert
        the value to the default value specified in the descriptor, use the
        ``del`` operator.
        """
        try:
            return self._value
        except AttributeError:
            self._value = self.field.default()
            return self._value

    @value.setter
    def value(self, value):
        options = self.options
        if value not in options:
            raise ValueError("{!r} not in field options: {!r}".format(
                value,
                tuple(options.keys()),
            ))

        self._value = value

    @value.deleter
    def value(self):
        try:
            del self._value
        except AttributeError:
            pass

    def load(self, field_xso):
        try:
            value = field_xso.values[0]
        except IndexError:
            try:
                del self._value
            except AttributeError:
                pass
        else:
            self._value = self.field.type_.parse(value)

        super().load(field_xso)

    def render(self, **kwargs):
        format_ = self._field.type_.format
        field_xso = super().render(**kwargs)
        value = self.value
        if value is not None:
            field_xso.values[:] = [format_(value)]
        return field_xso


class BoundMultiSelectField(BoundOptionsField):
    """
    Bound field carrying a subset of values out of a set of options.

    .. seealso::

       :class:`BoundField`
          for a description of the arguments.
       :attr:`BoundOptionsField.options`
          for semantics and behaviour of the ``options`` attribute

    .. autoattribute:: value
    """

    @property
    def value(self):
        """
        A :class:`frozenset` whose elements are a subset of the keys of the
        :attr:`~.BoundOptionsField.options` mapping.

        This value can be written with any iterable; the iterable is then
        evaluated into a :class:`frozenset`. If it contains any value not
        contained in the set of keys of options, the attribute is not written
        and :class:`ValueError` is raised.

        To revert the value to the default specified by the field descriptor,
        use the ``del`` operator.
        """
        try:
            return self._value
        except AttributeError:
            self.value = self.field.default()
            return self._value

    @value.setter
    def value(self, values):
        new_values = frozenset(values)
        options = set(self.options.keys())
        invalid = new_values - options
        if invalid:
            raise ValueError(
                "{!r} not in field options: {!r}".format(
                    next(iter(invalid)),
                    tuple(self.options.keys())
                )
            )

        self._value = new_values

    @value.deleter
    def value(self):
        try:
            del self._value
        except AttributeError:
            pass

    def load(self, field_xso):
        self._value = frozenset(
            self.field.type_.parse(value)
            for value in field_xso.values
        )
        super().load(field_xso)

    def render(self, **kwargs):
        format_ = self.field.type_.format

        result = super().render(**kwargs)
        result.values[:] = [
            format_(value)
            for value in self.value
        ]
        return result


class AbstractDescriptor(metaclass=abc.ABCMeta):
    attribute_name = None
    root_class = None

    @abc.abstractmethod
    def descriptor_keys(self):
        """
        Return an iterator with the descriptor keys for this descriptor. The
        keys will be added to the :attr:`DescriptorClass.DESCRIPTOR_KEYS`
        mapping, pointing to the descriptor.

        Duplicate keys will lead to a :class:`TypeError` being raised during
        declaration of the class.
        """


class AbstractField(AbstractDescriptor):
    """
    Abstract base class to implement field descriptor classes.

    :param var: The field ``var`` attribute this descriptor is supposed to
                represent.
    :type var: :class:`str`
    :param type_: The type of the data, defaults to :class:`~.xso.String`.
    :type type_: :class:`~.xso.AbstractCDataType`
    :param required: Flag to indicate that the field is required.
    :type required: :class:`bool`
    :param desc: Description text for the field, e.g. for tool-tips.
    :type desc: :class:`str`, without newlines
    :param label: Short, human-readable label for the field
    :type label: :class:`str`

    The arguments are used to initialise the respective attributes. Details on
    the semantics can be found in the respective documentation pieces below.

    .. autoattribute:: desc

    .. attribute:: label

       Represents the label flag as specified per :xep:`4`.

       The value of this attribute is used when forms are generated locally.
       When forms are received from remote peers and :class:`~.Form` instances
       are constructed from that data, this attribute is not used when
       rendering a reply or when the value is accessed through the bound field.

        .. seealso::

           :attr:`~.Field.label`
              for details on the semantics of this attribute

    .. attribute:: required

       Represents the required flag as specified per :xep:`4`.

       The value of this attribute is used when forms are generated locally.
       When forms are received from remote peers and :class:`~.Form` instances
       are constructed from that data, this attribute is not used when
       rendering a reply or when the value is accessed through the bound field.

        .. seealso::

           :attr:`~.Field.required`
              for details on the semantics of this attribute

    .. autoattribute:: var

    .. automethod:: create_bound

    .. automethod:: default

    .. automethod:: make_bound
    """

    def __init__(self, var, type_, *, required=False, desc=None, label=None):
        super().__init__()
        self._var = var
        self.required = required
        self.desc = desc
        self.label = label
        self._type = type_
        self.__doc__ = FIELD_DOCSTRING_TEMPLATE.format(
            field_type=self.FIELD_TYPE,
            var=self.var,
            desc=self.desc,
            label=self.label,
        )

    def descriptor_keys(self):
        yield descriptor_ns, self._var

    @property
    def type_(self):
        """
        :class:`.AbstractCDataType` instance used to parse, validate and
        format the value(s) of this field.

        The type of a field cannot be changed after its initialisation.
        """
        return self._type

    @property
    def desc(self):
        """
        Represents the description as specified per :xep:`4`.

        The value of this attribute is used when forms are generated locally.
        When forms are received from remote peers and :class:`~.Form` instances
        are constructed from that data, this attribute is not used when
        rendering a reply or when the value is accessed through the bound
        field.

        .. seealso::

           :attr:`~.Field.desc`
              for details on the semantics of this attribute
        """

        return self._desc

    @desc.setter
    def desc(self, value):
        if value is not None and any(ch == "\r" or ch == "\n" for ch in value):
            raise ValueError("desc must not contain newlines")
        self._desc = value

    @desc.deleter
    def desc(self):
        self._desc = None

    @property
    def var(self):
        """
        Represents the field ID as specified per :xep:`4`.

        The value of this attribute is used to match fields when instantiating
        :class:`~.Form` classes from :class:`~.Data` XSOs.

        .. seealso::

           :attr:`~.Field.var`
              for details on the semantics of this attribute
        """
        return self._var

    @abc.abstractmethod
    def default(self):
        """
        Create and return a default value for this field.

        This must be implemented by subclasses.
        """

    @abc.abstractmethod
    def create_bound(self, for_instance):
        """
        Create a :ref:`bound field class <api-aioxmpp.forms-bound-fields>`
        instance for this field for the given form object and return it.

        :param for_instance: The form instance to which the bound field should
                             be bound.

        This method must be re-implemented by subclasses.

        .. seealso::

           :meth:`make_bound`
              creates (using this method) or returns an existing bound field
              for a given form instance.

        """

    def make_bound(self, for_instance):
        """
        Create a new :ref:`bound field class <api-aioxmpp.forms-bound-fields>`
        or return an existing one for the given form object.

        :param for_instance: The form instance to which the bound field should
                             be bound.

        If no bound field can be found on the given `for_instance` for this
        field, a new one is created using :meth:`create_bound`, stored at the
        instance and returned. Otherwise, the existing instance is returned.

        .. seealso::

           :meth:`create_bound`
              creates a new bound field for the given form instance (without
              storing it anywhere).
        """

        try:
            return for_instance._descriptor_data[self]
        except KeyError:
            bound = self.create_bound(for_instance)
            for_instance._descriptor_data[self] = bound
            return bound

    def __get__(self, instance, type_):
        if instance is None:
            return self
        return self.make_bound(instance)


class TextSingle(AbstractField):
    """
    Represent a ``"text-single"`` input with the given `var`.

    :param default: A default value to initialise the field.

    .. seealso::

       :class:`~.fields.BoundSingleValueField`
          is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
          by fields of this type.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `type_`, `required`, `desc` and
          `label` arguments.

    """
    FIELD_TYPE = forms_xso.FieldType.TEXT_SINGLE

    def __init__(self, var, type_=xso.String(), *,
                 default=None,
                 **kwargs):
        super().__init__(var, type_, **kwargs)
        self._default = default

    def default(self):
        return self._default

    def create_bound(self, for_instance):
        return BoundSingleValueField(
            self,
            for_instance,
        )


class JIDSingle(AbstractField):
    """
    Represent a ``"jid-single"`` input with the given `var`.

    :param default: A default value to initialise the field.

    .. seealso::

       :class:`~.fields.BoundSingleValueField`
          is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
          by fields of this type.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `required`, `desc` and
          `label` arguments.

    """
    FIELD_TYPE = forms_xso.FieldType.JID_SINGLE

    def __init__(self, var, *, default=None, **kwargs):
        super().__init__(var, type_=xso.JID(), **kwargs)
        self._default = default

    def default(self):
        return self._default

    def create_bound(self, for_instance):
        return BoundSingleValueField(
            self,
            for_instance,
        )


class Boolean(AbstractField):
    """
    Represent a ``"boolean"`` input with the given `var`.

    :param default: A default value to initialise the field.

    .. seealso::

       :class:`~.fields.BoundSingleValueField`
          is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
          by fields of this type.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `required`, `desc` and
          `label` arguments.

    """

    FIELD_TYPE = forms_xso.FieldType.BOOLEAN

    def __init__(self, var, *, default=False, **kwargs):
        super().__init__(var, xso.Bool(), **kwargs)
        self._default = default

    def default(self):
        return self._default

    def create_bound(self, for_instance):
        return BoundSingleValueField(
            self,
            for_instance,
        )


class TextPrivate(TextSingle):
    """
    Represent a ``"text-private"`` input with the given `var`.

    :param default: A default value to initialise the field.

    .. seealso::

       :class:`~.fields.BoundSingleValueField`
          is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
          by fields of this type.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `type_`, `required`, `desc` and
          `label` arguments.

    """

    FIELD_TYPE = forms_xso.FieldType.TEXT_PRIVATE


class TextMulti(AbstractField):
    """
    Represent a ``"text-multi"`` input with the given `var`.

    :param default: A default value to initialise the field.
    :type default: :class:`tuple`

    .. seealso::

       :class:`~.fields.BoundMultiValueField`
          is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
          by fields of this type.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `type_`, `required`, `desc` and
          `label` arguments.

    """

    FIELD_TYPE = forms_xso.FieldType.TEXT_MULTI

    def __init__(self, var, type_=xso.String(), *,
                 default=(), **kwargs):
        super().__init__(var, type_, **kwargs)
        self._default = default

    def create_bound(self, for_instance):
        return BoundMultiValueField(self, for_instance)

    def default(self):
        return self._default


class JIDMulti(AbstractField):
    """
    Represent a ``"jid-multi"`` input with the given `var`.

    :param default: A default value to initialise the field.
    :type default: :class:`tuple`

    .. seealso::

       :class:`~.fields.BoundMultiValueField`
          is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
          by fields of this type.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `type_`, `required`, `desc` and
          `label` arguments.

    """

    FIELD_TYPE = forms_xso.FieldType.JID_MULTI

    def __init__(self, var, *, default=(), **kwargs):
        super().__init__(var, xso.JID(), **kwargs)
        self._default = default

    def create_bound(self, for_instance):
        return BoundMultiValueField(self, for_instance)

    def default(self):
        return self._default


class AbstractChoiceField(AbstractField):
    """
    Abstract base class to implement field descriptor classes using options.

    :param type_: Type used for the option keys.
    :type type_: :class:`~.xso.AbstractCDataType`
    :param options: A sequence of key-value pairs or a mapping object
                    representing the options available.
    :type options: sequence of pairs or mapping

    The keys of the `options` mapping (or the first elements in the pairs in
    the sequence of pairs) must be compatible with `type_`, in the sense that
    must pass through :meth:`~.xso.AbstractCDataType.coerce` (this is enforced
    when the field is instantiated).

    Fields using this base class:

    .. autosummary::

       aioxmpp.forms.ListSingle
       aioxmpp.forms.ListMulti

    .. seealso::

       :class:`~.fields.BoundOptionsField`
          is an abstract base class to implement :ref:`bound field classes
          <api-aioxmpp.forms-bound-fields>` for fields inheriting from this
          class.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `required`, `desc` and `label`
          arguments.

    """

    def __init__(self, var, *,
                 type_=xso.String(),
                 options=[],
                 **kwargs):
        super().__init__(var, type_, **kwargs)
        iterator = (options.items()
                    if isinstance(options, collections.abc.Mapping)
                    else options)
        self.options = collections.OrderedDict(
            (type_.coerce(k), v)
            for k, v in iterator
        )
        self._type = type_

    @property
    def type_(self):
        return self._type


class ListSingle(AbstractChoiceField):
    """
    Represent a ``"list-single"`` input with the given `var`.

    :param default: A default value to initialise the field. This must be a
                    member of the `options`.

    .. seealso::

       :class:`~.fields.BoundMultiValueField`
          is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
          by fields of this type.

       :class:`~.fields.AbstractChoiceField`
          for documentation on the `options` argument.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `type_`, `required`, `desc` and
          `label` arguments.

    """

    FIELD_TYPE = forms_xso.FieldType.LIST_SINGLE

    def __init__(self, var, *, default=None, **kwargs):
        super().__init__(var, **kwargs)
        if default is not None and default not in self.options:
            raise ValueError("invalid default: not in options")
        self._default = default

    def create_bound(self, for_instance):
        return BoundSelectField(self, for_instance)

    def default(self):
        return self._default


class ListMulti(AbstractChoiceField):
    """
    Represent a ``"list-multi"`` input with the given `var`.

    :param default: An iterable of `options` keys
    :type default: iterable

    `default` is evaluated into a :class:`frozenset` and all elements must be
    keys of the `options` mapping argument.

    .. seealso::

       :class:`~.fields.BoundMultiValueField`
          is the :ref:`bound field class <api-aioxmpp.forms-bound-fields>` used
          by fields of this type.

       :class:`~.fields.AbstractChoiceField`
          for documentation on the `options` argument.

       :class:`~.fields.AbstractField`
          for documentation on the `var`, `type_`, `required`, `desc` and
          `label` arguments.

    """

    FIELD_TYPE = forms_xso.FieldType.LIST_MULTI

    def __init__(self, var, *, default=frozenset(), **kwargs):
        super().__init__(var, **kwargs)
        self._default = frozenset(default)
        if any(value not in self.options for value in self._default):
            raise ValueError(
                "invalid default: not in options"
            )

    def create_bound(self, for_instance):
        return BoundMultiSelectField(self, for_instance)

    def default(self):
        return self._default