1 //===-- FileSpec.h ----------------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_FileSpec_h_
10 #define liblldb_FileSpec_h_
15 #include "lldb/Utility/ConstString.h"
17 #include "llvm/ADT/StringRef.h"
18 #include "llvm/Support/FileSystem.h"
19 #include "llvm/Support/FormatVariadic.h"
20 #include "llvm/Support/Path.h"
25 namespace lldb_private {
35 template <typename T> class SmallVectorImpl;
38 namespace lldb_private {
40 /// \class FileSpec FileSpec.h "lldb/Host/FileSpec.h"
41 /// A file utility class.
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.
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.
57 using Style = llvm::sys::path::Style;
61 /// Constructor with path.
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).
68 /// The full or partial path to a file.
71 /// The style of the path
73 /// \see FileSpec::SetFile (const char *path)
74 explicit FileSpec(llvm::StringRef path, Style style = Style::native);
76 explicit FileSpec(llvm::StringRef path, const llvm::Triple &triple);
78 bool DirectoryEquals(const FileSpec &other) const;
80 bool FileEquals(const FileSpec &other) const;
84 /// Tests if this object is equal to \a rhs.
87 /// A const FileSpec object reference to compare this object
91 /// \b true if this object is equal to \a rhs, \b false
93 bool operator==(const FileSpec &rhs) const;
95 /// Not equal to operator
97 /// Tests if this object is not equal to \a rhs.
100 /// A const FileSpec object reference to compare this object
104 /// \b true if this object is equal to \a rhs, \b false
106 bool operator!=(const FileSpec &rhs) const;
108 /// Less than to operator
110 /// Tests if this object is less than \a rhs.
113 /// A const FileSpec object reference to compare this object
117 /// \b true if this object is less than \a rhs, \b false
119 bool operator<(const FileSpec &rhs) const;
121 /// Convert to pointer operator.
123 /// This allows code to check a FileSpec object to see if it contains
124 /// anything valid using code such as:
127 /// FileSpec file_spec(...);
133 /// A pointer to this object if either the directory or filename
134 /// is valid, nullptr otherwise.
135 explicit operator bool() const;
137 /// Logical NOT operator.
139 /// This allows code to check a FileSpec object to see if it is invalid
140 /// using code such as:
143 /// FileSpec file_spec(...);
149 /// Returns \b true if the object has an empty directory and
150 /// filename, \b false otherwise.
151 bool operator!() const;
153 /// Clears the object state.
155 /// Clear this object by releasing both the directory and filename string
156 /// values and reverting them to empty strings.
159 /// Compare two FileSpec objects.
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.
168 /// A const reference to the Left Hand Side object to compare.
171 /// A const reference to the Right Hand Side object to compare.
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
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);
184 static bool Equal(const FileSpec &a, const FileSpec &b, bool full);
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);
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);
199 /// Case sensitivity of path.
202 /// \b true if the file path is case sensitive (POSIX), false
203 /// if case insensitive (Windows).
204 bool IsCaseSensitive() const { return m_style != Style::windows; }
206 /// Dump this object to a Stream.
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.
213 /// The stream to which to dump the object description.
214 void Dump(llvm::raw_ostream &s) const;
216 Style GetPathStyle() const;
218 /// Directory string get accessor.
221 /// A reference to the directory string object.
222 ConstString &GetDirectory();
224 /// Directory string const get accessor.
227 /// A const reference to the directory string object.
228 ConstString GetDirectory() const;
230 /// Filename string get accessor.
233 /// A reference to the filename string object.
234 ConstString &GetFilename();
236 /// Filename string const get accessor.
239 /// A const reference to the filename string object.
240 ConstString GetFilename() const;
242 /// Returns true if the filespec represents an implementation source file
243 /// (files with a ".c", ".cpp", ".m", ".mm" (many more) extension).
246 /// \b true if the filespec represents an implementation source
247 /// file, \b false otherwise.
248 bool IsSourceImplementationFile() const;
250 /// Returns true if the filespec represents a relative path.
253 /// \b true if the filespec represents a relative path,
254 /// \b false otherwise.
255 bool IsRelative() const;
257 /// Returns true if the filespec represents an absolute path.
260 /// \b true if the filespec represents an absolute path,
261 /// \b false otherwise.
262 bool IsAbsolute() const;
264 /// Make the FileSpec absolute by treating it relative to \a dir. Absolute
265 /// FileSpecs are never changed by this function.
266 void MakeAbsolute(const FileSpec &dir);
268 /// Temporary helper for FileSystem change.
269 void SetPath(llvm::StringRef p) { SetFile(p); }
271 /// Extract the full path to the file.
273 /// Extract the directory and path into a fixed buffer. This is needed as
274 /// the directory and path are stored in separate string values.
277 /// The buffer in which to place the extracted full path.
279 /// \param[in] max_path_length
280 /// The maximum length of \a path.
283 /// Returns the number of characters that would be needed to
284 /// properly copy the full path into \a path. If the returned
285 /// number is less than \a max_path_length, then the path is
286 /// properly copied and terminated. If the return value is
287 /// >= \a max_path_length, then the path was truncated (but is
288 /// still NULL terminated).
289 size_t GetPath(char *path, size_t max_path_length,
290 bool denormalize = true) const;
292 /// Extract the full path to the file.
294 /// Extract the directory and path into a std::string, which is returned.
297 /// Returns a std::string with the directory and filename
299 std::string GetPath(bool denormalize = true) const;
301 const char *GetCString(bool denormalize = true) const;
303 /// Extract the full path to the file.
305 /// Extract the directory and path into an llvm::SmallVectorImpl<>
306 void GetPath(llvm::SmallVectorImpl<char> &path,
307 bool denormalize = true) const;
309 /// Extract the extension of the file.
311 /// Returns a ConstString that represents the extension of the filename for
312 /// this FileSpec object. If this object does not represent a file, or the
313 /// filename has no extension, ConstString(nullptr) is returned. The dot
314 /// ('.') character is not returned as part of the extension
316 /// \return Returns the extension of the file as a ConstString object.
317 ConstString GetFileNameExtension() const;
319 /// Return the filename without the extension part
321 /// Returns a ConstString that represents the filename of this object
322 /// without the extension part (e.g. for a file named "foo.bar", "foo" is
325 /// \return Returns the filename without extension as a ConstString object.
326 ConstString GetFileNameStrippingExtension() const;
328 /// Get the memory cost of this object.
330 /// Return the size in bytes that this object takes in memory. This returns
331 /// the size in bytes of this object, not any shared string values it may
335 /// The number of bytes that this object occupies in memory.
337 /// \see ConstString::StaticMemorySize ()
338 size_t MemorySize() const;
340 /// Change the file specified with a new path.
342 /// Update the contents of this object with a new path. The path will be
343 /// split up into a directory and filename and stored as uniqued string
344 /// values for quick comparison and efficient memory usage.
347 /// A full, partial, or relative path to a file.
350 /// The style for the given path.
351 void SetFile(llvm::StringRef path, Style style);
353 /// Change the file specified with a new path.
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.
360 /// A full, partial, or relative path to a file.
362 /// \param[in] triple
363 /// The triple which is used to set the Path style.
364 void SetFile(llvm::StringRef path, const llvm::Triple &triple);
366 bool IsResolved() const { return m_is_resolved; }
368 /// Set if the file path has been resolved or not.
370 /// If you know a file path is already resolved and avoided passing a \b
371 /// true parameter for any functions that take a "bool resolve_path"
372 /// parameter, you can set the value manually using this call to make sure
373 /// we don't try and resolve it later, or try and resolve a path that has
374 /// already been resolved.
376 /// \param[in] is_resolved
377 /// A boolean value that will replace the current value that
378 /// indicates if the paths in this object have been resolved.
379 void SetIsResolved(bool is_resolved) { m_is_resolved = is_resolved; }
381 FileSpec CopyByAppendingPathComponent(llvm::StringRef component) const;
382 FileSpec CopyByRemovingLastPathComponent() const;
384 void PrependPathComponent(llvm::StringRef component);
385 void PrependPathComponent(const FileSpec &new_path);
387 void AppendPathComponent(llvm::StringRef component);
388 void AppendPathComponent(const FileSpec &new_path);
390 /// Removes the last path component by replacing the current path with its
391 /// parent. When the current path has no parent, this is a no-op.
394 /// A boolean value indicating whether the path was updated.
395 bool RemoveLastPathComponent();
397 ConstString GetLastPathComponent() const;
400 // Convenience method for setting the file without changing the style.
401 void SetFile(llvm::StringRef path);
404 ConstString m_directory; ///< The uniqued directory path
405 ConstString m_filename; ///< The uniqued filename path
406 mutable bool m_is_resolved = false; ///< True if this path has been resolved.
407 Style m_style; ///< The syntax that this path uses (e.g. Windows / Posix)
410 /// Dump a FileSpec object to a stream
411 Stream &operator<<(Stream &s, const FileSpec &f);
413 } // namespace lldb_private
417 /// Implementation of format_provider<T> for FileSpec.
419 /// The options string of a FileSpec has the grammar:
421 /// file_spec_options :: (empty) | F | D
423 /// =======================================================
424 /// | style | Meaning | Example |
425 /// -------------------------------------------------------
426 /// | | | Input | Output |
427 /// =======================================================
428 /// | F | Only print filename | /foo/bar | bar |
429 /// | D | Only print directory | /foo/bar | /foo/ |
430 /// | (empty) | Print file and dir | | |
431 /// =======================================================
433 /// Any other value is considered an invalid format string.
435 template <> struct format_provider<lldb_private::FileSpec> {
436 static void format(const lldb_private::FileSpec &F, llvm::raw_ostream &Stream,
441 #endif // liblldb_FileSpec_h_