# Copyright (C) 2018-'25  Frank Sachsenheim
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero 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 Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

"""
*delb* allows querying of nodes with CSS selector and XPath expressions. CSS selectors
are converted to XPath expressions with a third-party library before evaluation and they
are only supported as far as their computed XPath equivalents are supported by *delb*'s
very own XPath implementation.

This implementation is not fully compliant with one of the W3C's XPath specifications.
It mostly covers the `XPath 1.0 specs`_, but focuses on the querying via path
expressions with simple constraints while it omits a broad employment of  computations
(that's what programming languages are for) and has therefore these intended deviations
from that standard:

- Default namespaces can be addressed in node and attribute names, by simply using no
  prefix.
- The attribute and namespace axes are not supported in location steps (see also below).
- In predicates only the attribute axis can be used in its abbreviated form (``@name``).
- Path evaluations within predicates are not available.
- Only these predicate functions are provided and tested:
    - ``boolean``
    - ``concat``
    - ``contains``
    - ``last``
    - ``not``
    - ``position``
    - ``starts-with``
    - ``text``
        - Behaves as if deployed as a single step location path that only tests for the
          node type *text*. Hence it returns the contents of the context node's first
          child node that is a text node or an empty string when there is none.
    - Please refrain from extension requests without a proper, concrete implementation
      proposal.

If you're accustomed to retrieve attribute values with XPath expressions, employ the
functionality of the higher programming language at hand like this:

    >>> [x.attributes["target"] for x in root.xpath("//foo")
    ...  if "target" in x.attributes ]  # doctest: +SKIP

Instead of:

    >>> root.xpath("//foo/@target")  # doctest: +SKIP

See :meth:`_delb.plugins.PluginManager.register_xpath_function` regarding the use of
custom functions.

.. _XPath 1.0 specs: https://www.w3.org/TR/1999/REC-xpath-19991116/
"""

from __future__ import annotations

from collections.abc import Collection, Iterable, Mapping, Sequence
from functools import lru_cache
from typing import TYPE_CHECKING, Final, Optional, overload

from cssselect import GenericTranslator

from _delb.names import Namespaces
from _delb.utils import _sort_nodes_in_document_order
from _delb.typing import TagNodeType, XMLNodeType
from _delb.xpath.ast import EvaluationContext
from _delb.xpath import functions  # noqa: F401
from _delb.xpath.parser import parse


if TYPE_CHECKING:
    from typing import Any

    from _delb.typing import Filter, NamespaceDeclarations


_css_translator: Final = GenericTranslator()


class QueryResults(Sequence[XMLNodeType]):
    """
    A container with the the results of a CSS selector or XPath query with some helpers
    for better readable Python expressions.
    """

    def __init__(self, results: Iterable[XMLNodeType]):
        self.__items: Final = tuple(results)

    def __eq__(self, other: Any):
        if not isinstance(other, Collection):
            raise TypeError

        return len(self.__items) == len(other) and all(x in other for x in self.__items)

    @overload
    def __getitem__(self, item: int) -> XMLNodeType: ...

    @overload
    def __getitem__(self, item: slice) -> Sequence[XMLNodeType]: ...

    def __getitem__(self, item: int | slice) -> XMLNodeType | Sequence[XMLNodeType]:
        return self.__items[item]

    def __len__(self) -> int:
        return len(self.__items)

    def __repr__(self):
        return str([repr(x) for x in self.__items])

    def as_list(self) -> list[XMLNodeType]:
        """The contained nodes as a new :class:`list`."""
        return list(self.__items)

    @property
    def as_tuple(self) -> tuple[XMLNodeType, ...]:
        """The contained nodes in a :class:`tuple`."""
        return self.__items

    def filtered_by(self, *filters: Filter) -> QueryResults:
        """
        Returns another :class:`QueryResults` instance that contains all nodes filtered
        by the provided :class:`delb.typing.Filter` s.
        """
        items: Sequence[XMLNodeType] = self.__items
        for filter in filters:
            items = [x for x in items if filter(x)]
        return self.__class__(items)

    @property
    def first(self) -> Optional[XMLNodeType]:
        """The first node from the results or :obj:`None` if there are none."""
        if len(self.__items):
            return self.__items[0]
        else:
            return None

    def in_document_order(self) -> QueryResults:
        """
        Returns another :class:`QueryResults` instance where the contained nodes are
        sorted in document order.
        """
        return QueryResults(_sort_nodes_in_document_order(self))

    @property
    def last(self) -> Optional[XMLNodeType]:
        """The last node from the results or :obj:`None` if there are none."""
        if len(self.__items):
            return self.__items[-1]
        else:
            return None

    @property
    def size(self) -> int:
        """The amount of contained nodes."""
        return len(self.__items)


# TODO make cachesize configurable via environment variable?
@lru_cache(maxsize=64)
def _css_to_xpath(expression: str) -> str:
    return _css_translator.css_to_xpath(expression, prefix="descendant::")


def evaluate(
    node: XMLNodeType,
    expression: str,
    namespaces: Optional[NamespaceDeclarations] = None,
) -> QueryResults:
    # global namespaces are guaranteed by the Namespaces implementation
    match namespaces:
        case None:
            if isinstance(node, TagNodeType):
                _namespaces = Namespaces({"": node.namespace})
            else:
                _namespaces = Namespaces({})
        case Namespaces():
            # b/c it would break fallback chains
            raise TypeError
        case Mapping():
            _namespaces = Namespaces(namespaces)
        case _:
            raise TypeError

    return QueryResults(parse(expression).evaluate(node=node, namespaces=_namespaces))


__all__ = (
    _css_to_xpath.__name__,  # type:ignore
    evaluate.__name__,
    parse.__name__,  # type: ignore
    EvaluationContext.__name__,
    QueryResults.__name__,
)
