contrib/llvm-project/lldb/include/lldb/Utility/FileSpec.h

   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_