1 //===-- FileSpec.h ----------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_FileSpec_h_
11 #define liblldb_FileSpec_h_
18 // Other libraries and framework includes
20 #include "lldb/Utility/ConstString.h"
22 #include "llvm/ADT/StringRef.h" // for StringRef
23 #include "llvm/Support/FileSystem.h"
24 #include "llvm/Support/FormatVariadic.h"
26 #include <stddef.h> // for size_t
27 #include <stdint.h> // for uint32_t, uint64_t
29 namespace lldb_private {
39 template <typename T> class SmallVectorImpl;
42 namespace lldb_private {
44 //----------------------------------------------------------------------
45 /// @class FileSpec FileSpec.h "lldb/Host/FileSpec.h"
46 /// @brief A file utility class.
48 /// A file specification class that divides paths up into a directory
49 /// and basename. These string values of the paths are put into uniqued
50 /// string pools for fast comparisons and efficient memory usage.
52 /// Another reason the paths are split into the directory and basename
53 /// is to allow efficient debugger searching. Often in a debugger the
54 /// user types in the basename of the file, for example setting a
55 /// breakpoint by file and line, or specifying a module (shared library)
56 /// to limit the scope in which to execute a command. The user rarely
57 /// types in a full path. When the paths are already split up, it makes
58 /// it easy for us to compare only the basenames of a lot of file
59 /// specifications without having to split up the file path each time
60 /// to get to the basename.
61 //----------------------------------------------------------------------
72 //------------------------------------------------------------------
73 /// Constructor with path.
75 /// Takes a path to a file which can be just a filename, or a full
76 /// path. If \a path is not nullptr or empty, this function will call
77 /// FileSpec::SetFile (const char *path, bool resolve).
80 /// The full or partial path to a file.
82 /// @param[in] resolve_path
83 /// If \b true, then we resolve the path, removing stray ../.. and so
85 /// if \b false we trust the path is in canonical form already.
87 /// @see FileSpec::SetFile (const char *path, bool resolve)
88 //------------------------------------------------------------------
89 explicit FileSpec(llvm::StringRef path, bool resolve_path,
90 PathSyntax syntax = ePathSyntaxHostNative);
92 explicit FileSpec(llvm::StringRef path, bool resolve_path,
93 const llvm::Triple &Triple);
95 //------------------------------------------------------------------
98 /// Makes a copy of the uniqued directory and filename strings from
102 /// A const FileSpec object reference to copy.
103 //------------------------------------------------------------------
104 FileSpec(const FileSpec &rhs);
106 //------------------------------------------------------------------
109 /// Makes a copy of the uniqued directory and filename strings from
110 /// \a rhs if it is not nullptr.
113 /// A const FileSpec object pointer to copy if non-nullptr.
114 //------------------------------------------------------------------
115 FileSpec(const FileSpec *rhs);
117 //------------------------------------------------------------------
119 //------------------------------------------------------------------
122 bool DirectoryEquals(const FileSpec &other) const;
124 bool FileEquals(const FileSpec &other) const;
126 //------------------------------------------------------------------
127 /// Assignment operator.
129 /// Makes a copy of the uniqued directory and filename strings from
133 /// A const FileSpec object reference to assign to this object.
136 /// A const reference to this object.
137 //------------------------------------------------------------------
138 const FileSpec &operator=(const FileSpec &rhs);
140 //------------------------------------------------------------------
141 /// Equal to operator
143 /// Tests if this object is equal to \a rhs.
146 /// A const FileSpec object reference to compare this object
150 /// \b true if this object is equal to \a rhs, \b false
152 //------------------------------------------------------------------
153 bool operator==(const FileSpec &rhs) const;
155 //------------------------------------------------------------------
156 /// Not equal to operator
158 /// Tests if this object is not equal to \a rhs.
161 /// A const FileSpec object reference to compare this object
165 /// \b true if this object is equal to \a rhs, \b false
167 //------------------------------------------------------------------
168 bool operator!=(const FileSpec &rhs) const;
170 //------------------------------------------------------------------
171 /// Less than to operator
173 /// Tests if this object is less than \a rhs.
176 /// A const FileSpec object reference to compare this object
180 /// \b true if this object is less than \a rhs, \b false
182 //------------------------------------------------------------------
183 bool operator<(const FileSpec &rhs) const;
185 //------------------------------------------------------------------
186 /// Convert to pointer operator.
188 /// This allows code to check a FileSpec object to see if it
189 /// contains anything valid using code such as:
192 /// FileSpec file_spec(...);
198 /// A pointer to this object if either the directory or filename
199 /// is valid, nullptr otherwise.
200 //------------------------------------------------------------------
201 explicit operator bool() const;
203 //------------------------------------------------------------------
204 /// Logical NOT operator.
206 /// This allows code to check a FileSpec object to see if it is
207 /// invalid using code such as:
210 /// FileSpec file_spec(...);
216 /// Returns \b true if the object has an empty directory and
217 /// filename, \b false otherwise.
218 //------------------------------------------------------------------
219 bool operator!() const;
221 //------------------------------------------------------------------
222 /// Clears the object state.
224 /// Clear this object by releasing both the directory and filename
225 /// string values and reverting them to empty strings.
226 //------------------------------------------------------------------
229 //------------------------------------------------------------------
230 /// Compare two FileSpec objects.
232 /// If \a full is true, then both the directory and the filename
233 /// must match. If \a full is false, then the directory names for
234 /// \a lhs and \a rhs are only compared if they are both not empty.
235 /// This allows a FileSpec object to only contain a filename
236 /// and it can match FileSpec objects that have matching
237 /// filenames with different paths.
240 /// A const reference to the Left Hand Side object to compare.
243 /// A const reference to the Right Hand Side object to compare.
246 /// If true, then both the directory and filenames will have to
247 /// match for a compare to return zero (equal to). If false
248 /// and either directory from \a lhs or \a rhs is empty, then
249 /// only the filename will be compared, else a full comparison
253 /// @li -1 if \a lhs is less than \a rhs
254 /// @li 0 if \a lhs is equal to \a rhs
255 /// @li 1 if \a lhs is greater than \a rhs
256 //------------------------------------------------------------------
257 static int Compare(const FileSpec &lhs, const FileSpec &rhs, bool full);
259 static bool Equal(const FileSpec &a, const FileSpec &b, bool full,
260 bool remove_backups = false);
262 //------------------------------------------------------------------
263 /// Case sensitivity of path.
266 /// \b true if the file path is case sensitive (POSIX), false
267 /// if case insensitive (Windows).
268 //------------------------------------------------------------------
269 bool IsCaseSensitive() const { return m_syntax != ePathSyntaxWindows; }
271 //------------------------------------------------------------------
272 /// Dump this object to a Stream.
274 /// Dump the object to the supplied stream \a s. If the object
275 /// contains a valid directory name, it will be displayed followed
276 /// by a directory delimiter, and the filename.
279 /// The stream to which to dump the object description.
280 //------------------------------------------------------------------
281 void Dump(Stream *s) const;
283 //------------------------------------------------------------------
287 /// \b true if the file exists on disk, \b false otherwise.
288 //------------------------------------------------------------------
291 //------------------------------------------------------------------
292 /// Check if a file is readable by the current user
295 /// \b true if the file exists on disk and is readable, \b false
297 //------------------------------------------------------------------
298 bool Readable() const;
300 //------------------------------------------------------------------
301 /// Expanded existence test.
303 /// Call into the Host to see if it can help find the file (e.g. by
304 /// searching paths set in the environment, etc.).
306 /// If found, sets the value of m_directory to the directory where
307 /// the file was found.
310 /// \b true if was able to find the file using expanded search
311 /// methods, \b false otherwise.
312 //------------------------------------------------------------------
313 bool ResolveExecutableLocation();
315 //------------------------------------------------------------------
316 /// Canonicalize this file path (basically running the static
317 /// FileSpec::Resolve method on it). Useful if you asked us not to
318 /// resolve the file path when you set the file.
319 //------------------------------------------------------------------
322 uint64_t GetByteSize() const;
324 PathSyntax GetPathSyntax() const;
326 //------------------------------------------------------------------
327 /// Directory string get accessor.
330 /// A reference to the directory string object.
331 //------------------------------------------------------------------
332 ConstString &GetDirectory();
334 //------------------------------------------------------------------
335 /// Directory string const get accessor.
338 /// A const reference to the directory string object.
339 //------------------------------------------------------------------
340 const ConstString &GetDirectory() const;
342 //------------------------------------------------------------------
343 /// Filename string get accessor.
346 /// A reference to the filename string object.
347 //------------------------------------------------------------------
348 ConstString &GetFilename();
350 //------------------------------------------------------------------
351 /// Filename string const get accessor.
354 /// A const reference to the filename string object.
355 //------------------------------------------------------------------
356 const ConstString &GetFilename() const;
358 //------------------------------------------------------------------
359 /// Returns true if the filespec represents an implementation source
360 /// file (files with a ".c", ".cpp", ".m", ".mm" (many more)
364 /// \b true if the filespec represents an implementation source
365 /// file, \b false otherwise.
366 //------------------------------------------------------------------
367 bool IsSourceImplementationFile() const;
369 //------------------------------------------------------------------
370 /// Returns true if the filespec represents a relative path.
373 /// \b true if the filespec represents a relative path,
374 /// \b false otherwise.
375 //------------------------------------------------------------------
376 bool IsRelative() const;
378 //------------------------------------------------------------------
379 /// Returns true if the filespec represents an absolute path.
382 /// \b true if the filespec represents an absolute path,
383 /// \b false otherwise.
384 //------------------------------------------------------------------
385 bool IsAbsolute() const;
387 //------------------------------------------------------------------
388 /// Extract the full path to the file.
390 /// Extract the directory and path into a fixed buffer. This is
391 /// needed as the directory and path are stored in separate string
395 /// The buffer in which to place the extracted full path.
397 /// @param[in] max_path_length
398 /// The maximum length of \a path.
401 /// Returns the number of characters that would be needed to
402 /// properly copy the full path into \a path. If the returned
403 /// number is less than \a max_path_length, then the path is
404 /// properly copied and terminated. If the return value is
405 /// >= \a max_path_length, then the path was truncated (but is
406 /// still NULL terminated).
407 //------------------------------------------------------------------
408 size_t GetPath(char *path, size_t max_path_length,
409 bool denormalize = true) const;
411 //------------------------------------------------------------------
412 /// Extract the full path to the file.
414 /// Extract the directory and path into a std::string, which is returned.
417 /// Returns a std::string with the directory and filename
419 //------------------------------------------------------------------
420 std::string GetPath(bool denormalize = true) const;
422 const char *GetCString(bool denormalize = true) const;
424 //------------------------------------------------------------------
425 /// Extract the full path to the file.
427 /// Extract the directory and path into an llvm::SmallVectorImpl<>
430 /// Returns a std::string with the directory and filename
432 //------------------------------------------------------------------
433 void GetPath(llvm::SmallVectorImpl<char> &path,
434 bool denormalize = true) const;
436 //------------------------------------------------------------------
437 /// Extract the extension of the file.
439 /// Returns a ConstString that represents the extension of the filename
440 /// for this FileSpec object. If this object does not represent a file,
441 /// or the filename has no extension, ConstString(nullptr) is returned.
442 /// The dot ('.') character is not returned as part of the extension
445 /// Returns the extension of the file as a ConstString object.
446 //------------------------------------------------------------------
447 ConstString GetFileNameExtension() const;
449 //------------------------------------------------------------------
450 /// Return the filename without the extension part
452 /// Returns a ConstString that represents the filename of this object
453 /// without the extension part (e.g. for a file named "foo.bar", "foo"
457 /// Returns the filename without extension
458 /// as a ConstString object.
459 //------------------------------------------------------------------
460 ConstString GetFileNameStrippingExtension() const;
462 //------------------------------------------------------------------
463 /// Return the current permissions of the path.
465 /// Returns a bitmask for the current permissions of the file
466 /// ( zero or more of the permission bits defined in
467 /// File::Permissions).
470 /// Zero if the file doesn't exist or we are unable to get
471 /// information for the file, otherwise one or more permission
472 /// bits from the File::Permissions enumeration.
473 //------------------------------------------------------------------
474 uint32_t GetPermissions() const;
476 //------------------------------------------------------------------
477 /// Get the memory cost of this object.
479 /// Return the size in bytes that this object takes in memory. This
480 /// returns the size in bytes of this object, not any shared string
481 /// values it may refer to.
484 /// The number of bytes that this object occupies in memory.
486 /// @see ConstString::StaticMemorySize ()
487 //------------------------------------------------------------------
488 size_t MemorySize() const;
490 //------------------------------------------------------------------
491 /// Normalize a pathname by collapsing redundant separators and
492 /// up-level references.
493 //------------------------------------------------------------------
494 FileSpec GetNormalizedPath() const;
496 //------------------------------------------------------------------
497 /// Change the file specified with a new path.
499 /// Update the contents of this object with a new path. The path will
500 /// be split up into a directory and filename and stored as uniqued
501 /// string values for quick comparison and efficient memory usage.
504 /// A full, partial, or relative path to a file.
506 /// @param[in] resolve_path
507 /// If \b true, then we will try to resolve links the path using
508 /// the static FileSpec::Resolve.
509 //------------------------------------------------------------------
510 void SetFile(llvm::StringRef path, bool resolve_path,
511 PathSyntax syntax = ePathSyntaxHostNative);
513 void SetFile(llvm::StringRef path, bool resolve_path,
514 const llvm::Triple &Triple);
516 bool IsResolved() const { return m_is_resolved; }
518 //------------------------------------------------------------------
519 /// Set if the file path has been resolved or not.
521 /// If you know a file path is already resolved and avoided passing
522 /// a \b true parameter for any functions that take a "bool
523 /// resolve_path" parameter, you can set the value manually using
524 /// this call to make sure we don't try and resolve it later, or try
525 /// and resolve a path that has already been resolved.
527 /// @param[in] is_resolved
528 /// A boolean value that will replace the current value that
529 /// indicates if the paths in this object have been resolved.
530 //------------------------------------------------------------------
531 void SetIsResolved(bool is_resolved) { m_is_resolved = is_resolved; }
533 //------------------------------------------------------------------
534 /// Resolves user name and links in \a path, and overwrites the input
535 /// argument with the resolved path.
538 /// Input path to be resolved, in the form of a llvm::SmallString or
540 //------------------------------------------------------------------
541 static void Resolve(llvm::SmallVectorImpl<char> &path);
543 FileSpec CopyByAppendingPathComponent(llvm::StringRef component) const;
544 FileSpec CopyByRemovingLastPathComponent() const;
546 void PrependPathComponent(llvm::StringRef component);
547 void PrependPathComponent(const FileSpec &new_path);
549 void AppendPathComponent(llvm::StringRef component);
550 void AppendPathComponent(const FileSpec &new_path);
552 void RemoveLastPathComponent();
554 ConstString GetLastPathComponent() const;
556 enum EnumerateDirectoryResult {
557 eEnumerateDirectoryResultNext, // Enumerate next entry in the current
559 eEnumerateDirectoryResultEnter, // Recurse into the current entry if it is a
560 // directory or symlink, or next if not
561 eEnumerateDirectoryResultQuit // Stop directory enumerations at any level
564 typedef EnumerateDirectoryResult (*EnumerateDirectoryCallbackType)(
565 void *baton, llvm::sys::fs::file_type file_type, const FileSpec &spec);
567 static void EnumerateDirectory(llvm::StringRef dir_path,
568 bool find_directories, bool find_files,
570 EnumerateDirectoryCallbackType callback,
571 void *callback_baton);
573 typedef std::function<EnumerateDirectoryResult(
574 llvm::sys::fs::file_type file_type, const FileSpec &spec)>
578 //------------------------------------------------------------------
580 //------------------------------------------------------------------
581 ConstString m_directory; ///< The uniqued directory path
582 ConstString m_filename; ///< The uniqued filename path
583 mutable bool m_is_resolved = false; ///< True if this path has been resolved.
585 m_syntax; ///< The syntax that this path uses (e.g. Windows / Posix)
588 //----------------------------------------------------------------------
589 /// Dump a FileSpec object to a stream
590 //----------------------------------------------------------------------
591 Stream &operator<<(Stream &s, const FileSpec &f);
593 } // namespace lldb_private
597 /// Implementation of format_provider<T> for FileSpec.
599 /// The options string of a FileSpec has the grammar:
601 /// file_spec_options :: (empty) | F | D
603 /// =======================================================
604 /// | style | Meaning | Example |
605 /// -------------------------------------------------------
606 /// | | | Input | Output |
607 /// =======================================================
608 /// | F | Only print filename | /foo/bar | bar |
609 /// | D | Only print directory | /foo/bar | /foo/ |
610 /// | (empty) | Print file and dir | | |
611 /// =======================================================
613 /// Any other value is considered an invalid format string.
615 template <> struct format_provider<lldb_private::FileSpec> {
616 static void format(const lldb_private::FileSpec &F, llvm::raw_ostream &Stream,
621 #endif // liblldb_FileSpec_h_