# mercurial/interfaces/matcher - typing protocol for Matcher objects

#

# This software may be used and distributed according to the terms of the

# GNU General Public License version 2 or any later version.

from __future__ import annotations

import abc

from typing import (

    Callable,

    List,

    Optional,

    Protocol,

    Set,

    Union,

)

from ._basetypes import (

    HgPathT,

    UserMsgT,

)

class IMatcher(Protocol):

    @abc.abstractmethod

    def was_tampered_with_nonrec(self) -> bool:

        ...

    @abc.abstractmethod

    def was_tampered_with(self) -> bool:

        ...

    @abc.abstractmethod

    def __call__(self, fn: HgPathT) -> bool:

        ...

    # Callbacks related to how the matcher is used by dirstate.walk.

    # Subscribers to these events must monkeypatch the matcher object.

    @abc.abstractmethod

    def bad(self, f: HgPathT, msg: Optional[UserMsgT]) -> None:

        ...

    # If traversedir is set, it will be called when a directory discovered

    # by recursive traversal is visited.

    traversedir: Optional[Callable[[HgPathT], None]] = None

    @property

    @abc.abstractmethod

    def _files(self) -> List[HgPathT]:

        ...

    @abc.abstractmethod

    def files(self) -> List[HgPathT]:

        ...

    @property

    @abc.abstractmethod

    def _fileset(self) -> Set[HgPathT]:

        ...

    @abc.abstractmethod

    def exact(self, f: HgPathT) -> bool:

        """Returns True if f is in .files()."""

    @abc.abstractmethod

    def matchfn(self, f: HgPathT) -> bool:

        ...

    @abc.abstractmethod

    def visitdir(self, dir: HgPathT) -> Union[bool, bytes]:

        """Decides whether a directory should be visited based on whether it

        has potential matches in it or one of its subdirectories. This is

        based on the match's primary, included, and excluded patterns.

        Returns the string 'all' if the given directory and all subdirectories

        should be visited. Otherwise returns True or False indicating whether

        the given directory should be visited.

        """

    @abc.abstractmethod

    def visitchildrenset(self, dir: HgPathT) -> Union[Set[HgPathT], bytes]:

        """Decides whether a directory should be visited based on whether it

        has potential matches in it or one of its subdirectories, and

        potentially lists which subdirectories of that directory should be

        visited. This is based on the match's primary, included, and excluded

        patterns.

        This function is very similar to 'visitdir', and the following mapping

        can be applied:

             visitdir | visitchildrenlist

            ----------+-------------------

             False    | set()

             'all'    | 'all'

             True     | 'this' OR non-empty set of subdirs -or files- to visit

        Example:

          Assume matchers ['path:foo/bar', 'rootfilesin:qux'], we would return

          the following values (assuming the implementation of visitchildrenset

          is capable of recognizing this; some implementations are not).

          '' -> {'foo', 'qux'}

          'baz' -> set()

          'foo' -> {'bar'}

          # Ideally this would be 'all', but since the prefix nature of matchers

          # is applied to the entire matcher, we have to downgrade this to

          # 'this' due to the non-prefix 'rootfilesin'-kind matcher being mixed

          # in.

          'foo/bar' -> 'this'

          'qux' -> 'this'

        Important:

          Most matchers do not know if they're representing files or

          directories. They see ['path:dir/f'] and don't know whether 'f' is a

          file or a directory, so visitchildrenset('dir') for most matchers will

          return {'f'}, but if the matcher knows it's a file (like exactmatcher

          does), it may return 'this'. Do not rely on the return being a set

          indicating that there are no files in this dir to investigate (or

          equivalently that if there are files to investigate in 'dir' that it

          will always return 'this').

        """

    @abc.abstractmethod

    def always(self) -> bool:

        """Matcher will match everything and .files() will be empty --

        optimization might be possible."""

    @abc.abstractmethod

    def isexact(self) -> bool:

        """Matcher will match exactly the list of files in .files() --

        optimization might be possible."""

    @abc.abstractmethod

    def prefix(self) -> bool:

        """Matcher will match the paths in .files() recursively --

        optimization might be possible."""

    @abc.abstractmethod

    def anypats(self) -> bool:

        """None of .always(), .isexact(), and .prefix() is true --

        optimizations will be difficult."""