clang-tools  7.0.0
URI.h
Go to the documentation of this file.
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"
34  llvm::StringRef scheme() const { return Scheme; }
35  /// Returns decoded authority e.g. "reviews.lvm.org"
36  llvm::StringRef authority() const { return Authority; }
37  /// Returns decoded body e.g. "/D41946"
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.
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
friend bool operator==(const URI &LHS, const URI &RHS)
Definition: URI.h:73
URIScheme is an extension point for teaching clangd to recognize a custom URI scheme.
Definition: URI.h:94
virtual llvm::Expected< std::string > getIncludeSpelling(const URI &U) const
Returns the include path of the file (e.g.
Definition: URI.h:110
llvm::StringRef authority() const
Returns decoded authority e.g. "reviews.lvm.org".
Definition: URI.h:36
static URI createFile(llvm::StringRef AbsolutePath)
This creates a file:// URI for AbsolutePath. The path must be absolute.
Definition: URI.cpp:184
llvm::Registry< URIScheme > URISchemeRegistry
By default, a "file" scheme is supported where URI paths are always absolute in the file system...
Definition: URI.h:117
llvm::StringRef scheme() const
Returns decoded scheme e.g. "https".
Definition: URI.h:34
llvm::StringRef body() const
Returns decoded body e.g. "/D41946".
Definition: URI.h:38
static llvm::Expected< URI > create(llvm::StringRef AbsolutePath, llvm::StringRef Scheme)
Creates a URI for a file in the given scheme.
Definition: URI.cpp:174
friend bool operator<(const URI &LHS, const URI &RHS)
Definition: URI.h:78
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
A URI describes the location of a source file.
Definition: URI.h:29
static llvm::Expected< std::string > resolve(const URI &U, llvm::StringRef HintPath="")
Resolves the absolute path of U.
Definition: URI.cpp:191
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:199
static llvm::Expected< URI > parse(llvm::StringRef Uri)
Parse a URI string "<scheme>:[//<authority>/]<path>".
Definition: URI.cpp:156
std::string toString() const
Returns a string URI with all components percent-encoded.
Definition: URI.cpp:141