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