LLDB  mainline
FileSpec.h
Go to the documentation of this file.
1 //===-- FileSpec.h ----------------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLDB_UTILITY_FILESPEC_H
10 #define LLDB_UTILITY_FILESPEC_H
11 
12 #include <functional>
13 #include <string>
14 
16 
17 #include "llvm/ADT/StringRef.h"
18 #include "llvm/Support/FileSystem.h"
19 #include "llvm/Support/FormatVariadic.h"
20 #include "llvm/Support/Path.h"
21 
22 #include <cstddef>
23 #include <cstdint>
24 
25 namespace lldb_private {
26 class Stream;
27 }
28 namespace llvm {
29 class Triple;
30 }
31 namespace llvm {
32 class raw_ostream;
33 }
34 namespace llvm {
35 template <typename T> class SmallVectorImpl;
36 }
37 
38 namespace lldb_private {
39 
40 /// \class FileSpec FileSpec.h "lldb/Utility/FileSpec.h"
41 /// A file utility class.
42 ///
43 /// A file specification class that divides paths up into a directory
44 /// and basename. These string values of the paths are put into uniqued string
45 /// pools for fast comparisons and efficient memory usage.
46 ///
47 /// Another reason the paths are split into the directory and basename is to
48 /// allow efficient debugger searching. Often in a debugger the user types in
49 /// the basename of the file, for example setting a breakpoint by file and
50 /// line, or specifying a module (shared library) to limit the scope in which
51 /// to execute a command. The user rarely types in a full path. When the paths
52 /// are already split up, it makes it easy for us to compare only the
53 /// basenames of a lot of file specifications without having to split up the
54 /// file path each time to get to the basename.
55 class FileSpec {
56 public:
57  using Style = llvm::sys::path::Style;
58 
59  FileSpec();
60 
61  /// Constructor with path.
62  ///
63  /// Takes a path to a file which can be just a filename, or a full path. If
64  /// \a path is not nullptr or empty, this function will call
65  /// FileSpec::SetFile (const char *path).
66  ///
67  /// \param[in] path
68  /// The full or partial path to a file.
69  ///
70  /// \param[in] style
71  /// The style of the path
72  ///
73  /// \see FileSpec::SetFile (const char *path)
74  explicit FileSpec(llvm::StringRef path, Style style = Style::native);
75 
76  explicit FileSpec(llvm::StringRef path, const llvm::Triple &triple);
77 
78  bool DirectoryEquals(const FileSpec &other) const;
79 
80  bool FileEquals(const FileSpec &other) const;
81 
82  /// Equal to operator
83  ///
84  /// Tests if this object is equal to \a rhs.
85  ///
86  /// \param[in] rhs
87  /// A const FileSpec object reference to compare this object
88  /// to.
89  ///
90  /// \return
91  /// \b true if this object is equal to \a rhs, \b false
92  /// otherwise.
93  bool operator==(const FileSpec &rhs) const;
94 
95  /// Not equal to operator
96  ///
97  /// Tests if this object is not equal to \a rhs.
98  ///
99  /// \param[in] rhs
100  /// A const FileSpec object reference to compare this object
101  /// to.
102  ///
103  /// \return
104  /// \b true if this object is equal to \a rhs, \b false
105  /// otherwise.
106  bool operator!=(const FileSpec &rhs) const;
107 
108  /// Less than to operator
109  ///
110  /// Tests if this object is less than \a rhs.
111  ///
112  /// \param[in] rhs
113  /// A const FileSpec object reference to compare this object
114  /// to.
115  ///
116  /// \return
117  /// \b true if this object is less than \a rhs, \b false
118  /// otherwise.
119  bool operator<(const FileSpec &rhs) const;
120 
121  /// Convert to pointer operator.
122  ///
123  /// This allows code to check a FileSpec object to see if it contains
124  /// anything valid using code such as:
125  ///
126  /// \code
127  /// FileSpec file_spec(...);
128  /// if (file_spec)
129  /// { ...
130  /// \endcode
131  ///
132  /// \return
133  /// A pointer to this object if either the directory or filename
134  /// is valid, nullptr otherwise.
135  explicit operator bool() const;
136 
137  /// Logical NOT operator.
138  ///
139  /// This allows code to check a FileSpec object to see if it is invalid
140  /// using code such as:
141  ///
142  /// \code
143  /// FileSpec file_spec(...);
144  /// if (!file_spec)
145  /// { ...
146  /// \endcode
147  ///
148  /// \return
149  /// Returns \b true if the object has an empty directory and
150  /// filename, \b false otherwise.
151  bool operator!() const;
152 
153  /// Clears the object state.
154  ///
155  /// Clear this object by releasing both the directory and filename string
156  /// values and reverting them to empty strings.
157  void Clear();
158 
159  /// Compare two FileSpec objects.
160  ///
161  /// If \a full is true, then both the directory and the filename must match.
162  /// If \a full is false, then the directory names for \a lhs and \a rhs are
163  /// only compared if they are both not empty. This allows a FileSpec object
164  /// to only contain a filename and it can match FileSpec objects that have
165  /// matching filenames with different paths.
166  ///
167  /// \param[in] lhs
168  /// A const reference to the Left Hand Side object to compare.
169  ///
170  /// \param[in] rhs
171  /// A const reference to the Right Hand Side object to compare.
172  ///
173  /// \param[in] full
174  /// If true, then both the directory and filenames will have to
175  /// match for a compare to return zero (equal to). If false
176  /// and either directory from \a lhs or \a rhs is empty, then
177  /// only the filename will be compared, else a full comparison
178  /// is done.
179  ///
180  /// \return -1 if \a lhs is less than \a rhs, 0 if \a lhs is equal to \a rhs,
181  /// 1 if \a lhs is greater than \a rhs
182  static int Compare(const FileSpec &lhs, const FileSpec &rhs, bool full);
183 
184  static bool Equal(const FileSpec &a, const FileSpec &b, bool full);
185 
186  /// Match FileSpec \a pattern against FileSpec \a file. If \a pattern has a
187  /// directory component, then the \a file must have the same directory
188  /// component. Otherwise, just it matches just the filename. An empty \a
189  /// pattern matches everything.
190  static bool Match(const FileSpec &pattern, const FileSpec &file);
191 
192  /// Attempt to guess path style for a given path string. It returns a style,
193  /// if it was able to make a reasonable guess, or None if it wasn't. The guess
194  /// will be correct if the input path was a valid absolute path on the system
195  /// which produced it. On other paths the result of this function is
196  /// unreliable (e.g. "c:\foo.txt" is a valid relative posix path).
197  static llvm::Optional<Style> GuessPathStyle(llvm::StringRef absolute_path);
198 
199  /// Case sensitivity of path.
200  ///
201  /// \return
202  /// \b true if the file path is case sensitive (POSIX), false
203  /// if case insensitive (Windows).
204  bool IsCaseSensitive() const { return is_style_posix(m_style); }
205 
206  /// Dump this object to a Stream.
207  ///
208  /// Dump the object to the supplied stream \a s. If the object contains a
209  /// valid directory name, it will be displayed followed by a directory
210  /// delimiter, and the filename.
211  ///
212  /// \param[in] s
213  /// The stream to which to dump the object description.
214  void Dump(llvm::raw_ostream &s) const;
215 
216  Style GetPathStyle() const;
217 
218  /// Directory string const get accessor.
219  ///
220  /// \return
221  /// A const reference to the directory string object.
222  const ConstString &GetDirectory() const { return m_directory; }
223 
224  /// Directory string set accessor.
225  ///
226  /// \param[in] directory
227  /// The value to replace the directory with.
228  void SetDirectory(ConstString directory);
229  void SetDirectory(llvm::StringRef directory);
230 
231  /// Clear the directory in this object.
232  void ClearDirectory();
233 
234 
235  /// Filename string const get accessor.
236  ///
237  /// \return
238  /// A const reference to the filename string object.
239  const ConstString &GetFilename() const { return m_filename; }
240 
241  /// Filename string set accessor.
242  ///
243  /// \param[in] filename
244  /// The const string to replace the directory with.
245  void SetFilename(ConstString filename);
246  void SetFilename(llvm::StringRef filename);
247 
248  /// Clear the filename in this object.
249  void ClearFilename();
250 
251  /// Returns true if the filespec represents an implementation source file
252  /// (files with a ".c", ".cpp", ".m", ".mm" (many more) extension).
253  ///
254  /// \return
255  /// \b true if the filespec represents an implementation source
256  /// file, \b false otherwise.
257  bool IsSourceImplementationFile() const;
258 
259  /// Returns true if the filespec represents a relative path.
260  ///
261  /// \return
262  /// \b true if the filespec represents a relative path,
263  /// \b false otherwise.
264  bool IsRelative() const;
265 
266  /// Returns true if the filespec represents an absolute path.
267  ///
268  /// \return
269  /// \b true if the filespec represents an absolute path,
270  /// \b false otherwise.
271  bool IsAbsolute() const;
272 
273  /// Make the FileSpec absolute by treating it relative to \a dir. Absolute
274  /// FileSpecs are never changed by this function.
275  void MakeAbsolute(const FileSpec &dir);
276 
277  /// Temporary helper for FileSystem change.
278  void SetPath(llvm::StringRef p) { SetFile(p); }
279 
280  /// Extract the full path to the file.
281  ///
282  /// Extract the directory and path into a fixed buffer. This is needed as
283  /// the directory and path are stored in separate string values.
284  ///
285  /// \param[out] path
286  /// The buffer in which to place the extracted full path.
287  ///
288  /// \param[in] max_path_length
289  /// The maximum length of \a path.
290  ///
291  /// \return
292  /// Returns the number of characters that would be needed to
293  /// properly copy the full path into \a path. If the returned
294  /// number is less than \a max_path_length, then the path is
295  /// properly copied and terminated. If the return value is
296  /// >= \a max_path_length, then the path was truncated (but is
297  /// still NULL terminated).
298  size_t GetPath(char *path, size_t max_path_length,
299  bool denormalize = true) const;
300 
301  /// Extract the full path to the file.
302  ///
303  /// Extract the directory and path into a std::string, which is returned.
304  ///
305  /// \return
306  /// Returns a std::string with the directory and filename
307  /// concatenated.
308  std::string GetPath(bool denormalize = true) const;
309 
310  /// Get the full path as a ConstString.
311  ///
312  /// This method should only be used when you need a ConstString or the
313  /// const char * from a ConstString to ensure permanent lifetime of C string.
314  /// Anyone needing the path temporarily should use the GetPath() method that
315  /// returns a std:string.
316  ConstString GetPathAsConstString(bool denormalize = true) const;
317 
318  /// Extract the full path to the file.
319  ///
320  /// Extract the directory and path into an llvm::SmallVectorImpl<>
322  bool denormalize = true) const;
323 
324  /// Extract the extension of the file.
325  ///
326  /// Returns a ConstString that represents the extension of the filename for
327  /// this FileSpec object. If this object does not represent a file, or the
328  /// filename has no extension, ConstString(nullptr) is returned. The dot
329  /// ('.') character is not returned as part of the extension
330  ///
331  /// \return Returns the extension of the file as a ConstString object.
333 
334  /// Return the filename without the extension part
335  ///
336  /// Returns a ConstString that represents the filename of this object
337  /// without the extension part (e.g. for a file named "foo.bar", "foo" is
338  /// returned)
339  ///
340  /// \return Returns the filename without extension as a ConstString object.
342 
343  /// Get the memory cost of this object.
344  ///
345  /// Return the size in bytes that this object takes in memory. This returns
346  /// the size in bytes of this object, not any shared string values it may
347  /// refer to.
348  ///
349  /// \return
350  /// The number of bytes that this object occupies in memory.
351  size_t MemorySize() const;
352 
353  /// Change the file specified with a new path.
354  ///
355  /// Update the contents of this object with a new path. The path will be
356  /// split up into a directory and filename and stored as uniqued string
357  /// values for quick comparison and efficient memory usage.
358  ///
359  /// \param[in] path
360  /// A full, partial, or relative path to a file.
361  ///
362  /// \param[in] style
363  /// The style for the given path.
364  void SetFile(llvm::StringRef path, Style style);
365 
366  /// Change the file specified with a new path.
367  ///
368  /// Update the contents of this object with a new path. The path will be
369  /// split up into a directory and filename and stored as uniqued string
370  /// values for quick comparison and efficient memory usage.
371  ///
372  /// \param[in] path
373  /// A full, partial, or relative path to a file.
374  ///
375  /// \param[in] triple
376  /// The triple which is used to set the Path style.
377  void SetFile(llvm::StringRef path, const llvm::Triple &triple);
378 
379  bool IsResolved() const { return m_is_resolved; }
380 
381  /// Set if the file path has been resolved or not.
382  ///
383  /// If you know a file path is already resolved and avoided passing a \b
384  /// true parameter for any functions that take a "bool resolve_path"
385  /// parameter, you can set the value manually using this call to make sure
386  /// we don't try and resolve it later, or try and resolve a path that has
387  /// already been resolved.
388  ///
389  /// \param[in] is_resolved
390  /// A boolean value that will replace the current value that
391  /// indicates if the paths in this object have been resolved.
392  void SetIsResolved(bool is_resolved) { m_is_resolved = is_resolved; }
393 
394  FileSpec CopyByAppendingPathComponent(llvm::StringRef component) const;
396 
397  void PrependPathComponent(llvm::StringRef component);
398  void PrependPathComponent(const FileSpec &new_path);
399 
400  void AppendPathComponent(llvm::StringRef component);
401  void AppendPathComponent(const FileSpec &new_path);
402 
403  /// Removes the last path component by replacing the current path with its
404  /// parent. When the current path has no parent, this is a no-op.
405  ///
406  /// \return
407  /// A boolean value indicating whether the path was updated.
409 
411 
412 protected:
413  // Convenience method for setting the file without changing the style.
414  void SetFile(llvm::StringRef path);
415 
416  /// Called anytime m_directory or m_filename is changed to clear any cached
417  /// state in this object.
419  m_is_resolved = false;
421  }
422 
423  enum class Absolute : uint8_t {
424  Calculate,
425  Yes,
426  No
427  };
428 
429  // Member variables
430  ConstString m_directory; ///< The uniqued directory path
431  ConstString m_filename; ///< The uniqued filename path
432  mutable bool m_is_resolved = false; ///< True if this path has been resolved.
433  mutable Absolute m_absolute = Absolute::Calculate; ///< Cache absoluteness.
434  Style m_style; ///< The syntax that this path uses (e.g. Windows / Posix)
435 };
436 
437 /// Dump a FileSpec object to a stream
438 Stream &operator<<(Stream &s, const FileSpec &f);
439 } // namespace lldb_private
440 
441 namespace llvm {
442 
443 /// Implementation of format_provider<T> for FileSpec.
444 ///
445 /// The options string of a FileSpec has the grammar:
446 ///
447 /// file_spec_options :: (empty) | F | D
448 ///
449 /// =======================================================
450 /// | style | Meaning | Example |
451 /// -------------------------------------------------------
452 /// | | | Input | Output |
453 /// =======================================================
454 /// | F | Only print filename | /foo/bar | bar |
455 /// | D | Only print directory | /foo/bar | /foo/ |
456 /// | (empty) | Print file and dir | | |
457 /// =======================================================
458 ///
459 /// Any other value is considered an invalid format string.
460 ///
461 template <> struct format_provider<lldb_private::FileSpec> {
462  static void format(const lldb_private::FileSpec &F, llvm::raw_ostream &Stream,
463  StringRef Style);
464 };
465 
466 } // namespace llvm
467 
468 #endif // LLDB_UTILITY_FILESPEC_H
lldb_private::FileSpec::GetLastPathComponent
ConstString GetLastPathComponent() const
Definition: FileSpec.cpp:431
llvm
Definition: Debugger.h:50
lldb_private::FileSpec::ClearFilename
void ClearFilename()
Clear the filename in this object.
Definition: FileSpec.cpp:352
lldb_private::FileSpec::m_filename
ConstString m_filename
The uniqued filename path.
Definition: FileSpec.h:431
lldb_private::FileSpec::operator!
bool operator!() const
Logical NOT operator.
Definition: FileSpec.cpp:224
lldb_private::FileSpec::MemorySize
size_t MemorySize() const
Get the memory cost of this object.
Definition: FileSpec.cpp:411
lldb_private::FileSpec::GetPathStyle
Style GetPathStyle() const
Definition: FileSpec.cpp:330
lldb_private::FileSpec::GetFilename
const ConstString & GetFilename() const
Filename string const get accessor.
Definition: FileSpec.h:239
lldb_private::Stream
Definition: Stream.h:28
lldb_private::FileSpec::MakeAbsolute
void MakeAbsolute(const FileSpec &dir)
Make the FileSpec absolute by treating it relative to dir.
Definition: FileSpec.cpp:514
lldb_private::FileSpec::SetPath
void SetPath(llvm::StringRef p)
Temporary helper for FileSystem change.
Definition: FileSpec.h:278
lldb_private::FileSpec::CopyByRemovingLastPathComponent
FileSpec CopyByRemovingLastPathComponent() const
Definition: FileSpec.cpp:422
lldb_private::FileSpec::PrependPathComponent
void PrependPathComponent(llvm::StringRef component)
Definition: FileSpec.cpp:437
lldb_private::FileSpec::m_absolute
Absolute m_absolute
Cache absoluteness.
Definition: FileSpec.h:433
lldb_private::FileSpec::operator!=
bool operator!=(const FileSpec &rhs) const
Not equal to operator.
Definition: FileSpec.cpp:242
lldb_private::FileSpec
Definition: FileSpec.h:55
lldb_private::FileSpec::Compare
static int Compare(const FileSpec &lhs, const FileSpec &rhs, bool full)
Compare two FileSpec objects.
Definition: FileSpec.cpp:271
bool
lldb_private::FileSpec::operator<
bool operator<(const FileSpec &rhs) const
Less than to operator.
Definition: FileSpec.cpp:245
lldb_private::FileSpec::Match
static bool Match(const FileSpec &pattern, const FileSpec &file)
Match FileSpec pattern against FileSpec file.
Definition: FileSpec.cpp:299
lldb_private::FileSpec::SetIsResolved
void SetIsResolved(bool is_resolved)
Set if the file path has been resolved or not.
Definition: FileSpec.h:392
lldb_private::FileSpec::m_directory
ConstString m_directory
The uniqued directory path.
Definition: FileSpec.h:430
lldb_private::FileSpec::DirectoryEquals
bool DirectoryEquals(const FileSpec &other) const
Definition: FileSpec.cpp:226
lldb_private::ConstString
Definition: ConstString.h:39
lldb_private::FileSpec::GetPathAsConstString
ConstString GetPathAsConstString(bool denormalize=true) const
Get the full path as a ConstString.
Definition: FileSpec.cpp:380
lldb_private::FileSpec::IsSourceImplementationFile
bool IsSourceImplementationFile() const
Returns true if the filespec represents an implementation source file (files with a "....
Definition: FileSpec.cpp:478
string
string(SUBSTRING ${p} 10 -1 pStripped) if($
Definition: Plugins/CMakeLists.txt:40
lldb_private::FileSpec::CopyByAppendingPathComponent
FileSpec CopyByAppendingPathComponent(llvm::StringRef component) const
Definition: FileSpec.cpp:416
lldb_private::FileSpec::GuessPathStyle
static llvm::Optional< Style > GuessPathStyle(llvm::StringRef absolute_path)
Attempt to guess path style for a given path string.
Definition: FileSpec.cpp:307
lldb_private::FileSpec::IsAbsolute
bool IsAbsolute() const
Returns true if the filespec represents an absolute path.
Definition: FileSpec.cpp:495
lldb_private::FileSpec::Clear
void Clear()
Clears the object state.
Definition: FileSpec.cpp:257
lldb_private::FileSpec::Style
llvm::sys::path::Style Style
Definition: FileSpec.h:57
lldb_private::FileSpec::SetFilename
void SetFilename(ConstString filename)
Filename string set accessor.
Definition: FileSpec.cpp:342
lldb_private::FileSpec::FileEquals
bool FileEquals(const FileSpec &other) const
Definition: FileSpec.cpp:231
lldb_private::FileSpec::Absolute::No
@ No
lldb_private::FileSpec::IsRelative
bool IsRelative() const
Returns true if the filespec represents a relative path.
Definition: FileSpec.cpp:491
lldb_private::FileSpec::ClearDirectory
void ClearDirectory()
Clear the directory in this object.
Definition: FileSpec.cpp:357
lldb_private::operator<<
Stream & operator<<(Stream &s, const SourceLocationSpec &loc)
Dump a SourceLocationSpec object to a stream.
Definition: SourceLocationSpec.cpp:40
lldb_private::FileSpec::RemoveLastPathComponent
bool RemoveLastPathComponent()
Removes the last path component by replacing the current path with its parent.
Definition: FileSpec.cpp:462
lldb_private::FileSpec::GetDirectory
const ConstString & GetDirectory() const
Directory string const get accessor.
Definition: FileSpec.h:222
lldb_private::FileSpec::FileSpec
FileSpec()
Definition: FileSpec.cpp:66
lldb_private::FileSpec::Dump
void Dump(llvm::raw_ostream &s) const
Dump this object to a Stream.
Definition: FileSpec.cpp:322
lldb_private::FileSpec::SetDirectory
void SetDirectory(ConstString directory)
Directory string set accessor.
Definition: FileSpec.cpp:332
lldb_private::FileSpec::IsCaseSensitive
bool IsCaseSensitive() const
Case sensitivity of path.
Definition: FileSpec.h:204
lldb_private::FileSpec::PathWasModified
void PathWasModified()
Called anytime m_directory or m_filename is changed to clear any cached state in this object.
Definition: FileSpec.h:418
lldb_private::FileSpec::Absolute::Yes
@ Yes
lldb_private::FileSpec::m_is_resolved
bool m_is_resolved
True if this path has been resolved.
Definition: FileSpec.h:432
lldb_private::FileSpec::Absolute
Absolute
Definition: FileSpec.h:423
lldb_private::FileSpec::AppendPathComponent
void AppendPathComponent(llvm::StringRef component)
Definition: FileSpec.cpp:451
lldb_private
A class that represents a running process on the host machine.
Definition: SBCommandInterpreterRunOptions.h:16
lldb_private::FileSpec::IsResolved
bool IsResolved() const
Definition: FileSpec.h:379
lldb_private::FileSpec::Absolute::Calculate
@ Calculate
ConstString.h
lldb_private::FileSpec::SetFile
void SetFile(llvm::StringRef path, Style style)
Change the file specified with a new path.
Definition: FileSpec.cpp:172
llvm::SmallVectorImpl
Definition: Disassembler.h:42
lldb_private::FileSpec::GetPath
size_t GetPath(char *path, size_t max_path_length, bool denormalize=true) const
Extract the full path to the file.
Definition: FileSpec.cpp:364
lldb_private::FileSpec::GetFileNameExtension
ConstString GetFileNameExtension() const
Extract the extension of the file.
Definition: FileSpec.cpp:400
lldb_private::FileSpec::Equal
static bool Equal(const FileSpec &a, const FileSpec &b, bool full)
Definition: FileSpec.cpp:292
lldb_private::FileSpec::operator==
bool operator==(const FileSpec &rhs) const
Equal to operator.
Definition: FileSpec.cpp:237
lldb_private::FileSpec::m_style
Style m_style
The syntax that this path uses (e.g. Windows / Posix)
Definition: FileSpec.h:434
lldb_private::FileSpec::GetFileNameStrippingExtension
ConstString GetFileNameStrippingExtension() const
Return the filename without the extension part.
Definition: FileSpec.cpp:405