clang-tools-extra/clangd/URI.h

   1 //===--- URI.h - File URIs with schemes --------------------------*- 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 LLVM_CLANG_TOOLS_EXTRA_CLANGD_URI_H
  10 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_URI_H
  11
  12 #include "llvm/ADT/StringRef.h"
  13 #include "llvm/Support/Error.h"
  14 #include "llvm/Support/Registry.h"
  15
  16 namespace clang {
  17 namespace clangd {
  18
  19 /// A URI describes the location of a source file.
  20 /// In the simplest case, this is a "file" URI that directly encodes the
  21 /// absolute path to a file. More abstract cases are possible: a shared index
  22 /// service might expose repo:// URIs that are relative to the source control
  23 /// root.
  24 ///
  25 /// Clangd handles URIs of the form <scheme>:[//<authority>]<body>. It doesn't
  26 /// further split the authority or body into constituent parts (e.g. query
  27 /// strings is included in the body).
  28 class URI {
  29 public:
  30   URI(llvm::StringRef Scheme, llvm::StringRef Authority, llvm::StringRef Body);
  31
  32   /// Returns decoded scheme e.g. "https"
  33   llvm::StringRef scheme() const { return Scheme; }
  34   /// Returns decoded authority e.g. "reviews.lvm.org"
  35   llvm::StringRef authority() const { return Authority; }
  36   /// Returns decoded body e.g. "/D41946"
  37   llvm::StringRef body() const { return Body; }
  38
  39   /// Returns a string URI with all components percent-encoded.
  40   std::string toString() const;
  41
  42   /// Creates a URI for a file in the given scheme. \p Scheme must be
  43   /// registered. The URI is percent-encoded.
  44   static llvm::Expected<URI> create(llvm::StringRef AbsolutePath,
  45                                     llvm::StringRef Scheme);
  46
  47   // Similar to above except this picks a registered scheme that works. If none
  48   // works, this falls back to "file" scheme.
  49   static URI create(llvm::StringRef AbsolutePath);
  50
  51   /// This creates a file:// URI for \p AbsolutePath. The path must be absolute.
  52   static URI createFile(llvm::StringRef AbsolutePath);
  53
  54   /// Parse a URI string "<scheme>:[//<authority>/]<path>". Percent-encoded
  55   /// characters in the URI will be decoded.
  56   static llvm::Expected<URI> parse(llvm::StringRef Uri);
  57
  58   /// Resolves the absolute path of \p U. If there is no matching scheme, or the
  59   /// URI is invalid in the scheme, this returns an error.
  60   ///
  61   /// \p HintPath A related path, such as the current file or working directory,
  62   /// which can help disambiguate when the same file exists in many workspaces.
  63   static llvm::Expected<std::string> resolve(const URI &U,
  64                                              llvm::StringRef HintPath = "");
  65
  66   /// Same as above, in addition it parses the \p FileURI using URI::parse.
  67   static llvm::Expected<std::string> resolve(llvm::StringRef FileURI,
  68                                              llvm::StringRef HintPath = "");
  69
  70   /// Resolves \p AbsPath into a canonical path of its URI, by converting
  71   /// \p AbsPath to URI and resolving the URI to get th canonical path.
  72   /// This ensures that paths with the same URI are resolved into consistent
  73   /// file path.
  74   static llvm::Expected<std::string> resolvePath(llvm::StringRef AbsPath,
  75                                                  llvm::StringRef HintPath = "");
  76
  77   /// Gets the preferred spelling of this file for #include, if there is one,
  78   /// e.g. <system_header.h>, "path/to/x.h".
  79   ///
  80   /// This allows URI schemas to provide their customized include paths.
  81   ///
  82   /// Returns an empty string if normal include-shortening based on the absolute
  83   /// path should be used.
  84   /// Fails if the URI is not valid in the schema.
  85   static llvm::Expected<std::string> includeSpelling(const URI &U);
  86
  87   friend bool operator==(const URI &LHS, const URI &RHS) {
  88     return std::tie(LHS.Scheme, LHS.Authority, LHS.Body) ==
  89            std::tie(RHS.Scheme, RHS.Authority, RHS.Body);
  90   }
  91
  92   friend bool operator<(const URI &LHS, const URI &RHS) {
  93     return std::tie(LHS.Scheme, LHS.Authority, LHS.Body) <
  94            std::tie(RHS.Scheme, RHS.Authority, RHS.Body);
  95   }
  96
  97 private:
  98   URI() = default;
  99
 100   std::string Scheme;
 101   std::string Authority;
 102   std::string Body;
 103 };
 104
 105 /// URIScheme is an extension point for teaching clangd to recognize a custom
 106 /// URI scheme. This is expected to be implemented and exposed via the
 107 /// URISchemeRegistry.
 108 class URIScheme {
 109 public:
 110   virtual ~URIScheme() = default;
 111
 112   /// Returns the absolute path of the file corresponding to the URI
 113   /// authority+body in the file system. See URI::resolve for semantics of
 114   /// \p HintPath.
 115   virtual llvm::Expected<std::string>
 116   getAbsolutePath(llvm::StringRef Authority, llvm::StringRef Body,
 117                   llvm::StringRef HintPath) const = 0;
 118
 119   virtual llvm::Expected<URI>
 120   uriFromAbsolutePath(llvm::StringRef AbsolutePath) const = 0;
 121
 122   /// Returns the include path of the file (e.g. <path>, "path"), which can be
 123   /// #included directly. See URI::includeSpelling for details.
 124   virtual llvm::Expected<std::string> getIncludeSpelling(const URI &U) const {
 125     return ""; // no customized include path for this scheme.
 126   }
 127 };
 128
 129 /// By default, a "file" scheme is supported where URI paths are always absolute
 130 /// in the file system.
 131 typedef llvm::Registry<URIScheme> URISchemeRegistry;
 132
 133 } // namespace clangd
 134 } // namespace clang
 135
 136 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_URI_H