include/lldb/Host/FileSpec.h

   1 //===-- FileSpec.h ----------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_FileSpec_h_
  11 #define liblldb_FileSpec_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 #include <functional>
  16 #include <string>
  17
  18 // Other libraries and framework includes
  19 // Project includes
  20 #include "lldb/Core/ConstString.h"
  21 #include "lldb/Core/STLUtils.h"
  22 #include "lldb/Host/PosixApi.h"
  23 #include "lldb/lldb-private.h"
  24
  25 #include "llvm/Support/FormatVariadic.h"
  26
  27 namespace lldb_private {
  28
  29 //----------------------------------------------------------------------
  30 /// @class FileSpec FileSpec.h "lldb/Host/FileSpec.h"
  31 /// @brief A file utility class.
  32 ///
  33 /// A file specification class that divides paths up into a directory
  34 /// and basename. These string values of the paths are put into uniqued
  35 /// string pools for fast comparisons and efficient memory usage.
  36 ///
  37 /// Another reason the paths are split into the directory and basename
  38 /// is to allow efficient debugger searching. Often in a debugger the
  39 /// user types in the basename of the file, for example setting a
  40 /// breakpoint by file and line, or specifying a module (shared library)
  41 /// to limit the scope in which to execute a command. The user rarely
  42 /// types in a full path. When the paths are already split up, it makes
  43 /// it easy for us to compare only the basenames of a lot of file
  44 /// specifications without having to split up the file path each time
  45 /// to get to the basename.
  46 //----------------------------------------------------------------------
  47 class FileSpec {
  48 public:
  49   typedef enum FileType {
  50     eFileTypeInvalid = -1,
  51     eFileTypeUnknown = 0,
  52     eFileTypeDirectory,
  53     eFileTypePipe,
  54     eFileTypeRegular,
  55     eFileTypeSocket,
  56     eFileTypeSymbolicLink,
  57     eFileTypeOther
  58   } FileType;
  59
  60   enum PathSyntax {
  61     ePathSyntaxPosix,
  62     ePathSyntaxWindows,
  63     ePathSyntaxHostNative
  64   };
  65
  66   FileSpec();
  67
  68   //------------------------------------------------------------------
  69   /// Constructor with path.
  70   ///
  71   /// Takes a path to a file which can be just a filename, or a full
  72   /// path. If \a path is not nullptr or empty, this function will call
  73   /// FileSpec::SetFile (const char *path, bool resolve).
  74   ///
  75   /// @param[in] path
  76   ///     The full or partial path to a file.
  77   ///
  78   /// @param[in] resolve_path
  79   ///     If \b true, then we resolve the path, removing stray ../.. and so
  80   ///     forth,
  81   ///     if \b false we trust the path is in canonical form already.
  82   ///
  83   /// @see FileSpec::SetFile (const char *path, bool resolve)
  84   //------------------------------------------------------------------
  85   explicit FileSpec(llvm::StringRef path, bool resolve_path,
  86                     PathSyntax syntax = ePathSyntaxHostNative);
  87
  88   explicit FileSpec(llvm::StringRef path, bool resolve_path, ArchSpec arch);
  89
  90   //------------------------------------------------------------------
  91   /// Copy constructor
  92   ///
  93   /// Makes a copy of the uniqued directory and filename strings from
  94   /// \a rhs.
  95   ///
  96   /// @param[in] rhs
  97   ///     A const FileSpec object reference to copy.
  98   //------------------------------------------------------------------
  99   FileSpec(const FileSpec &rhs);
 100
 101   //------------------------------------------------------------------
 102   /// Copy constructor
 103   ///
 104   /// Makes a copy of the uniqued directory and filename strings from
 105   /// \a rhs if it is not nullptr.
 106   ///
 107   /// @param[in] rhs
 108   ///     A const FileSpec object pointer to copy if non-nullptr.
 109   //------------------------------------------------------------------
 110   FileSpec(const FileSpec *rhs);
 111
 112   //------------------------------------------------------------------
 113   /// Destructor.
 114   //------------------------------------------------------------------
 115   ~FileSpec();
 116
 117   bool DirectoryEquals(const FileSpec &other) const;
 118
 119   bool FileEquals(const FileSpec &other) const;
 120
 121   //------------------------------------------------------------------
 122   /// Assignment operator.
 123   ///
 124   /// Makes a copy of the uniqued directory and filename strings from
 125   /// \a rhs.
 126   ///
 127   /// @param[in] rhs
 128   ///     A const FileSpec object reference to assign to this object.
 129   ///
 130   /// @return
 131   ///     A const reference to this object.
 132   //------------------------------------------------------------------
 133   const FileSpec &operator=(const FileSpec &rhs);
 134
 135   //------------------------------------------------------------------
 136   /// Equal to operator
 137   ///
 138   /// Tests if this object is equal to \a rhs.
 139   ///
 140   /// @param[in] rhs
 141   ///     A const FileSpec object reference to compare this object
 142   ///     to.
 143   ///
 144   /// @return
 145   ///     \b true if this object is equal to \a rhs, \b false
 146   ///     otherwise.
 147   //------------------------------------------------------------------
 148   bool operator==(const FileSpec &rhs) const;
 149
 150   //------------------------------------------------------------------
 151   /// Not equal to operator
 152   ///
 153   /// Tests if this object is not equal to \a rhs.
 154   ///
 155   /// @param[in] rhs
 156   ///     A const FileSpec object reference to compare this object
 157   ///     to.
 158   ///
 159   /// @return
 160   ///     \b true if this object is equal to \a rhs, \b false
 161   ///     otherwise.
 162   //------------------------------------------------------------------
 163   bool operator!=(const FileSpec &rhs) const;
 164
 165   //------------------------------------------------------------------
 166   /// Less than to operator
 167   ///
 168   /// Tests if this object is less than \a rhs.
 169   ///
 170   /// @param[in] rhs
 171   ///     A const FileSpec object reference to compare this object
 172   ///     to.
 173   ///
 174   /// @return
 175   ///     \b true if this object is less than \a rhs, \b false
 176   ///     otherwise.
 177   //------------------------------------------------------------------
 178   bool operator<(const FileSpec &rhs) const;
 179
 180   //------------------------------------------------------------------
 181   /// Convert to pointer operator.
 182   ///
 183   /// This allows code to check a FileSpec object to see if it
 184   /// contains anything valid using code such as:
 185   ///
 186   /// @code
 187   /// FileSpec file_spec(...);
 188   /// if (file_spec)
 189   /// { ...
 190   /// @endcode
 191   ///
 192   /// @return
 193   ///     A pointer to this object if either the directory or filename
 194   ///     is valid, nullptr otherwise.
 195   //------------------------------------------------------------------
 196   explicit operator bool() const;
 197
 198   //------------------------------------------------------------------
 199   /// Logical NOT operator.
 200   ///
 201   /// This allows code to check a FileSpec object to see if it is
 202   /// invalid using code such as:
 203   ///
 204   /// @code
 205   /// FileSpec file_spec(...);
 206   /// if (!file_spec)
 207   /// { ...
 208   /// @endcode
 209   ///
 210   /// @return
 211   ///     Returns \b true if the object has an empty directory and
 212   ///     filename, \b false otherwise.
 213   //------------------------------------------------------------------
 214   bool operator!() const;
 215
 216   //------------------------------------------------------------------
 217   /// Clears the object state.
 218   ///
 219   /// Clear this object by releasing both the directory and filename
 220   /// string values and reverting them to empty strings.
 221   //------------------------------------------------------------------
 222   void Clear();
 223
 224   //------------------------------------------------------------------
 225   /// Compare two FileSpec objects.
 226   ///
 227   /// If \a full is true, then both the directory and the filename
 228   /// must match. If \a full is false, then the directory names for
 229   /// \a lhs and \a rhs are only compared if they are both not empty.
 230   /// This allows a FileSpec object to only contain a filename
 231   /// and it can match FileSpec objects that have matching
 232   /// filenames with different paths.
 233   ///
 234   /// @param[in] lhs
 235   ///     A const reference to the Left Hand Side object to compare.
 236   ///
 237   /// @param[in] rhs
 238   ///     A const reference to the Right Hand Side object to compare.
 239   ///
 240   /// @param[in] full
 241   ///     If true, then both the directory and filenames will have to
 242   ///     match for a compare to return zero (equal to). If false
 243   ///     and either directory from \a lhs or \a rhs is empty, then
 244   ///     only the filename will be compared, else a full comparison
 245   ///     is done.
 246   ///
 247   /// @return
 248   ///     @li -1 if \a lhs is less than \a rhs
 249   ///     @li 0 if \a lhs is equal to \a rhs
 250   ///     @li 1 if \a lhs is greater than \a rhs
 251   //------------------------------------------------------------------
 252   static int Compare(const FileSpec &lhs, const FileSpec &rhs, bool full);
 253
 254   static bool Equal(const FileSpec &a, const FileSpec &b, bool full,
 255                     bool remove_backups = false);
 256
 257   //------------------------------------------------------------------
 258   /// Case sensitivity of path.
 259   ///
 260   /// @return
 261   ///     \b true if the file path is case sensitive (POSIX), false
 262   ///           if case insensitive (Windows).
 263   //------------------------------------------------------------------
 264   bool IsCaseSensitive() const { return m_syntax != ePathSyntaxWindows; }
 265
 266   //------------------------------------------------------------------
 267   /// Dump this object to a Stream.
 268   ///
 269   /// Dump the object to the supplied stream \a s. If the object
 270   /// contains a valid directory name, it will be displayed followed
 271   /// by a directory delimiter, and the filename.
 272   ///
 273   /// @param[in] s
 274   ///     The stream to which to dump the object description.
 275   //------------------------------------------------------------------
 276   void Dump(Stream *s) const;
 277
 278   //------------------------------------------------------------------
 279   /// Existence test.
 280   ///
 281   /// @return
 282   ///     \b true if the file exists on disk, \b false otherwise.
 283   //------------------------------------------------------------------
 284   bool Exists() const;
 285
 286   //------------------------------------------------------------------
 287   /// Check if a file is readable by the current user
 288   ///
 289   /// @return
 290   ///     \b true if the file exists on disk and is readable, \b false
 291   ///     otherwise.
 292   //------------------------------------------------------------------
 293   bool Readable() const;
 294
 295   //------------------------------------------------------------------
 296   /// Expanded existence test.
 297   ///
 298   /// Call into the Host to see if it can help find the file (e.g. by
 299   /// searching paths set in the environment, etc.).
 300   ///
 301   /// If found, sets the value of m_directory to the directory where
 302   /// the file was found.
 303   ///
 304   /// @return
 305   ///     \b true if was able to find the file using expanded search
 306   ///     methods, \b false otherwise.
 307   //------------------------------------------------------------------
 308   bool ResolveExecutableLocation();
 309
 310   //------------------------------------------------------------------
 311   /// Canonicalize this file path (basically running the static
 312   /// FileSpec::Resolve method on it). Useful if you asked us not to
 313   /// resolve the file path when you set the file.
 314   //------------------------------------------------------------------
 315   bool ResolvePath();
 316
 317   uint64_t GetByteSize() const;
 318
 319   PathSyntax GetPathSyntax() const;
 320
 321   //------------------------------------------------------------------
 322   /// Directory string get accessor.
 323   ///
 324   /// @return
 325   ///     A reference to the directory string object.
 326   //------------------------------------------------------------------
 327   ConstString &GetDirectory();
 328
 329   //------------------------------------------------------------------
 330   /// Directory string const get accessor.
 331   ///
 332   /// @return
 333   ///     A const reference to the directory string object.
 334   //------------------------------------------------------------------
 335   const ConstString &GetDirectory() const;
 336
 337   //------------------------------------------------------------------
 338   /// Filename string get accessor.
 339   ///
 340   /// @return
 341   ///     A reference to the filename string object.
 342   //------------------------------------------------------------------
 343   ConstString &GetFilename();
 344
 345   //------------------------------------------------------------------
 346   /// Filename string const get accessor.
 347   ///
 348   /// @return
 349   ///     A const reference to the filename string object.
 350   //------------------------------------------------------------------
 351   const ConstString &GetFilename() const;
 352
 353   //------------------------------------------------------------------
 354   /// Returns true if the filespec represents an implementation source
 355   /// file (files with a ".c", ".cpp", ".m", ".mm" (many more)
 356   /// extension).
 357   ///
 358   /// @return
 359   ///     \b true if the filespec represents an implementation source
 360   ///     file, \b false otherwise.
 361   //------------------------------------------------------------------
 362   bool IsSourceImplementationFile() const;
 363
 364   //------------------------------------------------------------------
 365   /// Returns true if the filespec represents a relative path.
 366   ///
 367   /// @return
 368   ///     \b true if the filespec represents a relative path,
 369   ///     \b false otherwise.
 370   //------------------------------------------------------------------
 371   bool IsRelative() const;
 372
 373   //------------------------------------------------------------------
 374   /// Returns true if the filespec represents an absolute path.
 375   ///
 376   /// @return
 377   ///     \b true if the filespec represents an absolute path,
 378   ///     \b false otherwise.
 379   //------------------------------------------------------------------
 380   bool IsAbsolute() const;
 381
 382   //------------------------------------------------------------------
 383   /// Extract the full path to the file.
 384   ///
 385   /// Extract the directory and path into a fixed buffer. This is
 386   /// needed as the directory and path are stored in separate string
 387   /// values.
 388   ///
 389   /// @param[out] path
 390   ///     The buffer in which to place the extracted full path.
 391   ///
 392   /// @param[in] max_path_length
 393   ///     The maximum length of \a path.
 394   ///
 395   /// @return
 396   ///     Returns the number of characters that would be needed to
 397   ///     properly copy the full path into \a path. If the returned
 398   ///     number is less than \a max_path_length, then the path is
 399   ///     properly copied and terminated. If the return value is
 400   ///     >= \a max_path_length, then the path was truncated (but is
 401   ///     still NULL terminated).
 402   //------------------------------------------------------------------
 403   size_t GetPath(char *path, size_t max_path_length,
 404                  bool denormalize = true) const;
 405
 406   //------------------------------------------------------------------
 407   /// Extract the full path to the file.
 408   ///
 409   /// Extract the directory and path into a std::string, which is returned.
 410   ///
 411   /// @return
 412   ///     Returns a std::string with the directory and filename
 413   ///     concatenated.
 414   //------------------------------------------------------------------
 415   std::string GetPath(bool denormalize = true) const;
 416
 417   const char *GetCString(bool denormalize = true) const;
 418
 419   //------------------------------------------------------------------
 420   /// Extract the full path to the file.
 421   ///
 422   /// Extract the directory and path into an llvm::SmallVectorImpl<>
 423   ///
 424   /// @return
 425   ///     Returns a std::string with the directory and filename
 426   ///     concatenated.
 427   //------------------------------------------------------------------
 428   void GetPath(llvm::SmallVectorImpl<char> &path,
 429                bool denormalize = true) const;
 430
 431   //------------------------------------------------------------------
 432   /// Extract the extension of the file.
 433   ///
 434   /// Returns a ConstString that represents the extension of the filename
 435   /// for this FileSpec object. If this object does not represent a file,
 436   /// or the filename has no extension, ConstString(nullptr) is returned.
 437   /// The dot ('.') character is not returned as part of the extension
 438   ///
 439   /// @return
 440   ///     Returns the extension of the file as a ConstString object.
 441   //------------------------------------------------------------------
 442   ConstString GetFileNameExtension() const;
 443
 444   //------------------------------------------------------------------
 445   /// Return the filename without the extension part
 446   ///
 447   /// Returns a ConstString that represents the filename of this object
 448   /// without the extension part (e.g. for a file named "foo.bar", "foo"
 449   /// is returned)
 450   ///
 451   /// @return
 452   ///     Returns the filename without extension
 453   ///     as a ConstString object.
 454   //------------------------------------------------------------------
 455   ConstString GetFileNameStrippingExtension() const;
 456
 457   FileType GetFileType() const;
 458
 459   //------------------------------------------------------------------
 460   /// Return the current permissions of the path.
 461   ///
 462   /// Returns a bitmask for the current permissions of the file
 463   /// ( zero or more of the permission bits defined in
 464   /// File::Permissions).
 465   ///
 466   /// @return
 467   ///     Zero if the file doesn't exist or we are unable to get
 468   ///     information for the file, otherwise one or more permission
 469   ///     bits from the File::Permissions enumeration.
 470   //------------------------------------------------------------------
 471   uint32_t GetPermissions() const;
 472
 473   bool IsDirectory() const {
 474     return GetFileType() == FileSpec::eFileTypeDirectory;
 475   }
 476
 477   bool IsPipe() const { return GetFileType() == FileSpec::eFileTypePipe; }
 478
 479   bool IsRegularFile() const {
 480     return GetFileType() == FileSpec::eFileTypeRegular;
 481   }
 482
 483   bool IsSocket() const { return GetFileType() == FileSpec::eFileTypeSocket; }
 484
 485   bool IsSymbolicLink() const;
 486
 487   //------------------------------------------------------------------
 488   /// Get the memory cost of this object.
 489   ///
 490   /// Return the size in bytes that this object takes in memory. This
 491   /// returns the size in bytes of this object, not any shared string
 492   /// values it may refer to.
 493   ///
 494   /// @return
 495   ///     The number of bytes that this object occupies in memory.
 496   ///
 497   /// @see ConstString::StaticMemorySize ()
 498   //------------------------------------------------------------------
 499   size_t MemorySize() const;
 500
 501   //------------------------------------------------------------------
 502   /// Memory map part of, or the entire contents of, a file.
 503   ///
 504   /// Returns a shared pointer to a data buffer that contains all or
 505   /// part of the contents of a file. The data is memory mapped and
 506   /// will lazily page in data from the file as memory is accessed.
 507   /// The data that is mapped will start \a offset bytes into the
 508   /// file, and \a length bytes will be mapped. If \a length is
 509   /// greater than the number of bytes available in the file starting
 510   /// at \a offset, the number of bytes will be appropriately
 511   /// truncated. The final number of bytes that get mapped can be
 512   /// verified using the DataBuffer::GetByteSize() function on the return
 513   /// shared data pointer object contents.
 514   ///
 515   /// @param[in] offset
 516   ///     The offset in bytes from the beginning of the file where
 517   ///     memory mapping should begin.
 518   ///
 519   /// @param[in] length
 520   ///     The size in bytes that should be mapped starting \a offset
 521   ///     bytes into the file. If \a length is \c SIZE_MAX, map
 522   ///     as many bytes as possible.
 523   ///
 524   /// @return
 525   ///     A shared pointer to the memory mapped data. This shared
 526   ///     pointer can contain a nullptr DataBuffer pointer, so the contained
 527   ///     pointer must be checked prior to using it.
 528   //------------------------------------------------------------------
 529   lldb::DataBufferSP MemoryMapFileContents(off_t offset = 0,
 530                                            size_t length = SIZE_MAX) const;
 531
 532   //------------------------------------------------------------------
 533   /// Memory map part of, or the entire contents of, a file only if
 534   /// the file is local (not on a network mount).
 535   ///
 536   /// Returns a shared pointer to a data buffer that contains all or
 537   /// part of the contents of a file. The data will be memory mapped
 538   /// if the file is local and will lazily page in data from the file
 539   /// as memory is accessed. If the data is memory mapped, the data
 540   /// that is mapped will start \a offset bytes into the file, and
 541   /// \a length bytes will be mapped. If \a length is
 542   /// greater than the number of bytes available in the file starting
 543   /// at \a offset, the number of bytes will be appropriately
 544   /// truncated. The final number of bytes that get mapped can be
 545   /// verified using the DataBuffer::GetByteSize() function on the return
 546   /// shared data pointer object contents.
 547   ///
 548   /// If the file is on a network mount the data will be read into a
 549   /// heap buffer immediately so that accesses to the data won't later
 550   /// cause a crash if we touch a page that isn't paged in and the
 551   /// network mount has been disconnected or gone away.
 552   ///
 553   /// @param[in] offset
 554   ///     The offset in bytes from the beginning of the file where
 555   ///     memory mapping should begin.
 556   ///
 557   /// @param[in] length
 558   ///     The size in bytes that should be mapped starting \a offset
 559   ///     bytes into the file. If \a length is \c SIZE_MAX, map
 560   ///     as many bytes as possible.
 561   ///
 562   /// @return
 563   ///     A shared pointer to the memory mapped data. This shared
 564   ///     pointer can contain a nullptr DataBuffer pointer, so the contained
 565   ///     pointer must be checked prior to using it.
 566   //------------------------------------------------------------------
 567   lldb::DataBufferSP MemoryMapFileContentsIfLocal(off_t file_offset,
 568                                                   size_t file_size) const;
 569
 570   //------------------------------------------------------------------
 571   /// Read part of, or the entire contents of, a file into a heap based data
 572   /// buffer.
 573   ///
 574   /// Returns a shared pointer to a data buffer that contains all or
 575   /// part of the contents of a file. The data copies into a heap based
 576   /// buffer that lives in the DataBuffer shared pointer object returned.
 577   /// The data that is cached will start \a offset bytes into the
 578   /// file, and \a length bytes will be mapped. If \a length is
 579   /// greater than the number of bytes available in the file starting
 580   /// at \a offset, the number of bytes will be appropriately
 581   /// truncated. The final number of bytes that get mapped can be
 582   /// verified using the DataBuffer::GetByteSize() function.
 583   ///
 584   /// @param[in] offset
 585   ///     The offset in bytes from the beginning of the file where
 586   ///     memory mapping should begin.
 587   ///
 588   /// @param[in] length
 589   ///     The size in bytes that should be mapped starting \a offset
 590   ///     bytes into the file. If \a length is \c SIZE_MAX, map
 591   ///     as many bytes as possible.
 592   ///
 593   /// @return
 594   ///     A shared pointer to the memory mapped data. This shared
 595   ///     pointer can contain a nullptr DataBuffer pointer, so the contained
 596   ///     pointer must be checked prior to using it.
 597   //------------------------------------------------------------------
 598   lldb::DataBufferSP ReadFileContents(off_t offset = 0,
 599                                       size_t length = SIZE_MAX,
 600                                       Error *error_ptr = nullptr) const;
 601
 602   size_t ReadFileContents(off_t file_offset, void *dst, size_t dst_len,
 603                           Error *error_ptr) const;
 604
 605   //------------------------------------------------------------------
 606   /// Read the entire contents of a file as data that can be used
 607   /// as a C string.
 608   ///
 609   /// Read the entire contents of a file and ensure that the data
 610   /// is NULL terminated so it can be used as a C string.
 611   ///
 612   /// @return
 613   ///     A shared pointer to the data. This shared pointer can
 614   ///     contain a nullptr DataBuffer pointer, so the contained pointer
 615   ///     must be checked prior to using it.
 616   //------------------------------------------------------------------
 617   lldb::DataBufferSP ReadFileContentsAsCString(Error *error_ptr = nullptr);
 618
 619   //------------------------------------------------------------------
 620   /// Normalize a pathname by collapsing redundant separators and
 621   /// up-level references.
 622   //------------------------------------------------------------------
 623   FileSpec GetNormalizedPath() const;
 624
 625   //------------------------------------------------------------------
 626   /// Change the file specified with a new path.
 627   ///
 628   /// Update the contents of this object with a new path. The path will
 629   /// be split up into a directory and filename and stored as uniqued
 630   /// string values for quick comparison and efficient memory usage.
 631   ///
 632   /// @param[in] path
 633   ///     A full, partial, or relative path to a file.
 634   ///
 635   /// @param[in] resolve_path
 636   ///     If \b true, then we will try to resolve links the path using
 637   ///     the static FileSpec::Resolve.
 638   //------------------------------------------------------------------
 639   void SetFile(llvm::StringRef path, bool resolve_path,
 640                PathSyntax syntax = ePathSyntaxHostNative);
 641
 642   void SetFile(llvm::StringRef path, bool resolve_path, ArchSpec arch);
 643
 644   bool IsResolved() const { return m_is_resolved; }
 645
 646   //------------------------------------------------------------------
 647   /// Set if the file path has been resolved or not.
 648   ///
 649   /// If you know a file path is already resolved and avoided passing
 650   /// a \b true parameter for any functions that take a "bool
 651   /// resolve_path" parameter, you can set the value manually using
 652   /// this call to make sure we don't try and resolve it later, or try
 653   /// and resolve a path that has already been resolved.
 654   ///
 655   /// @param[in] is_resolved
 656   ///     A boolean value that will replace the current value that
 657   ///     indicates if the paths in this object have been resolved.
 658   //------------------------------------------------------------------
 659   void SetIsResolved(bool is_resolved) { m_is_resolved = is_resolved; }
 660
 661   //------------------------------------------------------------------
 662   /// Read the file into an array of strings, one per line.
 663   ///
 664   /// Opens and reads the file in this object into an array of strings,
 665   /// one string per line of the file. Returns a boolean indicating
 666   /// success or failure.
 667   ///
 668   /// @param[out] lines
 669   ///     The string array into which to read the file.
 670   ///
 671   /// @result
 672   ///     Returns the number of lines that were read from the file.
 673   //------------------------------------------------------------------
 674   size_t ReadFileLines(STLStringArray &lines);
 675
 676   //------------------------------------------------------------------
 677   /// Resolves user name and links in \a path, and overwrites the input
 678   /// argument with the resolved path.
 679   ///
 680   /// @param[in] path
 681   ///     Input path to be resolved, in the form of a llvm::SmallString or
 682   ///     similar.
 683   //------------------------------------------------------------------
 684   static void Resolve(llvm::SmallVectorImpl<char> &path);
 685
 686   FileSpec CopyByAppendingPathComponent(llvm::StringRef component) const;
 687   FileSpec CopyByRemovingLastPathComponent() const;
 688
 689   void PrependPathComponent(llvm::StringRef component);
 690   void PrependPathComponent(const FileSpec &new_path);
 691
 692   void AppendPathComponent(llvm::StringRef component);
 693   void AppendPathComponent(const FileSpec &new_path);
 694
 695   void RemoveLastPathComponent();
 696
 697   ConstString GetLastPathComponent() const;
 698
 699   //------------------------------------------------------------------
 700   /// Resolves the user name at the beginning of \a src_path, and writes the
 701   /// output
 702   /// to \a dst_path.  Note, \a src_path can contain other path components after
 703   /// the
 704   /// user name, they will be copied over, and if the path doesn't start with
 705   /// "~" it
 706   /// will also be copied over to \a dst_path.
 707   ///
 708   /// @param[in] src_path
 709   ///     Input path to be resolved.
 710   ///
 711   /// @param[in] dst_path
 712   ///     Buffer to store the resolved path.
 713   //------------------------------------------------------------------
 714   static void ResolveUsername(llvm::SmallVectorImpl<char> &path);
 715
 716   static size_t ResolvePartialUsername(llvm::StringRef partial_name,
 717                                        StringList &matches);
 718
 719   enum EnumerateDirectoryResult {
 720     eEnumerateDirectoryResultNext,  // Enumerate next entry in the current
 721                                     // directory
 722     eEnumerateDirectoryResultEnter, // Recurse into the current entry if it is a
 723                                     // directory or symlink, or next if not
 724     eEnumerateDirectoryResultExit,  // Exit from the current directory at the
 725                                     // current level.
 726     eEnumerateDirectoryResultQuit   // Stop directory enumerations at any level
 727   };
 728
 729   typedef EnumerateDirectoryResult (*EnumerateDirectoryCallbackType)(
 730       void *baton, FileType file_type, const FileSpec &spec);
 731
 732   static EnumerateDirectoryResult
 733   EnumerateDirectory(llvm::StringRef dir_path, bool find_directories,
 734                      bool find_files, bool find_other,
 735                      EnumerateDirectoryCallbackType callback,
 736                      void *callback_baton);
 737
 738   typedef std::function<EnumerateDirectoryResult(FileType file_type,
 739                                                  const FileSpec &spec)>
 740       DirectoryCallback;
 741
 742   static EnumerateDirectoryResult
 743   ForEachItemInDirectory(llvm::StringRef dir_path,
 744                          DirectoryCallback const &callback);
 745
 746 protected:
 747   //------------------------------------------------------------------
 748   // Member variables
 749   //------------------------------------------------------------------
 750   ConstString m_directory;            ///< The uniqued directory path
 751   ConstString m_filename;             ///< The uniqued filename path
 752   mutable bool m_is_resolved = false; ///< True if this path has been resolved.
 753   PathSyntax
 754       m_syntax; ///< The syntax that this path uses (e.g. Windows / Posix)
 755 };
 756
 757 //----------------------------------------------------------------------
 758 /// Dump a FileSpec object to a stream
 759 //----------------------------------------------------------------------
 760 Stream &operator<<(Stream &s, const FileSpec &f);
 761
 762 } // namespace lldb_private
 763
 764 namespace llvm {
 765
 766 /// Implementation of format_provider<T> for FileSpec.
 767 ///
 768 /// The options string of a FileSpec has the grammar:
 769 ///
 770 ///   file_spec_options   :: (empty) | F | D
 771 ///
 772 ///   =======================================================
 773 ///   |  style  |     Meaning          |      Example       |
 774 ///   -------------------------------------------------------
 775 ///   |         |                      |  Input   |  Output |
 776 ///   =======================================================
 777 ///   |    F    | Only print filename  | /foo/bar |   bar   |
 778 ///   |    D    | Only print directory | /foo/bar |  /foo/  |
 779 ///   | (empty) | Print file and dir   |          |         |
 780 ///   =======================================================
 781 ///
 782 /// Any other value is considered an invalid format string.
 783 ///
 784 template <> struct format_provider<lldb_private::FileSpec> {
 785   static void format(const lldb_private::FileSpec &F, llvm::raw_ostream &Stream,
 786                      StringRef Style);
 787 };
 788 }
 789
 790 #endif // liblldb_FileSpec_h_