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