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