FileSpec.h

Go to the documentation of this file.

//===-- FileSpec.h ----------------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
 
#ifndef LLDB_UTILITY_FILESPEC_H
#define LLDB_UTILITY_FILESPEC_H
 
#include 
#include 
#include 
 
#include "lldb/Utility/ConstString.h"
 
#include "llvm/ADT/StringRef.h"
#include "llvm/Support/FileSystem.h"
#include "llvm/Support/FormatVariadic.h"
#include "llvm/Support/Path.h"
 
#include 
#include 
 
namespace lldb_private {
class Stream;
}
namespace llvm {
class Triple;
}
namespace llvm {
class raw_ostream;
}
namespace llvm {
template <typename T> class SmallVectorImpl;
}
 
namespace lldb_private {
 
/// \class FileSpec FileSpec.h "lldb/Utility/FileSpec.h"
/// A file utility class.
///
/// A file specification class that divides paths up into a directory
/// and basename. These string values of the paths are put into uniqued string
/// pools for fast comparisons and efficient memory usage.
///
/// Another reason the paths are split into the directory and basename is to
/// allow efficient debugger searching. Often in a debugger the user types in
/// the basename of the file, for example setting a breakpoint by file and
/// line, or specifying a module (shared library) to limit the scope in which
/// to execute a command. The user rarely types in a full path. When the paths
/// are already split up, it makes it easy for us to compare only the
/// basenames of a lot of file specifications without having to split up the
/// file path each time to get to the basename.
class FileSpec {
public:
  using Style = llvm::sys::path::Style;
 
  FileSpec();
 
  /// Constructor with path.
  ///
  /// Takes a path to a file which can be just a filename, or a full path. If
  /// \a path is not nullptr or empty, this function will call
  /// FileSpec::SetFile (const char *path).
  ///
  /// \param[in] path
  ///     The full or partial path to a file.
  ///
  /// \param[in] style
  ///     The style of the path
  ///
  /// \see FileSpec::SetFile (const char *path)
  explicit FileSpec(llvm::StringRef path, Style style = Style::native);
 
  explicit FileSpec(llvm::StringRef path, const llvm::Triple &triple);
 
  bool DirectoryEquals(const FileSpec &other) const;
 
  bool FileEquals(const FileSpec &other) const;
 
  /// Equal to operator
  ///
  /// Tests if this object is equal to \a rhs.
  ///
  /// \param[in] rhs
  ///     A const FileSpec object reference to compare this object
  ///     to.
  ///
  /// \return
  ///     \b true if this object is equal to \a rhs, \b false
  ///     otherwise.
  bool operator==(const FileSpec &rhs) const;
 
  /// Not equal to operator
  ///
  /// Tests if this object is not equal to \a rhs.
  ///
  /// \param[in] rhs
  ///     A const FileSpec object reference to compare this object
  ///     to.
  ///
  /// \return
  ///     \b true if this object is equal to \a rhs, \b false
  ///     otherwise.
  bool operator!=(const FileSpec &rhs) const;
 
  /// Less than to operator
  ///
  /// Tests if this object is less than \a rhs.
  ///
  /// \param[in] rhs
  ///     A const FileSpec object reference to compare this object
  ///     to.
  ///
  /// \return
  ///     \b true if this object is less than \a rhs, \b false
  ///     otherwise.
  bool operator<(const FileSpec &rhs) const;
 
  /// Convert to pointer operator.
  ///
  /// This allows code to check a FileSpec object to see if it contains
  /// anything valid using code such as:
  ///
  /// \code
  /// FileSpec file_spec(...);
  /// if (file_spec)
  /// { ...
  /// \endcode
  ///
  /// \return
  ///     A pointer to this object if either the directory or filename
  ///     is valid, nullptr otherwise.
  explicit operator bool() const;
 
  /// Logical NOT operator.
  ///
  /// This allows code to check a FileSpec object to see if it is invalid
  /// using code such as:
  ///
  /// \code
  /// FileSpec file_spec(...);
  /// if (!file_spec)
  /// { ...
  /// \endcode
  ///
  /// \return
  ///     Returns \b true if the object has an empty directory and
  ///     filename, \b false otherwise.
  bool operator!() const;
 
  /// Clears the object state.
  ///
  /// Clear this object by releasing both the directory and filename string
  /// values and reverting them to empty strings.
  void Clear();
 
  /// Compare two FileSpec objects.
  ///
  /// If \a full is true, then both the directory and the filename must match.
  /// If \a full is false, then the directory names for \a lhs and \a rhs are
  /// only compared if they are both not empty. This allows a FileSpec object
  /// to only contain a filename and it can match FileSpec objects that have
  /// matching filenames with different paths.
  ///
  /// \param[in] lhs
  ///     A const reference to the Left Hand Side object to compare.
  ///
  /// \param[in] rhs
  ///     A const reference to the Right Hand Side object to compare.
  ///
  /// \param[in] full
  ///     If true, then both the directory and filenames will have to
  ///     match for a compare to return zero (equal to). If false
  ///     and either directory from \a lhs or \a rhs is empty, then
  ///     only the filename will be compared, else a full comparison
  ///     is done.
  ///
  /// \return -1 if \a lhs is less than \a rhs, 0 if \a lhs is equal to \a rhs,
  ///     1 if \a lhs is greater than \a rhs
  static int Compare(const FileSpec &lhs, const FileSpec &rhs, bool full);
 
  static bool Equal(const FileSpec &a, const FileSpec &b, bool full);
 
  /// Match FileSpec \a pattern against FileSpec \a file. If \a pattern has a
  /// directory component, then the \a file must have the same directory
  /// component. Otherwise, just it matches just the filename. An empty \a
  /// pattern matches everything.
  static bool Match(const FileSpec &pattern, const FileSpec &file);
 
  /// Attempt to guess path style for a given path string. It returns a style,
  /// if it was able to make a reasonable guess, or std::nullopt if it wasn't.
  /// The guess will be correct if the input path was a valid absolute path on
  /// the system which produced it. On other paths the result of this function
  /// is unreliable (e.g. "c:\foo.txt" is a valid relative posix path).
  static std::optional