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