# Source code for aioxmpp.forms.xso

    ########################################################################
    # File name: xso.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 collections
    import enum

    import aioxmpp
    import aioxmpp.xso as xso

    from aioxmpp.utils import namespaces

    namespaces.xep0004_data = "jabber:x:data"

    class Value(xso.XSO):
        TAG = (namespaces.xep0004_data, "value")

        value = xso.Text(default="")

    class ValueElement(xso.AbstractElementType):
        def unpack(self, item):
            return item.value

        def pack(self, value):
            v = Value()
            v.value = value
            return v

        def get_xso_types(self):
            return [Value]

    class Option(xso.XSO):
        TAG = (namespaces.xep0004_data, "option")

        label = xso.Attr(
            tag="label",
            default=None,
        )

        value = xso.ChildText(
            (namespaces.xep0004_data, "value"),
            default=None,
        )

        def validate(self):
            if self.value is None:
                raise ValueError("option is missing a value")

    class OptionElement(xso.AbstractElementType):
        def unpack(self, item):
            return (item.value, item.label)

        def pack(self, value):
            value, label = value
            o = Option()
            o.value = value
            o.label = label
            return o

        def get_xso_types(self):
            return [Option]

    class FieldType(enum.Enum):
        """
        Enumeration containing the field types defined in :xep:`4`.

        .. seealso::

           :attr:`Field.values`
              for important information regarding typing, restrictions, validation
              and constraints of values in that attribute.

        Each type has the following attributes and methods:

        .. automethod:: allow_upcast

        .. autoattribute:: has_options

        .. autoattribute:: is_multivalued

        Quotations in the following attribute descriptions are from said XEP.

        .. attribute:: BOOLEAN

           The ``"boolean"`` field:

              The field enables an entity to gather or provide an either-or choice
              between two options. The default value is "false".

           The :attr:`Field.values` sequence should contain zero or one elements.
           If it contains an element, it must be ``"0"``, ``"1"``, ``"false"``, or
           ``"true"``, in accordance with the XML Schema documents.

        .. attribute:: FIXED

           The ``"fixed"`` field:

              The field is intended for data description (e.g., human-readable text
              such as "section" headers) rather than data gathering or provision.
              The <value/> child SHOULD NOT contain newlines (the ``\\n`` and
              ``\\r`` characters); instead an application SHOULD generate multiple
              fixed fields, each with one <value/> child.

           As such, the :attr:`Field.values` sequence should contain exactly one
           element. :attr:`Field.desc`, :attr:`Field.label`, :attr:`Field.options`
           and :attr:`Field.var` should be set to :data:`None` or empty containers.

        .. attribute:: HIDDEN

           The ``"hidden"`` field:

              The field is not shown to the form-submitting entity, but instead is
              returned with the form. The form-submitting entity SHOULD NOT modify
              the value of a hidden field, but MAY do so if such behavior is
              defined for the "using protocol".

           This type is commonly used for the ``var="FORM_TYPE"`` field, as
           specified in :xep:`68`.

        .. attribute:: JID_MULTI

           The ``"jid-multi"`` field:

              The field enables an entity to gather or provide multiple Jabber IDs.
              Each provided JID SHOULD be unique (as determined by comparison that
              includes application of the Nodeprep, Nameprep, and Resourceprep
              profiles of Stringprep as specified in XMPP Core), and duplicate JIDs
              MUST be ignored.

           As such, the :attr:`Field.values` sequence should contain zero or more
           strings representing Jabber IDs. :attr:`Field.options` should be empty.

        .. attribute:: JID_SINGLE

           The ``"jid-single"`` field:

              The field enables an entity to gather or provide a single Jabber ID.

           As such, the :attr:`Field.values` sequence should contain zero or one
           string representing a Jabber ID. :attr:`Field.options` should be empty.

        .. attribute:: LIST_MULTI

           The ``"list-multi"`` field:

              The field enables an entity to gather or provide one or more options
              from among many. A form-submitting entity chooses one or more items
              from among the options presented by the form-processing entity and
              MUST NOT insert new options. The form-submitting entity MUST NOT
              modify the order of items as received from the form-processing
              entity, since the order of items MAY be significant.

           Thus, :attr:`Field.values` should contain a subset of the keys of the
           :class:`Field.options` dictionary.

        .. attribute:: LIST_SINGLE

           The ``"list-single"`` field:

              The field enables an entity to gather or provide one option from
              among many. A form-submitting entity chooses one item from among the
              options presented by the form-processing entity and MUST NOT insert
              new options.

           Thus, :attr:`Field.values` should contain a zero or one of the keys of
           the :class:`Field.options` dictionary.

        .. attribute:: TEXT_MULTI

           The ``"text-multi"`` field:

              The field enables an entity to gather or provide multiple lines of
              text.

           Each string in the :attr:`Field.values` attribute should be a single
           line of text. Newlines are not allowed in data forms fields (due to the
           ambiguity between ``\\r`` and ``\\n`` and combinations thereof), which
           is why the text is split on the line endings.

        .. attribute:: TEXT_PRIVATE

           The ``"text-private"`` field:

              The field enables an entity to gather or provide a single line or
              word of text, which shall be obscured in an interface (e.g., with
              multiple instances of the asterisk character).

           The :attr:`Field.values` attribute should contain zero or one string
           without any newlines.

        .. attribute:: TEXT_SINGLE

           The ``"text-single"`` field:

              The field enables an entity to gather or provide a single line or
              word of text, which may be shown in an interface. This field type is
              the default and MUST be assumed if a form-submitting entity receives
              a field type it does not understand.

           The :attr:`Field.values` attribute should contain zero or one string
           without any newlines.

        """

        FIXED = "fixed"
        HIDDEN = "hidden"
        BOOLEAN = "boolean"
        TEXT_SINGLE = "text-single"
        TEXT_MULTI = "text-multi"
        TEXT_PRIVATE = "text-private"
        LIST_SINGLE = "list-single"
        LIST_MULTI = "list-multi"
        JID_SINGLE = "jid-single"
        JID_MULTI = "jid-multi"

        @property
        def has_options(self):
            """
            true for the ``list-`` field types, false otherwise.
            """
            return self.value.startswith("list-")

        @property
        def is_multivalued(self):
            """
            true for the ``-multi`` field types, false otherwise.
            """
            return self.value.endswith("-multi")

        def allow_upcast(self, to):
            """
            Return true if the field type may be upcast to the other field type
            `to`.

            This relation specifies when it is safe to transfer data from this
            field type to the given other field type `to`.

            This is the case if any of the following holds true:

            * `to` is equal to this type
            * this type is :attr:`TEXT_SINGLE` and `to` is :attr:`TEXT_PRIVATE`
            """

            if self == to:
                return True
            if self == FieldType.TEXT_SINGLE and to == FieldType.TEXT_PRIVATE:
                return True
            return False

    class Field(xso.XSO):
        """
        Represent a single field in a Data Form.

        :param type_: Field type, must be one of the valid field types specified in
                      :xep:`4`.
        :type type_: :class:`FieldType`
        :param options: A mapping of values to labels defining the options in a
                        ``list-*`` field.
        :type options: :class:`dict` mapping :class:`str` to :class:`str`
        :param values: A sequence of values currently given for the field. Having
                       more than one value is only valid in ``*-multi`` fields.
        :type values: :class:`list` of :class:`str`
        :param desc: Description which can be shown in a tool-tip or similar,
                     without newlines.
        :type desc: :class:`str` or :data:`None`
        :param label: Human-readable label to be shown next to the field input
        :type label: :class:`str` or :data:`None`
        :param required: Flag to indicate that the field is required
        :type required: :class:`bool`
        :param var: "ID" identifying the field uniquely inside the form. Only
                    required for fields carrying a meaning (thus, not for
                    ``fixed``).
        :type var: :class:`str` or :data:`None`

        The semantics of a :class:`Field` are different depending on where it
        occurs: in a :class:`Data`, it is a form field to be filled in, in a
        :class:`Item` it is a cell of a row and in a :class:`Reported` it
        represents a column header.

        .. attribute:: required

           A boolean flag indicating whether the field is required.

           If true, the XML serialisation will contain the corresponding
           ``<required/>`` tag.

        .. attribute:: desc

           Single line of description for the field. This attribute represents the
           ``<desc/>`` element from :xep:`4`.

        .. attribute:: values

           A sequence of strings representing the ``<value/>`` elements of the
           field, one string for each value.

           .. note::

              Since the requirements on the sequence of strings in :attr:`values`
              change depending on the :attr:`type_` attribute, validation and type
              conversion on assignment is very lax. The attribute accepts all
              sequences of strings, even if the field is for example a
              :attr:`FieldType.BOOLEAN` field, which allows for at most one string
              of a well-defined format (see the documentation there for the
              details).

              This makes it easy to inadvertendly generate invalid forms, which is
              why you should be using :class:`Form` subclasses when accessing forms
              from within normal code and some other, generic mechanism taking care
              of these details when showing forms in a UI framework to users. Note
              that devising such a mechanism is out of scope for :mod:`aioxmpp`, as
              every UI framework has different requirements.

        .. attribute:: options

           A dictionary mapping values to human-readable labels, representing the
           ``<option/>`` elements of the field.

        .. attribute:: var

           The uniquely identifying string of the (valued, that is,
           non-:attr:`FieldType.FIXED` field). Represents the ``var`` attribute of
           the field.

        .. attribute:: type_

           The type of the field. The :attr:`type_` must be a :class:`FieldType`
           enumeration value and determines restrictions and constraints on other
           attributes. See the :class:`FieldType` enumeration and :xep:`4` for
           details.

        .. attribute:: label

           The human-readable label for the field, representing the ``label``
           attribute of the field. May be :data:`None` if the label is omitted.

        """

        TAG = (namespaces.xep0004_data, "field")

        required = xso.ChildFlag(
            (namespaces.xep0004_data, "required"),
        )

        desc = xso.ChildText(
            (namespaces.xep0004_data, "desc"),
            default=None
        )

        values = xso.ChildValueList(
            type_=ValueElement()
        )

        options = xso.ChildValueMap(
            type_=OptionElement(),
            mapping_type=collections.OrderedDict,
        )

        var = xso.Attr(
            (None, "var"),
            default=None
        )

        type_ = xso.Attr(
            (None, "type"),
            type_=xso.EnumCDataType(
                FieldType,
            ),
            default=None,
        )

        label = xso.Attr(
            (None, "label"),
            default=None
        )

        def __init__(self, *,
                     type_=FieldType.TEXT_SINGLE,
                     options={},
                     values=[],
                     desc=None,
                     label=None,
                     required=False,
                     var=None):
            super().__init__()
            self.type_ = type_
            self.options.update(options)
            self.values[:] = values
            self.desc = desc
            self.label = label
            self.required = required
            self.var = var

        def validate(self):
            super().validate()

            if self.type_ != FieldType.FIXED and not self.var:
                raise ValueError("missing attribute var")

            if self.type_ is not None:
                if not self.type_.has_options and self.options:
                    raise ValueError("unexpected option on non-list field")

                if not self.type_.is_multivalued and len(self.values) > 1:
                    raise ValueError("too many values on non-multi field")

            values_list = [opt for opt in self.options.values() if opt is not None]
            values_set = set(values_list)

            if len(values_list) != len(values_set):
                raise ValueError("duplicate option label in {}".format(
                    values_list
                ))

    class AbstractItem(xso.XSO):
        fields = xso.ChildList([Field])

    class Item(AbstractItem):
        """
        A single row in a report :class:`Data` object.

        .. attribute:: fields

           A sequence of :class:`Field` objects representing the cells of the row.
        """

        TAG = (namespaces.xep0004_data, "item")

    class Reported(AbstractItem):
        """
        The table heading of a report :class:`Data` object.

        .. attribute:: fields

           A sequence of :class:`Field` objects representing the columns of the
           report or table.

        """

        TAG = (namespaces.xep0004_data, "reported")

    class Instructions(xso.XSO):
        TAG = (namespaces.xep0004_data, "instructions")

        value = xso.Text(default="")

    class InstructionsElement(xso.AbstractElementType):
        def unpack(self, item):
            return item.value

        def pack(self, value):
            v = Instructions()
            v.value = value
            return v

        def get_xso_types(self):
            return [Instructions]

    class DataType(enum.Enum):
        """
        Enumeration containing the :class:`Data` types defined in :xep:`4`.

        Quotations in the following attribute descriptions are from :xep:`4`.

        .. attribute:: FORM

           The ``"form"`` type:

             The form-processing entity is asking the form-submitting entity to
             complete a form.

        .. attribute:: SUBMIT

           The ``"submit"`` type:

             The form-submitting entity is submitting data to the form-processing
             entity. The submission MAY include fields that were not provided in
             the empty form, but the form-processing entity MUST ignore any fields
             that it does not understand.

        .. attribute:: CANCEL

           The ``"cancel"`` type:

             The form-submitting entity has cancelled submission of data to the
             form-processing entity.

        .. attribute:: RESULT

           The ``"result"`` type:

             The form-processing entity is returning data (e.g., search results) to
             the form-submitting entity, or the data is a generic data set.
        """
        FORM = "form"
        SUBMIT = "submit"
        RESULT = "result"
        CANCEL = "cancel"

    class Data(AbstractItem):
        """
        A :xep:`4` ``x`` element, that is, a Data Form.

        :param type_: Initial value for the :attr:`type_` attribute.

        .. attribute:: type_

           The ``type`` attribute of the form, represented by one of the members of
           the :class:`DataType` enumeration.

        .. attribute:: title

           The (optional) title of the form. Either a :class:`str` or :data:`None`.

        .. attribute:: instructions

           A sequence of strings which represent the instructions elements on the
           form.

        .. attribute:: fields

           If the :class:`Data` is a form, this is a sequence of :class:`Field`
           elements which represent the fields to be filled in.

           This does not make sense on :attr:`.DataType.RESULT` typed objects.

        .. attribute:: items

           If the :class:`Data` is a table, this is a sequence of :class:`Item`
           instances which represent the table rows.

           This only makes sense on :attr:`.DataType.RESULT` typed objects.

        .. attribute:: reported

           If the :class:`Data` is a table, this is a :class:`Reported` object
           representing the table header.

           This only makes sense on :attr:`.DataType.RESULT` typed objects.

        .. automethod:: get_form_type
        """

        TAG = (namespaces.xep0004_data, "x")

        type_ = xso.Attr(
            "type",
            type_=xso.EnumCDataType(DataType)
        )

        title = xso.ChildText(
            (namespaces.xep0004_data, "title"),
            default=None,
        )

        instructions = xso.ChildValueList(
            type_=InstructionsElement()
        )

        items = xso.ChildList([Item])

        reported = xso.Child([Reported], required=False)

        def __init__(self, type_):
            super().__init__()
            self.type_ = type_

        def _validate_result(self):
            if self.fields:
                raise ValueError("field in report result")

            fieldvars = {field.var for field in self.reported.fields}

            if not fieldvars:
                raise ValueError("empty report header")

            for item in self.items:
                itemvars = {field.var for field in item.fields}
                if itemvars != fieldvars:
                    raise ValueError("field mismatch between row and header")

        def validate(self):
            super().validate()

            if (self.type_ != DataType.RESULT and
                    (self.reported is not None or self.items)):
                raise ValueError("report in non-result")

            if (self.type_ == DataType.RESULT and
                    (self.reported is not None or self.items)):
                self._validate_result()

        def get_form_type(self):
            """
            Extract the ``FORM_TYPE`` from the fields.

            :return: ``FORM_TYPE`` value or :data:`None`
            :rtype: :class:`str` or :data:`None`

            Return :data:`None` if no well-formed ``FORM_TYPE`` field is found in
            the list of fields.

            .. versionadded:: 0.8
            """

            for field in self.fields:
                if field.var == "FORM_TYPE" and field.type_ == FieldType.HIDDEN:
                    if len(field.values) != 1:
                        return None
                    return field.values[0]

    aioxmpp.Message.xep0004_data = xso.ChildList([Data])