E-MailRelay

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