E-MailRelay
gdirectory.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gdirectory.h
19///
20
21#ifndef G_DIRECTORY_H
22#define G_DIRECTORY_H
23
24#include "gdef.h"
25#include "gpath.h"
26#include "gexception.h"
27#include "gstringview.h"
28#include <string>
29#include <vector>
30#include <memory>
31#include <list>
32#include <sys/types.h>
33
34namespace G
35{
36 class DirectoryIteratorImp ;
37 class Directory ;
38 class DirectoryIterator ;
39 class DirectoryList ;
40}
41
42//| \class G::Directory
43/// An encapsulation of a file system directory that works with
44/// G::DirectoryIterator.
45/// \see G::Path, G::FileSystem, G::File
46///
48{
49public:
50 Directory() ;
51 ///< Default constructor for the current directory.
52
53 explicit Directory( const Path & path ) ;
54 ///< Constructor.
55
56 explicit Directory( const std::string & path ) ;
57 ///< Constructor.
58
59 int usable( bool for_creating_files = false ) const ;
60 ///< Returns zero if the object represents a valid directory
61 ///< with permissions that dont disallow reading of any
62 ///< contained files. Returns a non-zero errno otherwise.
63 ///<
64 ///< Does additional checks if the 'for-creating-files'
65 ///< parameter is true. But note that the answer is not
66 ///< definitive -- file creation may fail, even if
67 ///< usable() returns zero. For a more accurate test use
68 ///< writeable().
69
70 bool valid( bool for_creating_files = false ) const ;
71 ///< Returns true iff usable() is zero.
72
73 bool writeable( const std::string & probe_filename = tmp() ) const ;
74 ///< Tries to create and then delete an empty test file
75 ///< in the directory. Returns true on success.
76 ///< Precondition: valid()
77
78 Path path() const ;
79 ///< Returns the directory's path, as passed in to the ctor.
80
81 static std::string tmp() ;
82 ///< A convenience function for constructing a filename for
83 ///< writeable(). This is factored-out from writeable() into
84 ///< this public interface so that client code can minimise
85 ///< the time spent with a privileged effective userid.
86
87private:
88 Path m_path ;
89} ;
90
91//| \class G::DirectoryIterator
92/// A iterator that returns unsorted filenames in a directory.
93/// The iteration model is:
94/// \code
95/// while(iter.more()) { auto path = iter.filePath() ; }
96/// \endcode
97///
99{
100public:
101 explicit DirectoryIterator( const Directory & dir ) ;
102 ///< Constructor taking a directory reference.
103 ///< Iterates over all files in the directory.
104
106 ///< Destructor.
107
108 bool error() const ;
109 ///< Returns true on error. The caller should stop the iteration.
110
111 bool more() ;
112 ///< Returns true if more and advances by one.
113
114 bool isDir() const ;
115 ///< Returns true if the current item is a directory or
116 ///< a symlink to a directory.
117
118 bool isLink() const ;
119 ///< Returns true if the current item is a symlink.
120
121 std::string sizeString() const ;
122 ///< Returns the file size as a decimal string. The value
123 ///< may be bigger than any integer type can hold.
124
125 Path filePath() const ;
126 ///< Returns the path of the current item.
127
128 std::string fileName() const ;
129 ///< Returns the name of the current item. On Windows
130 ///< any characters that cannot be represented in the
131 ///< active code page are replaced by '?'.
132
133public:
134 DirectoryIterator( const DirectoryIterator & ) = delete ;
135 DirectoryIterator( DirectoryIterator && ) noexcept = default ;
136 DirectoryIterator & operator=( const DirectoryIterator & ) = delete ;
137 DirectoryIterator & operator=( DirectoryIterator && ) noexcept = default ;
138
139private:
140 std::unique_ptr<DirectoryIteratorImp> m_imp ;
141} ;
142
143//| \class G::DirectoryList
144/// A iterator similar to G::DirectoryIterator but doing all file
145/// i/o in one go and providing a sorted result. This can be useful
146/// when temporarily adopting additional process privileges to
147/// read a directory.
148///
150{
151public:
152 struct Item /// A directory-entry item for G::DirectoryList.
153 {
154 bool m_is_dir {false} ;
155 bool m_is_link {false} ;
156 Path m_path ;
157 std::string m_name ;
158 bool operator<( const Item & ) const noexcept ;
159 } ;
160
162 ///< Default constructor for an empty list. Initialise with one
163 ///< of the three read methods to do all the file i/o in one go.
164
165 std::size_t readAll( const Path & dir ) ;
166 ///< An initialiser that is to be used after default construction.
167 ///< Reads all files in the directory.
168
169 std::size_t readType( const Path & dir , std::string_view suffix , unsigned int limit = 0U ) ;
170 ///< An initialiser that is to be used after default
171 ///< construction. Reads all files that have the given
172 ///< suffix (unsorted).
173
174 std::size_t readDirectories( const Path & dir , unsigned int limit = 0U ) ;
175 ///< An initialiser that reads all sub-directories.
176
177 bool empty() const noexcept ;
178 ///< Returns true if empty.
179
180 bool more() ;
181 ///< Returns true if more and advances by one.
182
183 bool isDir() const ;
184 ///< Returns true if the current item is a directory.
185
186 bool isLink() const ;
187 ///< Returns true if the current item is a symlink.
188
189 Path filePath() const ;
190 ///< Returns the current path.
191
192 std::string fileName() const ;
193 ///< Returns the current filename.
194
195 static void readAll( const Path & dir , std::vector<Item> & out ) ;
196 ///< A static overload returning by reference a collection
197 ///< of Items, sorted by name.
198
199private:
200 void readImp( const Path & , bool , std::string_view , unsigned int ) ;
201
202private:
203 bool m_first {true} ;
204 unsigned int m_index {0U} ;
205 std::vector<Item> m_list ;
206} ;
207
208inline bool G::DirectoryList::Item::operator<( const Item & other ) const noexcept
209{
210 return m_name < other.m_name ;
211}
212
213#endif
A iterator that returns unsorted filenames in a directory.
Definition: gdirectory.h:99
DirectoryIterator(const Directory &dir)
Constructor taking a directory reference.
std::string fileName() const
Returns the name of the current item.
bool error() const
Returns true on error. The caller should stop the iteration.
std::string sizeString() const
Returns the file size as a decimal string.
bool isLink() const
Returns true if the current item is a symlink.
~DirectoryIterator()
Destructor.
bool isDir() const
Returns true if the current item is a directory or a symlink to a directory.
bool more()
Returns true if more and advances by one.
Path filePath() const
Returns the path of the current item.
A iterator similar to G::DirectoryIterator but doing all file i/o in one go and providing a sorted re...
Definition: gdirectory.h:150
DirectoryList()
Default constructor for an empty list.
An encapsulation of a file system directory that works with G::DirectoryIterator.
Definition: gdirectory.h:48
int usable(bool for_creating_files=false) const
Returns zero if the object represents a valid directory with permissions that dont disallow reading o...
bool writeable(const std::string &probe_filename=tmp()) const
Tries to create and then delete an empty test file in the directory.
static std::string tmp()
A convenience function for constructing a filename for writeable().
Definition: gdirectory.cpp:55
Path path() const
Returns the directory's path, as passed in to the ctor.
Definition: gdirectory.cpp:50
bool valid(bool for_creating_files=false) const
Returns true iff usable() is zero.
Definition: gdirectory.cpp:63
Directory()
Default constructor for the current directory.
Definition: gdirectory.cpp:32
A Path object represents a file system path.
Definition: gpath.h:82
A class like c++17's std::string_view.
Definition: gstringview.h:70
Low-level classes.
Definition: garg.h:36
STL namespace.
A directory-entry item for G::DirectoryList.
Definition: gdirectory.h:153