Debian Codegraph @

include/deal.II/base/path_search.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2005 - 2024 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_path_search_h
16 #define dealii_path_search_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/exceptions.h>
22
23 #include <fstream>
24 #include <map>
25 #include <memory>
26 #include <string>
27 #include <vector>
28
29
30 DEAL_II_NAMESPACE_OPEN
31
32 /**
33 * Support for searching files in a list of paths and with a list of suffixes.
34 *
35 * A list of search paths is maintained for each file class supported. A file
36 * class is defined by a unique string. The classes provided are <dl> <dt>
37 * MESH <dd> mesh input files in various formats (see GridIn) <dt> PARAMETER
38 * <dd> Parameter files (<tt>.prm</tt>) </dl>
39 *
40 * Additional file classes can be added easily by using add_class().
41 *
42 * Usage: First, you construct a PathSearch object for a certain file class,
43 * e.g. meshes. Then, you use the find() method to obtain a full path name and
44 * you can open the file.
45 * @code
46 * #include <deal.II/base/path_search.h>
47 *
48 * dealii::PathSearch search("MESH");
49 * std::string full_name = search.find("grid");
50 * std::ifstream in(full_name);
51 * ...
52 * @endcode
53 *
54 * This piece of code will first traverse all paths in the list set up for
55 * file class <tt>MESH</tt>. If it manages to open a file, it returns the
56 * <tt>istream</tt> object. If not, it will try to append the first suffix of
57 * the suffix list and do the same. And so on. If no file is found in the end,
58 * an exception is thrown.
59 *
60 * If you want to restrict your search to a certain mesh format, <tt>.inp</tt>
61 * for instance, then either use <tt>"grid.inp"</tt> in the code above or use
62 * the alternative find(const std::string&,const std::string&,const char*)
63 * function
64 * @code
65 * std::string full_name = search.find("grid", ".inp");
66 * @endcode
67 *
68 * Path lists are by default starting with the current directory
69 * (<tt>"./"</tt>), followed optionally by a standard directory of deal.II.
70 * Use show() to find out the path list for a given class. Paths and suffixes
71 * can be added using the functions add_path() and add_suffix(), respectively.
72 *
73 * @note Directories in the path list should always end with a trailing
74 * <tt>"/"</tt>, while suffixes should always start with a dot. These
75 * characters are not added automatically (allowing you to do some real file
76 * name editing).
77 *
78 * @deprecated Use the std::filesystem facilities instead.
79 *
80 * @ingroup input
81 */
82 class DEAL_II_DEPRECATED PathSearch
83 {
84 public:
85 /**
86 * Position for adding a new item to a list.
87 */
88 enum Position
89 {
90 /// Add new item at end of list
91 back,
92 /// Add new item at front of list
93 front,
94 /// Add in path list after empty element
95 after_none
96 };
97
98 /**
99 * Constructor. The first argument is a string identifying the class of
100 * files to be searched for.
101 *
102 * The debug argument determines the verbosity of this class.
103 */
104 PathSearch(const std::string &cls, const unsigned int debug = 0);
105
106 /**
107 * Find a file in the class specified by the constructor and return its
108 * complete path name (including a possible suffix).
109 *
110 * File search works by actually trying to open the file. If @p fopen is
111 * successful with the provided @p open_mode, then the file is found,
112 * otherwise the search continues.
113 *
114 * @warning Be careful with @p open_mode! In particular, use <tt>"w"</tt>
115 * with great care! If the file does not exist, it cannot be found. If it
116 * does exist, the @p fopen function will truncate it to zero length.
117 *
118 * @param filename The base name of the file to be found, without path
119 * components and suffix.
120 * @param open_mode The mode handed over to the @p fopen function.
121 */
122 std::string
123 find(const std::string &filename, const char *open_mode = "r");
124
125 /**
126 * Find a file in the class specified by the constructor and return its
127 * complete path name. Do not use the standard suffix list, but only try to
128 * apply the suffix given.
129 *
130 * File search works by actually trying to open the file. If @p fopen is
131 * successful with the provided @p open_mode, then the file is found,
132 * otherwise the search continues.
133 *
134 * @warning Be careful with @p open_mode! In particular, use <tt>"w"</tt>
135 * with great care! If the file does not exist, it cannot be found. If it
136 * does exist, the @p fopen function will truncate it to zero length.
137 *
138 * @param filename The base name of the file to be found, without path
139 * components and suffix.
140 * @param suffix The suffix to be used for opening.
141 * @param open_mode The mode handed over to the @p fopen function.
142 */
143 std::string
144 find(const std::string &filename,
145 const std::string &suffix,
146 const char *open_mode = "r");
147
148 /**
149 * Show the paths and suffixes used for this object.
150 */
151 template <typename StreamType>
152 void
153 show(StreamType &stream) const;
154
155 /**
156 * Add a new class.
157 */
158 static void
159 add_class(const std::string &cls);
160
161 /**
162 * Add a path to the current class. See PathSearch::Position for possible
163 * position arguments.
164 */
165 void
166 add_path(const std::string &path, Position pos = back);
167
168 /**
169 * Add a path to the current class. See PathSearch::Position for possible
170 * position arguments.
171 */
172 void
173 add_suffix(const std::string &suffix, Position pos = back);
174
175 /**
176 * This class was not registered in the path search mechanism.
177 * @ingroup Exceptions
178 */
179 DeclException1(ExcNoClass,
180 std::string,
181 << "The class " << arg1
182 << " must be registered before referring it in PathSearch.");
183 /**
184 * The PathSearch class could not find a file with this name in its path
185 * list.
186 * @ingroup Exceptions
187 */
188 DeclException2(ExcFileNotFound,
189 std::string,
190 std::string,
191 << "The file \"" << arg1 << "\" was not found in the path for "
192 << "files of class " << arg2 << '.');
193
194 private:
195 /**
196 * Type of values in the class maps.
197 */
198 using map_type = std::map<std::string, std::vector<std::string>>::value_type;
199
200 /**
201 * Initialize the static list objects for further use.
202 */
203 static void
204 initialize_classes();
205
206 /**
207 * Get path list for a certain class. Used to set up #my_path_list in
208 * constructor.
209 */
210 static std::vector<std::string> &
211 get_path_list(const std::string &cls);
212
213 /**
214 * Get suffix list for a certain class. Used to set up #my_suffix_list in
215 * constructor.
216 */
217 static std::vector<std::string> &
218 get_suffix_list(const std::string &cls);
219
220 /**
221 * The file class handled by this object.
222 */
223 const std::string cls;
224
225 /**
226 * All path lists for all classes, such that we can build them only once.
227 */
228 static std::map<std::string, std::vector<std::string>> path_lists;
229
230 /**
231 * List of suffixes for each class.
232 */
233 static std::map<std::string, std::vector<std::string>> suffix_lists;
234
235 /**
236 * Path list for the class this object belongs to.
237 */
238 std::vector<std::string> &my_path_list;
239
240 /**
241 * Suffix list for the class this object belongs to.
242 */
243 std::vector<std::string> &my_suffix_list;
244
245 /**
246 * Debug flag. No output if zero.
247 */
248 const unsigned int debug;
249
250 /**
251 * The empty string.
252 */
253 static std::string empty;
254 };
255
256
257 /* ----------------------------- inline functions ------------------------- */
258
259
260 template <typename StreamType>
261 inline void
262 PathSearch::show(StreamType &out) const
263 {
264 out << "DEAL_II_" << cls << "PATH=\"";
265 bool first = true;
266 for (const auto &p : my_path_list)
267 {
268 if (!first)
269 out << ':';
270 out << p;
271 first = false;
272 }
273 out << '"' << std::endl << " Suffixes";
274 for (const auto &s : my_suffix_list)
275 out << " \"" << s << '"';
276 out << std::endl;
277 }
278
279 DEAL_II_NAMESPACE_CLOSE
280
281 #endif