clang-tools-extra/clangd/ConfigProvider.h

   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