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 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 m_style != Style::windows; } 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 get accessor. 219 /// 220 /// \return 221 /// A reference to the directory string object. 222 ConstString &GetDirectory(); 223 224 /// Directory string const get accessor. 225 /// 226 /// \return 227 /// A const reference to the directory string object. 228 ConstString GetDirectory() const; 229 230 /// Filename string get accessor. 231 /// 232 /// \return 233 /// A reference to the filename string object. 234 ConstString &GetFilename(); 235 236 /// Filename string const get accessor. 237 /// 238 /// \return 239 /// A const reference to the filename string object. 240 ConstString GetFilename() const; 241 242 /// Returns true if the filespec represents an implementation source file 243 /// (files with a ".c", ".cpp", ".m", ".mm" (many more) extension). 244 /// 245 /// \return 246 /// \b true if the filespec represents an implementation source 247 /// file, \b false otherwise. 248 bool IsSourceImplementationFile() const; 249 250 /// Returns true if the filespec represents a relative path. 251 /// 252 /// \return 253 /// \b true if the filespec represents a relative path, 254 /// \b false otherwise. 255 bool IsRelative() const; 256 257 /// Returns true if the filespec represents an absolute path. 258 /// 259 /// \return 260 /// \b true if the filespec represents an absolute path, 261 /// \b false otherwise. 262 bool IsAbsolute() const; 263 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); 267 268 /// Temporary helper for FileSystem change. 269 void SetPath(llvm::StringRef p) { SetFile(p); } 270 271 /// Extract the full path to the file. 272 /// 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. 275 /// 276 /// \param[out] path 277 /// The buffer in which to place the extracted full path. 278 /// 279 /// \param[in] max_path_length 280 /// The maximum length of \a path. 281 /// 282 /// \return 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; 291 292 /// Extract the full path to the file. 293 /// 294 /// Extract the directory and path into a std::string, which is returned. 295 /// 296 /// \return 297 /// Returns a std::string with the directory and filename 298 /// concatenated. 299 std::string GetPath(bool denormalize = true) const; 300 301 const char *GetCString(bool denormalize = true) const; 302 303 /// Extract the full path to the file. 304 /// 305 /// Extract the directory and path into an llvm::SmallVectorImpl<> 306 void GetPath(llvm::SmallVectorImpl<char> &path, 307 bool denormalize = true) const; 308 309 /// Extract the extension of the file. 310 /// 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 315 /// 316 /// \return Returns the extension of the file as a ConstString object. 317 ConstString GetFileNameExtension() const; 318 319 /// Return the filename without the extension part 320 /// 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 323 /// returned) 324 /// 325 /// \return Returns the filename without extension as a ConstString object. 326 ConstString GetFileNameStrippingExtension() const; 327 328 /// Get the memory cost of this object. 329 /// 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 332 /// refer to. 333 /// 334 /// \return 335 /// The number of bytes that this object occupies in memory. 336 /// 337 /// \see ConstString::StaticMemorySize () 338 size_t MemorySize() const; 339 340 /// Change the file specified with a new path. 341 /// 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. 345 /// 346 /// \param[in] path 347 /// A full, partial, or relative path to a file. 348 /// 349 /// \param[in] style 350 /// The style for the given path. 351 void SetFile(llvm::StringRef path, Style style); 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] triple 363 /// The triple which is used to set the Path style. 364 void SetFile(llvm::StringRef path, const llvm::Triple &triple); 365 366 bool IsResolved() const { return m_is_resolved; } 367 368 /// Set if the file path has been resolved or not. 369 /// 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. 375 /// 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; } 380 381 FileSpec CopyByAppendingPathComponent(llvm::StringRef component) const; 382 FileSpec CopyByRemovingLastPathComponent() const; 383 384 void PrependPathComponent(llvm::StringRef component); 385 void PrependPathComponent(const FileSpec &new_path); 386 387 void AppendPathComponent(llvm::StringRef component); 388 void AppendPathComponent(const FileSpec &new_path); 389 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. 392 /// 393 /// \return 394 /// A boolean value indicating whether the path was updated. 395 bool RemoveLastPathComponent(); 396 397 ConstString GetLastPathComponent() const; 398 399 protected: 400 // Convenience method for setting the file without changing the style. 401 void SetFile(llvm::StringRef path); 402 403 // Member variables 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) 408 }; 409 410 /// Dump a FileSpec object to a stream 411 Stream &operator<<(Stream &s, const FileSpec &f); 412 413 } // namespace lldb_private 414 415 namespace llvm { 416 417 /// Implementation of format_provider<T> for FileSpec. 418 /// 419 /// The options string of a FileSpec has the grammar: 420 /// 421 /// file_spec_options :: (empty) | F | D 422 /// 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 /// ======================================================= 432 /// 433 /// Any other value is considered an invalid format string. 434 /// 435 template <> struct format_provider<lldb_private::FileSpec> { 436 static void format(const lldb_private::FileSpec &F, llvm::raw_ostream &Stream, 437 StringRef Style); 438 }; 439 } // namespace llvm 440 441 #endif // liblldb_FileSpec_h_ 442