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 liblldb_FileSpec_h_ 10 #define liblldb_FileSpec_h_ 11 12 #include <functional> 13 #include <string> 14 15 #include "lldb/Utility/ConstString.h" 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 <stddef.h> 23 #include <stdint.h> 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/Host/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 /// Copy constructor 79 /// 80 /// Makes a copy of the uniqued directory and filename strings from \a rhs 81 /// if it is not nullptr. 82 /// 83 /// \param[in] rhs 84 /// A const FileSpec object pointer to copy if non-nullptr. 85 FileSpec(const FileSpec *rhs); 86 87 /// Destructor. 88 ~FileSpec(); 89 90 bool DirectoryEquals(const FileSpec &other) const; 91 92 bool FileEquals(const FileSpec &other) const; 93 94 /// Assignment operator. 95 /// 96 /// Makes a copy of the uniqued directory and filename strings from \a rhs. 97 /// 98 /// \param[in] rhs 99 /// A const FileSpec object reference to assign to this object. 100 /// 101 /// \return 102 /// A const reference to this object. 103 const FileSpec &operator=(const FileSpec &rhs); 104 105 /// Equal to operator 106 /// 107 /// Tests if this object is equal to \a rhs. 108 /// 109 /// \param[in] rhs 110 /// A const FileSpec object reference to compare this object 111 /// to. 112 /// 113 /// \return 114 /// \b true if this object is equal to \a rhs, \b false 115 /// otherwise. 116 bool operator==(const FileSpec &rhs) const; 117 118 /// Not equal to operator 119 /// 120 /// Tests if this object is not equal to \a rhs. 121 /// 122 /// \param[in] rhs 123 /// A const FileSpec object reference to compare this object 124 /// to. 125 /// 126 /// \return 127 /// \b true if this object is equal to \a rhs, \b false 128 /// otherwise. 129 bool operator!=(const FileSpec &rhs) const; 130 131 /// Less than to operator 132 /// 133 /// Tests if this object is less than \a rhs. 134 /// 135 /// \param[in] rhs 136 /// A const FileSpec object reference to compare this object 137 /// to. 138 /// 139 /// \return 140 /// \b true if this object is less than \a rhs, \b false 141 /// otherwise. 142 bool operator<(const FileSpec &rhs) const; 143 144 /// Convert to pointer operator. 145 /// 146 /// This allows code to check a FileSpec object to see if it contains 147 /// anything valid using code such as: 148 /// 149 /// \code 150 /// FileSpec file_spec(...); 151 /// if (file_spec) 152 /// { ... 153 /// \endcode 154 /// 155 /// \return 156 /// A pointer to this object if either the directory or filename 157 /// is valid, nullptr otherwise. 158 explicit operator bool() const; 159 160 /// Logical NOT operator. 161 /// 162 /// This allows code to check a FileSpec object to see if it is invalid 163 /// using code such as: 164 /// 165 /// \code 166 /// FileSpec file_spec(...); 167 /// if (!file_spec) 168 /// { ... 169 /// \endcode 170 /// 171 /// \return 172 /// Returns \b true if the object has an empty directory and 173 /// filename, \b false otherwise. 174 bool operator!() const; 175 176 /// Clears the object state. 177 /// 178 /// Clear this object by releasing both the directory and filename string 179 /// values and reverting them to empty strings. 180 void Clear(); 181 182 /// Compare two FileSpec objects. 183 /// 184 /// If \a full is true, then both the directory and the filename must match. 185 /// If \a full is false, then the directory names for \a lhs and \a rhs are 186 /// only compared if they are both not empty. This allows a FileSpec object 187 /// to only contain a filename and it can match FileSpec objects that have 188 /// matching filenames with different paths. 189 /// 190 /// \param[in] lhs 191 /// A const reference to the Left Hand Side object to compare. 192 /// 193 /// \param[in] rhs 194 /// A const reference to the Right Hand Side object to compare. 195 /// 196 /// \param[in] full 197 /// If true, then both the directory and filenames will have to 198 /// match for a compare to return zero (equal to). If false 199 /// and either directory from \a lhs or \a rhs is empty, then 200 /// only the filename will be compared, else a full comparison 201 /// is done. 202 /// 203 /// \return 204 /// \li -1 if \a lhs is less than \a rhs 205 /// \li 0 if \a lhs is equal to \a rhs 206 /// \li 1 if \a lhs is greater than \a rhs 207 static int Compare(const FileSpec &lhs, const FileSpec &rhs, bool full); 208 209 static bool Equal(const FileSpec &a, const FileSpec &b, bool full); 210 211 /// Attempt to guess path style for a given path string. It returns a style, 212 /// if it was able to make a reasonable guess, or None if it wasn't. The guess 213 /// will be correct if the input path was a valid absolute path on the system 214 /// which produced it. On other paths the result of this function is 215 /// unreliable (e.g. "c:\foo.txt" is a valid relative posix path). 216 static llvm::Optional<Style> GuessPathStyle(llvm::StringRef absolute_path); 217 218 /// Case sensitivity of path. 219 /// 220 /// \return 221 /// \b true if the file path is case sensitive (POSIX), false 222 /// if case insensitive (Windows). 223 bool IsCaseSensitive() const { return m_style != Style::windows; } 224 225 /// Dump this object to a Stream. 226 /// 227 /// Dump the object to the supplied stream \a s. If the object contains a 228 /// valid directory name, it will be displayed followed by a directory 229 /// delimiter, and the filename. 230 /// 231 /// \param[in] s 232 /// The stream to which to dump the object description. 233 void Dump(Stream *s) const; 234 235 Style GetPathStyle() const; 236 237 /// Directory string get accessor. 238 /// 239 /// \return 240 /// A reference to the directory string object. 241 ConstString &GetDirectory(); 242 243 /// Directory string const get accessor. 244 /// 245 /// \return 246 /// A const reference to the directory string object. 247 ConstString GetDirectory() const; 248 249 /// Filename string get accessor. 250 /// 251 /// \return 252 /// A reference to the filename string object. 253 ConstString &GetFilename(); 254 255 /// Filename string const get accessor. 256 /// 257 /// \return 258 /// A const reference to the filename string object. 259 ConstString GetFilename() const; 260 261 /// Returns true if the filespec represents an implementation source file 262 /// (files with a ".c", ".cpp", ".m", ".mm" (many more) extension). 263 /// 264 /// \return 265 /// \b true if the filespec represents an implementation source 266 /// file, \b false otherwise. 267 bool IsSourceImplementationFile() const; 268 269 /// Returns true if the filespec represents a relative path. 270 /// 271 /// \return 272 /// \b true if the filespec represents a relative path, 273 /// \b false otherwise. 274 bool IsRelative() const; 275 276 /// Returns true if the filespec represents an absolute path. 277 /// 278 /// \return 279 /// \b true if the filespec represents an absolute path, 280 /// \b false otherwise. 281 bool IsAbsolute() const; 282 283 /// Make the FileSpec absolute by treating it relative to \a dir. Absolute 284 /// FileSpecs are never changed by this function. 285 void MakeAbsolute(const FileSpec &dir); 286 287 /// Temporary helper for FileSystem change. 288 void SetPath(llvm::StringRef p) { SetFile(p); } 289 290 /// Extract the full path to the file. 291 /// 292 /// Extract the directory and path into a fixed buffer. This is needed as 293 /// the directory and path are stored in separate string values. 294 /// 295 /// \param[out] path 296 /// The buffer in which to place the extracted full path. 297 /// 298 /// \param[in] max_path_length 299 /// The maximum length of \a path. 300 /// 301 /// \return 302 /// Returns the number of characters that would be needed to 303 /// properly copy the full path into \a path. If the returned 304 /// number is less than \a max_path_length, then the path is 305 /// properly copied and terminated. If the return value is 306 /// >= \a max_path_length, then the path was truncated (but is 307 /// still NULL terminated). 308 size_t GetPath(char *path, size_t max_path_length, 309 bool denormalize = true) const; 310 311 /// Extract the full path to the file. 312 /// 313 /// Extract the directory and path into a std::string, which is returned. 314 /// 315 /// \return 316 /// Returns a std::string with the directory and filename 317 /// concatenated. 318 std::string GetPath(bool denormalize = true) const; 319 320 const char *GetCString(bool denormalize = true) const; 321 322 /// Extract the full path to the file. 323 /// 324 /// Extract the directory and path into an llvm::SmallVectorImpl<> 325 /// 326 /// \return 327 /// Returns a std::string with the directory and filename 328 /// concatenated. 329 void GetPath(llvm::SmallVectorImpl<char> &path, 330 bool denormalize = true) const; 331 332 /// Extract the extension of the file. 333 /// 334 /// Returns a ConstString that represents the extension of the filename for 335 /// this FileSpec object. If this object does not represent a file, or the 336 /// filename has no extension, ConstString(nullptr) is returned. The dot 337 /// ('.') character is not returned as part of the extension 338 /// 339 /// \return 340 /// Returns the extension of the file as a ConstString object. 341 ConstString GetFileNameExtension() const; 342 343 /// Return the filename without the extension part 344 /// 345 /// Returns a ConstString that represents the filename of this object 346 /// without the extension part (e.g. for a file named "foo.bar", "foo" is 347 /// returned) 348 /// 349 /// \return 350 /// Returns the filename without extension 351 /// as a ConstString object. 352 ConstString GetFileNameStrippingExtension() const; 353 354 /// Get the memory cost of this object. 355 /// 356 /// Return the size in bytes that this object takes in memory. This returns 357 /// the size in bytes of this object, not any shared string values it may 358 /// refer to. 359 /// 360 /// \return 361 /// The number of bytes that this object occupies in memory. 362 /// 363 /// \see ConstString::StaticMemorySize () 364 size_t MemorySize() const; 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] resolve_path 376 /// If \b true, then we will try to resolve links the path using 377 /// the static FileSpec::Resolve. 378 void SetFile(llvm::StringRef path, Style style); 379 380 void SetFile(llvm::StringRef path, const llvm::Triple &Triple); 381 382 bool IsResolved() const { return m_is_resolved; } 383 384 /// Set if the file path has been resolved or not. 385 /// 386 /// If you know a file path is already resolved and avoided passing a \b 387 /// true parameter for any functions that take a "bool resolve_path" 388 /// parameter, you can set the value manually using this call to make sure 389 /// we don't try and resolve it later, or try and resolve a path that has 390 /// already been resolved. 391 /// 392 /// \param[in] is_resolved 393 /// A boolean value that will replace the current value that 394 /// indicates if the paths in this object have been resolved. 395 void SetIsResolved(bool is_resolved) { m_is_resolved = is_resolved; } 396 397 FileSpec CopyByAppendingPathComponent(llvm::StringRef component) const; 398 FileSpec CopyByRemovingLastPathComponent() const; 399 400 void PrependPathComponent(llvm::StringRef component); 401 void PrependPathComponent(const FileSpec &new_path); 402 403 void AppendPathComponent(llvm::StringRef component); 404 void AppendPathComponent(const FileSpec &new_path); 405 406 /// Removes the last path component by replacing the current path with its 407 /// parent. When the current path has no parent, this is a no-op. 408 /// 409 /// \return 410 /// A boolean value indicating whether the path was updated. 411 bool RemoveLastPathComponent(); 412 413 ConstString GetLastPathComponent() const; 414 415 protected: 416 // Convenience method for setting the file without changing the style. 417 void SetFile(llvm::StringRef path); 418 419 // Member variables 420 ConstString m_directory; ///< The uniqued directory path 421 ConstString m_filename; ///< The uniqued filename path 422 mutable bool m_is_resolved = false; ///< True if this path has been resolved. 423 Style m_style; ///< The syntax that this path uses (e.g. Windows / Posix) 424 }; 425 426 /// Dump a FileSpec object to a stream 427 Stream &operator<<(Stream &s, const FileSpec &f); 428 429 } // namespace lldb_private 430 431 namespace llvm { 432 433 /// Implementation of format_provider<T> for FileSpec. 434 /// 435 /// The options string of a FileSpec has the grammar: 436 /// 437 /// file_spec_options :: (empty) | F | D 438 /// 439 /// ======================================================= 440 /// | style | Meaning | Example | 441 /// ------------------------------------------------------- 442 /// | | | Input | Output | 443 /// ======================================================= 444 /// | F | Only print filename | /foo/bar | bar | 445 /// | D | Only print directory | /foo/bar | /foo/ | 446 /// | (empty) | Print file and dir | | | 447 /// ======================================================= 448 /// 449 /// Any other value is considered an invalid format string. 450 /// 451 template <> struct format_provider<lldb_private::FileSpec> { 452 static void format(const lldb_private::FileSpec &F, llvm::raw_ostream &Stream, 453 StringRef Style); 454 }; 455 } // namespace llvm 456 457 #endif // liblldb_FileSpec_h_ 458