· 8 years ago · Feb 18, 2018, 05:32 PM
1From b9c7869d265b5b6a00c3d365d11632383006fa43 Mon Sep 17 00:00:00 2001
2From: Aron Granberg <aron.granberg@gmail.com>
3Date: Sat, 17 Feb 2018 21:00:32 +0100
4Subject: [PATCH] [docs] Use literalinclude for most code in the Kaleidoscope
5 tutorial to ensure the code always compiles and is up to date
6
7---
8 docs/tutorial/LangImpl01.rst | 102 ++------
9 docs/tutorial/LangImpl02.rst | 426 ++++++++-----------------------
10 docs/tutorial/LangImpl03.rst | 201 ++++-----------
11 docs/tutorial/LangImpl04.rst | 224 ++++------------
12 docs/tutorial/LangImpl05.rst | 452 +++++++++------------------------
13 docs/tutorial/LangImpl06.rst | 260 +++----------------
14 docs/tutorial/LangImpl07.rst | 326 ++++++------------------
15 docs/tutorial/LangImpl08.rst | 91 +++----
16 examples/Kaleidoscope/Chapter2/toy.cpp | 54 +++-
17 examples/Kaleidoscope/Chapter3/toy.cpp | 24 ++
18 examples/Kaleidoscope/Chapter4/toy.cpp | 20 ++
19 examples/Kaleidoscope/Chapter5/toy.cpp | 40 +++
20 examples/Kaleidoscope/Chapter6/toy.cpp | 16 ++
21 examples/Kaleidoscope/Chapter7/toy.cpp | 36 +++
22 examples/Kaleidoscope/Chapter8/toy.cpp | 16 +-
23 15 files changed, 709 insertions(+), 1579 deletions(-)
24
25diff --git a/docs/tutorial/LangImpl01.rst b/docs/tutorial/LangImpl01.rst
26index f7fbd150ef1..a1ee601dbd1 100644
27--- a/docs/tutorial/LangImpl01.rst
28+++ b/docs/tutorial/LangImpl01.rst
29@@ -122,6 +122,7 @@ require type declarations. This gives the language a very nice and
30 simple syntax. For example, the following simple example computes
31 `Fibonacci numbers: <http://en.wikipedia.org/wiki/Fibonacci_number>`_
32
33+
34 ::
35
36 # Compute the x'th fibonacci number.
37@@ -164,24 +165,10 @@ traditional way to do this is to use a
38 the lexer includes a token code and potentially some metadata (e.g. the
39 numeric value of a number). First, we define the possibilities:
40
41-.. code-block:: c++
42-
43- // The lexer returns tokens [0-255] if it is an unknown character, otherwise one
44- // of these for known things.
45- enum Token {
46- tok_eof = -1,
47-
48- // commands
49- tok_def = -2,
50- tok_extern = -3,
51-
52- // primary
53- tok_identifier = -4,
54- tok_number = -5,
55- };
56-
57- static std::string IdentifierStr; // Filled in if tok_identifier
58- static double NumVal; // Filled in if tok_number
59+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
60+ :language: c++
61+ :start-after: chapter1-token
62+ :end-before: chapter1-token
63
64 Each token returned by our lexer will either be one of the Token enum
65 values or it will be an 'unknown' character like '+', which is returned
66@@ -195,15 +182,10 @@ The actual implementation of the lexer is a single function named
67 ``gettok``. The ``gettok`` function is called to return the next token
68 from standard input. Its definition starts as:
69
70-.. code-block:: c++
71-
72- /// gettok - Return the next token from standard input.
73- static int gettok() {
74- static int LastChar = ' ';
75-
76- // Skip any whitespace.
77- while (isspace(LastChar))
78- LastChar = getchar();
79+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
80+ :language: c++
81+ :start-after: chapter1-gettok1
82+ :end-before: chapter1-gettok1
83
84 ``gettok`` works by calling the C ``getchar()`` function to read
85 characters one at a time from standard input. It eats them as it
86@@ -215,36 +197,21 @@ The next thing ``gettok`` needs to do is recognize identifiers and
87 specific keywords like "def". Kaleidoscope does this with this simple
88 loop:
89
90-.. code-block:: c++
91-
92- if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
93- IdentifierStr = LastChar;
94- while (isalnum((LastChar = getchar())))
95- IdentifierStr += LastChar;
96-
97- if (IdentifierStr == "def")
98- return tok_def;
99- if (IdentifierStr == "extern")
100- return tok_extern;
101- return tok_identifier;
102- }
103+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
104+ :language: c++
105+ :start-after: chapter1-gettok2
106+ :end-before: chapter1-gettok2
107+ :dedent: 2
108
109 Note that this code sets the '``IdentifierStr``' global whenever it
110 lexes an identifier. Also, since language keywords are matched by the
111 same loop, we handle them here inline. Numeric values are similar:
112
113-.. code-block:: c++
114-
115- if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
116- std::string NumStr;
117- do {
118- NumStr += LastChar;
119- LastChar = getchar();
120- } while (isdigit(LastChar) || LastChar == '.');
121-
122- NumVal = strtod(NumStr.c_str(), 0);
123- return tok_number;
124- }
125+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
126+ :language: c++
127+ :start-after: chapter1-gettok3
128+ :end-before: chapter1-gettok3
129+ :dedent: 2
130
131 This is all pretty straight-forward code for processing input. When
132 reading a numeric value from input, we use the C ``strtod`` function to
133@@ -253,34 +220,21 @@ this isn't doing sufficient error checking: it will incorrectly read
134 "1.23.45.67" and handle it as if you typed in "1.23". Feel free to
135 extend it :). Next we handle comments:
136
137-.. code-block:: c++
138-
139- if (LastChar == '#') {
140- // Comment until end of line.
141- do
142- LastChar = getchar();
143- while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
144-
145- if (LastChar != EOF)
146- return gettok();
147- }
148+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
149+ :language: c++
150+ :start-after: chapter1-gettok4
151+ :end-before: chapter1-gettok4
152+ :dedent: 2
153
154 We handle comments by skipping to the end of the line and then return
155 the next token. Finally, if the input doesn't match one of the above
156 cases, it is either an operator character like '+' or the end of the
157 file. These are handled with this code:
158
159-.. code-block:: c++
160-
161- // Check for end of file. Don't eat the EOF.
162- if (LastChar == EOF)
163- return tok_eof;
164-
165- // Otherwise, just return the character as its ascii value.
166- int ThisChar = LastChar;
167- LastChar = getchar();
168- return ThisChar;
169- }
170+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
171+ :language: c++
172+ :start-after: chapter1-gettok5
173+ :end-before: chapter1-gettok5
174
175 With this, we have the complete lexer for the basic Kaleidoscope
176 language (the `full code listing <LangImpl02.html#full-code-listing>`_ for the Lexer
177diff --git a/docs/tutorial/LangImpl02.rst b/docs/tutorial/LangImpl02.rst
178index d72c8dc9add..c08d2cd70db 100644
179--- a/docs/tutorial/LangImpl02.rst
180+++ b/docs/tutorial/LangImpl02.rst
181@@ -33,21 +33,11 @@ language, and the AST should closely model the language. In
182 Kaleidoscope, we have expressions, a prototype, and a function object.
183 We'll start with expressions first:
184
185-.. code-block:: c++
186-
187- /// ExprAST - Base class for all expression nodes.
188- class ExprAST {
189- public:
190- virtual ~ExprAST() {}
191- };
192-
193- /// NumberExprAST - Expression class for numeric literals like "1.0".
194- class NumberExprAST : public ExprAST {
195- double Val;
196-
197- public:
198- NumberExprAST(double Val) : Val(Val) {}
199- };
200+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
201+ :language: c++
202+ :start-after: chapter2-ExprAST
203+ :end-before: chapter2-ExprAST
204+ :dedent: 0
205
206 The code above shows the definition of the base ExprAST class and one
207 subclass which we use for numeric literals. The important thing to note
208@@ -61,37 +51,11 @@ print the code, for example. Here are the other expression AST node
209 definitions that we'll use in the basic form of the Kaleidoscope
210 language:
211
212-.. code-block:: c++
213-
214- /// VariableExprAST - Expression class for referencing a variable, like "a".
215- class VariableExprAST : public ExprAST {
216- std::string Name;
217-
218- public:
219- VariableExprAST(const std::string &Name) : Name(Name) {}
220- };
221-
222- /// BinaryExprAST - Expression class for a binary operator.
223- class BinaryExprAST : public ExprAST {
224- char Op;
225- std::unique_ptr<ExprAST> LHS, RHS;
226-
227- public:
228- BinaryExprAST(char op, std::unique_ptr<ExprAST> LHS,
229- std::unique_ptr<ExprAST> RHS)
230- : Op(op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
231- };
232-
233- /// CallExprAST - Expression class for function calls.
234- class CallExprAST : public ExprAST {
235- std::string Callee;
236- std::vector<std::unique_ptr<ExprAST>> Args;
237-
238- public:
239- CallExprAST(const std::string &Callee,
240- std::vector<std::unique_ptr<ExprAST>> Args)
241- : Callee(Callee), Args(std::move(Args)) {}
242- };
243+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
244+ :language: c++
245+ :start-after: chapter2-VariableExprAST
246+ :end-before: chapter2-VariableExprAST
247+ :dedent: 0
248
249 This is all (intentionally) rather straight-forward: variables capture
250 the variable name, binary operators capture their opcode (e.g. '+'), and
251@@ -107,32 +71,11 @@ Turing-complete; we'll fix that in a later installment. The two things
252 we need next are a way to talk about the interface to a function, and a
253 way to talk about functions themselves:
254
255-.. code-block:: c++
256-
257- /// PrototypeAST - This class represents the "prototype" for a function,
258- /// which captures its name, and its argument names (thus implicitly the number
259- /// of arguments the function takes).
260- class PrototypeAST {
261- std::string Name;
262- std::vector<std::string> Args;
263-
264- public:
265- PrototypeAST(const std::string &name, std::vector<std::string> Args)
266- : Name(name), Args(std::move(Args)) {}
267-
268- const std::string &getName() const { return Name; }
269- };
270-
271- /// FunctionAST - This class represents a function definition itself.
272- class FunctionAST {
273- std::unique_ptr<PrototypeAST> Proto;
274- std::unique_ptr<ExprAST> Body;
275-
276- public:
277- FunctionAST(std::unique_ptr<PrototypeAST> Proto,
278- std::unique_ptr<ExprAST> Body)
279- : Proto(std::move(Proto)), Body(std::move(Body)) {}
280- };
281+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
282+ :language: c++
283+ :start-after: chapter2-PrototypeAST
284+ :end-before: chapter2-PrototypeAST
285+ :dedent: 0
286
287 In Kaleidoscope, functions are typed with just a count of their
288 arguments. Since all values are double precision floating point, the
289@@ -160,33 +103,22 @@ be generated with calls like this:
290
291 In order to do this, we'll start by defining some basic helper routines:
292
293-.. code-block:: c++
294-
295- /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current
296- /// token the parser is looking at. getNextToken reads another token from the
297- /// lexer and updates CurTok with its results.
298- static int CurTok;
299- static int getNextToken() {
300- return CurTok = gettok();
301- }
302+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
303+ :language: c++
304+ :start-after: chapter2-CurTok
305+ :end-before: chapter2-CurTok
306+ :dedent: 0
307
308 This implements a simple token buffer around the lexer. This allows us
309 to look one token ahead at what the lexer is returning. Every function
310 in our parser will assume that CurTok is the current token that needs to
311 be parsed.
312
313-.. code-block:: c++
314-
315-
316- /// LogError* - These are little helper functions for error handling.
317- std::unique_ptr<ExprAST> LogError(const char *Str) {
318- fprintf(stderr, "LogError: %s\n", Str);
319- return nullptr;
320- }
321- std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {
322- LogError(Str);
323- return nullptr;
324- }
325+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
326+ :language: c++
327+ :start-after: chapter2-logging
328+ :end-before: chapter2-logging
329+ :dedent: 0
330
331 The ``LogError`` routines are simple helper routines that our parser will
332 use to handle errors. The error recovery in our parser will not be the
333@@ -204,14 +136,11 @@ We start with numeric literals, because they are the simplest to
334 process. For each production in our grammar, we'll define a function
335 which parses that production. For numeric literals, we have:
336
337-.. code-block:: c++
338-
339- /// numberexpr ::= number
340- static std::unique_ptr<ExprAST> ParseNumberExpr() {
341- auto Result = llvm::make_unique<NumberExprAST>(NumVal);
342- getNextToken(); // consume the number
343- return std::move(Result);
344- }
345+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
346+ :language: c++
347+ :start-after: chapter2-ParseNumberExpr
348+ :end-before: chapter2-ParseNumberExpr
349+ :dedent: 0
350
351 This routine is very simple: it expects to be called when the current
352 token is a ``tok_number`` token. It takes the current number value,
353@@ -225,20 +154,11 @@ not part of the grammar production) ready to go. This is a fairly
354 standard way to go for recursive descent parsers. For a better example,
355 the parenthesis operator is defined like this:
356
357-.. code-block:: c++
358-
359- /// parenexpr ::= '(' expression ')'
360- static std::unique_ptr<ExprAST> ParseParenExpr() {
361- getNextToken(); // eat (.
362- auto V = ParseExpression();
363- if (!V)
364- return nullptr;
365-
366- if (CurTok != ')')
367- return LogError("expected ')'");
368- getNextToken(); // eat ).
369- return V;
370- }
371+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
372+ :language: c++
373+ :start-after: chapter2-ParseParenExpr
374+ :end-before: chapter2-ParseParenExpr
375+ :dedent: 0
376
377 This function illustrates a number of interesting things about the
378 parser:
379@@ -263,43 +183,11 @@ needed.
380 The next simple production is for handling variable references and
381 function calls:
382
383-.. code-block:: c++
384-
385- /// identifierexpr
386- /// ::= identifier
387- /// ::= identifier '(' expression* ')'
388- static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
389- std::string IdName = IdentifierStr;
390-
391- getNextToken(); // eat identifier.
392-
393- if (CurTok != '(') // Simple variable ref.
394- return llvm::make_unique<VariableExprAST>(IdName);
395-
396- // Call.
397- getNextToken(); // eat (
398- std::vector<std::unique_ptr<ExprAST>> Args;
399- if (CurTok != ')') {
400- while (1) {
401- if (auto Arg = ParseExpression())
402- Args.push_back(std::move(Arg));
403- else
404- return nullptr;
405-
406- if (CurTok == ')')
407- break;
408-
409- if (CurTok != ',')
410- return LogError("Expected ')' or ',' in argument list");
411- getNextToken();
412- }
413- }
414-
415- // Eat the ')'.
416- getNextToken();
417-
418- return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
419- }
420+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
421+ :language: c++
422+ :start-after: chapter2-ParseIdentifierExpr
423+ :end-before: chapter2-ParseIdentifierExpr
424+ :dedent: 0
425
426 This routine follows the same style as the other routines. (It expects
427 to be called if the current token is a ``tok_identifier`` token). It
428@@ -317,24 +205,11 @@ that will become more clear `later in the
429 tutorial <LangImpl6.html#user-defined-unary-operators>`_. In order to parse an arbitrary
430 primary expression, we need to determine what sort of expression it is:
431
432-.. code-block:: c++
433-
434- /// primary
435- /// ::= identifierexpr
436- /// ::= numberexpr
437- /// ::= parenexpr
438- static std::unique_ptr<ExprAST> ParsePrimary() {
439- switch (CurTok) {
440- default:
441- return LogError("unknown token when expecting an expression");
442- case tok_identifier:
443- return ParseIdentifierExpr();
444- case tok_number:
445- return ParseNumberExpr();
446- case '(':
447- return ParseParenExpr();
448- }
449- }
450+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
451+ :language: c++
452+ :start-after: chapter2-ParsePrimary
453+ :end-before: chapter2-ParsePrimary
454+ :dedent: 0
455
456 Now that you see the definition of this function, it is more obvious why
457 we can assume the state of CurTok in the various functions. This uses
458@@ -359,32 +234,17 @@ Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_.
459 This parsing technique uses the precedence of binary operators to guide
460 recursion. To start with, we need a table of precedences:
461
462-.. code-block:: c++
463-
464- /// BinopPrecedence - This holds the precedence for each binary operator that is
465- /// defined.
466- static std::map<char, int> BinopPrecedence;
467-
468- /// GetTokPrecedence - Get the precedence of the pending binary operator token.
469- static int GetTokPrecedence() {
470- if (!isascii(CurTok))
471- return -1;
472-
473- // Make sure it's a declared binop.
474- int TokPrec = BinopPrecedence[CurTok];
475- if (TokPrec <= 0) return -1;
476- return TokPrec;
477- }
478+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
479+ :language: c++
480+ :start-after: chapter2-BinopPrecedence
481+ :end-before: chapter2-BinopPrecedence
482+ :dedent: 0
483
484- int main() {
485- // Install standard binary operators.
486- // 1 is lowest precedence.
487- BinopPrecedence['<'] = 10;
488- BinopPrecedence['+'] = 20;
489- BinopPrecedence['-'] = 20;
490- BinopPrecedence['*'] = 40; // highest.
491- ...
492- }
493+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
494+ :language: c++
495+ :start-after: chapter2-SetBinopPrecedence
496+ :end-before: chapter2-SetBinopPrecedence
497+ :dedent: 0
498
499 For the basic form of Kaleidoscope, we will only support 4 binary
500 operators (this can obviously be extended by you, our brave and intrepid
501@@ -409,18 +269,11 @@ about nested subexpressions like (c+d) at all.
502 To start, an expression is a primary expression potentially followed by
503 a sequence of [binop,primaryexpr] pairs:
504
505-.. code-block:: c++
506-
507- /// expression
508- /// ::= primary binoprhs
509- ///
510- static std::unique_ptr<ExprAST> ParseExpression() {
511- auto LHS = ParsePrimary();
512- if (!LHS)
513- return nullptr;
514-
515- return ParseBinOpRHS(0, std::move(LHS));
516- }
517+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
518+ :language: c++
519+ :start-after: chapter2-ParseExpression
520+ :end-before: chapter2-ParseExpression
521+ :dedent: 0
522
523 ``ParseBinOpRHS`` is the function that parses the sequence of pairs for
524 us. It takes a precedence and a pointer to an expression for the part
525@@ -437,20 +290,11 @@ passed in a precedence of 40, it will not consume any tokens (because
526 the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``
527 starts with:
528
529-.. code-block:: c++
530-
531- /// binoprhs
532- /// ::= ('+' primary)*
533- static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
534- std::unique_ptr<ExprAST> LHS) {
535- // If this is a binop, find its precedence.
536- while (1) {
537- int TokPrec = GetTokPrecedence();
538-
539- // If this is a binop that binds at least as tightly as the current binop,
540- // consume it, otherwise we are done.
541- if (TokPrec < ExprPrec)
542- return LHS;
543+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
544+ :language: c++
545+ :start-after: chapter2-ParseBinOpRHS1
546+ :end-before: chapter2-ParseBinOpRHS1
547+ :dedent: 0
548
549 This code gets the precedence of the current token and checks to see if
550 if is too low. Because we defined invalid tokens to have a precedence of
551@@ -459,16 +303,11 @@ stream runs out of binary operators. If this check succeeds, we know
552 that the token is a binary operator and that it will be included in this
553 expression:
554
555-.. code-block:: c++
556-
557- // Okay, we know this is a binop.
558- int BinOp = CurTok;
559- getNextToken(); // eat binop
560-
561- // Parse the primary expression after the binary operator.
562- auto RHS = ParsePrimary();
563- if (!RHS)
564- return nullptr;
565+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
566+ :language: c++
567+ :start-after: chapter2-ParseBinOpRHS2
568+ :end-before: chapter2-ParseBinOpRHS2
569+ :dedent: 4
570
571 As such, this code eats (and remembers) the binary operator and then
572 parses the primary expression that follows. This builds up the whole
573@@ -520,21 +359,11 @@ our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression
574 variable. The code to do this is surprisingly simple (code from the
575 above two blocks duplicated for context):
576
577-.. code-block:: c++
578-
579- // If BinOp binds less tightly with RHS than the operator after RHS, let
580- // the pending operator take RHS as its LHS.
581- int NextPrec = GetTokPrecedence();
582- if (TokPrec < NextPrec) {
583- RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));
584- if (!RHS)
585- return nullptr;
586- }
587- // Merge LHS/RHS.
588- LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
589- std::move(RHS));
590- } // loop around to the top of the while loop.
591- }
592+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
593+ :language: c++
594+ :start-after: chapter2-ParseBinOpRHS3
595+ :end-before: chapter2-ParseBinOpRHS3
596+ :dedent: 0
597
598 At this point, we know that the binary operator to the RHS of our
599 primary has higher precedence than the binop we are currently parsing.
600@@ -567,76 +396,40 @@ well as function body definitions. The code to do this is
601 straight-forward and not very interesting (once you've survived
602 expressions):
603
604-.. code-block:: c++
605-
606- /// prototype
607- /// ::= id '(' id* ')'
608- static std::unique_ptr<PrototypeAST> ParsePrototype() {
609- if (CurTok != tok_identifier)
610- return LogErrorP("Expected function name in prototype");
611-
612- std::string FnName = IdentifierStr;
613- getNextToken();
614-
615- if (CurTok != '(')
616- return LogErrorP("Expected '(' in prototype");
617-
618- // Read the list of argument names.
619- std::vector<std::string> ArgNames;
620- while (getNextToken() == tok_identifier)
621- ArgNames.push_back(IdentifierStr);
622- if (CurTok != ')')
623- return LogErrorP("Expected ')' in prototype");
624-
625- // success.
626- getNextToken(); // eat ')'.
627-
628- return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));
629- }
630+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
631+ :language: c++
632+ :start-after: chapter2-ParsePrototype
633+ :end-before: chapter2-ParsePrototype
634+ :dedent: 0
635
636 Given this, a function definition is very simple, just a prototype plus
637 an expression to implement the body:
638
639-.. code-block:: c++
640-
641- /// definition ::= 'def' prototype expression
642- static std::unique_ptr<FunctionAST> ParseDefinition() {
643- getNextToken(); // eat def.
644- auto Proto = ParsePrototype();
645- if (!Proto) return nullptr;
646-
647- if (auto E = ParseExpression())
648- return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
649- return nullptr;
650- }
651+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
652+ :language: c++
653+ :start-after: chapter2-ParseDefinition
654+ :end-before: chapter2-ParseDefinition
655+ :dedent: 0
656
657 In addition, we support 'extern' to declare functions like 'sin' and
658 'cos' as well as to support forward declaration of user functions. These
659 'extern's are just prototypes with no body:
660
661-.. code-block:: c++
662-
663- /// external ::= 'extern' prototype
664- static std::unique_ptr<PrototypeAST> ParseExtern() {
665- getNextToken(); // eat extern.
666- return ParsePrototype();
667- }
668+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
669+ :language: c++
670+ :start-after: chapter2-ParseExtern
671+ :end-before: chapter2-ParseExtern
672+ :dedent: 0
673
674 Finally, we'll also let the user type in arbitrary top-level expressions
675 and evaluate them on the fly. We will handle this by defining anonymous
676 nullary (zero argument) functions for them:
677
678-.. code-block:: c++
679-
680- /// toplevelexpr ::= expression
681- static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
682- if (auto E = ParseExpression()) {
683- // Make an anonymous proto.
684- auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());
685- return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
686- }
687- return nullptr;
688- }
689+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
690+ :language: c++
691+ :start-after: chapter2-ParseTopLevelExpr
692+ :end-before: chapter2-ParseTopLevelExpr
693+ :dedent: 0
694
695 Now that we have all the pieces, let's build a little driver that will
696 let us actually *execute* this code we've built!
697@@ -649,30 +442,11 @@ top-level dispatch loop. There isn't much interesting here, so I'll just
698 include the top-level loop. See `below <#full-code-listing>`_ for full code in the
699 "Top-Level Parsing" section.
700
701-.. code-block:: c++
702-
703- /// top ::= definition | external | expression | ';'
704- static void MainLoop() {
705- while (1) {
706- fprintf(stderr, "ready> ");
707- switch (CurTok) {
708- case tok_eof:
709- return;
710- case ';': // ignore top-level semicolons.
711- getNextToken();
712- break;
713- case tok_def:
714- HandleDefinition();
715- break;
716- case tok_extern:
717- HandleExtern();
718- break;
719- default:
720- HandleTopLevelExpression();
721- break;
722- }
723- }
724- }
725+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
726+ :language: c++
727+ :start-after: chapter2-MainLoop
728+ :end-before: chapter2-MainLoop
729+ :dedent: 0
730
731 The most interesting part of this is that we ignore top-level
732 semicolons. Why is this, you ask? The basic reason is that if you type
733diff --git a/docs/tutorial/LangImpl03.rst b/docs/tutorial/LangImpl03.rst
734index fab2ddaf882..ec271a108d8 100644
735--- a/docs/tutorial/LangImpl03.rst
736+++ b/docs/tutorial/LangImpl03.rst
737@@ -27,26 +27,13 @@ Code Generation Setup
738
739 In order to generate LLVM IR, we want some simple setup to get started.
740 First we define virtual code generation (codegen) methods in each AST
741-class:
742+class (for brevity only the ExprAST and NumberExprAST classes are shown here):
743
744-.. code-block:: c++
745-
746- /// ExprAST - Base class for all expression nodes.
747- class ExprAST {
748- public:
749- virtual ~ExprAST() {}
750- virtual Value *codegen() = 0;
751- };
752-
753- /// NumberExprAST - Expression class for numeric literals like "1.0".
754- class NumberExprAST : public ExprAST {
755- double Val;
756-
757- public:
758- NumberExprAST(double Val) : Val(Val) {}
759- virtual Value *codegen();
760- };
761- ...
762+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
763+ :language: c++
764+ :start-after: chapter3-ExprAST-codegen
765+ :end-before: chapter3-ExprAST-codegen
766+ :emphasize-lines: 6,16
767
768 The codegen() method says to emit IR for that AST node along with all
769 the things it depends on, and they all return an LLVM Value object.
770@@ -71,17 +58,10 @@ The second thing we want is an "LogError" method like we used for the
771 parser, which will be used to report errors found during code generation
772 (for example, use of an undeclared parameter):
773
774-.. code-block:: c++
775-
776- static LLVMContext TheContext;
777- static IRBuilder<> Builder(TheContext);
778- static std::unique_ptr<Module> TheModule;
779- static std::map<std::string, Value *> NamedValues;
780-
781- Value *LogErrorV(const char *Str) {
782- LogError(Str);
783- return nullptr;
784- }
785+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
786+ :language: c++
787+ :start-after: chapter3-globals
788+ :end-before: chapter3-globals
789
790 The static variables will be used during code generation. ``TheContext``
791 is an opaque object that owns a lot of core LLVM data structures, such as
792@@ -119,11 +99,10 @@ Generating LLVM code for expression nodes is very straightforward: less
793 than 45 lines of commented code for all four of our expression nodes.
794 First we'll do numeric literals:
795
796-.. code-block:: c++
797-
798- Value *NumberExprAST::codegen() {
799- return ConstantFP::get(TheContext, APFloat(Val));
800- }
801+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
802+ :language: c++
803+ :start-after: chapter3-NumberExprAST-codegen
804+ :end-before: chapter3-NumberExprAST-codegen
805
806 In the LLVM IR, numeric constants are represented with the
807 ``ConstantFP`` class, which holds the numeric value in an ``APFloat``
808@@ -133,15 +112,10 @@ and returns a ``ConstantFP``. Note that in the LLVM IR that constants
809 are all uniqued together and shared. For this reason, the API uses the
810 "foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".
811
812-.. code-block:: c++
813-
814- Value *VariableExprAST::codegen() {
815- // Look this variable up in the function.
816- Value *V = NamedValues[Name];
817- if (!V)
818- LogErrorV("Unknown variable name");
819- return V;
820- }
821+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
822+ :language: c++
823+ :start-after: chapter3-VariableExprAST-codegen
824+ :end-before: chapter3-VariableExprAST-codegen
825
826 References to variables are also quite simple using LLVM. In the simple
827 version of Kaleidoscope, we assume that the variable has already been
828@@ -153,30 +127,10 @@ it. In future chapters, we'll add support for `loop induction
829 variables <LangImpl5.html#for-loop-expression>`_ in the symbol table, and for `local
830 variables <LangImpl7.html#user-defined-local-variables>`_.
831
832-.. code-block:: c++
833-
834- Value *BinaryExprAST::codegen() {
835- Value *L = LHS->codegen();
836- Value *R = RHS->codegen();
837- if (!L || !R)
838- return nullptr;
839-
840- switch (Op) {
841- case '+':
842- return Builder.CreateFAdd(L, R, "addtmp");
843- case '-':
844- return Builder.CreateFSub(L, R, "subtmp");
845- case '*':
846- return Builder.CreateFMul(L, R, "multmp");
847- case '<':
848- L = Builder.CreateFCmpULT(L, R, "cmptmp");
849- // Convert bool 0/1 to double 0.0 or 1.0
850- return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext),
851- "booltmp");
852- default:
853- return LogErrorV("invalid binary operator");
854- }
855- }
856+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
857+ :language: c++
858+ :start-after: chapter3-BinaryExprAST-codegen
859+ :end-before: chapter3-BinaryExprAST-codegen
860
861 Binary operators start to get more interesting. The basic idea here is
862 that we recursively emit code for the left-hand side of the expression,
863@@ -214,27 +168,10 @@ unsigned value. In contrast, if we used the `sitofp
864 instruction <../LangRef.html#sitofp-to-instruction>`_, the Kaleidoscope '<' operator
865 would return 0.0 and -1.0, depending on the input value.
866
867-.. code-block:: c++
868-
869- Value *CallExprAST::codegen() {
870- // Look up the name in the global module table.
871- Function *CalleeF = TheModule->getFunction(Callee);
872- if (!CalleeF)
873- return LogErrorV("Unknown function referenced");
874-
875- // If argument mismatch error.
876- if (CalleeF->arg_size() != Args.size())
877- return LogErrorV("Incorrect # arguments passed");
878-
879- std::vector<Value *> ArgsV;
880- for (unsigned i = 0, e = Args.size(); i != e; ++i) {
881- ArgsV.push_back(Args[i]->codegen());
882- if (!ArgsV.back())
883- return nullptr;
884- }
885-
886- return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
887- }
888+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
889+ :language: c++
890+ :start-after: chapter3-CallExprAST-codegen
891+ :end-before: chapter3-CallExprAST-codegen
892
893 Code generation for function calls is quite straightforward with LLVM. The code
894 above initially does a function name lookup in the LLVM Module's symbol table.
895@@ -265,17 +202,10 @@ lets talk about code generation for prototypes: they are used both for
896 function bodies and external function declarations. The code starts
897 with:
898
899-.. code-block:: c++
900-
901- Function *PrototypeAST::codegen() {
902- // Make the function type: double(double,double) etc.
903- std::vector<Type*> Doubles(Args.size(),
904- Type::getDoubleTy(TheContext));
905- FunctionType *FT =
906- FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
907-
908- Function *F =
909- Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
910+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
911+ :language: c++
912+ :start-after: chapter3-PrototypeAST-codegen1
913+ :end-before: chapter3-PrototypeAST-codegen1
914
915 This code packs a lot of power into a few lines. Note first that this
916 function returns a "Function\*" instead of a "Value\*". Because a
917@@ -301,14 +231,10 @@ functions outside the module. The Name passed in is the name the user
918 specified: since "``TheModule``" is specified, this name is registered
919 in "``TheModule``"s symbol table.
920
921-.. code-block:: c++
922-
923- // Set names for all arguments.
924- unsigned Idx = 0;
925- for (auto &Arg : F->args())
926- Arg.setName(Args[Idx++]);
927-
928- return F;
929+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
930+ :language: c++
931+ :start-after: chapter3-PrototypeAST-codegen2
932+ :end-before: chapter3-PrototypeAST-codegen2
933
934 Finally, we set the name of each of the function's arguments according to the
935 names given in the Prototype. This step isn't strictly necessary, but keeping
936@@ -321,38 +247,23 @@ represents function declarations. For extern statements in Kaleidoscope, this
937 is as far as we need to go. For function definitions however, we need to
938 codegen and attach a function body.
939
940-.. code-block:: c++
941-
942- Function *FunctionAST::codegen() {
943- // First, check for an existing function from a previous 'extern' declaration.
944- Function *TheFunction = TheModule->getFunction(Proto->getName());
945-
946- if (!TheFunction)
947- TheFunction = Proto->codegen();
948-
949- if (!TheFunction)
950- return nullptr;
951-
952- if (!TheFunction->empty())
953- return (Function*)LogErrorV("Function cannot be redefined.");
954+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
955+ :language: c++
956+ :start-after: chapter3-FunctionAST-codegen1
957+ :end-before: chapter3-FunctionAST-codegen1
958
959
960 For function definitions, we start by searching TheModule's symbol table for an
961 existing version of this function, in case one has already been created using an
962 'extern' statement. If Module::getFunction returns null then no previous version
963-exists, so we'll codegen one from the Prototype. In either case, we want to
964-assert that the function is empty (i.e. has no body yet) before we start.
965-
966-.. code-block:: c++
967+exists, so we'll codegen one from the Prototype.
968
969- // Create a new basic block to start insertion into.
970- BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
971- Builder.SetInsertPoint(BB);
972
973- // Record the function arguments in the NamedValues map.
974- NamedValues.clear();
975- for (auto &Arg : TheFunction->args())
976- NamedValues[Arg.getName()] = &Arg;
977+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
978+ :language: c++
979+ :start-after: chapter3-FunctionAST-codegen2
980+ :end-before: chapter3-FunctionAST-codegen2
981+ :dedent: 2
982
983 Now we get to the point where the ``Builder`` is set up. The first line
984 creates a new `basic block <http://en.wikipedia.org/wiki/Basic_block>`_
985@@ -367,17 +278,12 @@ at this point. We'll fix this in `Chapter 5 <LangImpl05.html>`_ :).
986 Next we add the function arguments to the NamedValues map (after first clearing
987 it out) so that they're accessible to ``VariableExprAST`` nodes.
988
989-.. code-block:: c++
990
991- if (Value *RetVal = Body->codegen()) {
992- // Finish off the function.
993- Builder.CreateRet(RetVal);
994-
995- // Validate the generated code, checking for consistency.
996- verifyFunction(*TheFunction);
997-
998- return TheFunction;
999- }
1000+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
1001+ :language: c++
1002+ :start-after: chapter3-FunctionAST-codegen3
1003+ :end-before: chapter3-FunctionAST-codegen3
1004+ :dedent: 2
1005
1006 Once the insertion point has been set up and the NamedValues map populated,
1007 we call the ``codegen()`` method for the root expression of the function. If no
1008@@ -390,12 +296,11 @@ the generated code, to determine if our compiler is doing everything
1009 right. Using this is important: it can catch a lot of bugs. Once the
1010 function is finished and validated, we return it.
1011
1012-.. code-block:: c++
1013
1014- // Error reading body, remove function.
1015- TheFunction->eraseFromParent();
1016- return nullptr;
1017- }
1018+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
1019+ :language: c++
1020+ :start-after: chapter3-FunctionAST-codegen4
1021+ :end-before: chapter3-FunctionAST-codegen4
1022
1023 The only piece left here is handling of the error case. For simplicity,
1024 we handle this by merely deleting the function we produced with the
1025diff --git a/docs/tutorial/LangImpl04.rst b/docs/tutorial/LangImpl04.rst
1026index b8e55b0fb21..d9077853b80 100644
1027--- a/docs/tutorial/LangImpl04.rst
1028+++ b/docs/tutorial/LangImpl04.rst
1029@@ -127,26 +127,11 @@ FunctionPassManager for each module that we want to optimize, so we'll
1030 write a function to create and initialize both the module and pass manager
1031 for us:
1032
1033-.. code-block:: c++
1034-
1035- void InitializeModuleAndPassManager(void) {
1036- // Open a new module.
1037- TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
1038-
1039- // Create a new pass manager attached to it.
1040- TheFPM = llvm::make_unique<FunctionPassManager>(TheModule.get());
1041-
1042- // Do simple "peephole" optimizations and bit-twiddling optzns.
1043- TheFPM->add(createInstructionCombiningPass());
1044- // Reassociate expressions.
1045- TheFPM->add(createReassociatePass());
1046- // Eliminate Common SubExpressions.
1047- TheFPM->add(createGVNPass());
1048- // Simplify the control flow graph (deleting unreachable blocks, etc).
1049- TheFPM->add(createCFGSimplificationPass());
1050-
1051- TheFPM->doInitialization();
1052- }
1053+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1054+ :language: c++
1055+ :start-after: chapter4-InitializeModuleAndPassManager
1056+ :end-before: chapter4-InitializeModuleAndPassManager
1057+ :lines: 1-3,5-
1058
1059 This code initializes the global module ``TheModule``, and the function pass
1060 manager ``TheFPM``, which is attached to ``TheModule``. Once the pass manager is
1061@@ -161,20 +146,11 @@ Once the PassManager is set up, we need to make use of it. We do this by
1062 running it after our newly created function is constructed (in
1063 ``FunctionAST::codegen()``), but before it is returned to the client:
1064
1065-.. code-block:: c++
1066-
1067- if (Value *RetVal = Body->codegen()) {
1068- // Finish off the function.
1069- Builder.CreateRet(RetVal);
1070-
1071- // Validate the generated code, checking for consistency.
1072- verifyFunction(*TheFunction);
1073-
1074- // Optimize the function.
1075- TheFPM->run(*TheFunction);
1076-
1077- return TheFunction;
1078- }
1079+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1080+ :language: c++
1081+ :start-after: chapter4-run-passes
1082+ :end-before: chapter4-run-passes
1083+ :dedent: 2
1084
1085 As you can see, this is pretty straightforward. The
1086 ``FunctionPassManager`` optimizes and updates the LLVM Function\* in
1087@@ -229,46 +205,24 @@ done by calling some ``InitializeNativeTarget\*`` functions and
1088 adding a global variable ``TheJIT``, and initializing it in
1089 ``main``:
1090
1091-.. code-block:: c++
1092-
1093- static std::unique_ptr<KaleidoscopeJIT> TheJIT;
1094- ...
1095- int main() {
1096- InitializeNativeTarget();
1097- InitializeNativeTargetAsmPrinter();
1098- InitializeNativeTargetAsmParser();
1099+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1100+ :language: c++
1101+ :start-after: chapter4-TheJIT
1102+ :end-before: chapter4-TheJIT
1103
1104- // Install standard binary operators.
1105- // 1 is lowest precedence.
1106- BinopPrecedence['<'] = 10;
1107- BinopPrecedence['+'] = 20;
1108- BinopPrecedence['-'] = 20;
1109- BinopPrecedence['*'] = 40; // highest.
1110-
1111- // Prime the first token.
1112- fprintf(stderr, "ready> ");
1113- getNextToken();
1114-
1115- TheJIT = llvm::make_unique<KaleidoscopeJIT>();
1116-
1117- // Run the main "interpreter loop" now.
1118- MainLoop();
1119-
1120- return 0;
1121- }
1122+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1123+ :language: c++
1124+ :start-after: chapter4-main
1125+ :end-before: chapter4-main
1126
1127 We also need to setup the data layout for the JIT:
1128
1129-.. code-block:: c++
1130-
1131- void InitializeModuleAndPassManager(void) {
1132- // Open a new module.
1133- TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
1134- TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
1135-
1136- // Create a new pass manager attached to it.
1137- TheFPM = llvm::make_unique<FunctionPassManager>(TheModule.get());
1138- ...
1139+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1140+ :language: c++
1141+ :start-after: chapter4-InitializeModuleAndPassManager
1142+ :end-before: chapter4-InitializeModuleAndPassManager
1143+ :emphasize-lines: 4
1144+ :lines: -7
1145
1146 The KaleidoscopeJIT class is a simple JIT built specifically for these
1147 tutorials, available inside the LLVM source code
1148@@ -283,30 +237,10 @@ to look up pointers to the compiled code.
1149 We can take this simple API and change our code that parses top-level expressions to
1150 look like this:
1151
1152-.. code-block:: c++
1153-
1154- static void HandleTopLevelExpression() {
1155- // Evaluate a top-level expression into an anonymous function.
1156- if (auto FnAST = ParseTopLevelExpr()) {
1157- if (FnAST->codegen()) {
1158-
1159- // JIT the module containing the anonymous expression, keeping a handle so
1160- // we can free it later.
1161- auto H = TheJIT->addModule(std::move(TheModule));
1162- InitializeModuleAndPassManager();
1163-
1164- // Search the JIT for the __anon_expr symbol.
1165- auto ExprSymbol = TheJIT->findSymbol("__anon_expr");
1166- assert(ExprSymbol && "Function not found");
1167-
1168- // Get the symbol's address and cast it to the right type (takes no
1169- // arguments, returns a double) so we can call it as a native function.
1170- double (*FP)() = (double (*)())(intptr_t)ExprSymbol.getAddress();
1171- fprintf(stderr, "Evaluated to %f\n", FP());
1172-
1173- // Delete the anonymous expression module from the JIT.
1174- TheJIT->removeModule(H);
1175- }
1176+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1177+ :language: c++
1178+ :start-after: chapter4-HandleTopLevelExpression
1179+ :end-before: chapter4-HandleTopLevelExpression
1180
1181 If parsing and codegen succeeed, the next step is to add the module containing
1182 the top-level expression to the JIT. We do this by calling addModule, which
1183@@ -427,44 +361,23 @@ the most recent definition:
1184 To allow each function to live in its own module we'll need a way to
1185 re-generate previous function declarations into each new module we open:
1186
1187-.. code-block:: c++
1188-
1189- static std::unique_ptr<KaleidoscopeJIT> TheJIT;
1190-
1191- ...
1192-
1193- Function *getFunction(std::string Name) {
1194- // First, see if the function has already been added to the current module.
1195- if (auto *F = TheModule->getFunction(Name))
1196- return F;
1197-
1198- // If not, check whether we can codegen the declaration from some existing
1199- // prototype.
1200- auto FI = FunctionProtos.find(Name);
1201- if (FI != FunctionProtos.end())
1202- return FI->second->codegen();
1203-
1204- // If no existing prototype exists, return null.
1205- return nullptr;
1206- }
1207-
1208- ...
1209-
1210- Value *CallExprAST::codegen() {
1211- // Look up the name in the global module table.
1212- Function *CalleeF = getFunction(Callee);
1213-
1214- ...
1215+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1216+ :language: c++
1217+ :start-after: chapter4-getFunction
1218+ :end-before: chapter4-getFunction
1219
1220- Function *FunctionAST::codegen() {
1221- // Transfer ownership of the prototype to the FunctionProtos map, but keep a
1222- // reference to it for use below.
1223- auto &P = *Proto;
1224- FunctionProtos[Proto->getName()] = std::move(Proto);
1225- Function *TheFunction = getFunction(P.getName());
1226- if (!TheFunction)
1227- return nullptr;
1228+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1229+ :language: c++
1230+ :start-after: chapter4-CallExprAST-codegen
1231+ :end-before: chapter4-CallExprAST-codegen
1232+ :lines: 1-5
1233+ :emphasize-lines: 3
1234
1235+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1236+ :language: c++
1237+ :start-after: chapter4-FunctionAST-codegen
1238+ :end-before: chapter4-FunctionAST-codegen
1239+ :lines: 1-8
1240
1241 To enable this, we'll start by adding a new global, ``FunctionProtos``, that
1242 holds the most recent prototype for each function. We'll also add a convenience
1243@@ -479,36 +392,10 @@ previously declared function.
1244
1245 We also need to update HandleDefinition and HandleExtern:
1246
1247-.. code-block:: c++
1248-
1249- static void HandleDefinition() {
1250- if (auto FnAST = ParseDefinition()) {
1251- if (auto *FnIR = FnAST->codegen()) {
1252- fprintf(stderr, "Read function definition:");
1253- FnIR->print(errs());
1254- fprintf(stderr, "\n");
1255- TheJIT->addModule(std::move(TheModule));
1256- InitializeModuleAndPassManager();
1257- }
1258- } else {
1259- // Skip token for error recovery.
1260- getNextToken();
1261- }
1262- }
1263-
1264- static void HandleExtern() {
1265- if (auto ProtoAST = ParseExtern()) {
1266- if (auto *FnIR = ProtoAST->codegen()) {
1267- fprintf(stderr, "Read extern: ");
1268- FnIR->print(errs());
1269- fprintf(stderr, "\n");
1270- FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
1271- }
1272- } else {
1273- // Skip token for error recovery.
1274- getNextToken();
1275- }
1276- }
1277+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1278+ :language: c++
1279+ :start-after: chapter4-HandleDefinition+HandleExtern
1280+ :end-before: chapter4-HandleDefinition+HandleExtern
1281
1282 In HandleDefinition, we add two lines to transfer the newly defined function to
1283 the JIT and open a new module. In HandleExtern, we just need to add one line to
1284@@ -595,19 +482,10 @@ One immediate benefit of the symbol resolution rule is that we can now extend
1285 the language by writing arbitrary C++ code to implement operations. For example,
1286 if we add:
1287
1288-.. code-block:: c++
1289-
1290- #ifdef LLVM_ON_WIN32
1291- #define DLLEXPORT __declspec(dllexport)
1292- #else
1293- #define DLLEXPORT
1294- #endif
1295-
1296- /// putchard - putchar that takes a double and returns 0.
1297- extern "C" DLLEXPORT double putchard(double X) {
1298- fputc((char)X, stderr);
1299- return 0;
1300- }
1301+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
1302+ :language: c++
1303+ :start-after: chapter4-extern
1304+ :end-before: chapter4-extern
1305
1306 Note, that for Windows we need to actually export the functions because
1307 the dynamic symbol loader will use GetProcAddress to find the symbols.
1308diff --git a/docs/tutorial/LangImpl05.rst b/docs/tutorial/LangImpl05.rst
1309index 8650892e8f8..9ef3d2db932 100644
1310--- a/docs/tutorial/LangImpl05.rst
1311+++ b/docs/tutorial/LangImpl05.rst
1312@@ -63,49 +63,33 @@ Lexer Extensions for If/Then/Else
1313 The lexer extensions are straightforward. First we add new enum values
1314 for the relevant tokens:
1315
1316-.. code-block:: c++
1317-
1318- // control
1319- tok_if = -6,
1320- tok_then = -7,
1321- tok_else = -8,
1322+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1323+ :language: c++
1324+ :start-after: chapter5-tokens1
1325+ :end-before: chapter5-tokens1
1326+ :lines: 1-4
1327+ :dedent: 2
1328
1329 Once we have that, we recognize the new keywords in the lexer. This is
1330 pretty simple stuff:
1331
1332-.. code-block:: c++
1333-
1334- ...
1335- if (IdentifierStr == "def")
1336- return tok_def;
1337- if (IdentifierStr == "extern")
1338- return tok_extern;
1339- if (IdentifierStr == "if")
1340- return tok_if;
1341- if (IdentifierStr == "then")
1342- return tok_then;
1343- if (IdentifierStr == "else")
1344- return tok_else;
1345- return tok_identifier;
1346+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1347+ :language: c++
1348+ :start-after: chapter5-gettok
1349+ :end-before: chapter5-gettok
1350+ :lines: -10,15
1351+ :emphasize-lines: 5-10
1352+ :dedent: 4
1353
1354 AST Extensions for If/Then/Else
1355 -------------------------------
1356
1357 To represent the new expression we add a new AST node for it:
1358
1359-.. code-block:: c++
1360-
1361- /// IfExprAST - Expression class for if/then/else.
1362- class IfExprAST : public ExprAST {
1363- std::unique_ptr<ExprAST> Cond, Then, Else;
1364-
1365- public:
1366- IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,
1367- std::unique_ptr<ExprAST> Else)
1368- : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}
1369-
1370- Value *codegen() override;
1371- };
1372+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1373+ :language: c++
1374+ :start-after: chapter5-IfExprAST
1375+ :end-before: chapter5-IfExprAST
1376
1377 The AST node just has pointers to the various subexpressions.
1378
1379@@ -116,56 +100,19 @@ Now that we have the relevant tokens coming from the lexer and we have
1380 the AST node to build, our parsing logic is relatively straightforward.
1381 First we define a new parsing function:
1382
1383-.. code-block:: c++
1384-
1385- /// ifexpr ::= 'if' expression 'then' expression 'else' expression
1386- static std::unique_ptr<ExprAST> ParseIfExpr() {
1387- getNextToken(); // eat the if.
1388-
1389- // condition.
1390- auto Cond = ParseExpression();
1391- if (!Cond)
1392- return nullptr;
1393-
1394- if (CurTok != tok_then)
1395- return LogError("expected then");
1396- getNextToken(); // eat the then
1397-
1398- auto Then = ParseExpression();
1399- if (!Then)
1400- return nullptr;
1401-
1402- if (CurTok != tok_else)
1403- return LogError("expected else");
1404-
1405- getNextToken();
1406-
1407- auto Else = ParseExpression();
1408- if (!Else)
1409- return nullptr;
1410-
1411- return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),
1412- std::move(Else));
1413- }
1414+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1415+ :language: c++
1416+ :start-after: chapter5-ParseIfExpr
1417+ :end-before: chapter5-ParseIfExpr
1418
1419 Next we hook it up as a primary expression:
1420
1421-.. code-block:: c++
1422-
1423- static std::unique_ptr<ExprAST> ParsePrimary() {
1424- switch (CurTok) {
1425- default:
1426- return LogError("unknown token when expecting an expression");
1427- case tok_identifier:
1428- return ParseIdentifierExpr();
1429- case tok_number:
1430- return ParseNumberExpr();
1431- case '(':
1432- return ParseParenExpr();
1433- case tok_if:
1434- return ParseIfExpr();
1435- }
1436- }
1437+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1438+ :language: c++
1439+ :start-after: chapter5-ParsePrimary
1440+ :end-before: chapter5-ParsePrimary
1441+ :lines: -12,15-
1442+ :emphasize-lines: 11-12
1443
1444 LLVM IR for If/Then/Else
1445 ------------------------
1446@@ -284,33 +231,20 @@ Code Generation for If/Then/Else
1447 In order to generate code for this, we implement the ``codegen`` method
1448 for ``IfExprAST``:
1449
1450-.. code-block:: c++
1451-
1452- Value *IfExprAST::codegen() {
1453- Value *CondV = Cond->codegen();
1454- if (!CondV)
1455- return nullptr;
1456-
1457- // Convert condition to a bool by comparing non-equal to 0.0.
1458- CondV = Builder.CreateFCmpONE(
1459- CondV, ConstantFP::get(TheContext, APFloat(0.0)), "ifcond");
1460+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1461+ :language: c++
1462+ :start-after: chapter5-IfExprAST-codegen1
1463+ :end-before: chapter5-IfExprAST-codegen1
1464
1465 This code is straightforward and similar to what we saw before. We emit
1466 the expression for the condition, then compare that value to zero to get
1467 a truth value as a 1-bit (bool) value.
1468
1469-.. code-block:: c++
1470-
1471- Function *TheFunction = Builder.GetInsertBlock()->getParent();
1472-
1473- // Create blocks for the then and else cases. Insert the 'then' block at the
1474- // end of the function.
1475- BasicBlock *ThenBB =
1476- BasicBlock::Create(TheContext, "then", TheFunction);
1477- BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
1478- BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
1479-
1480- Builder.CreateCondBr(CondV, ThenBB, ElseBB);
1481+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1482+ :language: c++
1483+ :start-after: chapter5-IfExprAST-codegen2
1484+ :end-before: chapter5-IfExprAST-codegen2
1485+ :dedent: 2
1486
1487 This code creates the basic blocks that are related to the if/then/else
1488 statement, and correspond directly to the blocks in the example above.
1489@@ -333,18 +267,11 @@ condition went into. Also note that it is creating a branch to the
1490 inserted into the function yet. This is all ok: it is the standard way
1491 that LLVM supports forward references.
1492
1493-.. code-block:: c++
1494-
1495- // Emit then value.
1496- Builder.SetInsertPoint(ThenBB);
1497-
1498- Value *ThenV = Then->codegen();
1499- if (!ThenV)
1500- return nullptr;
1501-
1502- Builder.CreateBr(MergeBB);
1503- // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
1504- ThenBB = Builder.GetInsertBlock();
1505+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1506+ :language: c++
1507+ :start-after: chapter5-IfExprAST-codegen3
1508+ :end-before: chapter5-IfExprAST-codegen3
1509+ :dedent: 2
1510
1511 After the conditional branch is inserted, we move the builder to start
1512 inserting into the "then" block. Strictly speaking, this call moves the
1513@@ -374,19 +301,11 @@ expression. Because calling ``codegen()`` recursively could arbitrarily change
1514 the notion of the current block, we are required to get an up-to-date
1515 value for code that will set up the Phi node.
1516
1517-.. code-block:: c++
1518-
1519- // Emit else block.
1520- TheFunction->getBasicBlockList().push_back(ElseBB);
1521- Builder.SetInsertPoint(ElseBB);
1522-
1523- Value *ElseV = Else->codegen();
1524- if (!ElseV)
1525- return nullptr;
1526-
1527- Builder.CreateBr(MergeBB);
1528- // codegen of 'Else' can change the current block, update ElseBB for the PHI.
1529- ElseBB = Builder.GetInsertBlock();
1530+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1531+ :language: c++
1532+ :start-after: chapter5-IfExprAST-codegen4
1533+ :end-before: chapter5-IfExprAST-codegen4
1534+ :dedent: 2
1535
1536 Code generation for the 'else' block is basically identical to codegen
1537 for the 'then' block. The only significant difference is the first line,
1538@@ -395,18 +314,10 @@ which adds the 'else' block to the function. Recall previously that the
1539 'then' and 'else' blocks are emitted, we can finish up with the merge
1540 code:
1541
1542-.. code-block:: c++
1543-
1544- // Emit merge block.
1545- TheFunction->getBasicBlockList().push_back(MergeBB);
1546- Builder.SetInsertPoint(MergeBB);
1547- PHINode *PN =
1548- Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");
1549-
1550- PN->addIncoming(ThenV, ThenBB);
1551- PN->addIncoming(ElseV, ElseBB);
1552- return PN;
1553- }
1554+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1555+ :language: c++
1556+ :start-after: chapter5-IfExprAST-codegen5
1557+ :end-before: chapter5-IfExprAST-codegen5
1558
1559 The first two lines here are now familiar: the first adds the "merge"
1560 block to the Function object (it was previously floating, like the else
1561@@ -458,29 +369,23 @@ Lexer Extensions for the 'for' Loop
1562
1563 The lexer extensions are the same sort of thing as for if/then/else:
1564
1565-.. code-block:: c++
1566-
1567- ... in enum Token ...
1568- // control
1569- tok_if = -6, tok_then = -7, tok_else = -8,
1570- tok_for = -9, tok_in = -10
1571-
1572- ... in gettok ...
1573- if (IdentifierStr == "def")
1574- return tok_def;
1575- if (IdentifierStr == "extern")
1576- return tok_extern;
1577- if (IdentifierStr == "if")
1578- return tok_if;
1579- if (IdentifierStr == "then")
1580- return tok_then;
1581- if (IdentifierStr == "else")
1582- return tok_else;
1583- if (IdentifierStr == "for")
1584- return tok_for;
1585- if (IdentifierStr == "in")
1586- return tok_in;
1587- return tok_identifier;
1588+In the Token enum:
1589+
1590+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1591+ :language: c++
1592+ :start-after: chapter5-tokens1
1593+ :end-before: chapter5-tokens1
1594+ :emphasize-lines: 5-6
1595+ :dedent: 2
1596+
1597+In the gettok function:
1598+
1599+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1600+ :language: c++
1601+ :start-after: chapter5-gettok
1602+ :end-before: chapter5-gettok
1603+ :emphasize-lines: 11-14
1604+ :dedent: 4
1605
1606 AST Extensions for the 'for' Loop
1607 ---------------------------------
1608@@ -488,22 +393,10 @@ AST Extensions for the 'for' Loop
1609 The AST node is just as simple. It basically boils down to capturing the
1610 variable name and the constituent expressions in the node.
1611
1612-.. code-block:: c++
1613-
1614- /// ForExprAST - Expression class for for/in.
1615- class ForExprAST : public ExprAST {
1616- std::string VarName;
1617- std::unique_ptr<ExprAST> Start, End, Step, Body;
1618-
1619- public:
1620- ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,
1621- std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,
1622- std::unique_ptr<ExprAST> Body)
1623- : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
1624- Step(std::move(Step)), Body(std::move(Body)) {}
1625-
1626- Value *codegen() override;
1627- };
1628+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1629+ :language: c++
1630+ :start-after: chapter5-ForExprAST
1631+ :end-before: chapter5-ForExprAST
1632
1633 Parser Extensions for the 'for' Loop
1634 ------------------------------------
1635@@ -513,76 +406,18 @@ is handling of the optional step value. The parser code handles it by
1636 checking to see if the second comma is present. If not, it sets the step
1637 value to null in the AST node:
1638
1639-.. code-block:: c++
1640-
1641- /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
1642- static std::unique_ptr<ExprAST> ParseForExpr() {
1643- getNextToken(); // eat the for.
1644-
1645- if (CurTok != tok_identifier)
1646- return LogError("expected identifier after for");
1647-
1648- std::string IdName = IdentifierStr;
1649- getNextToken(); // eat identifier.
1650-
1651- if (CurTok != '=')
1652- return LogError("expected '=' after for");
1653- getNextToken(); // eat '='.
1654-
1655-
1656- auto Start = ParseExpression();
1657- if (!Start)
1658- return nullptr;
1659- if (CurTok != ',')
1660- return LogError("expected ',' after for start value");
1661- getNextToken();
1662-
1663- auto End = ParseExpression();
1664- if (!End)
1665- return nullptr;
1666-
1667- // The step value is optional.
1668- std::unique_ptr<ExprAST> Step;
1669- if (CurTok == ',') {
1670- getNextToken();
1671- Step = ParseExpression();
1672- if (!Step)
1673- return nullptr;
1674- }
1675-
1676- if (CurTok != tok_in)
1677- return LogError("expected 'in' after for");
1678- getNextToken(); // eat 'in'.
1679-
1680- auto Body = ParseExpression();
1681- if (!Body)
1682- return nullptr;
1683-
1684- return llvm::make_unique<ForExprAST>(IdName, std::move(Start),
1685- std::move(End), std::move(Step),
1686- std::move(Body));
1687- }
1688+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1689+ :language: c++
1690+ :start-after: chapter5-ParseForExpr
1691+ :end-before: chapter5-ParseForExpr
1692
1693 And again we hook it up as a primary expression:
1694
1695-.. code-block:: c++
1696-
1697- static std::unique_ptr<ExprAST> ParsePrimary() {
1698- switch (CurTok) {
1699- default:
1700- return LogError("unknown token when expecting an expression");
1701- case tok_identifier:
1702- return ParseIdentifierExpr();
1703- case tok_number:
1704- return ParseNumberExpr();
1705- case '(':
1706- return ParseParenExpr();
1707- case tok_if:
1708- return ParseIfExpr();
1709- case tok_for:
1710- return ParseForExpr();
1711- }
1712- }
1713+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1714+ :language: c++
1715+ :start-after: chapter5-ParsePrimary
1716+ :end-before: chapter5-ParsePrimary
1717+ :emphasize-lines: 13-14
1718
1719 LLVM IR for the 'for' Loop
1720 --------------------------
1721@@ -628,13 +463,10 @@ Code Generation for the 'for' Loop
1722 The first part of codegen is very simple: we just output the start
1723 expression for the loop value:
1724
1725-.. code-block:: c++
1726-
1727- Value *ForExprAST::codegen() {
1728- // Emit the start code first, without 'variable' in scope.
1729- Value *StartVal = Start->codegen();
1730- if (!StartVal)
1731- return nullptr;
1732+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1733+ :language: c++
1734+ :start-after: chapter5-ForExprAST-codegen1
1735+ :end-before: chapter5-ForExprAST-codegen1
1736
1737 With this out of the way, the next step is to set up the LLVM basic
1738 block for the start of the loop body. In the case above, the whole loop
1739@@ -642,17 +474,11 @@ body is one block, but remember that the body code itself could consist
1740 of multiple blocks (e.g. if it contains an if/then/else or a for/in
1741 expression).
1742
1743-.. code-block:: c++
1744-
1745- // Make the new basic block for the loop header, inserting after current
1746- // block.
1747- Function *TheFunction = Builder.GetInsertBlock()->getParent();
1748- BasicBlock *PreheaderBB = Builder.GetInsertBlock();
1749- BasicBlock *LoopBB =
1750- BasicBlock::Create(TheContext, "loop", TheFunction);
1751-
1752- // Insert an explicit fall through from the current block to the LoopBB.
1753- Builder.CreateBr(LoopBB);
1754+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1755+ :language: c++
1756+ :start-after: chapter5-ForExprAST-codegen2
1757+ :end-before: chapter5-ForExprAST-codegen2
1758+ :dedent: 2
1759
1760 This code is similar to what we saw for if/then/else. Because we will
1761 need it to create the Phi node, we remember the block that falls through
1762@@ -660,15 +486,11 @@ into the loop. Once we have that, we create the actual block that starts
1763 the loop and create an unconditional branch for the fall-through between
1764 the two blocks.
1765
1766-.. code-block:: c++
1767-
1768- // Start insertion in LoopBB.
1769- Builder.SetInsertPoint(LoopBB);
1770-
1771- // Start the PHI node with an entry for Start.
1772- PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(TheContext),
1773- 2, VarName.c_str());
1774- Variable->addIncoming(StartVal, PreheaderBB);
1775+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1776+ :language: c++
1777+ :start-after: chapter5-ForExprAST-codegen3
1778+ :end-before: chapter5-ForExprAST-codegen3
1779+ :dedent: 2
1780
1781 Now that the "preheader" for the loop is set up, we switch to emitting
1782 code for the loop body. To begin with, we move the insertion point and
1783@@ -677,18 +499,11 @@ know the incoming value for the starting value, we add it to the Phi
1784 node. Note that the Phi will eventually get a second value for the
1785 backedge, but we can't set it up yet (because it doesn't exist!).
1786
1787-.. code-block:: c++
1788-
1789- // Within the loop, the variable is defined equal to the PHI node. If it
1790- // shadows an existing variable, we have to restore it, so save it now.
1791- Value *OldVal = NamedValues[VarName];
1792- NamedValues[VarName] = Variable;
1793-
1794- // Emit the body of the loop. This, like any other expr, can change the
1795- // current BB. Note that we ignore the value computed by the body, but don't
1796- // allow an error.
1797- if (!Body->codegen())
1798- return nullptr;
1799+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1800+ :language: c++
1801+ :start-after: chapter5-ForExprAST-codegen4
1802+ :end-before: chapter5-ForExprAST-codegen4
1803+ :dedent: 2
1804
1805 Now the code starts to get more interesting. Our 'for' loop introduces a
1806 new variable to the symbol table. This means that our symbol table can
1807@@ -707,53 +522,32 @@ recursively codegen's the body. This allows the body to use the loop
1808 variable: any references to it will naturally find it in the symbol
1809 table.
1810
1811-.. code-block:: c++
1812-
1813- // Emit the step value.
1814- Value *StepVal = nullptr;
1815- if (Step) {
1816- StepVal = Step->codegen();
1817- if (!StepVal)
1818- return nullptr;
1819- } else {
1820- // If not specified, use 1.0.
1821- StepVal = ConstantFP::get(TheContext, APFloat(1.0));
1822- }
1823-
1824- Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
1825+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1826+ :language: c++
1827+ :start-after: chapter5-ForExprAST-codegen5
1828+ :end-before: chapter5-ForExprAST-codegen5
1829+ :dedent: 2
1830
1831 Now that the body is emitted, we compute the next value of the iteration
1832 variable by adding the step value, or 1.0 if it isn't present.
1833 '``NextVar``' will be the value of the loop variable on the next
1834 iteration of the loop.
1835
1836-.. code-block:: c++
1837-
1838- // Compute the end condition.
1839- Value *EndCond = End->codegen();
1840- if (!EndCond)
1841- return nullptr;
1842-
1843- // Convert condition to a bool by comparing non-equal to 0.0.
1844- EndCond = Builder.CreateFCmpONE(
1845- EndCond, ConstantFP::get(TheContext, APFloat(0.0)), "loopcond");
1846+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1847+ :language: c++
1848+ :start-after: chapter5-ForExprAST-codegen6
1849+ :end-before: chapter5-ForExprAST-codegen6
1850+ :dedent: 2
1851
1852 Finally, we evaluate the exit value of the loop, to determine whether
1853 the loop should exit. This mirrors the condition evaluation for the
1854 if/then/else statement.
1855
1856-.. code-block:: c++
1857-
1858- // Create the "after loop" block and insert it.
1859- BasicBlock *LoopEndBB = Builder.GetInsertBlock();
1860- BasicBlock *AfterBB =
1861- BasicBlock::Create(TheContext, "afterloop", TheFunction);
1862-
1863- // Insert the conditional branch into the end of LoopEndBB.
1864- Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
1865-
1866- // Any new code will be inserted in AfterBB.
1867- Builder.SetInsertPoint(AfterBB);
1868+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1869+ :language: c++
1870+ :start-after: chapter5-ForExprAST-codegen7
1871+ :end-before: chapter5-ForExprAST-codegen7
1872+ :dedent: 2
1873
1874 With the code for the body of the loop complete, we just need to finish
1875 up the control flow for it. This code remembers the end block (for the
1876@@ -763,20 +557,10 @@ chooses between executing the loop again and exiting the loop. Any
1877 future code is emitted in the "afterloop" block, so it sets the
1878 insertion position to it.
1879
1880-.. code-block:: c++
1881-
1882- // Add a new entry to the PHI node for the backedge.
1883- Variable->addIncoming(NextVar, LoopEndBB);
1884-
1885- // Restore the unshadowed variable.
1886- if (OldVal)
1887- NamedValues[VarName] = OldVal;
1888- else
1889- NamedValues.erase(VarName);
1890-
1891- // for expr always returns 0.0.
1892- return Constant::getNullValue(Type::getDoubleTy(TheContext));
1893- }
1894+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
1895+ :language: c++
1896+ :start-after: chapter5-ForExprAST-codegen8
1897+ :end-before: chapter5-ForExprAST-codegen8
1898
1899 The final code handles various cleanups: now that we have the "NextVar"
1900 value, we can add the incoming value to the loop PHI node. After that,
1901diff --git a/docs/tutorial/LangImpl06.rst b/docs/tutorial/LangImpl06.rst
1902index cb8ec766bb2..9c3e04c3f97 100644
1903--- a/docs/tutorial/LangImpl06.rst
1904+++ b/docs/tutorial/LangImpl06.rst
1905@@ -127,35 +127,10 @@ definition is parsed as the "prototype" production and into the
1906 as prototypes, we have to extend the ``PrototypeAST`` AST node like
1907 this:
1908
1909-.. code-block:: c++
1910-
1911- /// PrototypeAST - This class represents the "prototype" for a function,
1912- /// which captures its argument names as well as if it is an operator.
1913- class PrototypeAST {
1914- std::string Name;
1915- std::vector<std::string> Args;
1916- bool IsOperator;
1917- unsigned Precedence; // Precedence if a binary op.
1918-
1919- public:
1920- PrototypeAST(const std::string &name, std::vector<std::string> Args,
1921- bool IsOperator = false, unsigned Prec = 0)
1922- : Name(name), Args(std::move(Args)), IsOperator(IsOperator),
1923- Precedence(Prec) {}
1924-
1925- Function *codegen();
1926- const std::string &getName() const { return Name; }
1927-
1928- bool isUnaryOp() const { return IsOperator && Args.size() == 1; }
1929- bool isBinaryOp() const { return IsOperator && Args.size() == 2; }
1930-
1931- char getOperatorName() const {
1932- assert(isUnaryOp() || isBinaryOp());
1933- return Name[Name.size() - 1];
1934- }
1935-
1936- unsigned getBinaryPrecedence() const { return Precedence; }
1937- };
1938+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
1939+ :language: c++
1940+ :start-after: chapter6-PrototypeAST
1941+ :end-before: chapter6-PrototypeAST
1942
1943 Basically, in addition to knowing a name for the prototype, we now keep
1944 track of whether it was an operator, and if it was, what precedence
1945@@ -164,63 +139,11 @@ operators (as you'll see below, it just doesn't apply for unary
1946 operators). Now that we have a way to represent the prototype for a
1947 user-defined operator, we need to parse it:
1948
1949-.. code-block:: c++
1950-
1951- /// prototype
1952- /// ::= id '(' id* ')'
1953- /// ::= binary LETTER number? (id, id)
1954- static std::unique_ptr<PrototypeAST> ParsePrototype() {
1955- std::string FnName;
1956-
1957- unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
1958- unsigned BinaryPrecedence = 30;
1959-
1960- switch (CurTok) {
1961- default:
1962- return LogErrorP("Expected function name in prototype");
1963- case tok_identifier:
1964- FnName = IdentifierStr;
1965- Kind = 0;
1966- getNextToken();
1967- break;
1968- case tok_binary:
1969- getNextToken();
1970- if (!isascii(CurTok))
1971- return LogErrorP("Expected binary operator");
1972- FnName = "binary";
1973- FnName += (char)CurTok;
1974- Kind = 2;
1975- getNextToken();
1976-
1977- // Read the precedence if present.
1978- if (CurTok == tok_number) {
1979- if (NumVal < 1 || NumVal > 100)
1980- return LogErrorP("Invalid precedence: must be 1..100");
1981- BinaryPrecedence = (unsigned)NumVal;
1982- getNextToken();
1983- }
1984- break;
1985- }
1986-
1987- if (CurTok != '(')
1988- return LogErrorP("Expected '(' in prototype");
1989-
1990- std::vector<std::string> ArgNames;
1991- while (getNextToken() == tok_identifier)
1992- ArgNames.push_back(IdentifierStr);
1993- if (CurTok != ')')
1994- return LogErrorP("Expected ')' in prototype");
1995-
1996- // success.
1997- getNextToken(); // eat ')'.
1998-
1999- // Verify right number of names for operator.
2000- if (Kind && ArgNames.size() != Kind)
2001- return LogErrorP("Invalid number of operands for operator");
2002-
2003- return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames), Kind != 0,
2004- BinaryPrecedence);
2005- }
2006+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
2007+ :language: c++
2008+ :start-after: chapter6-ParsePrototype
2009+ :end-before: chapter6-ParsePrototype
2010+ :lines: -18,28-
2011
2012 This is all fairly straightforward parsing code, and we have already
2013 seen a lot of similar code in the past. One interesting part about the
2014@@ -234,38 +157,10 @@ The next interesting thing to add, is codegen support for these binary
2015 operators. Given our current structure, this is a simple addition of a
2016 default case for our existing binary operator node:
2017
2018-.. code-block:: c++
2019-
2020- Value *BinaryExprAST::codegen() {
2021- Value *L = LHS->codegen();
2022- Value *R = RHS->codegen();
2023- if (!L || !R)
2024- return nullptr;
2025-
2026- switch (Op) {
2027- case '+':
2028- return Builder.CreateFAdd(L, R, "addtmp");
2029- case '-':
2030- return Builder.CreateFSub(L, R, "subtmp");
2031- case '*':
2032- return Builder.CreateFMul(L, R, "multmp");
2033- case '<':
2034- L = Builder.CreateFCmpULT(L, R, "cmptmp");
2035- // Convert bool 0/1 to double 0.0 or 1.0
2036- return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext),
2037- "booltmp");
2038- default:
2039- break;
2040- }
2041-
2042- // If it wasn't a builtin binary operator, it must be a user defined one. Emit
2043- // a call to it.
2044- Function *F = getFunction(std::string("binary") + Op);
2045- assert(F && "binary operator not found!");
2046-
2047- Value *Ops[2] = { L, R };
2048- return Builder.CreateCall(F, Ops, "binop");
2049- }
2050+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
2051+ :language: c++
2052+ :start-after: chapter6-BinaryExprAST-codegen
2053+ :end-before: chapter6-BinaryExprAST-codegen
2054
2055 As you can see above, the new code is actually really simple. It just
2056 does a lookup for the appropriate operator in the symbol table and
2057@@ -275,24 +170,10 @@ function with the right name) everything falls into place.
2058
2059 The final piece of code we are missing, is a bit of top-level magic:
2060
2061-.. code-block:: c++
2062-
2063- Function *FunctionAST::codegen() {
2064- // Transfer ownership of the prototype to the FunctionProtos map, but keep a
2065- // reference to it for use below.
2066- auto &P = *Proto;
2067- FunctionProtos[Proto->getName()] = std::move(Proto);
2068- Function *TheFunction = getFunction(P.getName());
2069- if (!TheFunction)
2070- return nullptr;
2071-
2072- // If this is an operator, install it.
2073- if (P.isBinaryOp())
2074- BinopPrecedence[P.getOperatorName()] = P.getBinaryPrecedence();
2075-
2076- // Create a new basic block to start insertion into.
2077- BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
2078- ...
2079+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
2080+ :language: c++
2081+ :start-after: chapter6-FunctionAST-codegen
2082+ :end-before: chapter6-FunctionAST-codegen
2083
2084 Basically, before codegening a function, if it is a user-defined
2085 operator, we register it in the precedence table. This allows the binary
2086@@ -313,42 +194,20 @@ language, we'll need to add everything to support them. Above, we added
2087 simple support for the 'unary' keyword to the lexer. In addition to
2088 that, we need an AST node:
2089
2090-.. code-block:: c++
2091-
2092- /// UnaryExprAST - Expression class for a unary operator.
2093- class UnaryExprAST : public ExprAST {
2094- char Opcode;
2095- std::unique_ptr<ExprAST> Operand;
2096-
2097- public:
2098- UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)
2099- : Opcode(Opcode), Operand(std::move(Operand)) {}
2100-
2101- Value *codegen() override;
2102- };
2103+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
2104+ :language: c++
2105+ :start-after: chapter6-UnaryExprAST
2106+ :end-before: chapter6-UnaryExprAST
2107
2108 This AST node is very simple and obvious by now. It directly mirrors the
2109 binary operator AST node, except that it only has one child. With this,
2110 we need to add the parsing logic. Parsing a unary operator is pretty
2111 simple: we'll add a new function to do it:
2112
2113-.. code-block:: c++
2114-
2115- /// unary
2116- /// ::= primary
2117- /// ::= '!' unary
2118- static std::unique_ptr<ExprAST> ParseUnary() {
2119- // If the current token is not an operator, it must be a primary expr.
2120- if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
2121- return ParsePrimary();
2122-
2123- // If this is a unary operator, read it.
2124- int Opc = CurTok;
2125- getNextToken();
2126- if (auto Operand = ParseUnary())
2127- return llvm::make_unique<UnaryExprAST>(Opc, std::move(Operand));
2128- return nullptr;
2129- }
2130+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
2131+ :language: c++
2132+ :start-after: chapter6-ParseUnary
2133+ :end-before: chapter6-ParseUnary
2134
2135 The grammar we add is pretty straightforward here. If we see a unary
2136 operator when parsing a primary operator, we eat the operator as a
2137@@ -374,72 +233,33 @@ call ParseUnary instead:
2138 return nullptr;
2139 ...
2140 }
2141- /// expression
2142- /// ::= unary binoprhs
2143- ///
2144- static std::unique_ptr<ExprAST> ParseExpression() {
2145- auto LHS = ParseUnary();
2146- if (!LHS)
2147- return nullptr;
2148-
2149- return ParseBinOpRHS(0, std::move(LHS));
2150- }
2151+
2152+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
2153+ :language: c++
2154+ :start-after: chapter6-ParseExpression
2155+ :end-before: chapter6-ParseExpression
2156
2157 With these two simple changes, we are now able to parse unary operators
2158 and build the AST for them. Next up, we need to add parser support for
2159 prototypes, to parse the unary operator prototype. We extend the binary
2160 operator code above with:
2161
2162-.. code-block:: c++
2163-
2164- /// prototype
2165- /// ::= id '(' id* ')'
2166- /// ::= binary LETTER number? (id, id)
2167- /// ::= unary LETTER (id)
2168- static std::unique_ptr<PrototypeAST> ParsePrototype() {
2169- std::string FnName;
2170-
2171- unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
2172- unsigned BinaryPrecedence = 30;
2173-
2174- switch (CurTok) {
2175- default:
2176- return LogErrorP("Expected function name in prototype");
2177- case tok_identifier:
2178- FnName = IdentifierStr;
2179- Kind = 0;
2180- getNextToken();
2181- break;
2182- case tok_unary:
2183- getNextToken();
2184- if (!isascii(CurTok))
2185- return LogErrorP("Expected unary operator");
2186- FnName = "unary";
2187- FnName += (char)CurTok;
2188- Kind = 1;
2189- getNextToken();
2190- break;
2191- case tok_binary:
2192- ...
2193+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
2194+ :language: c++
2195+ :start-after: chapter6-ParsePrototype
2196+ :end-before: chapter6-ParsePrototype
2197+ :emphasize-lines: 19-27
2198+ :lines: -28
2199
2200 As with binary operators, we name unary operators with a name that
2201 includes the operator character. This assists us at code generation
2202 time. Speaking of, the final piece we need to add is codegen support for
2203 unary operators. It looks like this:
2204
2205-.. code-block:: c++
2206-
2207- Value *UnaryExprAST::codegen() {
2208- Value *OperandV = Operand->codegen();
2209- if (!OperandV)
2210- return nullptr;
2211-
2212- Function *F = getFunction(std::string("unary") + Opcode);
2213- if (!F)
2214- return LogErrorV("Unknown unary operator");
2215-
2216- return Builder.CreateCall(F, OperandV, "unop");
2217- }
2218+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
2219+ :language: c++
2220+ :start-after: chapter6-UnaryExprAST-codegen
2221+ :end-before: chapter6-UnaryExprAST-codegen
2222
2223 This code is similar to, but simpler than, the code for binary
2224 operators. It is simpler primarily because it doesn't need to handle any
2225diff --git a/docs/tutorial/LangImpl07.rst b/docs/tutorial/LangImpl07.rst
2226index 582645f449b..131e2a76b52 100644
2227--- a/docs/tutorial/LangImpl07.rst
2228+++ b/docs/tutorial/LangImpl07.rst
2229@@ -331,17 +331,10 @@ Also, since we will need to create these allocas, we'll use a helper
2230 function that ensures that the allocas are created in the entry block of
2231 the function:
2232
2233-.. code-block:: c++
2234-
2235- /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
2236- /// the function. This is used for mutable variables etc.
2237- static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
2238- const std::string &VarName) {
2239- IRBuilder<> TmpB(&TheFunction->getEntryBlock(),
2240- TheFunction->getEntryBlock().begin());
2241- return TmpB.CreateAlloca(Type::getDoubleTy(TheContext), 0,
2242- VarName.c_str());
2243- }
2244+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2245+ :language: c++
2246+ :start-after: chapter7-CreateEntryBlockAlloca
2247+ :end-before: chapter7-CreateEntryBlockAlloca
2248
2249 This funny looking code creates an IRBuilder object that is pointing at
2250 the first instruction (.begin()) of the entry block. It then creates an
2251@@ -353,50 +346,27 @@ variable references. In our new scheme, variables live on the stack, so
2252 code generating a reference to them actually needs to produce a load
2253 from the stack slot:
2254
2255-.. code-block:: c++
2256-
2257- Value *VariableExprAST::codegen() {
2258- // Look this variable up in the function.
2259- Value *V = NamedValues[Name];
2260- if (!V)
2261- return LogErrorV("Unknown variable name");
2262-
2263- // Load the value.
2264- return Builder.CreateLoad(V, Name.c_str());
2265- }
2266+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2267+ :language: c++
2268+ :start-after: chapter7-VariableExprAST-codegen
2269+ :end-before: chapter7-VariableExprAST-codegen
2270
2271 As you can see, this is pretty straightforward. Now we need to update
2272 the things that define the variables to set up the alloca. We'll start
2273 with ``ForExprAST::codegen()`` (see the `full code listing <#id1>`_ for
2274 the unabridged code):
2275
2276-.. code-block:: c++
2277-
2278- Function *TheFunction = Builder.GetInsertBlock()->getParent();
2279+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2280+ :language: c++
2281+ :start-after: chapter7-ForExprAST-codegen1
2282+ :end-before: chapter7-ForExprAST-codegen1
2283+ :dedent: 2
2284
2285- // Create an alloca for the variable in the entry block.
2286- AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
2287-
2288- // Emit the start code first, without 'variable' in scope.
2289- Value *StartVal = Start->codegen();
2290- if (!StartVal)
2291- return nullptr;
2292-
2293- // Store the value into the alloca.
2294- Builder.CreateStore(StartVal, Alloca);
2295- ...
2296-
2297- // Compute the end condition.
2298- Value *EndCond = End->codegen();
2299- if (!EndCond)
2300- return nullptr;
2301-
2302- // Reload, increment, and restore the alloca. This handles the case where
2303- // the body of the loop mutates the variable.
2304- Value *CurVar = Builder.CreateLoad(Alloca);
2305- Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
2306- Builder.CreateStore(NextVar, Alloca);
2307- ...
2308+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2309+ :language: c++
2310+ :start-after: chapter7-ForExprAST-codegen2
2311+ :end-before: chapter7-ForExprAST-codegen2
2312+ :dedent: 2
2313
2314 This code is virtually identical to the code `before we allowed mutable
2315 variables <LangImpl5.html#code-generation-for-the-for-loop>`_. The big difference is that we
2316@@ -406,27 +376,15 @@ the variable as needed.
2317 To support mutable argument variables, we need to also make allocas for
2318 them. The code for this is also pretty simple:
2319
2320-.. code-block:: c++
2321+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2322+ :language: c++
2323+ :start-after: chapter7-FunctionAST-codegen1
2324+ :end-before: chapter7-FunctionAST-codegen1
2325
2326- Function *FunctionAST::codegen() {
2327- ...
2328- Builder.SetInsertPoint(BB);
2329-
2330- // Record the function arguments in the NamedValues map.
2331- NamedValues.clear();
2332- for (auto &Arg : TheFunction->args()) {
2333- // Create an alloca for this variable.
2334- AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, Arg.getName());
2335-
2336- // Store the initial value into the alloca.
2337- Builder.CreateStore(&Arg, Alloca);
2338-
2339- // Add arguments to variable symbol table.
2340- NamedValues[Arg.getName()] = Alloca;
2341- }
2342-
2343- if (Value *RetVal = Body->codegen()) {
2344- ...
2345+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2346+ :language: c++
2347+ :start-after: chapter7-FunctionAST-codegen2
2348+ :end-before: chapter7-FunctionAST-codegen2
2349
2350 For each argument, we make an alloca, store the input value to the
2351 function into the alloca, and register the alloca as the memory location
2352@@ -436,15 +394,12 @@ right after it sets up the entry block for the function.
2353 The final missing piece is adding the mem2reg pass, which allows us to
2354 get good codegen once again:
2355
2356-.. code-block:: c++
2357-
2358- // Promote allocas to registers.
2359- TheFPM->add(createPromoteMemoryToRegisterPass());
2360- // Do simple "peephole" optimizations and bit-twiddling optzns.
2361- TheFPM->add(createInstructionCombiningPass());
2362- // Reassociate expressions.
2363- TheFPM->add(createReassociatePass());
2364- ...
2365+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2366+ :language: c++
2367+ :start-after: chapter7-passes
2368+ :end-before: chapter7-passes
2369+ :emphasize-lines: 1-2
2370+ :dedent: 2
2371
2372 It is interesting to see what the code looks like before and after the
2373 mem2reg optimization runs. For example, this is the before/after code
2374@@ -572,15 +527,10 @@ Now that the parser knows the precedence of the binary operator, it
2375 takes care of all the parsing and AST generation. We just need to
2376 implement codegen for the assignment operator. This looks like:
2377
2378-.. code-block:: c++
2379-
2380- Value *BinaryExprAST::codegen() {
2381- // Special case '=' because we don't want to emit the LHS as an expression.
2382- if (Op == '=') {
2383- // Assignment requires the LHS to be an identifier.
2384- VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS.get());
2385- if (!LHSE)
2386- return LogErrorV("destination of '=' must be a variable");
2387+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2388+ :language: c++
2389+ :start-after: chapter7-BinaryExprAST-codegen1
2390+ :end-before: chapter7-BinaryExprAST-codegen1
2391
2392 Unlike the rest of the binary operators, our assignment operator doesn't
2393 follow the "emit LHS, emit RHS, do computation" model. As such, it is
2394@@ -589,22 +539,11 @@ The other strange thing is that it requires the LHS to be a variable. It
2395 is invalid to have "(x+1) = expr" - only things like "x = expr" are
2396 allowed.
2397
2398-.. code-block:: c++
2399-
2400- // Codegen the RHS.
2401- Value *Val = RHS->codegen();
2402- if (!Val)
2403- return nullptr;
2404-
2405- // Look up the name.
2406- Value *Variable = NamedValues[LHSE->getName()];
2407- if (!Variable)
2408- return LogErrorV("Unknown variable name");
2409-
2410- Builder.CreateStore(Val, Variable);
2411- return Val;
2412- }
2413- ...
2414+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2415+ :language: c++
2416+ :start-after: chapter7-BinaryExprAST-codegen2
2417+ :end-before: chapter7-BinaryExprAST-codegen2
2418+ :dedent: 2
2419
2420 Once we have the variable, codegen'ing the assignment is
2421 straightforward: we emit the RHS of the assignment, create a store, and
2422@@ -670,20 +609,10 @@ this:
2423 The next step is to define the AST node that we will construct. For
2424 var/in, it looks like this:
2425
2426-.. code-block:: c++
2427-
2428- /// VarExprAST - Expression class for var/in
2429- class VarExprAST : public ExprAST {
2430- std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
2431- std::unique_ptr<ExprAST> Body;
2432-
2433- public:
2434- VarExprAST(std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,
2435- std::unique_ptr<ExprAST> Body)
2436- : VarNames(std::move(VarNames)), Body(std::move(Body)) {}
2437-
2438- Value *codegen() override;
2439- };
2440+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2441+ :language: c++
2442+ :start-after: chapter7-VarExprAST
2443+ :end-before: chapter7-VarExprAST
2444
2445 var/in allows a list of names to be defined all at once, and each name
2446 can optionally have an initializer value. As such, we capture this
2447@@ -693,164 +622,71 @@ is allowed to access the variables defined by the var/in.
2448 With this in place, we can define the parser pieces. The first thing we
2449 do is add it as a primary expression:
2450
2451-.. code-block:: c++
2452-
2453- /// primary
2454- /// ::= identifierexpr
2455- /// ::= numberexpr
2456- /// ::= parenexpr
2457- /// ::= ifexpr
2458- /// ::= forexpr
2459- /// ::= varexpr
2460- static std::unique_ptr<ExprAST> ParsePrimary() {
2461- switch (CurTok) {
2462- default:
2463- return LogError("unknown token when expecting an expression");
2464- case tok_identifier:
2465- return ParseIdentifierExpr();
2466- case tok_number:
2467- return ParseNumberExpr();
2468- case '(':
2469- return ParseParenExpr();
2470- case tok_if:
2471- return ParseIfExpr();
2472- case tok_for:
2473- return ParseForExpr();
2474- case tok_var:
2475- return ParseVarExpr();
2476- }
2477- }
2478+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2479+ :language: c++
2480+ :start-after: chapter7-ParsePrimary
2481+ :end-before: chapter7-ParsePrimary
2482+ :emphasize-lines: 22-23
2483
2484 Next we define ParseVarExpr:
2485
2486-.. code-block:: c++
2487-
2488- /// varexpr ::= 'var' identifier ('=' expression)?
2489- // (',' identifier ('=' expression)?)* 'in' expression
2490- static std::unique_ptr<ExprAST> ParseVarExpr() {
2491- getNextToken(); // eat the var.
2492-
2493- std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
2494-
2495- // At least one variable name is required.
2496- if (CurTok != tok_identifier)
2497- return LogError("expected identifier after var");
2498+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2499+ :language: c++
2500+ :start-after: chapter7-ParseVarExpr1
2501+ :end-before: chapter7-ParseVarExpr1
2502
2503 The first part of this code parses the list of identifier/expr pairs
2504 into the local ``VarNames`` vector.
2505
2506-.. code-block:: c++
2507-
2508- while (1) {
2509- std::string Name = IdentifierStr;
2510- getNextToken(); // eat identifier.
2511-
2512- // Read the optional initializer.
2513- std::unique_ptr<ExprAST> Init;
2514- if (CurTok == '=') {
2515- getNextToken(); // eat the '='.
2516-
2517- Init = ParseExpression();
2518- if (!Init) return nullptr;
2519- }
2520-
2521- VarNames.push_back(std::make_pair(Name, std::move(Init)));
2522-
2523- // End of var list, exit loop.
2524- if (CurTok != ',') break;
2525- getNextToken(); // eat the ','.
2526-
2527- if (CurTok != tok_identifier)
2528- return LogError("expected identifier list after var");
2529- }
2530+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2531+ :language: c++
2532+ :start-after: chapter7-ParseVarExpr2
2533+ :end-before: chapter7-ParseVarExpr2
2534+ :dedent: 2
2535
2536 Once all the variables are parsed, we then parse the body and create the
2537 AST node:
2538
2539-.. code-block:: c++
2540-
2541- // At this point, we have to have 'in'.
2542- if (CurTok != tok_in)
2543- return LogError("expected 'in' keyword after 'var'");
2544- getNextToken(); // eat 'in'.
2545-
2546- auto Body = ParseExpression();
2547- if (!Body)
2548- return nullptr;
2549-
2550- return llvm::make_unique<VarExprAST>(std::move(VarNames),
2551- std::move(Body));
2552- }
2553+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2554+ :language: c++
2555+ :start-after: chapter7-ParseVarExpr3
2556+ :end-before: chapter7-ParseVarExpr3
2557
2558 Now that we can parse and represent the code, we need to support
2559 emission of LLVM IR for it. This code starts out with:
2560
2561-.. code-block:: c++
2562-
2563- Value *VarExprAST::codegen() {
2564- std::vector<AllocaInst *> OldBindings;
2565-
2566- Function *TheFunction = Builder.GetInsertBlock()->getParent();
2567-
2568- // Register all variables and emit their initializer.
2569- for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
2570- const std::string &VarName = VarNames[i].first;
2571- ExprAST *Init = VarNames[i].second.get();
2572+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2573+ :language: c++
2574+ :start-after: chapter7-VarExprAST-codegen1
2575+ :end-before: chapter7-VarExprAST-codegen1
2576
2577 Basically it loops over all the variables, installing them one at a
2578 time. For each variable we put into the symbol table, we remember the
2579 previous value that we replace in OldBindings.
2580
2581-.. code-block:: c++
2582-
2583- // Emit the initializer before adding the variable to scope, this prevents
2584- // the initializer from referencing the variable itself, and permits stuff
2585- // like this:
2586- // var a = 1 in
2587- // var a = a in ... # refers to outer 'a'.
2588- Value *InitVal;
2589- if (Init) {
2590- InitVal = Init->codegen();
2591- if (!InitVal)
2592- return nullptr;
2593- } else { // If not specified, use 0.0.
2594- InitVal = ConstantFP::get(TheContext, APFloat(0.0));
2595- }
2596-
2597- AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
2598- Builder.CreateStore(InitVal, Alloca);
2599-
2600- // Remember the old variable binding so that we can restore the binding when
2601- // we unrecurse.
2602- OldBindings.push_back(NamedValues[VarName]);
2603-
2604- // Remember this binding.
2605- NamedValues[VarName] = Alloca;
2606- }
2607+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2608+ :language: c++
2609+ :start-after: chapter7-VarExprAST-codegen2
2610+ :end-before: chapter7-VarExprAST-codegen2
2611+ :dedent: 2
2612
2613 There are more comments here than code. The basic idea is that we emit
2614 the initializer, create the alloca, then update the symbol table to
2615 point to it. Once all the variables are installed in the symbol table,
2616 we evaluate the body of the var/in expression:
2617
2618-.. code-block:: c++
2619-
2620- // Codegen the body, now that all vars are in scope.
2621- Value *BodyVal = Body->codegen();
2622- if (!BodyVal)
2623- return nullptr;
2624+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2625+ :language: c++
2626+ :start-after: chapter7-VarExprAST-codegen3
2627+ :end-before: chapter7-VarExprAST-codegen3
2628+ :dedent: 2
2629
2630 Finally, before returning, we restore the previous variable bindings:
2631
2632-.. code-block:: c++
2633-
2634- // Pop all our variables from scope.
2635- for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
2636- NamedValues[VarNames[i].first] = OldBindings[i];
2637-
2638- // Return the body computation.
2639- return BodyVal;
2640- }
2641+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
2642+ :language: c++
2643+ :start-after: chapter7-VarExprAST-codegen4
2644+ :end-before: chapter7-VarExprAST-codegen4
2645
2646 The end result of all of this is that we get properly scoped variable
2647 definitions, and we even (trivially) allow mutation of them :).
2648diff --git a/docs/tutorial/LangImpl08.rst b/docs/tutorial/LangImpl08.rst
2649index da4e60f84b8..dd4e0b70df2 100644
2650--- a/docs/tutorial/LangImpl08.rst
2651+++ b/docs/tutorial/LangImpl08.rst
2652@@ -40,9 +40,11 @@ Fortunately, we don't need to hard-code a target triple to target the
2653 current machine. LLVM provides ``sys::getDefaultTargetTriple``, which
2654 returns the target triple of the current machine.
2655
2656-.. code-block:: c++
2657-
2658- auto TargetTriple = sys::getDefaultTargetTriple();
2659+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
2660+ :language: c++
2661+ :start-after: chapter8-TargetTriple
2662+ :end-before: chapter8-TargetTriple
2663+ :dedent: 2
2664
2665 LLVM doesn't require us to link in all the target
2666 functionality. For example, if we're just using the JIT, we don't need
2667@@ -53,28 +55,19 @@ architectures.
2668 For this example, we'll initialize all the targets for emitting object
2669 code.
2670
2671-.. code-block:: c++
2672-
2673- InitializeAllTargetInfos();
2674- InitializeAllTargets();
2675- InitializeAllTargetMCs();
2676- InitializeAllAsmParsers();
2677- InitializeAllAsmPrinters();
2678+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
2679+ :language: c++
2680+ :start-after: chapter8-initialize
2681+ :end-before: chapter8-initialize
2682+ :dedent: 2
2683
2684 We can now use our target triple to get a ``Target``:
2685
2686-.. code-block:: c++
2687-
2688- std::string Error;
2689- auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);
2690-
2691- // Print an error and exit if we couldn't find the requested target.
2692- // This generally occurs if we've forgotten to initialise the
2693- // TargetRegistry or we have a bogus target triple.
2694- if (!Target) {
2695- errs() << Error;
2696- return 1;
2697- }
2698+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
2699+ :language: c++
2700+ :start-after: chapter8-lookup
2701+ :end-before: chapter8-lookup
2702+ :dedent: 2
2703
2704 Target Machine
2705 ==============
2706@@ -108,14 +101,11 @@ To see which features and CPUs that LLVM knows about, we can use
2707 For our example, we'll use the generic CPU without any additional
2708 features, options or relocation model.
2709
2710-.. code-block:: c++
2711-
2712- auto CPU = "generic";
2713- auto Features = "";
2714-
2715- TargetOptions opt;
2716- auto RM = Optional<Reloc::Model>();
2717- auto TargetMachine = Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);
2718+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
2719+ :language: c++
2720+ :start-after: chapter8-target-machine
2721+ :end-before: chapter8-target-machine
2722+ :dedent: 2
2723
2724
2725 Configuring the Module
2726@@ -127,43 +117,32 @@ performance guide <../Frontend/PerformanceTips.html>`_ recommends
2727 this. Optimizations benefit from knowing about the target and data
2728 layout.
2729
2730-.. code-block:: c++
2731+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
2732+ :language: c++
2733+ :start-after: chapter8-module
2734+ :end-before: chapter8-module
2735+ :dedent: 2
2736
2737- TheModule->setDataLayout(TargetMachine->createDataLayout());
2738- TheModule->setTargetTriple(TargetTriple);
2739-
2740 Emit Object Code
2741 ================
2742
2743 We're ready to emit object code! Let's define where we want to write
2744 our file to:
2745
2746-.. code-block:: c++
2747-
2748- auto Filename = "output.o";
2749- std::error_code EC;
2750- raw_fd_ostream dest(Filename, EC, sys::fs::F_None);
2751-
2752- if (EC) {
2753- errs() << "Could not open file: " << EC.message();
2754- return 1;
2755- }
2756+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
2757+ :language: c++
2758+ :start-after: chapter8-emit
2759+ :end-before: chapter8-emit
2760+ :dedent: 2
2761
2762 Finally, we define a pass that emits object code, then we run that
2763 pass:
2764
2765-.. code-block:: c++
2766-
2767- legacy::PassManager pass;
2768- auto FileType = TargetMachine::CGFT_ObjectFile;
2769-
2770- if (TargetMachine->addPassesToEmitFile(pass, dest, FileType)) {
2771- errs() << "TargetMachine can't emit a file of this type";
2772- return 1;
2773- }
2774-
2775- pass.run(*TheModule);
2776- dest.flush();
2777+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
2778+ :language: c++
2779+ :start-after: chapter8-pass
2780+ :end-before: chapter8-pass
2781+ :dedent: 2
2782
2783 Putting It All Together
2784 =======================
2785diff --git a/examples/Kaleidoscope/Chapter2/toy.cpp b/examples/Kaleidoscope/Chapter2/toy.cpp
2786index 4dc917e3f06..36255f0c9ae 100644
2787--- a/examples/Kaleidoscope/Chapter2/toy.cpp
2788+++ b/examples/Kaleidoscope/Chapter2/toy.cpp
2789@@ -12,6 +12,7 @@
2790 // Lexer
2791 //===----------------------------------------------------------------------===//
2792
2793+/// [chapter1-token]
2794 // The lexer returns tokens [0-255] if it is an unknown character, otherwise one
2795 // of these for known things.
2796 enum Token {
2797@@ -28,7 +29,9 @@ enum Token {
2798
2799 static std::string IdentifierStr; // Filled in if tok_identifier
2800 static double NumVal; // Filled in if tok_number
2801+/// [chapter1-token]
2802
2803+/// [chapter1-gettok1]
2804 /// gettok - Return the next token from standard input.
2805 static int gettok() {
2806 static int LastChar = ' ';
2807@@ -36,7 +39,8 @@ static int gettok() {
2808 // Skip any whitespace.
2809 while (isspace(LastChar))
2810 LastChar = getchar();
2811-
2812+ /// [chapter1-gettok1]
2813+ /// [chapter1-gettok2]
2814 if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
2815 IdentifierStr = LastChar;
2816 while (isalnum((LastChar = getchar())))
2817@@ -48,7 +52,8 @@ static int gettok() {
2818 return tok_extern;
2819 return tok_identifier;
2820 }
2821-
2822+ /// [chapter1-gettok2]
2823+ /// [chapter1-gettok3]
2824 if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
2825 std::string NumStr;
2826 do {
2827@@ -59,7 +64,9 @@ static int gettok() {
2828 NumVal = strtod(NumStr.c_str(), nullptr);
2829 return tok_number;
2830 }
2831+ /// [chapter1-gettok3]
2832
2833+ /// [chapter1-gettok4]
2834 if (LastChar == '#') {
2835 // Comment until end of line.
2836 do
2837@@ -69,7 +76,9 @@ static int gettok() {
2838 if (LastChar != EOF)
2839 return gettok();
2840 }
2841+ /// [chapter1-gettok4]
2842
2843+ /// [chapter1-gettok5]
2844 // Check for end of file. Don't eat the EOF.
2845 if (LastChar == EOF)
2846 return tok_eof;
2847@@ -79,6 +88,7 @@ static int gettok() {
2848 LastChar = getchar();
2849 return ThisChar;
2850 }
2851+/// [chapter1-gettok5]
2852
2853 //===----------------------------------------------------------------------===//
2854 // Abstract Syntax Tree (aka Parse Tree)
2855@@ -86,6 +96,7 @@ static int gettok() {
2856
2857 namespace {
2858
2859+/// [chapter2-ExprAST]
2860 /// ExprAST - Base class for all expression nodes.
2861 class ExprAST {
2862 public:
2863@@ -99,7 +110,9 @@ class NumberExprAST : public ExprAST {
2864 public:
2865 NumberExprAST(double Val) : Val(Val) {}
2866 };
2867+/// [chapter2-ExprAST]
2868
2869+/// [chapter2-VariableExprAST]
2870 /// VariableExprAST - Expression class for referencing a variable, like "a".
2871 class VariableExprAST : public ExprAST {
2872 std::string Name;
2873@@ -129,7 +142,9 @@ public:
2874 std::vector<std::unique_ptr<ExprAST>> Args)
2875 : Callee(Callee), Args(std::move(Args)) {}
2876 };
2877+/// [chapter2-VariableExprAST]
2878
2879+/// [chapter2-PrototypeAST]
2880 /// PrototypeAST - This class represents the "prototype" for a function,
2881 /// which captures its name, and its argument names (thus implicitly the number
2882 /// of arguments the function takes).
2883@@ -154,6 +169,7 @@ public:
2884 std::unique_ptr<ExprAST> Body)
2885 : Proto(std::move(Proto)), Body(std::move(Body)) {}
2886 };
2887+/// [chapter2-PrototypeAST]
2888
2889 } // end anonymous namespace
2890
2891@@ -161,12 +177,15 @@ public:
2892 // Parser
2893 //===----------------------------------------------------------------------===//
2894
2895+/// [chapter2-CurTok]
2896 /// CurTok/getNextToken - Provide a simple token buffer. CurTok is the current
2897 /// token the parser is looking at. getNextToken reads another token from the
2898 /// lexer and updates CurTok with its results.
2899 static int CurTok;
2900 static int getNextToken() { return CurTok = gettok(); }
2901+/// [chapter2-CurTok]
2902
2903+/// [chapter2-BinopPrecedence]
2904 /// BinopPrecedence - This holds the precedence for each binary operator that is
2905 /// defined.
2906 static std::map<char, int> BinopPrecedence;
2907@@ -182,7 +201,9 @@ static int GetTokPrecedence() {
2908 return -1;
2909 return TokPrec;
2910 }
2911+/// [chapter2-BinopPrecedence]
2912
2913+/// [chapter2-logging]
2914 /// LogError* - These are little helper functions for error handling.
2915 std::unique_ptr<ExprAST> LogError(const char *Str) {
2916 fprintf(stderr, "Error: %s\n", Str);
2917@@ -192,16 +213,20 @@ std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {
2918 LogError(Str);
2919 return nullptr;
2920 }
2921+/// [chapter2-logging]
2922
2923 static std::unique_ptr<ExprAST> ParseExpression();
2924
2925+/// [chapter2-ParseNumberExpr]
2926 /// numberexpr ::= number
2927 static std::unique_ptr<ExprAST> ParseNumberExpr() {
2928 auto Result = llvm::make_unique<NumberExprAST>(NumVal);
2929 getNextToken(); // consume the number
2930 return std::move(Result);
2931 }
2932+/// [chapter2-ParseNumberExpr]
2933
2934+/// [chapter2-ParseParenExpr]
2935 /// parenexpr ::= '(' expression ')'
2936 static std::unique_ptr<ExprAST> ParseParenExpr() {
2937 getNextToken(); // eat (.
2938@@ -214,7 +239,9 @@ static std::unique_ptr<ExprAST> ParseParenExpr() {
2939 getNextToken(); // eat ).
2940 return V;
2941 }
2942+/// [chapter2-ParseParenExpr]
2943
2944+/// [chapter2-ParseIdentifierExpr]
2945 /// identifierexpr
2946 /// ::= identifier
2947 /// ::= identifier '(' expression* ')'
2948@@ -250,7 +277,9 @@ static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
2949
2950 return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
2951 }
2952+/// [chapter2-ParseIdentifierExpr]
2953
2954+/// [chapter2-ParsePrimary]
2955 /// primary
2956 /// ::= identifierexpr
2957 /// ::= numberexpr
2958@@ -267,7 +296,9 @@ static std::unique_ptr<ExprAST> ParsePrimary() {
2959 return ParseParenExpr();
2960 }
2961 }
2962+/// [chapter2-ParsePrimary]
2963
2964+/// [chapter2-ParseBinOpRHS1]
2965 /// binoprhs
2966 /// ::= ('+' primary)*
2967 static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
2968@@ -280,7 +311,9 @@ static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
2969 // consume it, otherwise we are done.
2970 if (TokPrec < ExprPrec)
2971 return LHS;
2972+ /// [chapter2-ParseBinOpRHS1]
2973
2974+ /// [chapter2-ParseBinOpRHS2]
2975 // Okay, we know this is a binop.
2976 int BinOp = CurTok;
2977 getNextToken(); // eat binop
2978@@ -289,7 +322,9 @@ static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
2979 auto RHS = ParsePrimary();
2980 if (!RHS)
2981 return nullptr;
2982+ /// [chapter2-ParseBinOpRHS2]
2983
2984+ /// [chapter2-ParseBinOpRHS3]
2985 // If BinOp binds less tightly with RHS than the operator after RHS, let
2986 // the pending operator take RHS as its LHS.
2987 int NextPrec = GetTokPrecedence();
2988@@ -304,7 +339,9 @@ static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
2989 std::move(RHS));
2990 }
2991 }
2992+/// [chapter2-ParseBinOpRHS3]
2993
2994+/// [chapter2-ParseExpression]
2995 /// expression
2996 /// ::= primary binoprhs
2997 ///
2998@@ -315,7 +352,9 @@ static std::unique_ptr<ExprAST> ParseExpression() {
2999
3000 return ParseBinOpRHS(0, std::move(LHS));
3001 }
3002+/// [chapter2-ParseExpression]
3003
3004+/// [chapter2-ParsePrototype]
3005 /// prototype
3006 /// ::= id '(' id* ')'
3007 static std::unique_ptr<PrototypeAST> ParsePrototype() {
3008@@ -339,7 +378,9 @@ static std::unique_ptr<PrototypeAST> ParsePrototype() {
3009
3010 return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));
3011 }
3012+/// [chapter2-ParsePrototype]
3013
3014+/// [chapter2-ParseDefinition]
3015 /// definition ::= 'def' prototype expression
3016 static std::unique_ptr<FunctionAST> ParseDefinition() {
3017 getNextToken(); // eat def.
3018@@ -351,7 +392,9 @@ static std::unique_ptr<FunctionAST> ParseDefinition() {
3019 return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
3020 return nullptr;
3021 }
3022+/// [chapter2-ParseDefinition]
3023
3024+/// [chapter2-ParseTopLevelExpr]
3025 /// toplevelexpr ::= expression
3026 static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
3027 if (auto E = ParseExpression()) {
3028@@ -362,12 +405,15 @@ static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
3029 }
3030 return nullptr;
3031 }
3032+/// [chapter2-ParseTopLevelExpr]
3033
3034+/// [chapter2-ParseExtern]
3035 /// external ::= 'extern' prototype
3036 static std::unique_ptr<PrototypeAST> ParseExtern() {
3037 getNextToken(); // eat extern.
3038 return ParsePrototype();
3039 }
3040+/// [chapter2-ParseExtern]
3041
3042 //===----------------------------------------------------------------------===//
3043 // Top-Level parsing
3044@@ -401,6 +447,7 @@ static void HandleTopLevelExpression() {
3045 }
3046 }
3047
3048+/// [chapter2-MainLoop]
3049 /// top ::= definition | external | expression | ';'
3050 static void MainLoop() {
3051 while (true) {
3052@@ -423,11 +470,13 @@ static void MainLoop() {
3053 }
3054 }
3055 }
3056+/// [chapter2-MainLoop]
3057
3058 //===----------------------------------------------------------------------===//
3059 // Main driver code.
3060 //===----------------------------------------------------------------------===//
3061
3062+/// [chapter2-SetBinopPrecedence]
3063 int main() {
3064 // Install standard binary operators.
3065 // 1 is lowest precedence.
3066@@ -435,6 +484,7 @@ int main() {
3067 BinopPrecedence['+'] = 20;
3068 BinopPrecedence['-'] = 20;
3069 BinopPrecedence['*'] = 40; // highest.
3070+ /// [chapter2-SetBinopPrecedence]
3071
3072 // Prime the first token.
3073 fprintf(stderr, "ready> ");
3074diff --git a/examples/Kaleidoscope/Chapter3/toy.cpp b/examples/Kaleidoscope/Chapter3/toy.cpp
3075index 8aad3f4d7be..04d84baac57 100644
3076--- a/examples/Kaleidoscope/Chapter3/toy.cpp
3077+++ b/examples/Kaleidoscope/Chapter3/toy.cpp
3078@@ -98,6 +98,7 @@ static int gettok() {
3079
3080 namespace {
3081
3082+/// [chapter3-ExprAST-codegen]
3083 /// ExprAST - Base class for all expression nodes.
3084 class ExprAST {
3085 public:
3086@@ -115,6 +116,7 @@ public:
3087
3088 Value *codegen() override;
3089 };
3090+/// [chapter3-ExprAST-codegen]
3091
3092 /// VariableExprAST - Expression class for referencing a variable, like "a".
3093 class VariableExprAST : public ExprAST {
3094@@ -399,6 +401,7 @@ static std::unique_ptr<PrototypeAST> ParseExtern() {
3095 // Code Generation
3096 //===----------------------------------------------------------------------===//
3097
3098+/// [chapter3-globals]
3099 static LLVMContext TheContext;
3100 static IRBuilder<> Builder(TheContext);
3101 static std::unique_ptr<Module> TheModule;
3102@@ -408,11 +411,15 @@ Value *LogErrorV(const char *Str) {
3103 LogError(Str);
3104 return nullptr;
3105 }
3106+/// [chapter3-globals]
3107
3108+/// [chapter3-NumberExprAST-codegen]
3109 Value *NumberExprAST::codegen() {
3110 return ConstantFP::get(TheContext, APFloat(Val));
3111 }
3112+/// [chapter3-NumberExprAST-codegen]
3113
3114+/// [chapter3-VariableExprAST-codegen]
3115 Value *VariableExprAST::codegen() {
3116 // Look this variable up in the function.
3117 Value *V = NamedValues[Name];
3118@@ -420,7 +427,9 @@ Value *VariableExprAST::codegen() {
3119 return LogErrorV("Unknown variable name");
3120 return V;
3121 }
3122+/// [chapter3-VariableExprAST-codegen]
3123
3124+/// [chapter3-BinaryExprAST-codegen]
3125 Value *BinaryExprAST::codegen() {
3126 Value *L = LHS->codegen();
3127 Value *R = RHS->codegen();
3128@@ -442,7 +451,9 @@ Value *BinaryExprAST::codegen() {
3129 return LogErrorV("invalid binary operator");
3130 }
3131 }
3132+/// [chapter3-BinaryExprAST-codegen]
3133
3134+/// [chapter3-CallExprAST-codegen]
3135 Value *CallExprAST::codegen() {
3136 // Look up the name in the global module table.
3137 Function *CalleeF = TheModule->getFunction(Callee);
3138@@ -462,7 +473,9 @@ Value *CallExprAST::codegen() {
3139
3140 return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
3141 }
3142+/// [chapter3-CallExprAST-codegen]
3143
3144+/// [chapter3-PrototypeAST-codegen1]
3145 Function *PrototypeAST::codegen() {
3146 // Make the function type: double(double,double) etc.
3147 std::vector<Type *> Doubles(Args.size(), Type::getDoubleTy(TheContext));
3148@@ -471,7 +484,9 @@ Function *PrototypeAST::codegen() {
3149
3150 Function *F =
3151 Function::Create(FT, Function::ExternalLinkage, Name, TheModule.get());
3152+ /// [chapter3-PrototypeAST-codegen1]
3153
3154+ /// [chapter3-PrototypeAST-codegen2]
3155 // Set names for all arguments.
3156 unsigned Idx = 0;
3157 for (auto &Arg : F->args())
3158@@ -479,7 +494,9 @@ Function *PrototypeAST::codegen() {
3159
3160 return F;
3161 }
3162+/// [chapter3-PrototypeAST-codegen2]
3163
3164+/// [chapter3-FunctionAST-codegen1]
3165 Function *FunctionAST::codegen() {
3166 // First, check for an existing function from a previous 'extern' declaration.
3167 Function *TheFunction = TheModule->getFunction(Proto->getName());
3168@@ -490,6 +507,8 @@ Function *FunctionAST::codegen() {
3169 if (!TheFunction)
3170 return nullptr;
3171
3172+ /// [chapter3-FunctionAST-codegen1]
3173+ /// [chapter3-FunctionAST-codegen2]
3174 // Create a new basic block to start insertion into.
3175 BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
3176 Builder.SetInsertPoint(BB);
3177@@ -498,7 +517,9 @@ Function *FunctionAST::codegen() {
3178 NamedValues.clear();
3179 for (auto &Arg : TheFunction->args())
3180 NamedValues[Arg.getName()] = &Arg;
3181+ /// [chapter3-FunctionAST-codegen2]
3182
3183+ /// [chapter3-FunctionAST-codegen3]
3184 if (Value *RetVal = Body->codegen()) {
3185 // Finish off the function.
3186 Builder.CreateRet(RetVal);
3187@@ -508,11 +529,14 @@ Function *FunctionAST::codegen() {
3188
3189 return TheFunction;
3190 }
3191+ /// [chapter3-FunctionAST-codegen3]
3192
3193+ /// [chapter3-FunctionAST-codegen4]
3194 // Error reading body, remove function.
3195 TheFunction->eraseFromParent();
3196 return nullptr;
3197 }
3198+/// [chapter3-FunctionAST-codegen4]
3199
3200 //===----------------------------------------------------------------------===//
3201 // Top-Level parsing and JIT Driver
3202diff --git a/examples/Kaleidoscope/Chapter4/toy.cpp b/examples/Kaleidoscope/Chapter4/toy.cpp
3203index 921fa890804..cbbb2889f9b 100644
3204--- a/examples/Kaleidoscope/Chapter4/toy.cpp
3205+++ b/examples/Kaleidoscope/Chapter4/toy.cpp
3206@@ -413,7 +413,9 @@ static IRBuilder<> Builder(TheContext);
3207 static std::unique_ptr<Module> TheModule;
3208 static std::map<std::string, Value *> NamedValues;
3209 static std::unique_ptr<legacy::FunctionPassManager> TheFPM;
3210+/// [chapter4-TheJIT]
3211 static std::unique_ptr<KaleidoscopeJIT> TheJIT;
3212+/// [chapter4-TheJIT]
3213 static std::map<std::string, std::unique_ptr<PrototypeAST>> FunctionProtos;
3214
3215 Value *LogErrorV(const char *Str) {
3216@@ -421,6 +423,7 @@ Value *LogErrorV(const char *Str) {
3217 return nullptr;
3218 }
3219
3220+/// [chapter4-getFunction]
3221 Function *getFunction(std::string Name) {
3222 // First, see if the function has already been added to the current module.
3223 if (auto *F = TheModule->getFunction(Name))
3224@@ -435,6 +438,7 @@ Function *getFunction(std::string Name) {
3225 // If no existing prototype exists, return null.
3226 return nullptr;
3227 }
3228+/// [chapter4-getFunction]
3229
3230 Value *NumberExprAST::codegen() {
3231 return ConstantFP::get(TheContext, APFloat(Val));
3232@@ -470,6 +474,7 @@ Value *BinaryExprAST::codegen() {
3233 }
3234 }
3235
3236+/// [chapter4-CallExprAST-codegen]
3237 Value *CallExprAST::codegen() {
3238 // Look up the name in the global module table.
3239 Function *CalleeF = getFunction(Callee);
3240@@ -489,6 +494,7 @@ Value *CallExprAST::codegen() {
3241
3242 return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
3243 }
3244+/// [chapter4-CallExprAST-codegen]
3245
3246 Function *PrototypeAST::codegen() {
3247 // Make the function type: double(double,double) etc.
3248@@ -507,6 +513,7 @@ Function *PrototypeAST::codegen() {
3249 return F;
3250 }
3251
3252+/// [chapter4-FunctionAST-codegen]
3253 Function *FunctionAST::codegen() {
3254 // Transfer ownership of the prototype to the FunctionProtos map, but keep a
3255 // reference to it for use below.
3256@@ -525,6 +532,7 @@ Function *FunctionAST::codegen() {
3257 for (auto &Arg : TheFunction->args())
3258 NamedValues[Arg.getName()] = &Arg;
3259
3260+ /// [chapter4-run-passes]
3261 if (Value *RetVal = Body->codegen()) {
3262 // Finish off the function.
3263 Builder.CreateRet(RetVal);
3264@@ -537,16 +545,19 @@ Function *FunctionAST::codegen() {
3265
3266 return TheFunction;
3267 }
3268+ /// [chapter4-run-passes]
3269
3270 // Error reading body, remove function.
3271 TheFunction->eraseFromParent();
3272 return nullptr;
3273 }
3274+/// [chapter4-FunctionAST-codegen]
3275
3276 //===----------------------------------------------------------------------===//
3277 // Top-Level parsing and JIT Driver
3278 //===----------------------------------------------------------------------===//
3279
3280+/// [chapter4-InitializeModuleAndPassManager]
3281 static void InitializeModuleAndPassManager() {
3282 // Open a new module.
3283 TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
3284@@ -566,7 +577,9 @@ static void InitializeModuleAndPassManager() {
3285
3286 TheFPM->doInitialization();
3287 }
3288+/// [chapter4-InitializeModuleAndPassManager]
3289
3290+/// [chapter4-HandleDefinition+HandleExtern]
3291 static void HandleDefinition() {
3292 if (auto FnAST = ParseDefinition()) {
3293 if (auto *FnIR = FnAST->codegen()) {
3294@@ -595,7 +608,9 @@ static void HandleExtern() {
3295 getNextToken();
3296 }
3297 }
3298+/// [chapter4-HandleDefinition+HandleExtern]
3299
3300+/// [chapter4-HandleTopLevelExpression]
3301 static void HandleTopLevelExpression() {
3302 // Evaluate a top-level expression into an anonymous function.
3303 if (auto FnAST = ParseTopLevelExpr()) {
3304@@ -622,6 +637,7 @@ static void HandleTopLevelExpression() {
3305 getNextToken();
3306 }
3307 }
3308+/// [chapter4-HandleTopLevelExpression]
3309
3310 /// top ::= definition | external | expression | ';'
3311 static void MainLoop() {
3312@@ -650,6 +666,7 @@ static void MainLoop() {
3313 // "Library" functions that can be "extern'd" from user code.
3314 //===----------------------------------------------------------------------===//
3315
3316+/// [chapter4-extern]
3317 #ifdef LLVM_ON_WIN32
3318 #define DLLEXPORT __declspec(dllexport)
3319 #else
3320@@ -667,11 +684,13 @@ extern "C" DLLEXPORT double printd(double X) {
3321 fprintf(stderr, "%f\n", X);
3322 return 0;
3323 }
3324+/// [chapter4-extern]
3325
3326 //===----------------------------------------------------------------------===//
3327 // Main driver code.
3328 //===----------------------------------------------------------------------===//
3329
3330+/// [chapter4-main]
3331 int main() {
3332 InitializeNativeTarget();
3333 InitializeNativeTargetAsmPrinter();
3334@@ -697,3 +716,4 @@ int main() {
3335
3336 return 0;
3337 }
3338+/// [chapter4-main]
3339diff --git a/examples/Kaleidoscope/Chapter5/toy.cpp b/examples/Kaleidoscope/Chapter5/toy.cpp
3340index 2d23bdb26c2..90b5ea51590 100644
3341--- a/examples/Kaleidoscope/Chapter5/toy.cpp
3342+++ b/examples/Kaleidoscope/Chapter5/toy.cpp
3343@@ -47,12 +47,14 @@ enum Token {
3344 tok_identifier = -4,
3345 tok_number = -5,
3346
3347+ /// [chapter5-tokens1]
3348 // control
3349 tok_if = -6,
3350 tok_then = -7,
3351 tok_else = -8,
3352 tok_for = -9,
3353 tok_in = -10
3354+ /// [chapter5-tokens1]
3355 };
3356
3357 static std::string IdentifierStr; // Filled in if tok_identifier
3358@@ -71,6 +73,7 @@ static int gettok() {
3359 while (isalnum((LastChar = getchar())))
3360 IdentifierStr += LastChar;
3361
3362+ /// [chapter5-gettok]
3363 if (IdentifierStr == "def")
3364 return tok_def;
3365 if (IdentifierStr == "extern")
3366@@ -86,6 +89,7 @@ static int gettok() {
3367 if (IdentifierStr == "in")
3368 return tok_in;
3369 return tok_identifier;
3370+ /// [chapter5-gettok]
3371 }
3372
3373 if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
3374@@ -179,6 +183,7 @@ public:
3375 Value *codegen() override;
3376 };
3377
3378+/// [chapter5-IfExprAST]
3379 /// IfExprAST - Expression class for if/then/else.
3380 class IfExprAST : public ExprAST {
3381 std::unique_ptr<ExprAST> Cond, Then, Else;
3382@@ -190,7 +195,9 @@ public:
3383
3384 Value *codegen() override;
3385 };
3386+/// [chapter5-IfExprAST]
3387
3388+/// [chapter5-ForExprAST]
3389 /// ForExprAST - Expression class for for/in.
3390 class ForExprAST : public ExprAST {
3391 std::string VarName;
3392@@ -205,6 +212,7 @@ public:
3393
3394 Value *codegen() override;
3395 };
3396+/// [chapter5-ForExprAST]
3397
3398 /// PrototypeAST - This class represents the "prototype" for a function,
3399 /// which captures its name, and its argument names (thus implicitly the number
3400@@ -331,6 +339,7 @@ static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
3401 return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
3402 }
3403
3404+/// [chapter5-ParseIfExpr]
3405 /// ifexpr ::= 'if' expression 'then' expression 'else' expression
3406 static std::unique_ptr<ExprAST> ParseIfExpr() {
3407 getNextToken(); // eat the if.
3408@@ -360,7 +369,9 @@ static std::unique_ptr<ExprAST> ParseIfExpr() {
3409 return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),
3410 std::move(Else));
3411 }
3412+/// [chapter5-ParseIfExpr]
3413
3414+/// [chapter5-ParseForExpr]
3415 /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
3416 static std::unique_ptr<ExprAST> ParseForExpr() {
3417 getNextToken(); // eat the for.
3418@@ -406,6 +417,7 @@ static std::unique_ptr<ExprAST> ParseForExpr() {
3419 return llvm::make_unique<ForExprAST>(IdName, std::move(Start), std::move(End),
3420 std::move(Step), std::move(Body));
3421 }
3422+/// [chapter5-ParseForExpr]
3423
3424 /// primary
3425 /// ::= identifierexpr
3426@@ -413,6 +425,7 @@ static std::unique_ptr<ExprAST> ParseForExpr() {
3427 /// ::= parenexpr
3428 /// ::= ifexpr
3429 /// ::= forexpr
3430+/// [chapter5-ParsePrimary]
3431 static std::unique_ptr<ExprAST> ParsePrimary() {
3432 switch (CurTok) {
3433 default:
3434@@ -429,6 +442,7 @@ static std::unique_ptr<ExprAST> ParsePrimary() {
3435 return ParseForExpr();
3436 }
3437 }
3438+/// [chapter5-ParsePrimary]
3439
3440 /// binoprhs
3441 /// ::= ('+' primary)*
3442@@ -617,6 +631,7 @@ Value *CallExprAST::codegen() {
3443 return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
3444 }
3445
3446+/// [chapter5-IfExprAST-codegen1]
3447 Value *IfExprAST::codegen() {
3448 Value *CondV = Cond->codegen();
3449 if (!CondV)
3450@@ -625,7 +640,9 @@ Value *IfExprAST::codegen() {
3451 // Convert condition to a bool by comparing non-equal to 0.0.
3452 CondV = Builder.CreateFCmpONE(
3453 CondV, ConstantFP::get(TheContext, APFloat(0.0)), "ifcond");
3454+ /// [chapter5-IfExprAST-codegen1]
3455
3456+ /// [chapter5-IfExprAST-codegen2]
3457 Function *TheFunction = Builder.GetInsertBlock()->getParent();
3458
3459 // Create blocks for the then and else cases. Insert the 'then' block at the
3460@@ -635,7 +652,9 @@ Value *IfExprAST::codegen() {
3461 BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
3462
3463 Builder.CreateCondBr(CondV, ThenBB, ElseBB);
3464+ /// [chapter5-IfExprAST-codegen2]
3465
3466+ /// [chapter5-IfExprAST-codegen3]
3467 // Emit then value.
3468 Builder.SetInsertPoint(ThenBB);
3469
3470@@ -646,7 +665,9 @@ Value *IfExprAST::codegen() {
3471 Builder.CreateBr(MergeBB);
3472 // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
3473 ThenBB = Builder.GetInsertBlock();
3474+ /// [chapter5-IfExprAST-codegen3]
3475
3476+ /// [chapter5-IfExprAST-codegen4]
3477 // Emit else block.
3478 TheFunction->getBasicBlockList().push_back(ElseBB);
3479 Builder.SetInsertPoint(ElseBB);
3480@@ -658,7 +679,9 @@ Value *IfExprAST::codegen() {
3481 Builder.CreateBr(MergeBB);
3482 // Codegen of 'Else' can change the current block, update ElseBB for the PHI.
3483 ElseBB = Builder.GetInsertBlock();
3484+ /// [chapter5-IfExprAST-codegen4]
3485
3486+ /// [chapter5-IfExprAST-codegen5]
3487 // Emit merge block.
3488 TheFunction->getBasicBlockList().push_back(MergeBB);
3489 Builder.SetInsertPoint(MergeBB);
3490@@ -668,6 +691,7 @@ Value *IfExprAST::codegen() {
3491 PN->addIncoming(ElseV, ElseBB);
3492 return PN;
3493 }
3494+/// [chapter5-IfExprAST-codegen5]
3495
3496 // Output for-loop as:
3497 // ...
3498@@ -684,12 +708,15 @@ Value *IfExprAST::codegen() {
3499 // endcond = endexpr
3500 // br endcond, loop, endloop
3501 // outloop:
3502+/// [chapter5-ForExprAST-codegen1]
3503 Value *ForExprAST::codegen() {
3504 // Emit the start code first, without 'variable' in scope.
3505 Value *StartVal = Start->codegen();
3506 if (!StartVal)
3507 return nullptr;
3508
3509+ /// [chapter5-ForExprAST-codegen1]
3510+ /// [chapter5-ForExprAST-codegen2]
3511 // Make the new basic block for the loop header, inserting after current
3512 // block.
3513 Function *TheFunction = Builder.GetInsertBlock()->getParent();
3514@@ -698,7 +725,9 @@ Value *ForExprAST::codegen() {
3515
3516 // Insert an explicit fall through from the current block to the LoopBB.
3517 Builder.CreateBr(LoopBB);
3518+ /// [chapter5-ForExprAST-codegen2]
3519
3520+ /// [chapter5-ForExprAST-codegen3]
3521 // Start insertion in LoopBB.
3522 Builder.SetInsertPoint(LoopBB);
3523
3524@@ -706,7 +735,9 @@ Value *ForExprAST::codegen() {
3525 PHINode *Variable =
3526 Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, VarName);
3527 Variable->addIncoming(StartVal, PreheaderBB);
3528+ /// [chapter5-ForExprAST-codegen3]
3529
3530+ /// [chapter5-ForExprAST-codegen4]
3531 // Within the loop, the variable is defined equal to the PHI node. If it
3532 // shadows an existing variable, we have to restore it, so save it now.
3533 Value *OldVal = NamedValues[VarName];
3534@@ -717,7 +748,9 @@ Value *ForExprAST::codegen() {
3535 // allow an error.
3536 if (!Body->codegen())
3537 return nullptr;
3538+ /// [chapter5-ForExprAST-codegen4]
3539
3540+ /// [chapter5-ForExprAST-codegen5]
3541 // Emit the step value.
3542 Value *StepVal = nullptr;
3543 if (Step) {
3544@@ -730,7 +763,9 @@ Value *ForExprAST::codegen() {
3545 }
3546
3547 Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
3548+ /// [chapter5-ForExprAST-codegen5]
3549
3550+ /// [chapter5-ForExprAST-codegen6]
3551 // Compute the end condition.
3552 Value *EndCond = End->codegen();
3553 if (!EndCond)
3554@@ -739,7 +774,9 @@ Value *ForExprAST::codegen() {
3555 // Convert condition to a bool by comparing non-equal to 0.0.
3556 EndCond = Builder.CreateFCmpONE(
3557 EndCond, ConstantFP::get(TheContext, APFloat(0.0)), "loopcond");
3558+ /// [chapter5-ForExprAST-codegen6]
3559
3560+ /// [chapter5-ForExprAST-codegen7]
3561 // Create the "after loop" block and insert it.
3562 BasicBlock *LoopEndBB = Builder.GetInsertBlock();
3563 BasicBlock *AfterBB =
3564@@ -750,7 +787,9 @@ Value *ForExprAST::codegen() {
3565
3566 // Any new code will be inserted in AfterBB.
3567 Builder.SetInsertPoint(AfterBB);
3568+ /// [chapter5-ForExprAST-codegen7]
3569
3570+ /// [chapter5-ForExprAST-codegen8]
3571 // Add a new entry to the PHI node for the backedge.
3572 Variable->addIncoming(NextVar, LoopEndBB);
3573
3574@@ -763,6 +802,7 @@ Value *ForExprAST::codegen() {
3575 // for expr always returns 0.0.
3576 return Constant::getNullValue(Type::getDoubleTy(TheContext));
3577 }
3578+/// [chapter5-ForExprAST-codegen8]
3579
3580 Function *PrototypeAST::codegen() {
3581 // Make the function type: double(double,double) etc.
3582diff --git a/examples/Kaleidoscope/Chapter6/toy.cpp b/examples/Kaleidoscope/Chapter6/toy.cpp
3583index b5e4495539f..aa75f294af8 100644
3584--- a/examples/Kaleidoscope/Chapter6/toy.cpp
3585+++ b/examples/Kaleidoscope/Chapter6/toy.cpp
3586@@ -161,6 +161,7 @@ public:
3587 Value *codegen() override;
3588 };
3589
3590+/// [chapter6-UnaryExprAST]
3591 /// UnaryExprAST - Expression class for a unary operator.
3592 class UnaryExprAST : public ExprAST {
3593 char Opcode;
3594@@ -172,6 +173,7 @@ public:
3595
3596 Value *codegen() override;
3597 };
3598+/// [chapter6-UnaryExprAST]
3599
3600 /// BinaryExprAST - Expression class for a binary operator.
3601 class BinaryExprAST : public ExprAST {
3602@@ -226,6 +228,7 @@ public:
3603 Value *codegen() override;
3604 };
3605
3606+/// [chapter6-PrototypeAST]
3607 /// PrototypeAST - This class represents the "prototype" for a function,
3608 /// which captures its name, and its argument names (thus implicitly the number
3609 /// of arguments the function takes), as well as if it is an operator.
3610@@ -254,6 +257,7 @@ public:
3611
3612 unsigned getBinaryPrecedence() const { return Precedence; }
3613 };
3614+/// [chapter6-PrototypeAST]
3615
3616 /// FunctionAST - This class represents a function definition itself.
3617 class FunctionAST {
3618@@ -464,6 +468,7 @@ static std::unique_ptr<ExprAST> ParsePrimary() {
3619 }
3620 }
3621
3622+/// [chapter6-ParseUnary]
3623 /// unary
3624 /// ::= primary
3625 /// ::= '!' unary
3626@@ -479,6 +484,7 @@ static std::unique_ptr<ExprAST> ParseUnary() {
3627 return llvm::make_unique<UnaryExprAST>(Opc, std::move(Operand));
3628 return nullptr;
3629 }
3630+/// [chapter6-ParseUnary]
3631
3632 /// binoprhs
3633 /// ::= ('+' unary)*
3634@@ -517,6 +523,7 @@ static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
3635 }
3636 }
3637
3638+/// [chapter6-ParseExpression]
3639 /// expression
3640 /// ::= unary binoprhs
3641 ///
3642@@ -527,7 +534,9 @@ static std::unique_ptr<ExprAST> ParseExpression() {
3643
3644 return ParseBinOpRHS(0, std::move(LHS));
3645 }
3646+/// [chapter6-ParseExpression]
3647
3648+/// [chapter6-ParsePrototype]
3649 /// prototype
3650 /// ::= id '(' id* ')'
3651 /// ::= binary LETTER number? (id, id)
3652@@ -593,6 +602,7 @@ static std::unique_ptr<PrototypeAST> ParsePrototype() {
3653 return llvm::make_unique<PrototypeAST>(FnName, ArgNames, Kind != 0,
3654 BinaryPrecedence);
3655 }
3656+/// [chapter6-ParsePrototype]
3657
3658 /// definition ::= 'def' prototype expression
3659 static std::unique_ptr<FunctionAST> ParseDefinition() {
3660@@ -667,6 +677,7 @@ Value *VariableExprAST::codegen() {
3661 return V;
3662 }
3663
3664+/// [chapter6-UnaryExprAST-codegen]
3665 Value *UnaryExprAST::codegen() {
3666 Value *OperandV = Operand->codegen();
3667 if (!OperandV)
3668@@ -678,7 +689,9 @@ Value *UnaryExprAST::codegen() {
3669
3670 return Builder.CreateCall(F, OperandV, "unop");
3671 }
3672+/// [chapter6-UnaryExprAST-codegen]
3673
3674+/// [chapter6-BinaryExprAST-codegen]
3675 Value *BinaryExprAST::codegen() {
3676 Value *L = LHS->codegen();
3677 Value *R = RHS->codegen();
3678@@ -708,6 +721,7 @@ Value *BinaryExprAST::codegen() {
3679 Value *Ops[] = {L, R};
3680 return Builder.CreateCall(F, Ops, "binop");
3681 }
3682+/// [chapter6-BinaryExprAST-codegen]
3683
3684 Value *CallExprAST::codegen() {
3685 // Look up the name in the global module table.
3686@@ -893,6 +907,7 @@ Function *PrototypeAST::codegen() {
3687 return F;
3688 }
3689
3690+/// [chapter6-FunctionAST-codegen]
3691 Function *FunctionAST::codegen() {
3692 // Transfer ownership of the prototype to the FunctionProtos map, but keep a
3693 // reference to it for use below.
3694@@ -908,6 +923,7 @@ Function *FunctionAST::codegen() {
3695
3696 // Create a new basic block to start insertion into.
3697 BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
3698+ /// [chapter6-FunctionAST-codegen]
3699 Builder.SetInsertPoint(BB);
3700
3701 // Record the function arguments in the NamedValues map.
3702diff --git a/examples/Kaleidoscope/Chapter7/toy.cpp b/examples/Kaleidoscope/Chapter7/toy.cpp
3703index 32f4a658c5d..8b4c990814a 100644
3704--- a/examples/Kaleidoscope/Chapter7/toy.cpp
3705+++ b/examples/Kaleidoscope/Chapter7/toy.cpp
3706@@ -233,6 +233,7 @@ public:
3707 Value *codegen() override;
3708 };
3709
3710+/// [chapter7-VarExprAST]
3711 /// VarExprAST - Expression class for var/in
3712 class VarExprAST : public ExprAST {
3713 std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
3714@@ -246,6 +247,7 @@ public:
3715
3716 Value *codegen() override;
3717 };
3718+/// [chapter7-VarExprAST]
3719
3720 /// PrototypeAST - This class represents the "prototype" for a function,
3721 /// which captures its name, and its argument names (thus implicitly the number
3722@@ -462,6 +464,7 @@ static std::unique_ptr<ExprAST> ParseForExpr() {
3723 std::move(Step), std::move(Body));
3724 }
3725
3726+/// [chapter7-ParseVarExpr1]
3727 /// varexpr ::= 'var' identifier ('=' expression)?
3728 // (',' identifier ('=' expression)?)* 'in' expression
3729 static std::unique_ptr<ExprAST> ParseVarExpr() {
3730@@ -472,7 +475,9 @@ static std::unique_ptr<ExprAST> ParseVarExpr() {
3731 // At least one variable name is required.
3732 if (CurTok != tok_identifier)
3733 return LogError("expected identifier after var");
3734+ /// [chapter7-ParseVarExpr1]
3735
3736+ /// [chapter7-ParseVarExpr2]
3737 while (true) {
3738 std::string Name = IdentifierStr;
3739 getNextToken(); // eat identifier.
3740@@ -497,7 +502,9 @@ static std::unique_ptr<ExprAST> ParseVarExpr() {
3741 if (CurTok != tok_identifier)
3742 return LogError("expected identifier list after var");
3743 }
3744+ /// [chapter7-ParseVarExpr2]
3745
3746+ /// [chapter7-ParseVarExpr3]
3747 // At this point, we have to have 'in'.
3748 if (CurTok != tok_in)
3749 return LogError("expected 'in' keyword after 'var'");
3750@@ -509,7 +516,9 @@ static std::unique_ptr<ExprAST> ParseVarExpr() {
3751
3752 return llvm::make_unique<VarExprAST>(std::move(VarNames), std::move(Body));
3753 }
3754+/// [chapter7-ParseVarExpr3]
3755
3756+/// [chapter7-ParsePrimary]
3757 /// primary
3758 /// ::= identifierexpr
3759 /// ::= numberexpr
3760@@ -535,6 +544,7 @@ static std::unique_ptr<ExprAST> ParsePrimary() {
3761 return ParseVarExpr();
3762 }
3763 }
3764+/// [chapter7-ParsePrimary]
3765
3766 /// unary
3767 /// ::= primary
3768@@ -727,6 +737,7 @@ Function *getFunction(std::string Name) {
3769 return nullptr;
3770 }
3771
3772+/// [chapter7-CreateEntryBlockAlloca]
3773 /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
3774 /// the function. This is used for mutable variables etc.
3775 static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
3776@@ -735,11 +746,13 @@ static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
3777 TheFunction->getEntryBlock().begin());
3778 return TmpB.CreateAlloca(Type::getDoubleTy(TheContext), nullptr, VarName);
3779 }
3780+/// [chapter7-CreateEntryBlockAlloca]
3781
3782 Value *NumberExprAST::codegen() {
3783 return ConstantFP::get(TheContext, APFloat(Val));
3784 }
3785
3786+/// [chapter7-VariableExprAST-codegen]
3787 Value *VariableExprAST::codegen() {
3788 // Look this variable up in the function.
3789 Value *V = NamedValues[Name];
3790@@ -749,6 +762,7 @@ Value *VariableExprAST::codegen() {
3791 // Load the value.
3792 return Builder.CreateLoad(V, Name.c_str());
3793 }
3794+/// [chapter7-VariableExprAST-codegen]
3795
3796 Value *UnaryExprAST::codegen() {
3797 Value *OperandV = Operand->codegen();
3798@@ -762,6 +776,7 @@ Value *UnaryExprAST::codegen() {
3799 return Builder.CreateCall(F, OperandV, "unop");
3800 }
3801
3802+/// [chapter7-BinaryExprAST-codegen1]
3803 Value *BinaryExprAST::codegen() {
3804 // Special case '=' because we don't want to emit the LHS as an expression.
3805 if (Op == '=') {
3806@@ -772,6 +787,8 @@ Value *BinaryExprAST::codegen() {
3807 VariableExprAST *LHSE = static_cast<VariableExprAST *>(LHS.get());
3808 if (!LHSE)
3809 return LogErrorV("destination of '=' must be a variable");
3810+ /// [chapter7-BinaryExprAST-codegen1]
3811+ /// [chapter7-BinaryExprAST-codegen2]
3812 // Codegen the RHS.
3813 Value *Val = RHS->codegen();
3814 if (!Val)
3815@@ -785,6 +802,7 @@ Value *BinaryExprAST::codegen() {
3816 Builder.CreateStore(Val, Variable);
3817 return Val;
3818 }
3819+ /// [chapter7-BinaryExprAST-codegen2]
3820
3821 Value *L = LHS->codegen();
3822 Value *R = RHS->codegen();
3823@@ -907,6 +925,7 @@ Value *IfExprAST::codegen() {
3824 // br endcond, loop, endloop
3825 // outloop:
3826 Value *ForExprAST::codegen() {
3827+ /// [chapter7-ForExprAST-codegen1]
3828 Function *TheFunction = Builder.GetInsertBlock()->getParent();
3829
3830 // Create an alloca for the variable in the entry block.
3831@@ -919,6 +938,7 @@ Value *ForExprAST::codegen() {
3832
3833 // Store the value into the alloca.
3834 Builder.CreateStore(StartVal, Alloca);
3835+ /// [chapter7-ForExprAST-codegen1]
3836
3837 // Make the new basic block for the loop header, inserting after current
3838 // block.
3839@@ -952,6 +972,7 @@ Value *ForExprAST::codegen() {
3840 StepVal = ConstantFP::get(TheContext, APFloat(1.0));
3841 }
3842
3843+ /// [chapter7-ForExprAST-codegen2]
3844 // Compute the end condition.
3845 Value *EndCond = End->codegen();
3846 if (!EndCond)
3847@@ -962,6 +983,7 @@ Value *ForExprAST::codegen() {
3848 Value *CurVar = Builder.CreateLoad(Alloca, VarName.c_str());
3849 Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
3850 Builder.CreateStore(NextVar, Alloca);
3851+ /// [chapter7-ForExprAST-codegen2]
3852
3853 // Convert condition to a bool by comparing non-equal to 0.0.
3854 EndCond = Builder.CreateFCmpONE(
3855@@ -987,6 +1009,7 @@ Value *ForExprAST::codegen() {
3856 return Constant::getNullValue(Type::getDoubleTy(TheContext));
3857 }
3858
3859+/// [chapter7-VarExprAST-codegen1]
3860 Value *VarExprAST::codegen() {
3861 std::vector<AllocaInst *> OldBindings;
3862
3863@@ -996,7 +1019,9 @@ Value *VarExprAST::codegen() {
3864 for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
3865 const std::string &VarName = VarNames[i].first;
3866 ExprAST *Init = VarNames[i].second.get();
3867+ /// [chapter7-VarExprAST-codegen1]
3868
3869+ /// [chapter7-VarExprAST-codegen2]
3870 // Emit the initializer before adding the variable to scope, this prevents
3871 // the initializer from referencing the variable itself, and permits stuff
3872 // like this:
3873@@ -1021,12 +1046,16 @@ Value *VarExprAST::codegen() {
3874 // Remember this binding.
3875 NamedValues[VarName] = Alloca;
3876 }
3877+ /// [chapter7-VarExprAST-codegen2]
3878
3879+ /// [chapter7-VarExprAST-codegen3]
3880 // Codegen the body, now that all vars are in scope.
3881 Value *BodyVal = Body->codegen();
3882 if (!BodyVal)
3883 return nullptr;
3884+ /// [chapter7-VarExprAST-codegen3]
3885
3886+ /// [chapter7-VarExprAST-codegen4]
3887 // Pop all our variables from scope.
3888 for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
3889 NamedValues[VarNames[i].first] = OldBindings[i];
3890@@ -1034,6 +1063,7 @@ Value *VarExprAST::codegen() {
3891 // Return the body computation.
3892 return BodyVal;
3893 }
3894+/// [chapter7-VarExprAST-codegen4]
3895
3896 Function *PrototypeAST::codegen() {
3897 // Make the function type: double(double,double) etc.
3898@@ -1052,7 +1082,9 @@ Function *PrototypeAST::codegen() {
3899 return F;
3900 }
3901
3902+/// [chapter7-FunctionAST-codegen1]
3903 Function *FunctionAST::codegen() {
3904+ /// [chapter7-FunctionAST-codegen1]
3905 // Transfer ownership of the prototype to the FunctionProtos map, but keep a
3906 // reference to it for use below.
3907 auto &P = *Proto;
3908@@ -1067,6 +1099,7 @@ Function *FunctionAST::codegen() {
3909
3910 // Create a new basic block to start insertion into.
3911 BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
3912+ /// [chapter7-FunctionAST-codegen2]
3913 Builder.SetInsertPoint(BB);
3914
3915 // Record the function arguments in the NamedValues map.
3916@@ -1083,6 +1116,7 @@ Function *FunctionAST::codegen() {
3917 }
3918
3919 if (Value *RetVal = Body->codegen()) {
3920+ /// [chapter7-FunctionAST-codegen2]
3921 // Finish off the function.
3922 Builder.CreateRet(RetVal);
3923
3924@@ -1115,12 +1149,14 @@ static void InitializeModuleAndPassManager() {
3925 // Create a new pass manager attached to it.
3926 TheFPM = llvm::make_unique<legacy::FunctionPassManager>(TheModule.get());
3927
3928+ /// [chapter7-passes]
3929 // Promote allocas to registers.
3930 TheFPM->add(createPromoteMemoryToRegisterPass());
3931 // Do simple "peephole" optimizations and bit-twiddling optzns.
3932 TheFPM->add(createInstructionCombiningPass());
3933 // Reassociate expressions.
3934 TheFPM->add(createReassociatePass());
3935+ /// [chapter7-passes]
3936 // Eliminate Common SubExpressions.
3937 TheFPM->add(createGVNPass());
3938 // Simplify the control flow graph (deleting unreachable blocks, etc).
3939diff --git a/examples/Kaleidoscope/Chapter8/toy.cpp b/examples/Kaleidoscope/Chapter8/toy.cpp
3940index 3ed98fcfdb5..7bed23b6ad3 100644
3941--- a/examples/Kaleidoscope/Chapter8/toy.cpp
3942+++ b/examples/Kaleidoscope/Chapter8/toy.cpp
3943@@ -1213,15 +1213,19 @@ int main() {
3944 MainLoop();
3945
3946 // Initialize the target registry etc.
3947+ /// [chapter8-initialize]
3948 InitializeAllTargetInfos();
3949 InitializeAllTargets();
3950 InitializeAllTargetMCs();
3951 InitializeAllAsmParsers();
3952 InitializeAllAsmPrinters();
3953+ /// [chapter8-initialize]
3954
3955+ /// [chapter8-TargetTriple]
3956 auto TargetTriple = sys::getDefaultTargetTriple();
3957- TheModule->setTargetTriple(TargetTriple);
3958+ /// [chapter8-TargetTriple]
3959
3960+ /// [chapter8-lookup]
3961 std::string Error;
3962 auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);
3963
3964@@ -1232,7 +1236,9 @@ int main() {
3965 errs() << Error;
3966 return 1;
3967 }
3968+ /// [chapter8-lookup]
3969
3970+ /// [chapter8-target-machine]
3971 auto CPU = "generic";
3972 auto Features = "";
3973
3974@@ -1240,9 +1246,14 @@ int main() {
3975 auto RM = Optional<Reloc::Model>();
3976 auto TheTargetMachine =
3977 Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);
3978+ /// [chapter8-target-machine]
3979
3980+ /// [chapter8-module]
3981 TheModule->setDataLayout(TheTargetMachine->createDataLayout());
3982+ TheModule->setTargetTriple(TargetTriple);
3983+ /// [chapter8-module]
3984
3985+ /// [chapter8-emit]
3986 auto Filename = "output.o";
3987 std::error_code EC;
3988 raw_fd_ostream dest(Filename, EC, sys::fs::F_None);
3989@@ -1251,7 +1262,9 @@ int main() {
3990 errs() << "Could not open file: " << EC.message();
3991 return 1;
3992 }
3993+ /// [chapter8-emit]
3994
3995+ /// [chapter8-pass]
3996 legacy::PassManager pass;
3997 auto FileType = TargetMachine::CGFT_ObjectFile;
3998
3999@@ -1262,6 +1275,7 @@ int main() {
4000
4001 pass.run(*TheModule);
4002 dest.flush();
4003+ /// [chapter8-pass]
4004
4005 outs() << "Wrote " << Filename << "\n";
4006
4007--
40082.14.1