clang-tools  16.0.0git
ConfigProvider.h
Go to the documentation of this file.
1 //===--- ConfigProvider.h - Loading of user configuration --------*- 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 // Various clangd features have configurable behaviour (or can be disabled).
10 // The configuration system allows users to control this:
11 // - in a user config file, a project config file, via LSP, or via flags
12 // - specifying different settings for different files
13 // This file defines the structures used for this, that produce a Config.
14 //
15 //===----------------------------------------------------------------------===//
16 
17 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_CONFIGPROVIDER_H
18 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_CONFIGPROVIDER_H
19 
20 #include "llvm/ADT/StringRef.h"
21 #include "llvm/Support/SourceMgr.h"
22 #include <chrono>
23 #include <string>
24 #include <vector>
25 
26 namespace clang {
27 namespace clangd {
28 struct Config;
29 class ThreadsafeFS;
30 namespace config {
31 
32 /// Describes the context used to evaluate configuration fragments.
33 struct Params {
34  /// Absolute path to a source file we're applying the config to. Unix slashes.
35  /// Empty if not configuring a particular file.
36  llvm::StringRef Path;
37  /// Hint that stale data is OK to improve performance (e.g. avoid IO).
38  /// FreshTime sets a bound for how old the data can be.
39  /// By default, providers should validate caches against the data source.
40  std::chrono::steady_clock::time_point FreshTime =
41  std::chrono::steady_clock::time_point::max();
42 };
43 
44 /// Used to report problems in parsing or interpreting a config.
45 /// Errors reflect structurally invalid config that should be user-visible.
46 /// Warnings reflect e.g. unknown properties that are recoverable.
47 /// Notes are used to report files and fragments.
48 /// (This can be used to track when previous warnings/errors have been "fixed").
49 using DiagnosticCallback = llvm::function_ref<void(const llvm::SMDiagnostic &)>;
50 
51 /// A chunk of configuration that has been fully analyzed and is ready to apply.
52 /// Typically this is obtained from a Fragment by calling Fragment::compile().
53 ///
54 /// Calling it updates the configuration to reflect settings from the fragment.
55 /// Returns true if the condition was met and the settings were used.
56 using CompiledFragment = std::function<bool(const Params &, Config &)>;
57 
58 /// A source of configuration fragments.
59 /// Generally these providers reflect a fixed policy for obtaining config,
60 /// but return different concrete configuration over time.
61 /// e.g. a provider that reads config from files is responsive to file changes.
62 class Provider {
63 public:
64  virtual ~Provider() = default;
65 
66  /// Reads fragments from a single YAML file with a fixed path. If non-empty,
67  /// Directory will be used to resolve relative paths in the fragments.
68  static std::unique_ptr<Provider> fromYAMLFile(llvm::StringRef AbsPath,
69  llvm::StringRef Directory,
70  const ThreadsafeFS &,
71  bool Trusted = false);
72  // Reads fragments from YAML files found relative to ancestors of Params.Path.
73  //
74  // All fragments that exist are returned, starting from distant ancestors.
75  // For instance, given RelPath of ".clangd", then for source file /foo/bar.cc,
76  // the searched fragments are [/.clangd, /foo/.clangd].
77  //
78  // If Params does not specify a path, no fragments are returned.
79  static std::unique_ptr<Provider>
80  fromAncestorRelativeYAMLFiles(llvm::StringRef RelPath, const ThreadsafeFS &,
81  bool Trusted = false);
82 
83  /// A provider that includes fragments from all the supplied providers.
84  /// Order is preserved; later providers take precedence over earlier ones.
85  static std::unique_ptr<Provider> combine(std::vector<const Provider *>);
86 
87  /// Build a config based on this provider.
88  Config getConfig(const Params &, DiagnosticCallback) const;
89 
90 private:
91  /// Provide fragments that may be relevant to the file.
92  /// The configuration provider is not responsible for testing conditions.
93  ///
94  /// Providers are expected to cache compiled fragments, and only
95  /// reparse/recompile when the source data has changed.
96  /// Despite the need for caching, this function must be threadsafe.
97  ///
98  /// When parsing/compiling, the DiagnosticCallback is used to report errors.
99  virtual std::vector<CompiledFragment>
100  getFragments(const Params &, DiagnosticCallback) const = 0;
101 };
102 
103 } // namespace config
104 } // namespace clangd
105 } // namespace clang
106 
107 #endif
clang::clangd::config::Params::FreshTime
std::chrono::steady_clock::time_point FreshTime
Hint that stale data is OK to improve performance (e.g.
Definition: ConfigProvider.h:40
clang::clangd::Config
Settings that express user/project preferences and control clangd behavior.
Definition: Config.h:44
clang::clangd::config::Provider
A source of configuration fragments.
Definition: ConfigProvider.h:62
Trusted
bool Trusted
Definition: ConfigCompile.cpp:104
Config
static cl::opt< std::string > Config("config", cl::desc(R"( Specifies a configuration in YAML/JSON format: -config="{Checks:' *', CheckOptions:{x:y}}" When the value is empty, clang-tidy will attempt to find a file named .clang-tidy for each source file in its parent directories. )"), cl::init(""), cl::cat(ClangTidyCategory))
Directory
llvm::StringRef Directory
Definition: Serialization.cpp:422
clang::clangd::config::Provider::getConfig
Config getConfig(const Params &, DiagnosticCallback) const
Build a config based on this provider.
Definition: ConfigProvider.cpp:168
clang::clangd::config::Provider::fromAncestorRelativeYAMLFiles
static std::unique_ptr< Provider > fromAncestorRelativeYAMLFiles(llvm::StringRef RelPath, const ThreadsafeFS &, bool Trusted=false)
Definition: ConfigProvider.cpp:83
clang::clangd::config::CompiledFragment
std::function< bool(const Params &, Config &)> CompiledFragment
A chunk of configuration that has been fully analyzed and is ready to apply.
Definition: ConfigProvider.h:56
clang::clangd::config::Provider::fromYAMLFile
static std::unique_ptr< Provider > fromYAMLFile(llvm::StringRef AbsPath, llvm::StringRef Directory, const ThreadsafeFS &, bool Trusted=false)
Reads fragments from a single YAML file with a fixed path.
Definition: ConfigProvider.cpp:55
clang::clangd::config::Provider::combine
static std::unique_ptr< Provider > combine(std::vector< const Provider * >)
A provider that includes fragments from all the supplied providers.
Definition: ConfigProvider.cpp:146
clang::clangd::config::Provider::~Provider
virtual ~Provider()=default
clang::clangd::ThreadsafeFS
Wrapper for vfs::FileSystem for use in multithreaded programs like clangd.
Definition: ThreadsafeFS.h:27
clang::clangd::config::Params
Describes the context used to evaluate configuration fragments.
Definition: ConfigProvider.h:33
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::config::Params::Path
llvm::StringRef Path
Absolute path to a source file we're applying the config to.
Definition: ConfigProvider.h:36
clang::clangd::config::DiagnosticCallback
llvm::function_ref< void(const llvm::SMDiagnostic &)> DiagnosticCallback
Used to report problems in parsing or interpreting a config.
Definition: ConfigProvider.h:49