clang-tools 20.0.0git
URI.h
Go to the documentation of this file.
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
16namespace clang {
17namespace 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).
28class URI {
29public:
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
97private:
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.
108class URIScheme {
109public:
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.
131typedef llvm::Registry<URIScheme> URISchemeRegistry;
132
133} // namespace clangd
134} // namespace clang
135
136#endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_URI_H
clang::clangd::URIScheme
URIScheme is an extension point for teaching clangd to recognize a custom URI scheme.
Definition: URI.h:108
clang::clangd::URIScheme::getAbsolutePath
virtual llvm::Expected< std::string > getAbsolutePath(llvm::StringRef Authority, llvm::StringRef Body, llvm::StringRef HintPath) const =0
Returns the absolute path of the file corresponding to the URI authority+body in the file system.
clang::clangd::URIScheme::getIncludeSpelling
virtual llvm::Expected< std::string > getIncludeSpelling(const URI &U) const
Returns the include path of the file (e.g.
Definition: URI.h:124
clang::clangd::URIScheme::uriFromAbsolutePath
virtual llvm::Expected< URI > uriFromAbsolutePath(llvm::StringRef AbsolutePath) const =0
clang::clangd::URIScheme::~URIScheme
virtual ~URIScheme()=default
clang::clangd::URI
A URI describes the location of a source file.
Definition: URI.h:28
clang::clangd::URI::includeSpelling
static llvm::Expected< std::string > includeSpelling(const URI &U)
Gets the preferred spelling of this file for #include, if there is one, e.g.
Definition: URI.cpp:272
clang::clangd::URI::operator<
friend bool operator<(const URI &LHS, const URI &RHS)
Definition: URI.h:92
clang::clangd::URI::resolvePath
static llvm::Expected< std::string > resolvePath(llvm::StringRef AbsPath, llvm::StringRef HintPath="")
Resolves AbsPath into a canonical path of its URI, by converting AbsPath to URI and resolving the URI...
Definition: URI.cpp:252
clang::clangd::URI::create
static llvm::Expected< URI > create(llvm::StringRef AbsolutePath, llvm::StringRef Scheme)
Creates a URI for a file in the given scheme.
Definition: URI.cpp:208
clang::clangd::URI::createFile
static URI createFile(llvm::StringRef AbsolutePath)
This creates a file:// URI for AbsolutePath. The path must be absolute.
Definition: URI.cpp:237
clang::clangd::URI::body
llvm::StringRef body() const
Returns decoded body e.g. "/D41946".
Definition: URI.h:37
clang::clangd::URI::scheme
llvm::StringRef scheme() const
Returns decoded scheme e.g. "https".
Definition: URI.h:33
clang::clangd::URI::toString
std::string toString() const
Returns a string URI with all components percent-encoded.
Definition: URI.cpp:160
clang::clangd::URI::resolve
static llvm::Expected< std::string > resolve(const URI &U, llvm::StringRef HintPath="")
Resolves the absolute path of U.
Definition: URI.cpp:244
clang::clangd::URI::authority
llvm::StringRef authority() const
Returns decoded authority e.g. "reviews.lvm.org".
Definition: URI.h:35
clang::clangd::URI::operator==
friend bool operator==(const URI &LHS, const URI &RHS)
Definition: URI.h:87
clang::clangd::URI::parse
static llvm::Expected< URI > parse(llvm::StringRef Uri)
Parse a URI string "<scheme>:[//<authority>/]<path>".
Definition: URI.cpp:176
clang::clangd::URISchemeRegistry
llvm::Registry< URIScheme > URISchemeRegistry
By default, a "file" scheme is supported where URI paths are always absolute in the file system.
Definition: URI.h:131
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
Generated on Wed Nov 20 2024 18:25:01 for clang-tools by doxygen 1.9.6