Mercurial > hgrepos > Python > apps > py-cutils

annotate cutils/util/glob.py @ 296:ca293f708cb4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Begin some preparation for handling glob-style patterns in treeview. Needed to implement inclusions and exclusions.
author Franz Glasner <fzglas.hg@dom66.de>
date Sun, 02 Mar 2025 22:54:40 +0100
parents
children 141a3aa0b403
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
296
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
1 # -*- coding: utf-8 -*-
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
2 # :-
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
3 # :Copyright: (c) 2020-2025 Franz Glasner
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
4 # :License: BSD-3-Clause
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
5 # :-
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
6 r"""Glob handling.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
7
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
8 .. seealso::
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
9 - https://docs.oracle.com/javase/8/docs/api/java/nio/file/FileSystem.html#getPathMatcher-java.lang.String-
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
10 - https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
11
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
12 The following rules are used to interpret glob patterns:
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
13
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
14 - The ``*`` character matches zero or more characters of a name
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
15 component without crossing directory boundaries.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
16
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
17 - The ``**`` characters matches zero or more characters crossing
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
18 directory boundaries.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
19
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
20 - The ``?`` character matches exactly one character of a name component.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
21
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
22 - The backslash character (``\``) is used to escape characters that
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
23 would otherwise be interpreted as special characters. The expression
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
24 ``\\`` matches a single backslash and ``\{`` matches a left brace for
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
25 example.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
26
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
27 - The ``[ ]`` characters are a bracket expression that match a single
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
28 character of a name component out of a set of characters. For example,
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
29 ``[abc]`` matches "``a``", "``b``", or "``c``". The hyphen (``-``) may
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
30 be used to specify a range so ``[a-z]`` specifies a range that matches
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
31 from "``a``" to "``z``" (inclusive). These forms can be mixed so
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
32 ``[abce-g]`` matches "``a``", "``b``", "``c``", "``ey", "``f``" or
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
33 "``g``".
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
34
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
35 If the character after the ``[`` is a ``!`` then it is used for negation
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
36 so ``[!a-c]`` matches any character except "``a``", "``b``", or "``c``".
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
37
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
38 Within a bracket expression the ``*``, ``?`` and ``\`` characters match
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
39 themselves.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
40
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
41 The ``-`` character matches itself if it is the first or last character
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
42 within the brackets, or the first or last character after the ``!`` if
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
43 negating.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
44
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
45 Also, the ``]`` character matches itself if it is the first character
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
46 within the brackets, or the first character after the ``!`` if negating.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
47
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
48 - The ``{ }`` characters are a group of subpatterns, where the group matches
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
49 if any subpattern in the group matches.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
50
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
51 The ``,`` character is used to separate the subpatterns. Groups cannot be
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
52 nested.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
53
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
54 - Leading period/dot characters in file name are treated as regular characters
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
55 in match operations. For example, the ``*`` glob pattern matches file name
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
56 ``.login``.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
57
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
58 - All other characters match themselves.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
59
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
60 """
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
61
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
62 from __future__ import print_function, absolute_import
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
63
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
64
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
65 __all__ = ["glob_to_regexp"]
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
66
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
67
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
68 from . import PY2
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
69
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
70
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
71 def glob_to_regexp(g):
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
72 pass
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
73
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
74
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
75 class CharIter(object):
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
76
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
77 """Iterator over byte or unicode strings with peek support.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
78
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
79 On Python3 always yields an octet of :class:`bytes` instead of
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
80 :class:`int`s if the iterator iterates over :class:`bytes`.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
81
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
82 """
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
83
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
84 __slots__ = ("_it", "_nch")
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
85
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
86 def __init__(self, w):
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
87 self._nch = None
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
88 if PY2:
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
89 if isinstance(w, (bytes, unicode)): # noqa: F821 undefined name
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
90 self._it = iter(w)
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
91 else:
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
92 self._it = w
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
93 else:
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
94 if isinstance(w, (bytes, str)):
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
95 self._it = iter(w)
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
96 else:
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
97 self._it = w
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
98
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
99 def __iter__(self):
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
100 return self
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
101
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
102 def __next__(self):
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
103 if self._nch is not None:
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
104 c = self._nch
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
105 self._nch = None
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
106 return c
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
107 c = next(self._it)
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
108 return bytes((c,)) if isinstance(c, int) else c
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
109
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
110 if PY2:
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
111 next = __next__
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
112
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
113 def peek(self):
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
114 """Peek the next character.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
115
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
116 Return `None` if the iterator is exhausted.
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
117
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
118 """
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
119 if self._nch is not None:
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
120 return self._nch
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
121 self._nch = next(self._it, None)
ca293f708cb4 Begin some preparation for handling glob-style patterns in treeview.
Franz Glasner <fzglas.hg@dom66.de>
parents:
diff changeset
122 return self._nch