• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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   // Reads fragments from YAML files found relative to ancestors of Params.Path.
74   //
75   // All fragments that exist are returned, starting from distant ancestors.
76   // For instance, given RelPath of ".clangd", then for source file /foo/bar.cc,
77   // the searched fragments are [/.clangd, /foo/.clangd].
78   //
79   // If Params does not specify a path, no fragments are returned.
80   static std::unique_ptr<Provider>
81   fromAncestorRelativeYAMLFiles(llvm::StringRef RelPath, const ThreadsafeFS &);
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
108