clang-tools  10.0.0git
FormattedString.h
Go to the documentation of this file.
1 //===--- FormattedString.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 simple intermediate representation of formatted text that could be
10 // converted to plaintext or markdown.
11 //
12 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_FORMATTEDSTRING_H
14 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_FORMATTEDSTRING_H
15 
16 #include "llvm/Support/raw_ostream.h"
17 #include <cstddef>
18 #include <memory>
19 #include <string>
20 #include <vector>
21 
22 namespace clang {
23 namespace clangd {
24 namespace markup {
25 
26 /// Holds text and knows how to lay it out. Multiple blocks can be grouped to
27 /// form a document. Blocks include their own trailing newlines, container
28 /// should trim them if need be.
29 class Block {
30 public:
31  virtual void renderMarkdown(llvm::raw_ostream &OS) const = 0;
32  virtual void renderPlainText(llvm::raw_ostream &OS) 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 
48  /// Append plain text to the end of the string.
49  Paragraph &appendText(std::string Text);
50 
51  /// Append inline code, this translates to the ` block in markdown.
52  Paragraph &appendCode(std::string Code);
53 
54 private:
55  struct Chunk {
56  enum {
57  PlainText,
58  InlineCode,
59  } Kind = PlainText;
60  std::string Contents;
61  /// Language for code block chunks. Ignored for other chunks.
62  std::string Language;
63  };
64  std::vector<Chunk> Chunks;
65 };
66 
67 /// Represents a sequence of one or more documents. Knows how to print them in a
68 /// list like format, e.g. by prepending with "- " and indentation.
69 class BulletList : public Block {
70 public:
71  void renderMarkdown(llvm::raw_ostream &OS) const override;
72  void renderPlainText(llvm::raw_ostream &OS) const override;
73 
74  class Document &addItem();
75 
76 private:
77  std::vector<class Document> Items;
78 };
79 
80 /// A format-agnostic representation for structured text. Allows rendering into
81 /// markdown and plaintext.
82 class Document {
83 public:
84  /// Adds a semantical block that will be separate from others.
85  Paragraph &addParagraph();
86  /// Inserts a horizontal separator to the document.
87  void addRuler();
88  /// Adds a block of code. This translates to a ``` block in markdown. In plain
89  /// text representation, the code block will be surrounded by newlines.
90  void addCodeBlock(std::string Code, std::string Language = "cpp");
91  /// Heading is a special type of paragraph that will be prepended with \p
92  /// Level many '#'s in markdown.
93  Paragraph &addHeading(size_t Level);
94 
95  BulletList &addBulletList();
96 
97  /// Doesn't contain any trailing newlines.
98  std::string asMarkdown() const;
99  /// Doesn't contain any trailing newlines.
100  std::string asPlainText() const;
101 
102 private:
103  std::vector<std::unique_ptr<Block>> Children;
104 };
105 } // namespace markup
106 } // namespace clangd
107 } // namespace clang
108 
109 #endif
std::string Code
llvm::StringRef Contents
std::string Text
virtual void renderPlainText(llvm::raw_ostream &OS) const =0
BindArgumentKind Kind
std::string asPlainText() const
virtual bool isRuler() const
std::string asMarkdown() const
A format-agnostic representation for structured text.
virtual ~Block()=default
std::vector< std::unique_ptr< HTMLNode > > Children
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Represents parts of the markup that can contain strings, like inline code, code block or plain text...
Holds text and knows how to lay it out.
virtual void renderMarkdown(llvm::raw_ostream &OS) const =0
Represents a sequence of one or more documents.