| 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 |