1//
2// Glob.h
3//
4// Library: Foundation
5// Package: Filesystem
6// Module: Glob
7//
8// Definition of the Glob class.
9//
10// Copyright (c) 2004-2009, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef Foundation_Glob_INCLUDED
18#define Foundation_Glob_INCLUDED
19
20
21#include "Poco/Foundation.h"
22#include "Poco/TextIterator.h"
23#include <set>
24
25
26namespace Poco {
27
28
29class Path;
30
31
32class Foundation_API Glob
33 /// This class implements glob-style pattern matching
34 /// as known from Unix shells.
35 ///
36 /// In the pattern string, '*' matches any sequence of characters,
37 /// '?' matches any single character, [SET] matches any single character
38 /// in the specified set, [!SET] matches any character not in the
39 /// specified set.
40 ///
41 /// A set is composed of characters or ranges; a range looks like
42 /// character hyphen character (as in 0-9 or A-Z).
43 /// [0-9a-zA-Z_] is the set of characters allowed in C identifiers.
44 /// Any other character in the pattern must be matched exactly.
45 ///
46 /// To suppress the special syntactic significance of any of '[]*?!-\',
47 /// and match the character exactly, precede it with a backslash.
48 ///
49 /// All strings are assumed to be UTF-8 encoded.
50{
51public:
52 enum Options
53 /// Flags that modify the matching behavior.
54 {
55 GLOB_DEFAULT = 0x00, /// default behavior
56 GLOB_DOT_SPECIAL = 0x01, /// '*' and '?' do not match '.' at beginning of subject
57 GLOB_FOLLOW_SYMLINKS = 0x02, /// follow symbolic links
58 GLOB_CASELESS = 0x04, /// ignore case when comparing characters
59 GLOB_DIRS_ONLY = 0x80 /// only glob for directories (for internal use only)
60 };
61
62 Glob(const std::string& pattern, int options = 0);
63 /// Creates the Glob, using the given pattern. The pattern
64 /// must not be an empty string.
65 ///
66 /// If the GLOB_DOT_SPECIAL option is specified, '*' and '?' do
67 /// not match '.' at the beginning of a matched subject. This is useful for
68 /// making dot-files invisible in good old Unix-style.
69
70 ~Glob();
71 /// Destroys the Glob.
72
73 bool match(const std::string& subject);
74 /// Matches the given subject against the glob pattern.
75 /// Returns true if the subject matches the pattern, false
76 /// otherwise.
77
78 static void glob(const std::string& pathPattern, std::set<std::string>& files, int options = 0);
79 /// Creates a set of files that match the given pathPattern.
80 ///
81 /// The path may be give in either Unix or Windows syntax and
82 /// is automatically expanded by calling Path::expand().
83 ///
84 /// The pattern may contain wildcard expressions even in intermediate
85 /// directory names (e.g. /usr/include/*/*.h).
86 ///
87 /// Note that, for obvious reasons, escaping characters in a pattern
88 /// with a backslash does not work in Windows-style paths.
89 ///
90 /// Directories that for whatever reason cannot be traversed are
91 /// ignored.
92
93 static void glob(const char* pathPattern, std::set<std::string>& files, int options = 0);
94 /// Creates a set of files that match the given pathPattern.
95 ///
96 /// The path may be give in either Unix or Windows syntax and
97 /// is automatically expanded by calling Path::expand().
98 ///
99 /// The pattern may contain wildcard expressions even in intermediate
100 /// directory names (e.g. /usr/include/*/*.h).
101 ///
102 /// Note that, for obvious reasons, escaping characters in a pattern
103 /// with a backslash does not work in Windows-style paths.
104 ///
105 /// Directories that for whatever reason cannot be traversed are
106 /// ignored.
107
108 static void glob(const Path& pathPattern, std::set<std::string>& files, int options = 0);
109 /// Creates a set of files that match the given pathPattern.
110 ///
111 /// The pattern may contain wildcard expressions even in intermediate
112 /// directory names (e.g. /usr/include/*/*.h).
113 ///
114 /// Note that, for obvious reasons, escaping characters in a pattern
115 /// with a backslash does not work in Windows-style paths.
116 ///
117 /// Directories that for whatever reason cannot be traversed are
118 /// ignored.
119
120 static void glob(const Path& pathPattern, const Path& basePath, std::set<std::string>& files, int options = 0);
121 /// Creates a set of files that match the given pathPattern, starting from basePath.
122 ///
123 /// The pattern may contain wildcard expressions even in intermediate
124 /// directory names (e.g. /usr/include/*/*.h).
125 ///
126 /// Note that, for obvious reasons, escaping characters in a pattern
127 /// with a backslash does not work in Windows-style paths.
128 ///
129 /// Directories that for whatever reason cannot be traversed are
130 /// ignored.
131
132protected:
133 bool match(TextIterator& itp, const TextIterator& endp, TextIterator& its, const TextIterator& ends);
134 bool matchAfterAsterisk(TextIterator itp, const TextIterator& endp, TextIterator its, const TextIterator& ends);
135 bool matchSet(TextIterator& itp, const TextIterator& endp, int c);
136 static void collect(const Path& pathPattern, const Path& base, const Path& current, const std::string& pattern, std::set<std::string>& files, int options);
137 static bool isDirectory(const Path& path, bool followSymlink);
138
139private:
140 std::string _pattern;
141 int _options;
142
143 Glob();
144 Glob(const Glob&);
145 Glob& operator = (const Glob&);
146};
147
148
149} // namespace Poco
150
151
152#endif // Foundation_Glob_INCLUDED
153