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_PATHURI_H 10 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_PATHURI_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" scheme()33 llvm::StringRef scheme() const { return Scheme; } 34 /// Returns decoded authority e.g. "reviews.lvm.org" authority()35 llvm::StringRef authority() const { return Authority; } 36 /// Returns decoded body e.g. "/D41946" body()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. getIncludeSpelling(const URI & U)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_PATHURI_H 137