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