clang-tools  9.0.0
FileDistance.h
Go to the documentation of this file.
1 //===--- FileDistance.h - File proximity scoring -----------------*- 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 // This library measures the distance between file paths.
10 // It's used for ranking symbols, e.g. in code completion.
11 // |foo/bar.h -> foo/bar.h| = 0.
12 // |foo/bar.h -> foo/baz.h| < |foo/bar.h -> baz.h|.
13 // This is an edit-distance, where edits go up or down the directory tree.
14 // It's not symmetrical, the costs of going up and down may not match.
15 //
16 // Dealing with multiple sources:
17 // In practice we care about the distance from a source file, but files near
18 // its main-header and #included files are considered "close".
19 // So we start with a set of (anchor, cost) pairs, and call the distance to a
20 // path the minimum of `cost + |source -> path|`.
21 //
22 // We allow each source to limit the number of up-traversals paths may start
23 // with. Up-traversals may reach things that are not "semantically near".
24 //
25 // Symbol URI schemes:
26 // Symbol locations may be represented by URIs rather than file paths directly.
27 // In this case we want to perform distance computations in URI space rather
28 // than in file-space, without performing redundant conversions.
29 // Therefore we have a lookup structure that accepts URIs, so that intermediate
30 // calculations for the same scheme can be reused.
31 //
32 // Caveats:
33 // Assuming up and down traversals each have uniform costs is simplistic.
34 // Often there are "semantic roots" whose children are almost unrelated.
35 // (e.g. /usr/include/, or / in an umbrella repository). We ignore this.
36 //
37 //===----------------------------------------------------------------------===//
38 
39 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_FILEDISTANCE_H
40 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_FILEDISTANCE_H
41 
42 #include "URI.h"
43 #include "llvm/ADT/DenseMap.h"
44 #include "llvm/ADT/DenseMapInfo.h"
45 #include "llvm/ADT/SmallString.h"
46 #include "llvm/ADT/StringRef.h"
47 #include "llvm/Support/Allocator.h"
48 #include "llvm/Support/Path.h"
49 #include "llvm/Support/StringSaver.h"
50 #include <memory>
51 
52 namespace clang {
53 namespace clangd {
54 
56  unsigned UpCost = 2; // |foo/bar.h -> foo|
57  unsigned DownCost = 1; // |foo -> foo/bar.h|
58  unsigned IncludeCost = 2; // |foo.cc -> included_header.h|
59  bool AllowDownTraversalFromRoot = true; // | / -> /a |
60 };
61 
62 struct SourceParams {
63  // Base cost for paths starting at this source.
64  unsigned Cost = 0;
65  // Limits the number of upwards traversals allowed from this source.
66  unsigned MaxUpTraversals = std::numeric_limits<unsigned>::max();
67 };
68 
69 // Supports lookups to find the minimum distance to a file from any source.
70 // This object should be reused, it memoizes intermediate computations.
71 class FileDistance {
72 public:
73  static constexpr unsigned Unreachable = std::numeric_limits<unsigned>::max();
74  static const llvm::hash_code RootHash;
75 
76  FileDistance(llvm::StringMap<SourceParams> Sources,
77  const FileDistanceOptions &Opts = {});
78 
79  // Computes the minimum distance from any source to the file path.
80  unsigned distance(llvm::StringRef Path);
81 
82 private:
83  // Costs computed so far. Always contains sources and their ancestors.
84  // We store hash codes only. Collisions are rare and consequences aren't dire.
85  llvm::DenseMap<llvm::hash_code, unsigned> Cache;
87 };
88 
89 // Supports lookups like FileDistance, but the lookup keys are URIs.
90 // We convert each of the sources to the scheme of the URI and do a FileDistance
91 // comparison on the bodies.
92 class URIDistance {
93 public:
94  // \p Sources must contain absolute paths, not URIs.
95  URIDistance(llvm::StringMap<SourceParams> Sources,
96  const FileDistanceOptions &Opts = {})
97  : Sources(Sources), Opts(Opts) {}
98 
99  // Computes the minimum distance from any source to the URI.
100  // Only sources that can be mapped into the URI's scheme are considered.
101  unsigned distance(llvm::StringRef URI);
102 
103 private:
104  // Returns the FileDistance for a URI scheme, creating it if needed.
105  FileDistance &forScheme(llvm::StringRef Scheme);
106 
107  // We cache the results using the original strings so we can skip URI parsing.
108  llvm::DenseMap<llvm::hash_code, unsigned> Cache;
109  llvm::StringMap<SourceParams> Sources;
110  llvm::StringMap<std::unique_ptr<FileDistance>> ByScheme;
111  FileDistanceOptions Opts;
112 };
113 
114 /// Support lookups like FileDistance, but the lookup keys are symbol scopes.
115 /// For example, a scope "na::nb::" is converted to "/na/nb".
117 public:
118  /// QueryScopes[0] is the preferred scope.
119  ScopeDistance(llvm::ArrayRef<std::string> QueryScopes);
120 
121  unsigned distance(llvm::StringRef SymbolScope);
122 
123 private:
124  FileDistance Distance;
125 };
126 
127 } // namespace clangd
128 } // namespace clang
129 
130 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_FILEDISTANCE_H
URIDistance(llvm::StringMap< SourceParams > Sources, const FileDistanceOptions &Opts={})
Definition: FileDistance.h:95
std::string Path
A typedef to represent a file path.
Definition: Path.h:20
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Support lookups like FileDistance, but the lookup keys are symbol scopes.
Definition: FileDistance.h:116
A URI describes the location of a source file.
Definition: URI.h:28
static const llvm::hash_code RootHash
Definition: FileDistance.h:74