| 1 |
//===--- Markup.h -------------------------------------------*- 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 |
// A model of formatted text that can be rendered to plaintext or markdown. |
| 10 |
// |
| 11 |
//===----------------------------------------------------------------------===// |
| 12 |
#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_SUPPORT_MARKUP_H |
| 13 |
#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SUPPORT_MARKUP_H |
| 14 |
|
| 15 |
#include "llvm/Support/raw_ostream.h" |
| 16 |
#include <cstddef> |
| 17 |
#include <memory> |
| 18 |
#include <string> |
| 19 |
#include <vector> |
| 20 |
|
| 21 |
namespace clang { |
| 22 |
namespace clangd { |
| 23 |
namespace markup { |
| 24 |
|
| 25 |
/// Holds text and knows how to lay it out. Multiple blocks can be grouped to |
| 26 |
/// form a document. Blocks include their own trailing newlines, container |
| 27 |
/// should trim them if need be. |
| 28 |
class Block { |
| 29 |
public: |
| 30 |
virtual void renderMarkdown(llvm::raw_ostream &OS) const = 0; |
| 31 |
virtual void renderPlainText(llvm::raw_ostream &OS) const = 0; |
| 32 |
virtual std::unique_ptr<Block> clone() const = 0; |
| 33 |
std::string asMarkdown() const; |
| 34 |
std::string asPlainText() const; |
| 35 |
|
| 36 |
virtual bool isRuler() const { return false; } |
| 37 |
virtual ~Block() = default; |
| 38 |
}; |
| 39 |
|
| 40 |
/// Represents parts of the markup that can contain strings, like inline code, |
| 41 |
/// code block or plain text. |
| 42 |
/// One must introduce different paragraphs to create separate blocks. |
| 43 |
class Paragraph : public Block { |
| 44 |
public: |
| 45 |
void renderMarkdown(llvm::raw_ostream &OS) const override; |
| 46 |
void renderPlainText(llvm::raw_ostream &OS) const override; |
| 47 |
std::unique_ptr<Block> clone() const override; |
| 48 |
|
| 49 |
/// Append plain text to the end of the string. |
| 50 |
Paragraph &appendText(llvm::StringRef Text); |
| 51 |
|
| 52 |
/// Append inline code, this translates to the ` block in markdown. |
| 53 |
/// \p Preserve indicates the code span must be apparent even in plaintext. |
| 54 |
Paragraph &appendCode(llvm::StringRef Code, bool Preserve = false); |
| 55 |
|
| 56 |
/// Ensure there is space between the surrounding chunks. |
| 57 |
/// Has no effect at the beginning or end of a paragraph. |
| 58 |
Paragraph &appendSpace(); |
| 59 |
|
| 60 |
private: |
| 61 |
struct Chunk { |
| 62 |
enum { |
| 63 |
PlainText, |
| 64 |
InlineCode, |
| 65 |
} Kind = PlainText; |
| 66 |
// Preserve chunk markers in plaintext. |
| 67 |
bool Preserve = false; |
| 68 |
std::string Contents; |
| 69 |
// Whether this chunk should be surrounded by whitespace. |
| 70 |
// Consecutive SpaceAfter and SpaceBefore will be collapsed into one space. |
| 71 |
// Code spans don't usually set this: their spaces belong "inside" the span. |
| 72 |
bool SpaceBefore = false; |
| 73 |
bool SpaceAfter = false; |
| 74 |
}; |
| 75 |
std::vector<Chunk> Chunks; |
| 76 |
}; |
| 77 |
|
| 78 |
/// Represents a sequence of one or more documents. Knows how to print them in a |
| 79 |
/// list like format, e.g. by prepending with "- " and indentation. |
| 80 |
class BulletList : public Block { |
| 81 |
public: |
| 82 |
BulletList(); |
| 83 |
~BulletList(); |
| 84 |
|
| 85 |
void renderMarkdown(llvm::raw_ostream &OS) const override; |
| 86 |
void renderPlainText(llvm::raw_ostream &OS) const override; |
| 87 |
std::unique_ptr<Block> clone() const override; |
| 88 |
|
| 89 |
class Document &addItem(); |
| 90 |
|
| 91 |
private: |
| 92 |
std::vector<class Document> Items; |
| 93 |
}; |
| 94 |
|
| 95 |
/// A format-agnostic representation for structured text. Allows rendering into |
| 96 |
/// markdown and plaintext. |
| 97 |
class Document { |
| 98 |
public: |
| 99 |
Document() = default; |
| 100 |
Document(const Document &Other) { *this = Other; } |
| 101 |
Document &operator=(const Document &); |
| 102 |
Document(Document &&) = default; |
| 103 |
Document &operator=(Document &&) = default; |
| 104 |
|
| 105 |
void append(Document Other); |
| 106 |
|
| 107 |
/// Adds a semantical block that will be separate from others. |
| 108 |
Paragraph &addParagraph(); |
| 109 |
/// Inserts a horizontal separator to the document. |
| 110 |
void addRuler(); |
| 111 |
/// Adds a block of code. This translates to a ``` block in markdown. In plain |
| 112 |
/// text representation, the code block will be surrounded by newlines. |
| 113 |
void addCodeBlock(std::string Code, std::string Language = "cpp"); |
| 114 |
/// Heading is a special type of paragraph that will be prepended with \p |
| 115 |
/// Level many '#'s in markdown. |
| 116 |
Paragraph &addHeading(size_t Level); |
| 117 |
|
| 118 |
BulletList &addBulletList(); |
| 119 |
|
| 120 |
/// Doesn't contain any trailing newlines. |
| 121 |
/// We try to make the markdown human-readable, e.g. avoid extra escaping. |
| 122 |
/// At least one client (coc.nvim) displays the markdown verbatim! |
| 123 |
std::string asMarkdown() const; |
| 124 |
/// Doesn't contain any trailing newlines. |
| 125 |
std::string asPlainText() const; |
| 126 |
|
| 127 |
private: |
| 128 |
std::vector<std::unique_ptr<Block>> Children; |
| 129 |
}; |
| 130 |
} // namespace markup |
| 131 |
} // namespace clangd |
| 132 |
} // namespace clang |
| 133 |
|
| 134 |
#endif |