clang-tools  8.0.0
Protocol.h
Go to the documentation of this file.
1 //===--- Protocol.h - Language Server Protocol Implementation ---*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file contains structs based on the LSP specification at
11 // https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md
12 //
13 // This is not meant to be a complete implementation, new interfaces are added
14 // when they're needed.
15 //
16 // Each struct has a toJSON and fromJSON function, that converts between
17 // the struct and a JSON representation. (See JSON.h)
18 //
19 // Some structs also have operator<< serialization. This is for debugging and
20 // tests, and is not generally machine-readable.
21 //
22 //===----------------------------------------------------------------------===//
23 
24 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_PROTOCOL_H
25 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_PROTOCOL_H
26 
27 #include "URI.h"
28 #include "index/SymbolID.h"
29 #include "llvm/ADT/Optional.h"
30 #include "llvm/Support/JSON.h"
31 #include <bitset>
32 #include <string>
33 #include <vector>
34 
35 namespace clang {
36 namespace clangd {
37 
38 enum class ErrorCode {
39  // Defined by JSON RPC.
40  ParseError = -32700,
41  InvalidRequest = -32600,
42  MethodNotFound = -32601,
43  InvalidParams = -32602,
44  InternalError = -32603,
45 
46  ServerNotInitialized = -32002,
47  UnknownErrorCode = -32001,
48 
49  // Defined by the protocol.
50  RequestCancelled = -32800,
51 };
52 // Models an LSP error as an llvm::Error.
53 class LSPError : public llvm::ErrorInfo<LSPError> {
54 public:
55  std::string Message;
57  static char ID;
58 
59  LSPError(std::string Message, ErrorCode Code)
60  : Message(std::move(Message)), Code(Code) {}
61 
62  void log(llvm::raw_ostream &OS) const override {
63  OS << int(Code) << ": " << Message;
64  }
65  std::error_code convertToErrorCode() const override {
66  return llvm::inconvertibleErrorCode();
67  }
68 };
69 
70 // URI in "file" scheme for a file.
71 struct URIForFile {
72  URIForFile() = default;
73 
74  /// Canonicalizes \p AbsPath via URI.
75  ///
76  /// File paths in URIForFile can come from index or local AST. Path from
77  /// index goes through URI transformation, and the final path is resolved by
78  /// URI scheme and could potentially be different from the original path.
79  /// Hence, we do the same transformation for all paths.
80  ///
81  /// Files can be referred to by several paths (e.g. in the presence of links).
82  /// Which one we prefer may depend on where we're coming from. \p TUPath is a
83  /// hint, and should usually be the main entrypoint file we're processing.
84  static URIForFile canonicalize(llvm::StringRef AbsPath,
85  llvm::StringRef TUPath);
86 
87  static llvm::Expected<URIForFile> fromURI(const URI &U,
88  llvm::StringRef HintPath);
89 
90  /// Retrieves absolute path to the file.
91  llvm::StringRef file() const { return File; }
92 
93  explicit operator bool() const { return !File.empty(); }
94  std::string uri() const { return URI::createFile(File).toString(); }
95 
96  friend bool operator==(const URIForFile &LHS, const URIForFile &RHS) {
97  return LHS.File == RHS.File;
98  }
99 
100  friend bool operator!=(const URIForFile &LHS, const URIForFile &RHS) {
101  return !(LHS == RHS);
102  }
103 
104  friend bool operator<(const URIForFile &LHS, const URIForFile &RHS) {
105  return LHS.File < RHS.File;
106  }
107 
108 private:
109  explicit URIForFile(std::string &&File) : File(std::move(File)) {}
110 
111  std::string File;
112 };
113 
114 /// Serialize/deserialize \p URIForFile to/from a string URI.
115 llvm::json::Value toJSON(const URIForFile &U);
116 bool fromJSON(const llvm::json::Value &, URIForFile &);
117 
119  /// The text document's URI.
121 };
122 llvm::json::Value toJSON(const TextDocumentIdentifier &);
123 bool fromJSON(const llvm::json::Value &, TextDocumentIdentifier &);
124 
125 struct Position {
126  /// Line position in a document (zero-based).
127  int line = 0;
128 
129  /// Character offset on a line in a document (zero-based).
130  /// WARNING: this is in UTF-16 codepoints, not bytes or characters!
131  /// Use the functions in SourceCode.h to construct/interpret Positions.
132  int character = 0;
133 
134  friend bool operator==(const Position &LHS, const Position &RHS) {
135  return std::tie(LHS.line, LHS.character) ==
136  std::tie(RHS.line, RHS.character);
137  }
138  friend bool operator!=(const Position &LHS, const Position &RHS) {
139  return !(LHS == RHS);
140  }
141  friend bool operator<(const Position &LHS, const Position &RHS) {
142  return std::tie(LHS.line, LHS.character) <
143  std::tie(RHS.line, RHS.character);
144  }
145  friend bool operator<=(const Position &LHS, const Position &RHS) {
146  return std::tie(LHS.line, LHS.character) <=
147  std::tie(RHS.line, RHS.character);
148  }
149 };
150 bool fromJSON(const llvm::json::Value &, Position &);
151 llvm::json::Value toJSON(const Position &);
152 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const Position &);
153 
154 struct Range {
155  /// The range's start position.
157 
158  /// The range's end position.
160 
161  friend bool operator==(const Range &LHS, const Range &RHS) {
162  return std::tie(LHS.start, LHS.end) == std::tie(RHS.start, RHS.end);
163  }
164  friend bool operator!=(const Range &LHS, const Range &RHS) {
165  return !(LHS == RHS);
166  }
167  friend bool operator<(const Range &LHS, const Range &RHS) {
168  return std::tie(LHS.start, LHS.end) < std::tie(RHS.start, RHS.end);
169  }
170 
171  bool contains(Position Pos) const { return start <= Pos && Pos < end; }
172  bool contains(Range Rng) const {
173  return start <= Rng.start && Rng.end <= end;
174  }
175 };
176 bool fromJSON(const llvm::json::Value &, Range &);
177 llvm::json::Value toJSON(const Range &);
178 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const Range &);
179 
180 struct Location {
181  /// The text document's URI.
184 
185  friend bool operator==(const Location &LHS, const Location &RHS) {
186  return LHS.uri == RHS.uri && LHS.range == RHS.range;
187  }
188 
189  friend bool operator!=(const Location &LHS, const Location &RHS) {
190  return !(LHS == RHS);
191  }
192 
193  friend bool operator<(const Location &LHS, const Location &RHS) {
194  return std::tie(LHS.uri, LHS.range) < std::tie(RHS.uri, RHS.range);
195  }
196 };
197 llvm::json::Value toJSON(const Location &);
198 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const Location &);
199 
200 struct TextEdit {
201  /// The range of the text document to be manipulated. To insert
202  /// text into a document create a range where start === end.
204 
205  /// The string to be inserted. For delete operations use an
206  /// empty string.
207  std::string newText;
208 
209  bool operator==(const TextEdit &rhs) const {
210  return newText == rhs.newText && range == rhs.range;
211  }
212 };
213 bool fromJSON(const llvm::json::Value &, TextEdit &);
214 llvm::json::Value toJSON(const TextEdit &);
215 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const TextEdit &);
216 
218  /// The text document's URI.
220 
221  /// The text document's language identifier.
222  std::string languageId;
223 
224  /// The version number of this document (it will strictly increase after each
225  int version = 0;
226 
227  /// The content of the opened text document.
228  std::string text;
229 };
230 bool fromJSON(const llvm::json::Value &, TextDocumentItem &);
231 
232 enum class TraceLevel {
233  Off = 0,
234  Messages = 1,
235  Verbose = 2,
236 };
237 bool fromJSON(const llvm::json::Value &E, TraceLevel &Out);
238 
239 struct NoParams {};
240 inline bool fromJSON(const llvm::json::Value &, NoParams &) { return true; }
243 
244 /// Defines how the host (editor) should sync document changes to the language
245 /// server.
247  /// Documents should not be synced at all.
248  None = 0,
249 
250  /// Documents are synced by always sending the full content of the document.
251  Full = 1,
252 
253  /// Documents are synced by sending the full content on open. After that
254  /// only incremental updates to the document are send.
255  Incremental = 2,
256 };
257 
258 /// The kind of a completion entry.
259 enum class CompletionItemKind {
260  Missing = 0,
261  Text = 1,
262  Method = 2,
263  Function = 3,
264  Constructor = 4,
265  Field = 5,
266  Variable = 6,
267  Class = 7,
268  Interface = 8,
269  Module = 9,
270  Property = 10,
271  Unit = 11,
272  Value = 12,
273  Enum = 13,
274  Keyword = 14,
275  Snippet = 15,
276  Color = 16,
277  File = 17,
278  Reference = 18,
279  Folder = 19,
280  EnumMember = 20,
281  Constant = 21,
282  Struct = 22,
283  Event = 23,
284  Operator = 24,
285  TypeParameter = 25,
286 };
287 bool fromJSON(const llvm::json::Value &, CompletionItemKind &);
288 constexpr auto CompletionItemKindMin =
289  static_cast<size_t>(CompletionItemKind::Text);
290 constexpr auto CompletionItemKindMax =
291  static_cast<size_t>(CompletionItemKind::TypeParameter);
292 using CompletionItemKindBitset = std::bitset<CompletionItemKindMax + 1>;
293 bool fromJSON(const llvm::json::Value &, CompletionItemKindBitset &);
296  CompletionItemKindBitset &supportedCompletionItemKinds);
297 
298 /// A symbol kind.
299 enum class SymbolKind {
300  File = 1,
301  Module = 2,
302  Namespace = 3,
303  Package = 4,
304  Class = 5,
305  Method = 6,
306  Property = 7,
307  Field = 8,
308  Constructor = 9,
309  Enum = 10,
310  Interface = 11,
311  Function = 12,
312  Variable = 13,
313  Constant = 14,
314  String = 15,
315  Number = 16,
316  Boolean = 17,
317  Array = 18,
318  Object = 19,
319  Key = 20,
320  Null = 21,
321  EnumMember = 22,
322  Struct = 23,
323  Event = 24,
324  Operator = 25,
325  TypeParameter = 26
326 };
327 bool fromJSON(const llvm::json::Value &, SymbolKind &);
328 constexpr auto SymbolKindMin = static_cast<size_t>(SymbolKind::File);
329 constexpr auto SymbolKindMax = static_cast<size_t>(SymbolKind::TypeParameter);
330 using SymbolKindBitset = std::bitset<SymbolKindMax + 1>;
331 bool fromJSON(const llvm::json::Value &, SymbolKindBitset &);
333  SymbolKindBitset &supportedSymbolKinds);
334 
335 // This struct doesn't mirror LSP!
336 // The protocol defines deeply nested structures for client capabilities.
337 // Instead of mapping them all, this just parses out the bits we care about.
339  /// The supported set of SymbolKinds for workspace/symbol.
340  /// workspace.symbol.symbolKind.valueSet
341  llvm::Optional<SymbolKindBitset> WorkspaceSymbolKinds;
342 
343  /// Whether the client accepts diagnostics with codeActions attached inline.
344  /// textDocument.publishDiagnostics.codeActionsInline.
345  bool DiagnosticFixes = false;
346 
347  /// Whether the client accepts diagnostics with category attached to it
348  /// using the "category" extension.
349  /// textDocument.publishDiagnostics.categorySupport
350  bool DiagnosticCategory = false;
351 
352  /// Client supports snippets as insert text.
353  /// textDocument.completion.completionItem.snippetSupport
354  bool CompletionSnippets = false;
355 
356  /// Client supports hierarchical document symbols.
357  bool HierarchicalDocumentSymbol = false;
358 
359  /// The supported set of CompletionItemKinds for textDocument/completion.
360  /// textDocument.completion.completionItemKind.valueSet
361  llvm::Optional<CompletionItemKindBitset> CompletionItemKinds;
362 
363  /// Client supports CodeAction return value for textDocument/codeAction.
364  /// textDocument.codeAction.codeActionLiteralSupport.
365  bool CodeActionStructure = false;
366 };
367 bool fromJSON(const llvm::json::Value &, ClientCapabilities &);
368 
369 /// Clangd extension that's used in the 'compilationDatabaseChanges' in
370 /// workspace/didChangeConfiguration to record updates to the in-memory
371 /// compilation database.
373  std::string workingDirectory;
374  std::vector<std::string> compilationCommand;
375 };
376 bool fromJSON(const llvm::json::Value &, ClangdCompileCommand &);
377 
378 /// Clangd extension: parameters configurable at any time, via the
379 /// `workspace/didChangeConfiguration` notification.
380 /// LSP defines this type as `any`.
382  // Changes to the in-memory compilation database.
383  // The key of the map is a file name.
384  std::map<std::string, ClangdCompileCommand> compilationDatabaseChanges;
385 };
386 bool fromJSON(const llvm::json::Value &, ConfigurationSettings &);
387 
388 /// Clangd extension: parameters configurable at `initialize` time.
389 /// LSP defines this type as `any`.
391  // What we can change throught the didChangeConfiguration request, we can
392  // also set through the initialize request (initializationOptions field).
394 
395  llvm::Optional<std::string> compilationDatabasePath;
396  // Additional flags to be included in the "fallback command" used when
397  // the compilation database doesn't describe an opened file.
398  // The command used will be approximately `clang $FILE $fallbackFlags`.
399  std::vector<std::string> fallbackFlags;
400 
401  /// Clients supports show file status for textDocument/clangd.fileStatus.
402  bool FileStatus = false;
403 };
404 bool fromJSON(const llvm::json::Value &, InitializationOptions &);
405 
407  /// The process Id of the parent process that started
408  /// the server. Is null if the process has not been started by another
409  /// process. If the parent process is not alive then the server should exit
410  /// (see exit notification) its process.
411  llvm::Optional<int> processId;
412 
413  /// The rootPath of the workspace. Is null
414  /// if no folder is open.
415  ///
416  /// @deprecated in favour of rootUri.
417  llvm::Optional<std::string> rootPath;
418 
419  /// The rootUri of the workspace. Is null if no
420  /// folder is open. If both `rootPath` and `rootUri` are set
421  /// `rootUri` wins.
422  llvm::Optional<URIForFile> rootUri;
423 
424  // User provided initialization options.
425  // initializationOptions?: any;
426 
427  /// The capabilities provided by the client (editor or tool)
429 
430  /// The initial trace setting. If omitted trace is disabled ('off').
431  llvm::Optional<TraceLevel> trace;
432 
433  /// User-provided initialization options.
435 };
436 bool fromJSON(const llvm::json::Value &, InitializeParams &);
437 
439  /// The document that was opened.
441 };
442 bool fromJSON(const llvm::json::Value &, DidOpenTextDocumentParams &);
443 
445  /// The document that was closed.
447 };
448 bool fromJSON(const llvm::json::Value &, DidCloseTextDocumentParams &);
449 
451  /// The range of the document that changed.
452  llvm::Optional<Range> range;
453 
454  /// The length of the range that got replaced.
455  llvm::Optional<int> rangeLength;
456 
457  /// The new text of the range/document.
458  std::string text;
459 };
460 bool fromJSON(const llvm::json::Value &, TextDocumentContentChangeEvent &);
461 
463  /// The document that did change. The version number points
464  /// to the version after all provided content changes have
465  /// been applied.
467 
468  /// The actual content changes.
469  std::vector<TextDocumentContentChangeEvent> contentChanges;
470 
471  /// Forces diagnostics to be generated, or to not be generated, for this
472  /// version of the file. If not set, diagnostics are eventually consistent:
473  /// either they will be provided for this version or some subsequent one.
474  /// This is a clangd extension.
475  llvm::Optional<bool> wantDiagnostics;
476 };
477 bool fromJSON(const llvm::json::Value &, DidChangeTextDocumentParams &);
478 
479 enum class FileChangeType {
480  /// The file got created.
481  Created = 1,
482  /// The file got changed.
483  Changed = 2,
484  /// The file got deleted.
485  Deleted = 3
486 };
487 bool fromJSON(const llvm::json::Value &E, FileChangeType &Out);
488 
489 struct FileEvent {
490  /// The file's URI.
492  /// The change type.
494 };
495 bool fromJSON(const llvm::json::Value &, FileEvent &);
496 
498  /// The actual file events.
499  std::vector<FileEvent> changes;
500 };
501 bool fromJSON(const llvm::json::Value &, DidChangeWatchedFilesParams &);
502 
505 };
506 bool fromJSON(const llvm::json::Value &, DidChangeConfigurationParams &);
507 
509  /// Size of a tab in spaces.
510  int tabSize = 0;
511 
512  /// Prefer spaces over tabs.
513  bool insertSpaces = false;
514 };
515 bool fromJSON(const llvm::json::Value &, FormattingOptions &);
516 llvm::json::Value toJSON(const FormattingOptions &);
517 
519  /// The document to format.
521 
522  /// The range to format
524 
525  /// The format options
527 };
528 bool fromJSON(const llvm::json::Value &, DocumentRangeFormattingParams &);
529 
531  /// The document to format.
533 
534  /// The position at which this request was sent.
536 
537  /// The character that has been typed.
538  std::string ch;
539 
540  /// The format options.
542 };
543 bool fromJSON(const llvm::json::Value &, DocumentOnTypeFormattingParams &);
544 
546  /// The document to format.
548 
549  /// The format options
551 };
552 bool fromJSON(const llvm::json::Value &, DocumentFormattingParams &);
553 
555  // The text document to find symbols in.
557 };
558 bool fromJSON(const llvm::json::Value &, DocumentSymbolParams &);
559 
560 struct CodeAction;
561 struct Diagnostic {
562  /// The range at which the message applies.
564 
565  /// The diagnostic's severity. Can be omitted. If omitted it is up to the
566  /// client to interpret diagnostics as error, warning, info or hint.
567  int severity = 0;
568 
569  /// The diagnostic's code. Can be omitted.
570  /// Note: Not currently used by clangd
571  // std::string code;
572 
573  /// A human-readable string describing the source of this
574  /// diagnostic, e.g. 'typescript' or 'super lint'.
575  /// Note: Not currently used by clangd
576  // std::string source;
577 
578  /// The diagnostic's message.
579  std::string message;
580 
581  /// The diagnostic's category. Can be omitted.
582  /// An LSP extension that's used to send the name of the category over to the
583  /// client. The category typically describes the compilation stage during
584  /// which the issue was produced, e.g. "Semantic Issue" or "Parse Issue".
585  llvm::Optional<std::string> category;
586 
587  /// Clangd extension: code actions related to this diagnostic.
588  /// Only with capability textDocument.publishDiagnostics.codeActionsInline.
589  /// (These actions can also be obtained using textDocument/codeAction).
590  llvm::Optional<std::vector<CodeAction>> codeActions;
591 };
592 llvm::json::Value toJSON(const Diagnostic &);
593 
594 /// A LSP-specific comparator used to find diagnostic in a container like
595 /// std:map.
596 /// We only use the required fields of Diagnostic to do the comparsion to avoid
597 /// any regression issues from LSP clients (e.g. VScode), see
598 /// https://git.io/vbr29
600  bool operator()(const Diagnostic &LHS, const Diagnostic &RHS) const {
601  return std::tie(LHS.range, LHS.message) < std::tie(RHS.range, RHS.message);
602  }
603 };
604 bool fromJSON(const llvm::json::Value &, Diagnostic &);
605 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const Diagnostic &);
606 
608  /// An array of diagnostics.
609  std::vector<Diagnostic> diagnostics;
610 };
611 bool fromJSON(const llvm::json::Value &, CodeActionContext &);
612 
614  /// The document in which the command was invoked.
616 
617  /// The range for which the command was invoked.
619 
620  /// Context carrying additional information.
622 };
623 bool fromJSON(const llvm::json::Value &, CodeActionParams &);
624 
626  /// Holds changes to existing resources.
627  llvm::Optional<std::map<std::string, std::vector<TextEdit>>> changes;
628 
629  /// Note: "documentChanges" is not currently used because currently there is
630  /// no support for versioned edits.
631 };
632 bool fromJSON(const llvm::json::Value &, WorkspaceEdit &);
633 llvm::json::Value toJSON(const WorkspaceEdit &WE);
634 
635 /// Exact commands are not specified in the protocol so we define the
636 /// ones supported by Clangd here. The protocol specifies the command arguments
637 /// to be "any[]" but to make this safer and more manageable, each command we
638 /// handle maps to a certain llvm::Optional of some struct to contain its
639 /// arguments. Different commands could reuse the same llvm::Optional as
640 /// arguments but a command that needs different arguments would simply add a
641 /// new llvm::Optional and not use any other ones. In practice this means only
642 /// one argument type will be parsed and set.
644  // Command to apply fix-its. Uses WorkspaceEdit as argument.
645  const static llvm::StringLiteral CLANGD_APPLY_FIX_COMMAND;
646 
647  /// The command identifier, e.g. CLANGD_APPLY_FIX_COMMAND
648  std::string command;
649 
650  // Arguments
651  llvm::Optional<WorkspaceEdit> workspaceEdit;
652 };
653 bool fromJSON(const llvm::json::Value &, ExecuteCommandParams &);
654 
655 struct Command : public ExecuteCommandParams {
656  std::string title;
657 };
658 llvm::json::Value toJSON(const Command &C);
659 
660 /// A code action represents a change that can be performed in code, e.g. to fix
661 /// a problem or to refactor code.
662 ///
663 /// A CodeAction must set either `edit` and/or a `command`. If both are
664 /// supplied, the `edit` is applied first, then the `command` is executed.
665 struct CodeAction {
666  /// A short, human-readable, title for this code action.
667  std::string title;
668 
669  /// The kind of the code action.
670  /// Used to filter code actions.
671  llvm::Optional<std::string> kind;
672  const static llvm::StringLiteral QUICKFIX_KIND;
673 
674  /// The diagnostics that this code action resolves.
675  llvm::Optional<std::vector<Diagnostic>> diagnostics;
676 
677  /// The workspace edit this code action performs.
678  llvm::Optional<WorkspaceEdit> edit;
679 
680  /// A command this code action executes. If a code action provides an edit
681  /// and a command, first the edit is executed and then the command.
682  llvm::Optional<Command> command;
683 };
684 llvm::json::Value toJSON(const CodeAction &);
685 
686 /// Represents programming constructs like variables, classes, interfaces etc.
687 /// that appear in a document. Document symbols can be hierarchical and they
688 /// have two ranges: one that encloses its definition and one that points to its
689 /// most interesting range, e.g. the range of an identifier.
691  /// The name of this symbol.
692  std::string name;
693 
694  /// More detail for this symbol, e.g the signature of a function.
695  std::string detail;
696 
697  /// The kind of this symbol.
699 
700  /// Indicates if this symbol is deprecated.
702 
703  /// The range enclosing this symbol not including leading/trailing whitespace
704  /// but everything else like comments. This information is typically used to
705  /// determine if the clients cursor is inside the symbol to reveal in the
706  /// symbol in the UI.
708 
709  /// The range that should be selected and revealed when this symbol is being
710  /// picked, e.g the name of a function. Must be contained by the `range`.
712 
713  /// Children of this symbol, e.g. properties of a class.
714  std::vector<DocumentSymbol> children;
715 };
716 llvm::raw_ostream &operator<<(llvm::raw_ostream &O, const DocumentSymbol &S);
717 llvm::json::Value toJSON(const DocumentSymbol &S);
718 
719 /// Represents information about programming constructs like variables, classes,
720 /// interfaces etc.
722  /// The name of this symbol.
723  std::string name;
724 
725  /// The kind of this symbol.
727 
728  /// The location of this symbol.
730 
731  /// The name of the symbol containing this symbol.
732  std::string containerName;
733 };
734 llvm::json::Value toJSON(const SymbolInformation &);
735 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const SymbolInformation &);
736 
737 /// Represents information about identifier.
738 /// This is returned from textDocument/symbolInfo, which is a clangd extension.
740  std::string name;
741 
742  std::string containerName;
743 
744  /// Unified Symbol Resolution identifier
745  /// This is an opaque string uniquely identifying a symbol.
746  /// Unlike SymbolID, it is variable-length and somewhat human-readable.
747  /// It is a common representation across several clang tools.
748  /// (See USRGeneration.h)
749  std::string USR;
750 
751  llvm::Optional<SymbolID> ID;
752 };
753 llvm::json::Value toJSON(const SymbolDetails &);
754 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const SymbolDetails &);
755 bool operator==(const SymbolDetails &, const SymbolDetails &);
756 
757 /// The parameters of a Workspace Symbol Request.
759  /// A non-empty query string
760  std::string query;
761 };
762 bool fromJSON(const llvm::json::Value &, WorkspaceSymbolParams &);
763 
766 };
767 llvm::json::Value toJSON(const ApplyWorkspaceEditParams &);
768 
770  /// The text document.
772 
773  /// The position inside the text document.
775 };
776 bool fromJSON(const llvm::json::Value &, TextDocumentPositionParams &);
777 
779  /// Completion was triggered by typing an identifier (24x7 code
780  /// complete), manual invocation (e.g Ctrl+Space) or via API.
781  Invoked = 1,
782  /// Completion was triggered by a trigger character specified by
783  /// the `triggerCharacters` properties of the `CompletionRegistrationOptions`.
784  TriggerCharacter = 2,
785  /// Completion was re-triggered as the current completion list is incomplete.
787 };
788 
790  /// How the completion was triggered.
792  /// The trigger character (a single character) that has trigger code complete.
793  /// Is undefined if `triggerKind !== CompletionTriggerKind.TriggerCharacter`
794  std::string triggerCharacter;
795 };
796 bool fromJSON(const llvm::json::Value &, CompletionContext &);
797 
800 };
801 bool fromJSON(const llvm::json::Value &, CompletionParams &);
802 
803 enum class MarkupKind {
804  PlainText,
805  Markdown,
806 };
807 
810  std::string value;
811 };
812 llvm::json::Value toJSON(const MarkupContent &MC);
813 
814 struct Hover {
815  /// The hover's content
817 
818  /// An optional range is a range inside a text document
819  /// that is used to visualize a hover, e.g. by changing the background color.
820  llvm::Optional<Range> range;
821 };
822 llvm::json::Value toJSON(const Hover &H);
823 
824 /// Defines whether the insert text in a completion item should be interpreted
825 /// as plain text or a snippet.
826 enum class InsertTextFormat {
827  Missing = 0,
828  /// The primary text to be inserted is treated as a plain string.
829  PlainText = 1,
830  /// The primary text to be inserted is treated as a snippet.
831  ///
832  /// A snippet can define tab stops and placeholders with `$1`, `$2`
833  /// and `${3:foo}`. `$0` defines the final tab stop, it defaults to the end
834  /// of the snippet. Placeholders with equal identifiers are linked, that is
835  /// typing in one will update others too.
836  ///
837  /// See also:
838  /// https//github.com/Microsoft/vscode/blob/master/src/vs/editor/contrib/snippet/common/snippet.md
839  Snippet = 2,
840 };
841 
843  /// The label of this completion item. By default also the text that is
844  /// inserted when selecting this completion.
845  std::string label;
846 
847  /// The kind of this completion item. Based of the kind an icon is chosen by
848  /// the editor.
850 
851  /// A human-readable string with additional information about this item, like
852  /// type or symbol information.
853  std::string detail;
854 
855  /// A human-readable string that represents a doc-comment.
856  std::string documentation;
857 
858  /// A string that should be used when comparing this item with other items.
859  /// When `falsy` the label is used.
860  std::string sortText;
861 
862  /// A string that should be used when filtering a set of completion items.
863  /// When `falsy` the label is used.
864  std::string filterText;
865 
866  /// A string that should be inserted to a document when selecting this
867  /// completion. When `falsy` the label is used.
868  std::string insertText;
869 
870  /// The format of the insert text. The format applies to both the `insertText`
871  /// property and the `newText` property of a provided `textEdit`.
873 
874  /// An edit which is applied to a document when selecting this completion.
875  /// When an edit is provided `insertText` is ignored.
876  ///
877  /// Note: The range of the edit must be a single line range and it must
878  /// contain the position at which completion has been requested.
879  llvm::Optional<TextEdit> textEdit;
880 
881  /// An optional array of additional text edits that are applied when selecting
882  /// this completion. Edits must not overlap with the main edit nor with
883  /// themselves.
884  std::vector<TextEdit> additionalTextEdits;
885 
886  /// Indicates if this item is deprecated.
887  bool deprecated = false;
888 
889  // TODO(krasimir): The following optional fields defined by the language
890  // server protocol are unsupported:
891  //
892  // data?: any - A data entry field that is preserved on a completion item
893  // between a completion and a completion resolve request.
894 };
895 llvm::json::Value toJSON(const CompletionItem &);
896 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const CompletionItem &);
897 
898 bool operator<(const CompletionItem &, const CompletionItem &);
899 
900 /// Represents a collection of completion items to be presented in the editor.
902  /// The list is not complete. Further typing should result in recomputing the
903  /// list.
904  bool isIncomplete = false;
905 
906  /// The completion items.
907  std::vector<CompletionItem> items;
908 };
909 llvm::json::Value toJSON(const CompletionList &);
910 
911 /// A single parameter of a particular signature.
913 
914  /// The label of this parameter. Mandatory.
915  std::string label;
916 
917  /// The documentation of this parameter. Optional.
918  std::string documentation;
919 };
920 llvm::json::Value toJSON(const ParameterInformation &);
921 
922 /// Represents the signature of something callable.
924 
925  /// The label of this signature. Mandatory.
926  std::string label;
927 
928  /// The documentation of this signature. Optional.
929  std::string documentation;
930 
931  /// The parameters of this signature.
932  std::vector<ParameterInformation> parameters;
933 };
934 llvm::json::Value toJSON(const SignatureInformation &);
935 llvm::raw_ostream &operator<<(llvm::raw_ostream &,
936  const SignatureInformation &);
937 
938 /// Represents the signature of a callable.
940 
941  /// The resulting signatures.
942  std::vector<SignatureInformation> signatures;
943 
944  /// The active signature.
945  int activeSignature = 0;
946 
947  /// The active parameter of the active signature.
948  int activeParameter = 0;
949 
950  /// Position of the start of the argument list, including opening paren. e.g.
951  /// foo("first arg", "second arg",
952  /// ^-argListStart ^-cursor
953  /// This is a clangd-specific extension, it is only available via C++ API and
954  /// not currently serialized for the LSP.
956 };
957 llvm::json::Value toJSON(const SignatureHelp &);
958 
959 struct RenameParams {
960  /// The document that was opened.
962 
963  /// The position at which this request was sent.
965 
966  /// The new name of the symbol.
967  std::string newName;
968 };
969 bool fromJSON(const llvm::json::Value &, RenameParams &);
970 
971 enum class DocumentHighlightKind { Text = 1, Read = 2, Write = 3 };
972 
973 /// A document highlight is a range inside a text document which deserves
974 /// special attention. Usually a document highlight is visualized by changing
975 /// the background color of its range.
976 
978  /// The range this highlight applies to.
980 
981  /// The highlight kind, default is DocumentHighlightKind.Text.
983 
984  friend bool operator<(const DocumentHighlight &LHS,
985  const DocumentHighlight &RHS) {
986  int LHSKind = static_cast<int>(LHS.kind);
987  int RHSKind = static_cast<int>(RHS.kind);
988  return std::tie(LHS.range, LHSKind) < std::tie(RHS.range, RHSKind);
989  }
990 
991  friend bool operator==(const DocumentHighlight &LHS,
992  const DocumentHighlight &RHS) {
993  return LHS.kind == RHS.kind && LHS.range == RHS.range;
994  }
995 };
996 llvm::json::Value toJSON(const DocumentHighlight &DH);
997 llvm::raw_ostream &operator<<(llvm::raw_ostream &, const DocumentHighlight &);
998 
1000  // For now, no options like context.includeDeclaration are supported.
1001 };
1002 bool fromJSON(const llvm::json::Value &, ReferenceParams &);
1003 
1004 /// Clangd extension: indicates the current state of the file in clangd,
1005 /// sent from server via the `textDocument/clangd.fileStatus` notification.
1006 struct FileStatus {
1007  /// The text document's URI.
1009  /// The human-readable string presents the current state of the file, can be
1010  /// shown in the UI (e.g. status bar).
1011  std::string state;
1012  // FIXME: add detail messages.
1013 };
1014 llvm::json::Value toJSON(const FileStatus &FStatus);
1015 
1016 } // namespace clangd
1017 } // namespace clang
1018 
1019 namespace llvm {
1020 template <> struct format_provider<clang::clangd::Position> {
1021  static void format(const clang::clangd::Position &Pos, raw_ostream &OS,
1022  StringRef Style) {
1023  assert(Style.empty() && "style modifiers for this type are not supported");
1024  OS << Pos;
1025  }
1026 };
1027 } // namespace llvm
1028 
1029 #endif
std::string insertText
A string that should be inserted to a document when selecting this completion.
Definition: Protocol.h:868
Range range
The range to format.
Definition: Protocol.h:523
std::string USR
Unified Symbol Resolution identifier This is an opaque string uniquely identifying a symbol...
Definition: Protocol.h:749
const tooling::CompileCommand & Command
friend bool operator<(const Location &LHS, const Location &RHS)
Definition: Protocol.h:193
TextDocumentIdentifier textDocument
The document to format.
Definition: Protocol.h:547
URIForFile uri
The file&#39;s URI.
Definition: Protocol.h:491
llvm::json::Value toJSON(const FuzzyFindRequest &Request)
Definition: Index.cpp:189
Location location
The location of this symbol.
Definition: Protocol.h:729
friend bool operator==(const Location &LHS, const Location &RHS)
Definition: Protocol.h:185
llvm::Optional< TextEdit > textEdit
An edit which is applied to a document when selecting this completion.
Definition: Protocol.h:879
Exact commands are not specified in the protocol so we define the ones supported by Clangd here...
Definition: Protocol.h:643
TextDocumentIdentifier textDocument
The document to format.
Definition: Protocol.h:532
llvm::Optional< SymbolKindBitset > WorkspaceSymbolKinds
The supported set of SymbolKinds for workspace/symbol.
Definition: Protocol.h:341
Some operations such as code completion produce a set of candidates.
llvm::Optional< URIForFile > rootUri
The rootUri of the workspace.
Definition: Protocol.h:422
Position start
The range&#39;s start position.
Definition: Protocol.h:156
friend bool operator==(const URIForFile &LHS, const URIForFile &RHS)
Definition: Protocol.h:96
Represents a collection of completion items to be presented in the editor.
Definition: Protocol.h:901
Range range
The range this highlight applies to.
Definition: Protocol.h:979
std::string label
The label of this parameter. Mandatory.
Definition: Protocol.h:915
llvm::Optional< bool > wantDiagnostics
Forces diagnostics to be generated, or to not be generated, for this version of the file...
Definition: Protocol.h:475
friend bool operator<=(const Position &LHS, const Position &RHS)
Definition: Protocol.h:145
std::vector< std::string > compilationCommand
Definition: Protocol.h:374
Range range
The range for which the command was invoked.
Definition: Protocol.h:618
CodeActionContext context
Context carrying additional information.
Definition: Protocol.h:621
static const llvm::StringLiteral CLANGD_APPLY_FIX_COMMAND
Definition: Protocol.h:645
Clangd extension: parameters configurable at initialize time.
Definition: Protocol.h:390
std::string ch
The character that has been typed.
Definition: Protocol.h:538
std::vector< CompletionItem > items
The completion items.
Definition: Protocol.h:907
Documents are synced by always sending the full content of the document.
Documents are synced by sending the full content on open.
llvm::Optional< std::vector< CodeAction > > codeActions
Clangd extension: code actions related to this diagnostic.
Definition: Protocol.h:590
llvm::Optional< std::map< std::string, std::vector< TextEdit > > > changes
Holds changes to existing resources.
Definition: Protocol.h:627
llvm::Optional< std::string > kind
The kind of the code action.
Definition: Protocol.h:671
bool operator==(const SymbolLocation::Position &L, const SymbolLocation::Position &R)
Definition: Index.h:74
bool operator()(const Diagnostic &LHS, const Diagnostic &RHS) const
Definition: Protocol.h:600
std::string title
A short, human-readable, title for this code action.
Definition: Protocol.h:667
llvm::Optional< Range > range
An optional range is a range inside a text document that is used to visualize a hover, e.g.
Definition: Protocol.h:820
TextDocumentIdentifier textDocument
The document that was closed.
Definition: Protocol.h:446
std::string label
The label of this signature. Mandatory.
Definition: Protocol.h:926
std::string state
The human-readable string presents the current state of the file, can be shown in the UI (e...
Definition: Protocol.h:1011
An Event<T> allows events of type T to be broadcast to listeners.
Definition: Function.h:88
A code action represents a change that can be performed in code, e.g.
Definition: Protocol.h:665
friend bool operator!=(const URIForFile &LHS, const URIForFile &RHS)
Definition: Protocol.h:100
URIForFile uri
The text document&#39;s URI.
Definition: Protocol.h:182
std::string text
The new text of the range/document.
Definition: Protocol.h:458
friend bool operator!=(const Position &LHS, const Position &RHS)
Definition: Protocol.h:138
llvm::Optional< WorkspaceEdit > edit
The workspace edit this code action performs.
Definition: Protocol.h:678
Range selectionRange
The range that should be selected and revealed when this symbol is being picked, e.g the name of a function.
Definition: Protocol.h:711
Values in a Context are indexed by typed keys.
Definition: Context.h:41
constexpr auto SymbolKindMin
Definition: Protocol.h:328
llvm::Optional< std::string > compilationDatabasePath
Definition: Protocol.h:395
std::string sortText
A string that should be used when comparing this item with other items.
Definition: Protocol.h:860
constexpr auto CompletionItemKindMin
Definition: Protocol.h:288
std::string title
Definition: Protocol.h:656
friend bool operator!=(const Range &LHS, const Range &RHS)
Definition: Protocol.h:164
std::vector< ParameterInformation > parameters
The parameters of this signature.
Definition: Protocol.h:932
std::bitset< CompletionItemKindMax+1 > CompletionItemKindBitset
Definition: Protocol.h:292
Documents should not be synced at all.
std::string documentation
A human-readable string that represents a doc-comment.
Definition: Protocol.h:856
InsertTextFormat
Defines whether the insert text in a completion item should be interpreted as plain text or a snippet...
Definition: Protocol.h:826
Range range
The range enclosing this symbol not including leading/trailing whitespace but everything else like co...
Definition: Protocol.h:707
URIForFile uri
The text document&#39;s URI.
Definition: Protocol.h:1008
FormattingOptions options
The format options.
Definition: Protocol.h:541
std::vector< TextEdit > additionalTextEdits
An optional array of additional text edits that are applied when selecting this completion.
Definition: Protocol.h:884
constexpr auto CompletionItemKindMax
Definition: Protocol.h:290
Represents programming constructs like variables, classes, interfaces etc.
Definition: Protocol.h:690
llvm::Optional< int > processId
The process Id of the parent process that started the server.
Definition: Protocol.h:411
bool operator==(const TextEdit &rhs) const
Definition: Protocol.h:209
CompletionItemKind
The kind of a completion entry.
Definition: Protocol.h:259
bool operator<(const SymbolLocation::Position &L, const SymbolLocation::Position &R)
Definition: Index.h:79
ConfigurationSettings ConfigSettings
Definition: Protocol.h:393
std::string uri() const
Definition: Protocol.h:94
BindArgumentKind Kind
TextDocumentSyncKind
Defines how the host (editor) should sync document changes to the language server.
Definition: Protocol.h:246
MarkupContent contents
The hover&#39;s content.
Definition: Protocol.h:816
std::error_code convertToErrorCode() const override
Definition: Protocol.h:65
A document highlight is a range inside a text document which deserves special attention.
Definition: Protocol.h:977
URIForFile uri
The text document&#39;s URI.
Definition: Protocol.h:219
std::string detail
A human-readable string with additional information about this item, like type or symbol information...
Definition: Protocol.h:853
llvm::Optional< SymbolID > ID
Definition: Protocol.h:751
LSPError(std::string Message, ErrorCode Code)
Definition: Protocol.h:59
static URI createFile(llvm::StringRef AbsolutePath)
This creates a file:// URI for AbsolutePath. The path must be absolute.
Definition: URI.cpp:217
TextDocumentIdentifier textDocument
The document that was opened.
Definition: Protocol.h:961
std::string newText
The string to be inserted.
Definition: Protocol.h:207
std::string newName
The new name of the symbol.
Definition: Protocol.h:967
Represents the signature of something callable.
Definition: Protocol.h:923
Clangd extension: parameters configurable at any time, via the workspace/didChangeConfiguration notif...
Definition: Protocol.h:381
std::string command
The command identifier, e.g. CLANGD_APPLY_FIX_COMMAND.
Definition: Protocol.h:648
InitializationOptions initializationOptions
User-provided initialization options.
Definition: Protocol.h:434
TextDocumentIdentifier textDocument
Definition: Protocol.h:556
std::string filterText
A string that should be used when filtering a set of completion items.
Definition: Protocol.h:864
friend bool operator<(const Position &LHS, const Position &RHS)
Definition: Protocol.h:141
TextDocumentIdentifier textDocument
The document in which the command was invoked.
Definition: Protocol.h:615
Range range
The range of the text document to be manipulated.
Definition: Protocol.h:203
std::vector< std::string > fallbackFlags
Definition: Protocol.h:399
std::string Message
Definition: Protocol.h:55
friend bool operator<(const Range &LHS, const Range &RHS)
Definition: Protocol.h:167
llvm::Optional< Range > range
The range of the document that changed.
Definition: Protocol.h:452
llvm::Optional< std::string > category
The diagnostic&#39;s category.
Definition: Protocol.h:585
Position position
The position inside the text document.
Definition: Protocol.h:774
std::vector< DocumentSymbol > children
Children of this symbol, e.g. properties of a class.
Definition: Protocol.h:714
Position argListStart
Position of the start of the argument list, including opening paren.
Definition: Protocol.h:955
std::string documentation
The documentation of this parameter. Optional.
Definition: Protocol.h:918
SymbolKind kind
The kind of this symbol.
Definition: Protocol.h:726
std::vector< SignatureInformation > signatures
The resulting signatures.
Definition: Protocol.h:942
llvm::Optional< int > rangeLength
The length of the range that got replaced.
Definition: Protocol.h:455
static llvm::SmallString< 128 > canonicalize(llvm::StringRef Path)
std::string name
The name of this symbol.
Definition: Protocol.h:692
Completion was triggered by typing an identifier (24x7 code complete), manual invocation (e...
ClientCapabilities capabilities
The capabilities provided by the client (editor or tool)
Definition: Protocol.h:428
TextDocumentItem textDocument
The document that was opened.
Definition: Protocol.h:440
TextDocumentIdentifier textDocument
The document that did change.
Definition: Protocol.h:466
std::map< std::string, ClangdCompileCommand > compilationDatabaseChanges
Definition: Protocol.h:384
std::string detail
More detail for this symbol, e.g the signature of a function.
Definition: Protocol.h:695
Completion was triggered by a trigger character specified by the triggerCharacters properties of the ...
std::vector< FileEvent > changes
The actual file events.
Definition: Protocol.h:499
FormattingOptions options
The format options.
Definition: Protocol.h:526
llvm::Optional< CompletionItemKindBitset > CompletionItemKinds
The supported set of CompletionItemKinds for textDocument/completion.
Definition: Protocol.h:361
Position Pos
std::string languageId
The text document&#39;s language identifier.
Definition: Protocol.h:222
llvm::Optional< std::string > rootPath
The rootPath of the workspace.
Definition: Protocol.h:417
Position position
The position at which this request was sent.
Definition: Protocol.h:535
bool fromJSON(const llvm::json::Value &Parameters, FuzzyFindRequest &Request)
Definition: Index.cpp:176
A single parameter of a particular signature.
Definition: Protocol.h:912
A LSP-specific comparator used to find diagnostic in a container like std:map.
Definition: Protocol.h:599
FormattingOptions options
The format options.
Definition: Protocol.h:550
int line
Line position in a document (zero-based).
Definition: Protocol.h:127
std::vector< TextDocumentContentChangeEvent > contentChanges
The actual content changes.
Definition: Protocol.h:469
friend bool operator<(const DocumentHighlight &LHS, const DocumentHighlight &RHS)
Definition: Protocol.h:984
int character
Character offset on a line in a document (zero-based).
Definition: Protocol.h:132
CompletionContext context
Definition: Protocol.h:799
bool contains(Position Pos) const
Definition: Protocol.h:171
Represents the signature of a callable.
Definition: Protocol.h:939
std::string query
A non-empty query string.
Definition: Protocol.h:760
SymbolKind kind
The kind of this symbol.
Definition: Protocol.h:698
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
std::bitset< SymbolKindMax+1 > SymbolKindBitset
Definition: Protocol.h:330
SymbolKind
A symbol kind.
Definition: Protocol.h:299
std::string message
The diagnostic&#39;s code.
Definition: Protocol.h:579
std::string triggerCharacter
The trigger character (a single character) that has trigger code complete.
Definition: Protocol.h:794
TextDocumentIdentifier textDocument
The text document.
Definition: Protocol.h:771
std::string label
The label of this completion item.
Definition: Protocol.h:845
friend bool operator==(const DocumentHighlight &LHS, const DocumentHighlight &RHS)
Definition: Protocol.h:991
DocumentHighlightKind kind
The highlight kind, default is DocumentHighlightKind.Text.
Definition: Protocol.h:982
SymbolKind adjustKindToCapability(SymbolKind Kind, SymbolKindBitset &SupportedSymbolKinds)
Definition: Protocol.cpp:198
static const llvm::StringLiteral QUICKFIX_KIND
Definition: Protocol.h:672
bool contains(Range Rng) const
Definition: Protocol.h:172
A URI describes the location of a source file.
Definition: URI.h:29
std::vector< Diagnostic > diagnostics
An array of diagnostics.
Definition: Protocol.h:609
bool deprecated
Indicates if this symbol is deprecated.
Definition: Protocol.h:701
llvm::Optional< Command > command
A command this code action executes.
Definition: Protocol.h:682
The parameters of a Workspace Symbol Request.
Definition: Protocol.h:758
std::string text
The content of the opened text document.
Definition: Protocol.h:228
Clangd extension: indicates the current state of the file in clangd, sent from server via the textDoc...
Definition: Protocol.h:1006
std::string containerName
The name of the symbol containing this symbol.
Definition: Protocol.h:732
llvm::Optional< std::vector< Diagnostic > > diagnostics
The diagnostics that this code action resolves.
Definition: Protocol.h:675
Position position
The position at which this request was sent.
Definition: Protocol.h:964
URIForFile uri
The text document&#39;s URI.
Definition: Protocol.h:120
friend bool operator!=(const Location &LHS, const Location &RHS)
Definition: Protocol.h:189
Range range
The range at which the message applies.
Definition: Protocol.h:563
friend bool operator<(const URIForFile &LHS, const URIForFile &RHS)
Definition: Protocol.h:104
TextDocumentIdentifier textDocument
The document to format.
Definition: Protocol.h:520
Position end
The range&#39;s end position.
Definition: Protocol.h:159
llvm::Optional< WorkspaceEdit > workspaceEdit
Definition: Protocol.h:651
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
std::string name
The name of this symbol.
Definition: Protocol.h:723
Completion was re-triggered as the current completion list is incomplete.
std::string toString() const
Returns a string URI with all components percent-encoded.
Definition: URI.cpp:151
Clangd extension that&#39;s used in the &#39;compilationDatabaseChanges&#39; in workspace/didChangeConfiguration ...
Definition: Protocol.h:372
friend bool operator==(const Position &LHS, const Position &RHS)
Definition: Protocol.h:134
void log(llvm::raw_ostream &OS) const override
Definition: Protocol.h:62
friend bool operator==(const Range &LHS, const Range &RHS)
Definition: Protocol.h:161
Represents information about identifier.
Definition: Protocol.h:739
constexpr auto SymbolKindMax
Definition: Protocol.h:329
static void format(const clang::clangd::Position &Pos, raw_ostream &OS, StringRef Style)
Definition: Protocol.h:1021
llvm::Optional< TraceLevel > trace
The initial trace setting. If omitted trace is disabled (&#39;off&#39;).
Definition: Protocol.h:431
std::string documentation
The documentation of this signature. Optional.
Definition: Protocol.h:929
llvm::StringRef file() const
Retrieves absolute path to the file.
Definition: Protocol.h:91
Represents information about programming constructs like variables, classes, interfaces etc...
Definition: Protocol.h:721