1 //===- llvm/System/Path.h ---------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file was developed by Reid Spencer and is distributed under the
6 // University of Illinois Open Source License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file declares the llvm::sys::Path class.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_SYSTEM_PATH_H
15 #define LLVM_SYSTEM_PATH_H
22 /// This class provides an abstraction for the path to a file or directory
23 /// in the operating system's filesystem and provides various basic operations
24 /// on it. Note that this class only represents the name of a path to a file
25 /// or directory which may or may not be valid for a given machine's file
26 /// system. A Path ensures that the name it encapsulates is syntactical valid
27 /// for the operating system it is running on but does not ensure correctness
28 /// for any particular file system. A Path either references a file or a
29 /// directory and the distinction is consistently maintained. Most operations
30 /// on the class have invariants that require the Path object to be either a
31 /// file path or a directory path, but not both. Those operations will also
32 /// leave the object as either a file path or object path. There is exactly
33 /// one invalid Path which is the empty path. The class should never allow any
34 /// other syntactically invalid non-empty path name to be assigned. Empty
35 /// paths are required in order to indicate an error result. If the path is
36 /// empty, the is_valid operation will return false. All operations will fail
37 /// if is_valid is false. Operations that change the path will either return
38 /// false if it would cause a syntactically invalid path name (in which case
39 /// the Path object is left unchanged) or throw an std::string exception
40 /// indicating the error.
42 /// @brief An abstraction for operating system paths.
44 /// @name Constructors
47 /// Construct a path to the root directory of the file system. The root
48 /// directory is a top level directory above which there are no more
49 /// directories. For example, on UNIX, the root directory is /. On Windows
50 /// it is C:\. Other operating systems may have different notions of
51 /// what the root directory is.
53 static Path GetRootDirectory();
55 /// Construct a path to a unique temporary directory that is created in
56 /// a "standard" place for the operating system. The directory is
57 /// guaranteed to be created on exit from this function. If the directory
58 /// cannot be created, the function will throw an exception.
59 /// @throws std::string indicating why the directory could not be created.
60 /// @brief Constrct a path to an new, unique, existing temporary
62 static Path GetTemporaryDirectory();
64 /// Construct a path to the first system library directory. The
65 /// implementation of Path on a given platform must ensure that this
66 /// directory both exists and also contains standard system libraries
67 /// suitable for linking into programs.
69 /// @brief Construct a path to the first system library directory
70 static Path GetSystemLibraryPath1();
72 /// Construct a path to the second system library directory. The
73 /// implementation of Path on a given platform must ensure that this
74 /// directory both exists and also contains standard system libraries
75 /// suitable for linking into programs. Note that the "second" system
76 /// library directory may or may not be different from the first.
78 /// @brief Construct a path to the second system library directory
79 static Path GetSystemLibraryPath2();
81 /// Construct a path to the default LLVM configuration directory. The
82 /// implementation must ensure that this is a well-known (same on many
83 /// systems) directory in which llvm configuration files exist. For
84 /// example, on Unix, the /etc/llvm directory has been selected.
86 /// @brief Construct a path to the default LLVM configuration directory
87 static Path GetLLVMDefaultConfigDir();
89 /// Construct a path to the LLVM installed configuration directory. The
90 /// implementation must ensure that this refers to the "etc" directory of
91 /// the LLVM installation. This is the location where configuration files
92 /// will be located for a particular installation of LLVM on a machine.
94 /// @brief Construct a path to the LLVM installed configuration directory
95 static Path GetLLVMConfigDir();
97 /// Construct a path to the current user's home directory. The
98 /// implementation must use an operating system specific mechanism for
99 /// determining the user's home directory. For example, the environment
100 /// variable "HOME" could be used on Unix. If a given operating system
101 /// does not have the concept of a user's home directory, this static
102 /// constructor must provide the same result as GetRootDirectory.
104 /// @brief Construct a path to the current user's "home" directory
105 static Path GetUserHomeDirectory();
107 /// This is one of the very few ways in which a path can be constructed
108 /// with a syntactically invalid name. The only *legal* invalid name is an
109 /// empty one. Other invalid names are not permitted. Empty paths are
110 /// provided so that they can be used to indicate null or error results in
111 /// other lib/System functionality.
113 /// @brief Construct an empty (and invalid) path.
116 /// This constructor will accept a std::string as a path but if verifies
117 /// that the path string has a legal syntax for the operating system on
118 /// which it is running. This allows a path to be taken in from outside
119 /// the program. However, if the path is not valid, the Path object will
120 /// be set to an empty string and an exception will be thrown.
121 /// @throws std::string if the path string is not legal.
122 /// @param unvalidated_path The path to verify and assign.
123 /// @brief Construct a Path from a string.
124 explicit Path(std::string unverified_path);
130 /// Makes a copy of \p that to \p this.
133 /// @brief Assignment Operator
134 Path & operator = ( const Path & that ) {
139 /// Compares \p this Path with \p that Path for equality.
140 /// @returns true if \p this and \p that refer to the same thing.
142 /// @brief Equality Operator
143 bool operator == (const Path& that) const {
144 return 0 == path.compare(that.path) ;
147 /// Compares \p this Path with \p that Path for inequality.
148 /// @returns true if \p this and \p that refer to different things.
150 /// @brief Inequality Operator
151 bool operator !=( const Path & that ) const {
152 return 0 != path.compare( that.path );
155 /// Determines if \p this Path is less than \p that Path. This is required
156 /// so that Path objects can be placed into ordered collections (e.g.
157 /// std::map). The comparison is done lexicographically as defined by
158 /// the std::string::compare method.
159 /// @returns true if \p this path is lexicographically less than \p that.
161 /// @brief Less Than Operator
162 bool operator< (const Path& that) const {
163 return 0 > path.compare( that.path );
170 /// This function will use an operating system specific algorithm to
171 /// determine if the current value of \p this is a syntactically valid
172 /// path name for the operating system. The path name does not need to
173 /// exist, validity is simply syntactical. Empty paths are always invalid.
174 /// @returns true iff the path name is syntactically legal for the
175 /// host operating system.
176 /// @brief Determine if a path is syntactically valid or not.
177 bool is_valid() const;
179 /// This function determines if the contents of the path name are
180 /// empty. That is, the path has a zero length.
181 /// @returns true iff the path is empty.
182 /// @brief Determines if the path name is empty (invalid).
183 bool is_empty() const { return path.empty(); }
185 /// This function determines if the path name in this object is intended
186 /// to reference a legal file name (as opposed to a directory name). This
187 /// function does not verify anything with the file system, it merely
188 /// determines if the syntax of the path represents a file name or not.
189 /// @returns true if this path name references a file.
190 /// @brief Determines if the path name references a file.
191 bool is_file() const;
193 /// This function determines if the path name in this object is intended
194 /// to reference a legal directory name (as opposed to a file name). This
195 /// function does not verify anything with the file system, it merely
196 /// determines if the syntax of the path represents a directory name or
198 /// @returns true if the path name references a directory
199 /// @brief Determines if the path name references a directory.
200 bool is_directory() const;
202 /// This function determines if the path name in this object references
203 /// the root (top level directory) of the file system. The details of what
204 /// is considered the "root" may vary from system to system so this method
205 /// will do the necessary checking.
206 /// @returns true iff the path name references the root directory.
207 /// @brief Determines if the path references the root directory.
208 bool is_root_directory() const;
210 /// This function determines if the path name references an existing file
211 /// or directory in the file system. Unlike is_file and is_directory, this
212 /// function actually checks for the existence of the file or directory.
213 /// @returns true if the pathname references an existing file.
214 /// @brief Determines if the path is a file or directory in
218 /// This function determines if the path name references a readable file
219 /// or directory in the file system. Unlike is_file and is_directory, this
220 /// function actually checks for the existence and readability (by the
221 /// current program) of the file or directory.
222 /// @returns true if the pathname references a readable file.
223 /// @brief Determines if the path is a readable file or directory
224 /// in the file system.
225 bool readable() const;
227 /// This function determines if the path name references a writable file
228 /// or directory in the file system. Unlike is_file and is_directory, this
229 /// function actually checks for the existence and writability (by the
230 /// current program) of the file or directory.
231 /// @returns true if the pathname references a writable file.
232 /// @brief Determines if the path is a writable file or directory
233 /// in the file system.
234 bool writable() const;
236 /// This function determines if the path name references an executable
237 /// file in the file system. Unlike is_file and is_directory, this
238 /// function actually checks for the existence and executability (by
239 /// the current program) of the file.
240 /// @returns true if the pathname references an executable file.
241 /// @brief Determines if the path is an executable file in the file
243 bool executable() const;
245 /// This function returns the current contents of the path as a
246 /// std::string. This allows the underlying path string to be manipulated
247 /// by other software.
248 /// @returns std::string containing the path name.
249 /// @brief Returns the path as a std::string.
250 std::string get() const { return path; }
252 /// This function returns the last component of the path name. If the
253 /// is_directory() function would return true then this returns the name
254 /// of the last directory in the path. If the is_file() function would
255 /// return true then this function returns the name of the file without
256 /// any of the preceding directories.
257 /// @returns std::string containing the last component of the path name.
258 /// @brief Returns the last component of the path name.
259 std::string getLast() const;
261 /// @returns a c string containing the path name.
262 /// @brief Returns the path as a C string.
263 const char* const c_str() const { return path.c_str(); }
269 /// The path name is cleared and becomes empty. This is an invalid
270 /// path name but is the *only* invalid path name. This is provided
271 /// so that path objects can be used to indicate the lack of a
272 /// valid path being found.
273 void clear() { path.clear(); }
275 /// This method attempts to set the Path object to \p unverified_path
276 /// and interpret the name as a directory name. The \p unverified_path
277 /// is verified. If verification succeeds then \p unverified_path
278 /// is accepted as a directory and true is returned. Otherwise,
279 /// the Path object remains unchanged and false is returned.
280 /// @returns true if the path was set, false otherwise.
281 /// @param unverified_path The path to be set in Path object.
283 /// @brief Set a full path from a std::string
284 bool set_directory(const std::string& unverified_path);
286 /// This method attempts to set the Path object to \p unverified_path
287 /// and interpret the name as a file name. The \p unverified_path
288 /// is verified. If verification succeeds then \p unverified_path
289 /// is accepted as a file name and true is returned. Otherwise,
290 /// the Path object remains unchanged and false is returned.
291 /// @returns true if the path was set, false otherwise.
292 /// @param unverified_path The path to be set in Path object.
294 /// @brief Set a full path from a std::string
295 bool set_file(const std::string& unverified_path);
297 /// The \p dirname is added to the end of the Path if it is a legal
298 /// directory name for the operating system. The precondition for this
299 /// function is that the Path must reference a directory name (i.e.
300 /// is_directory() returns true).
301 /// @param dirname A string providing the directory name to
302 /// be added to the end of the path.
303 /// @returns false if the directory name could not be added
305 /// @brief Adds the name of a directory to a Path.
306 bool append_directory( const std::string& dirname );
308 /// One directory component is removed from the Path name. The Path must
309 /// refer to a non-root directory name (i.e. is_directory() returns true
310 /// but is_root_directory() returns false). Upon exit, the Path will
311 /// refer to the directory above it.
313 /// @returns false if the directory name could not be removed.
314 /// @brief Removes the last directory component of the Path.
315 bool elide_directory();
317 /// The \p filename is added to the end of the Path if it is a legal
318 /// directory name for the operating system. The precondition for this
319 /// function is that the Path reference a directory name (i.e.
320 /// is_directory() returns true).
322 /// @returns false if the file name could not be added.
323 /// @brief Appends the name of a file.
324 bool append_file( const std::string& filename );
326 /// One file component is removed from the Path name. The Path must
327 /// refer to a file (i.e. is_file() returns true). Upon exit,
328 /// the Path will refer to the directory above it.
330 /// @returns false if the file name could not be removed
331 /// @brief Removes the last file component of the path.
334 /// A period and the \p suffix are appended to the end of the pathname.
335 /// The precondition for this function is that the Path reference a file
336 /// name (i.e. is_file() returns true). If the Path is not a file, no
337 /// action is taken and the function returns false. If the path would
338 /// become invalid for the host operating system, false is returned.
339 /// @returns false if the suffix could not be added, true if it was.
341 /// @brief Adds a period and the \p suffix to the end of the pathname.
342 bool append_suffix(const std::string& suffix);
344 /// The suffix of the filename is removed. The suffix begins with and
345 /// includes the last . character in the filename after the last directory
346 /// separator and extends until the end of the name. If no . character is
347 /// after the last directory separator, then the file name is left
348 /// unchanged (i.e. it was already without a suffix) but the function return
350 /// @returns false if there was no suffix to remove, true otherwise.
352 /// @brief Remove the suffix from a path name.
355 /// This method attempts to create a directory in the file system with the
356 /// same name as the Path object. The \p create_parents parameter controls
357 /// whether intermediate directories are created or not. if \p
358 /// create_parents is true, then an attempt will be made to create all
359 /// intermediate directories. If \p create_parents is false, then only the
360 /// final directory component of the Path name will be created. The
361 /// created directory will have no entries.
362 /// @returns false if the Path does not reference a directory, true
364 /// @param create_parents Determines whether non-existent directory
365 /// components other than the last one (the "parents") are created or not.
366 /// @throws std::string if an error occurs.
367 /// @brief Create the directory this Path refers to.
368 bool create_directory( bool create_parents = false );
370 /// This method attempts to create a file in the file system with the same
371 /// name as the Path object. The intermediate directories must all exist
372 /// at the time this method is called. Use create_directories to
373 /// accomplish that. The created file will be empty upon return from this
375 /// @returns false if the Path does not reference a file, true otherwise.
376 /// @throws std::string if an error occurs.
377 /// @brief Create the file this Path refers to.
380 /// This method attempts to destroy the directory named by the last in
381 /// the Path name. If \p remove_contents is false, an attempt will be
382 /// made to remove just the directory that this Path object refers to
383 /// (the final Path component). If \p remove_contents is true, an attempt
384 /// will be made to remove the entire contents of the directory,
386 /// @param destroy_contents Indicates whether the contents of a destroyed
387 /// directory should also be destroyed (recursively).
388 /// @returns false if the Path does not refer to a directory, true
390 /// @throws std::string if there is an error.
391 /// @brief Removes the file or directory from the filesystem.
392 bool destroy_directory( bool destroy_contents = false );
394 /// This method attempts to destroy the file named by the last item in the
396 /// @returns false if the Path does not refer to a file, true otherwise.
397 /// @throws std::string if there is an error.
398 /// @brief Destroy the file this Path refers to.
405 std::string path; ///< Platform agnostic storage for the path name.