[docs] Use literalinclude for most code in the Kaleidoscope tutorial to ensure the code always compiles and is up to date

[Voxel]

Summary

Hi

This is my first patch submission to this list, so you'll have to tell me if I do anything wrong somewhere.

I originally submitted this to llvm-commits directly a few days ago, but I later figured out how to use Differential to submit a patch, so it seemed reasonable to resubmit it here.

The code in the kaleidoscope tutorial is currently inlined in the documentation pages and is thus never compiled to ensure it still works. Over time this code has diverged from the full code listing in small and subtle ways (such as the FunctionPassManager now being in the legacy namespace) which makes it harder for anyone following the tutorial to actually get something working.

I have replaced almost all of the code blocks in the tutorial with literalinclude blocks which include code directly from the source files based on markers. This ensures that the code in the tutorial actually compiles and is up to date, even when future changes are made and reduces the maintenance burden since changes only have to be done in a single place.

I have also uploaded a visual html diff here: https://arongranberg.com/temp/llvm-diff/
with the changed files having URLs on the format https://arongranberg.com/temp/llvm-diff/LangImpl0[1-8].html
Note that the html diff library gets a little confused when some lines have been emphasized and it may emphasize more lines than are actually emphasized or may add lots of additional spacing.

The downside of this change is that some markers are required in the source files, however they are relatively few so hopefully it is not too big of a problem.

I added as reviewers two people who seem to have done large parts of the tutorial. Hopefully that's alright.

[Wilfred]

Thanks. I think this is a big improvement: it ensures the docs stay in sync with the code rather than discovering that they rely on removed APIs.

I like the token approach you've taken.

[Voxel]

In D43505#1014086, @Wilfred wrote:

Thanks. I think this is a big improvement: it ensures the docs stay in sync with the code rather than discovering that they rely on removed APIs.

I like the token approach you've taken.

Nice!
Since I don't have write access to the repository, how do we go about applying the patch?

[dblaikie]

Love this!

Though the ":lines: X, Y" doesn't seem to do the right thing for me (using sphinx-build v1.5.6 on my Ubuntu system). Any of the code samples that use the 'lines:' property end up empty for me.

Any ideas?

Though honestly, I'm thinking maybe it'd be better to not 'lines:' property anyway. Perhaps it's better to have the start/end comments in the source so when code is refactored, line wrapped, etc, the line counts don't end up becoming out of date?

Nitpick: Might be good to keep any whitespace that was present before (in some cases an empty line has been replaced with two comments (the end of one region and the start of the next) - perhaps keep the empty line between those two comments, for readibility and to reduce the noise in this diff)?

[dblaikie]

Another note/thought: It'd be great if, when including the whole file, there was some way to omit the snippet marker comments - but, on looking around at the Sphinx docs I don't see anything immediately obvious & figure there's nothing specifically to support that (I guess if someone cared a lot they could add new build rules that would strip the comments & produce some temporary files that could then be included when the whole source listing was desired).

[Voxel]

Though the ":lines: X, Y" doesn't seem to do the right thing for me (using sphinx-build v1.5.6 on my Ubuntu system). Any of the code samples that use the 'lines:' property end up empty for me.

Looking at sphinx docs it seems like :lines: together with :start-after: only works properly in v1.6 or higher.

Though honestly, I'm thinking maybe it'd be better to not 'lines:' property anyway. Perhaps it's better to have the start/end comments in the source so when code is refactored, line wrapped, etc, the line counts don't end up becoming out of date?

I agree that line counts are not ideal, unfortunately (also related to your other comment) it does not seem possible to strip the tags using sphinx, and in several places in the tutorial there are overlapping code blocks which would mean that tags would show up inside those code blocks, and that's not ideal either.

Nitpick: Might be good to keep any whitespace that was present before (in some cases an empty line has been replaced with two comments (the end of one region and the start of the next) - perhaps keep the empty line between those two comments, for readibility and to reduce the noise in this diff)?

Ah, true. I tried to keep it, but it looks like I missed a few places. I'll see if I can tweak the diff a bit.

[Voxel]

Fixed some newline noise in the diff.

[Voxel]

Anyone who knows which version of Sphinx that the server that builds the documentation uses? Or anyone who knows how to look that up?

[dblaikie]

In D43505#1018775, @Voxel wrote:

Anyone who knows which version of Sphinx that the server that builds the documentation uses? Or anyone who knows how to look that up?

Looks like maybe the closest to guidance on that we have is: https://llvm.org/docs/GettingStarted.html#local-llvm-configuration which says "Sphinx version 1.5 or later recommended.".

[Voxel]

I found that there is apparently a config file that can be used to set the minimum sphinx version that is required.

It can be found in the llvm/docs/conf.py file:

# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'

Currently it is not set, but I suppose one option would be to set that to 1.6 to at least ensure that anyone who tries to build the docs with an outdated version of sphinx will get an error message.

[dblaikie]

Hey Aaron (Ballman) - do you happen to know who maintains sphinx bots, etc?
Wondering if we can reasonably require a certain version (looks like
there's a feature in 1.6 that could be handy).

[aaron.ballman]

In D43505#1031205, @dblaikie wrote:

Hey Aaron (Ballman) - do you happen to know who maintains sphinx bots, etc?
Wondering if we can reasonably require a certain version (looks like
there's a feature in 1.6 that could be handy).

Tanya Lattner is the one currently maintaining the automatic docs builder for attributes (and I believe compiler flags as well) and I think Dmitri Gribenko maintains the actual bots (clang-sphinx-docs, llvm-sphinx-docs, etc).

I'm not certain what version we're building with currently -- I couldn't find the information in any of my emails. I think 1.6 was released in May 2017 which seems a bit recent for it being a minimum requirement. That said, I don't have Opinions on whether to bump the min version or not.

[Voxel]

@tonic and @gribozavr, do you have any opinions or info about this?

docs/tutorial/LangImpl01.rst

 When it comes to implementing a language, the first thing needed is the
 ability to process a text file and recognize what it says. The
 traditional way to do this is to use a
 "`lexer <http://en.wikipedia.org/wiki/Lexical_analysis>`_" (aka
 'scanner') to break the input up into "tokens". Each token returned by
 the lexer includes a token code and potentially some metadata (e.g. the
 numeric value of a number). First, we define the possibilities:
 
-.. code-block:: c++
-
-    // The lexer returns tokens [0-255] if it is an unknown character, otherwise one
-    // of these for known things.
-    enum Token {
-      tok_eof = -1,
-
-      // commands
-      tok_def = -2,
-      tok_extern = -3,
-
-      // primary
-      tok_identifier = -4,
-      tok_number = -5,
-    };
-
-    static std::string IdentifierStr; // Filled in if tok_identifier
-    static double NumVal;             // Filled in if tok_number
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter1-token
+  :end-before: chapter1-token
 
 Each token returned by our lexer will either be one of the Token enum
 values or it will be an 'unknown' character like '+', which is returned
 as its ASCII value. If the current token is an identifier, the
 ``IdentifierStr`` global variable holds the name of the identifier. If
 the current token is a numeric literal (like 1.0), ``NumVal`` holds its
 value. Note that we use global variables for simplicity, this is not the
 best choice for a real language implementation :).
 
 The actual implementation of the lexer is a single function named
 ``gettok``. The ``gettok`` function is called to return the next token
 from standard input. Its definition starts as:
 
-.. code-block:: c++
-
-    /// gettok - Return the next token from standard input.
-    static int gettok() {
-      static int LastChar = ' ';
-
-      // Skip any whitespace.
-      while (isspace(LastChar))
-        LastChar = getchar();
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter1-gettok1
+  :end-before: chapter1-gettok1
 
 ``gettok`` works by calling the C ``getchar()`` function to read
 characters one at a time from standard input. It eats them as it
 recognizes them and stores the last character read, but not processed,
 in LastChar. The first thing that it has to do is ignore whitespace
 between tokens. This is accomplished with the loop above.
 
 The next thing ``gettok`` needs to do is recognize identifiers and
 specific keywords like "def". Kaleidoscope does this with this simple
 loop:
 
-.. code-block:: c++
-
-      if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
-        IdentifierStr = LastChar;
-        while (isalnum((LastChar = getchar())))
-          IdentifierStr += LastChar;
-
-        if (IdentifierStr == "def")
-          return tok_def;
-        if (IdentifierStr == "extern")
-          return tok_extern;
-        return tok_identifier;
-      }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter1-gettok2
+  :end-before: chapter1-gettok2
+  :dedent: 2
 
 Note that this code sets the '``IdentifierStr``' global whenever it
 lexes an identifier. Also, since language keywords are matched by the
 same loop, we handle them here inline. Numeric values are similar:
 
-.. code-block:: c++
-
-      if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
-        std::string NumStr;
-        do {
-          NumStr += LastChar;
-          LastChar = getchar();
-        } while (isdigit(LastChar) || LastChar == '.');
-
-        NumVal = strtod(NumStr.c_str(), 0);
-        return tok_number;
-      }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter1-gettok3
+  :end-before: chapter1-gettok3
+  :dedent: 2
 
 This is all pretty straight-forward code for processing input. When
 reading a numeric value from input, we use the C ``strtod`` function to
 convert it to a numeric value that we store in ``NumVal``. Note that
 this isn't doing sufficient error checking: it will incorrectly read
 "1.23.45.67" and handle it as if you typed in "1.23". Feel free to
 extend it :). Next we handle comments:
 
-.. code-block:: c++
-
-      if (LastChar == '#') {
-        // Comment until end of line.
-        do
-          LastChar = getchar();
-        while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
-
-        if (LastChar != EOF)
-          return gettok();
-      }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter1-gettok4
+  :end-before: chapter1-gettok4
+  :dedent: 2
 
 We handle comments by skipping to the end of the line and then return
 the next token. Finally, if the input doesn't match one of the above
 cases, it is either an operator character like '+' or the end of the
 file. These are handled with this code:
 
-.. code-block:: c++
-
-      // Check for end of file.  Don't eat the EOF.
-      if (LastChar == EOF)
-        return tok_eof;
-
-      // Otherwise, just return the character as its ascii value.
-      int ThisChar = LastChar;
-      LastChar = getchar();
-      return ThisChar;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter1-gettok5
+  :end-before: chapter1-gettok5
 
 With this, we have the complete lexer for the basic Kaleidoscope
 language (the `full code listing <LangImpl02.html#full-code-listing>`_ for the Lexer
 is available in the `next chapter <LangImpl02.html>`_ of the tutorial).
 Next we'll `build a simple parser that uses this to build an Abstract
 Syntax Tree <LangImpl02.html>`_. When we have that, we'll include a
 driver so that you can use the lexer and parser together.
 
 `Next: Implementing a Parser and AST <LangImpl02.html>`_
 

docs/tutorial/LangImpl02.rst

 
 The AST for a program captures its behavior in such a way that it is
 easy for later stages of the compiler (e.g. code generation) to
 interpret. We basically want one object for each construct in the
 language, and the AST should closely model the language. In
 Kaleidoscope, we have expressions, a prototype, and a function object.
 We'll start with expressions first:
 
-.. code-block:: c++
-
-    /// ExprAST - Base class for all expression nodes.
-    class ExprAST {
-    public:
-      virtual ~ExprAST() {}
-    };
-
-    /// NumberExprAST - Expression class for numeric literals like "1.0".
-    class NumberExprAST : public ExprAST {
-      double Val;
-
-    public:
-      NumberExprAST(double Val) : Val(Val) {}
-    };
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ExprAST
+  :end-before: chapter2-ExprAST
+  :dedent: 0
 
 The code above shows the definition of the base ExprAST class and one
 subclass which we use for numeric literals. The important thing to note
 about this code is that the NumberExprAST class captures the numeric
 value of the literal as an instance variable. This allows later phases
 of the compiler to know what the stored numeric value is.
 
 Right now we only create the AST, so there are no useful accessor
 methods on them. It would be very easy to add a virtual method to pretty
 print the code, for example. Here are the other expression AST node
 definitions that we'll use in the basic form of the Kaleidoscope
 language:
 
-.. code-block:: c++
-
-    /// VariableExprAST - Expression class for referencing a variable, like "a".
-    class VariableExprAST : public ExprAST {
-      std::string Name;
-
-    public:
-      VariableExprAST(const std::string &Name) : Name(Name) {}
-    };
-
-    /// BinaryExprAST - Expression class for a binary operator.
-    class BinaryExprAST : public ExprAST {
-      char Op;
-      std::unique_ptr<ExprAST> LHS, RHS;
-
-    public:
-      BinaryExprAST(char op, std::unique_ptr<ExprAST> LHS,
-                    std::unique_ptr<ExprAST> RHS)
-        : Op(op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
-    };
-
-    /// CallExprAST - Expression class for function calls.
-    class CallExprAST : public ExprAST {
-      std::string Callee;
-      std::vector<std::unique_ptr<ExprAST>> Args;
-
-    public:
-      CallExprAST(const std::string &Callee,
-                  std::vector<std::unique_ptr<ExprAST>> Args)
-        : Callee(Callee), Args(std::move(Args)) {}
-    };
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-VariableExprAST
+  :end-before: chapter2-VariableExprAST
+  :dedent: 0
 
 This is all (intentionally) rather straight-forward: variables capture
 the variable name, binary operators capture their opcode (e.g. '+'), and
 calls capture a function name as well as a list of any argument
 expressions. One thing that is nice about our AST is that it captures
 the language features without talking about the syntax of the language.
 Note that there is no discussion about precedence of binary operators,
 lexical structure, etc.
 
 For our basic language, these are all of the expression nodes we'll
 define. Because it doesn't have conditional control flow, it isn't
 Turing-complete; we'll fix that in a later installment. The two things
 we need next are a way to talk about the interface to a function, and a
 way to talk about functions themselves:
 
-.. code-block:: c++
-
-    /// PrototypeAST - This class represents the "prototype" for a function,
-    /// which captures its name, and its argument names (thus implicitly the number
-    /// of arguments the function takes).
-    class PrototypeAST {
-      std::string Name;
-      std::vector<std::string> Args;
-
-    public:
-      PrototypeAST(const std::string &name, std::vector<std::string> Args)
-        : Name(name), Args(std::move(Args)) {}
-
-      const std::string &getName() const { return Name; }
-    };
-
-    /// FunctionAST - This class represents a function definition itself.
-    class FunctionAST {
-      std::unique_ptr<PrototypeAST> Proto;
-      std::unique_ptr<ExprAST> Body;
-
-    public:
-      FunctionAST(std::unique_ptr<PrototypeAST> Proto,
-                  std::unique_ptr<ExprAST> Body)
-        : Proto(std::move(Proto)), Body(std::move(Body)) {}
-    };
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-PrototypeAST
+  :end-before: chapter2-PrototypeAST
+  :dedent: 0
 
 In Kaleidoscope, functions are typed with just a count of their
 arguments. Since all values are double precision floating point, the
 type of each argument doesn't need to be stored anywhere. In a more
 aggressive and realistic language, the "ExprAST" class would probably
 have a type field.
 
 With this scaffolding, we can now talk about parsing expressions and
.. code-block:: c++
 
       auto LHS = llvm::make_unique<VariableExprAST>("x");
       auto RHS = llvm::make_unique<VariableExprAST>("y");
       auto Result = std::make_unique<BinaryExprAST>('+', std::move(LHS),
                                                     std::move(RHS));
 
 In order to do this, we'll start by defining some basic helper routines:
 
-.. code-block:: c++
-
-    /// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
-    /// token the parser is looking at.  getNextToken reads another token from the
-    /// lexer and updates CurTok with its results.
-    static int CurTok;
-    static int getNextToken() {
-      return CurTok = gettok();
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-CurTok
+  :end-before: chapter2-CurTok
+  :dedent: 0
 
 This implements a simple token buffer around the lexer. This allows us
 to look one token ahead at what the lexer is returning. Every function
 in our parser will assume that CurTok is the current token that needs to
 be parsed.
 
-.. code-block:: c++
-
-
-    /// LogError* - These are little helper functions for error handling.
-    std::unique_ptr<ExprAST> LogError(const char *Str) {
-      fprintf(stderr, "LogError: %s\n", Str);
-      return nullptr;
-    }
-    std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {
-      LogError(Str);
-      return nullptr;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-logging
+  :end-before: chapter2-logging
+  :dedent: 0
 
 The ``LogError`` routines are simple helper routines that our parser will
 use to handle errors. The error recovery in our parser will not be the
 best and is not particular user-friendly, but it will be enough for our
 tutorial. These routines make it easier to handle errors in routines
 that have various return types: they always return null.
 
 With these basic helper functions, we can implement the first piece of
 our grammar: numeric literals.
 
 Basic Expression Parsing
 ========================
 
 We start with numeric literals, because they are the simplest to
 process. For each production in our grammar, we'll define a function
 which parses that production. For numeric literals, we have:
 
-.. code-block:: c++
-
-    /// numberexpr ::= number
-    static std::unique_ptr<ExprAST> ParseNumberExpr() {
-      auto Result = llvm::make_unique<NumberExprAST>(NumVal);
-      getNextToken(); // consume the number
-      return std::move(Result);
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseNumberExpr
+  :end-before: chapter2-ParseNumberExpr
+  :dedent: 0
 
 This routine is very simple: it expects to be called when the current
 token is a ``tok_number`` token. It takes the current number value,
 creates a ``NumberExprAST`` node, advances the lexer to the next token,
 and finally returns.
 
 There are some interesting aspects to this. The most important one is
 that this routine eats all of the tokens that correspond to the
 production and returns the lexer buffer with the next token (which is
 not part of the grammar production) ready to go. This is a fairly
 standard way to go for recursive descent parsers. For a better example,
 the parenthesis operator is defined like this:
 
-.. code-block:: c++
-
-    /// parenexpr ::= '(' expression ')'
-    static std::unique_ptr<ExprAST> ParseParenExpr() {
-      getNextToken(); // eat (.
-      auto V = ParseExpression();
-      if (!V)
-        return nullptr;
-
-      if (CurTok != ')')
-        return LogError("expected ')'");
-      getNextToken(); // eat ).
-      return V;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseParenExpr
+  :end-before: chapter2-ParseParenExpr
+  :dedent: 0
 
 This function illustrates a number of interesting things about the
 parser:
 
 1) It shows how we use the LogError routines. When called, this function
 expects that the current token is a '(' token, but after parsing the
 subexpression, it is possible that there is no ')' waiting. For example,
 if the user types in "(4 x" instead of "(4)", the parser should emit an
 error. Because errors can occur, the parser needs a way to indicate that
 they happened: in our parser, we return null on an error.
 
 2) Another interesting aspect of this function is that it uses recursion
 by calling ``ParseExpression`` (we will soon see that
 ``ParseExpression`` can call ``ParseParenExpr``). This is powerful
 because it allows us to handle recursive grammars, and keeps each
 production very simple. Note that parentheses do not cause construction
 of AST nodes themselves. While we could do it this way, the most
 important role of parentheses are to guide the parser and provide
 grouping. Once the parser constructs the AST, parentheses are not
 needed.
 
 The next simple production is for handling variable references and
 function calls:
 
-.. code-block:: c++
-
-    /// identifierexpr
-    ///   ::= identifier
-    ///   ::= identifier '(' expression* ')'
-    static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
-      std::string IdName = IdentifierStr;
-
-      getNextToken();  // eat identifier.
-
-      if (CurTok != '(') // Simple variable ref.
-        return llvm::make_unique<VariableExprAST>(IdName);
-
-      // Call.
-      getNextToken();  // eat (
-      std::vector<std::unique_ptr<ExprAST>> Args;
-      if (CurTok != ')') {
-        while (1) {
-          if (auto Arg = ParseExpression())
-            Args.push_back(std::move(Arg));
-          else
-            return nullptr;
-
-          if (CurTok == ')')
-            break;
-
-          if (CurTok != ',')
-            return LogError("Expected ')' or ',' in argument list");
-          getNextToken();
-        }
-      }
-
-      // Eat the ')'.
-      getNextToken();
-
-      return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseIdentifierExpr
+  :end-before: chapter2-ParseIdentifierExpr
+  :dedent: 0
 
 This routine follows the same style as the other routines. (It expects
 to be called if the current token is a ``tok_identifier`` token). It
 also has recursion and error handling. One interesting aspect of this is
 that it uses *look-ahead* to determine if the current identifier is a
 stand alone variable reference or if it is a function call expression.
 It handles this by checking to see if the token after the identifier is
 a '(' token, constructing either a ``VariableExprAST`` or
 ``CallExprAST`` node as appropriate.
 
 Now that we have all of our simple expression-parsing logic in place, we
 can define a helper function to wrap it together into one entry point.
 We call this class of expressions "primary" expressions, for reasons
 that will become more clear `later in the
 tutorial <LangImpl6.html#user-defined-unary-operators>`_. In order to parse an arbitrary
 primary expression, we need to determine what sort of expression it is:
 
-.. code-block:: c++
-
-    /// primary
-    ///   ::= identifierexpr
-    ///   ::= numberexpr
-    ///   ::= parenexpr
-    static std::unique_ptr<ExprAST> ParsePrimary() {
-      switch (CurTok) {
-      default:
-        return LogError("unknown token when expecting an expression");
-      case tok_identifier:
-        return ParseIdentifierExpr();
-      case tok_number:
-        return ParseNumberExpr();
-      case '(':
-        return ParseParenExpr();
-      }
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParsePrimary
+  :end-before: chapter2-ParsePrimary
+  :dedent: 0
 
 Now that you see the definition of this function, it is more obvious why
 we can assume the state of CurTok in the various functions. This uses
 look-ahead to determine which sort of expression is being inspected, and
 then parses it with a function call.
 
 Now that basic expressions are handled, we need to handle binary
 expressions. They are a bit more complex.
 
 Binary Expression Parsing
 =========================
 
 Binary expressions are significantly harder to parse because they are
 often ambiguous. For example, when given the string "x+y\*z", the parser
 can choose to parse it as either "(x+y)\*z" or "x+(y\*z)". With common
 definitions from mathematics, we expect the later parse, because "\*"
 (multiplication) has higher *precedence* than "+" (addition).
 
 There are many ways to handle this, but an elegant and efficient way is
 to use `Operator-Precedence
 Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_.
 This parsing technique uses the precedence of binary operators to guide
 recursion. To start with, we need a table of precedences:
 
-.. code-block:: c++
-
-    /// BinopPrecedence - This holds the precedence for each binary operator that is
-    /// defined.
-    static std::map<char, int> BinopPrecedence;
-
-    /// GetTokPrecedence - Get the precedence of the pending binary operator token.
-    static int GetTokPrecedence() {
-      if (!isascii(CurTok))
-        return -1;
-
-      // Make sure it's a declared binop.
-      int TokPrec = BinopPrecedence[CurTok];
-      if (TokPrec <= 0) return -1;
-      return TokPrec;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-BinopPrecedence
+  :end-before: chapter2-BinopPrecedence
+  :dedent: 0
 
-    int main() {
-      // Install standard binary operators.
-      // 1 is lowest precedence.
-      BinopPrecedence['<'] = 10;
-      BinopPrecedence['+'] = 20;
-      BinopPrecedence['-'] = 20;
-      BinopPrecedence['*'] = 40;  // highest.
-      ...
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-SetBinopPrecedence
+  :end-before: chapter2-SetBinopPrecedence
+  :dedent: 0
 
 For the basic form of Kaleidoscope, we will only support 4 binary
 operators (this can obviously be extended by you, our brave and intrepid
 reader). The ``GetTokPrecedence`` function returns the precedence for
 the current token, or -1 if the token is not a binary operator. Having a
 map makes it easy to add new operators and makes it clear that the
 algorithm doesn't depend on the specific operators involved, but it
 would be easy enough to eliminate the map and do the comparisons in the
 ``GetTokPrecedence`` function. (Or just use a fixed-size array).
 
 With the helper above defined, we can now start parsing binary
 expressions. The basic idea of operator precedence parsing is to break
 down an expression with potentially ambiguous binary operators into
 pieces. Consider, for example, the expression "a+b+(c+d)\*e\*f+g".
 Operator precedence parsing considers this as a stream of primary
 expressions separated by binary operators. As such, it will first parse
 the leading primary expression "a", then it will see the pairs [+, b]
 [+, (c+d)] [\*, e] [\*, f] and [+, g]. Note that because parentheses are
 primary expressions, the binary expression parser doesn't need to worry
 about nested subexpressions like (c+d) at all.
 
 To start, an expression is a primary expression potentially followed by
 a sequence of [binop,primaryexpr] pairs:
 
-.. code-block:: c++
-
-    /// expression
-    ///   ::= primary binoprhs
-    ///
-    static std::unique_ptr<ExprAST> ParseExpression() {
-      auto LHS = ParsePrimary();
-      if (!LHS)
-        return nullptr;
-
-      return ParseBinOpRHS(0, std::move(LHS));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseExpression
+  :end-before: chapter2-ParseExpression
+  :dedent: 0
 
 ``ParseBinOpRHS`` is the function that parses the sequence of pairs for
 us. It takes a precedence and a pointer to an expression for the part
 that has been parsed so far. Note that "x" is a perfectly valid
 expression: As such, "binoprhs" is allowed to be empty, in which case it
 returns the expression that is passed into it. In our example above, the
 code passes the expression for "a" into ``ParseBinOpRHS`` and the
 current token is "+".
 
 The precedence value passed into ``ParseBinOpRHS`` indicates the
 *minimal operator precedence* that the function is allowed to eat. For
 example, if the current pair stream is [+, x] and ``ParseBinOpRHS`` is
 passed in a precedence of 40, it will not consume any tokens (because
 the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``
 starts with:
 
-.. code-block:: c++
-
-    /// binoprhs
-    ///   ::= ('+' primary)*
-    static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
-                                                  std::unique_ptr<ExprAST> LHS) {
-      // If this is a binop, find its precedence.
-      while (1) {
-        int TokPrec = GetTokPrecedence();
-
-        // If this is a binop that binds at least as tightly as the current binop,
-        // consume it, otherwise we are done.
-        if (TokPrec < ExprPrec)
-          return LHS;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseBinOpRHS1
+  :end-before: chapter2-ParseBinOpRHS1
+  :dedent: 0
 
 This code gets the precedence of the current token and checks to see if
 if is too low. Because we defined invalid tokens to have a precedence of
 -1, this check implicitly knows that the pair-stream ends when the token
 stream runs out of binary operators. If this check succeeds, we know
 that the token is a binary operator and that it will be included in this
 expression:
 
-.. code-block:: c++
-
-        // Okay, we know this is a binop.
-        int BinOp = CurTok;
-        getNextToken();  // eat binop
-
-        // Parse the primary expression after the binary operator.
-        auto RHS = ParsePrimary();
-        if (!RHS)
-          return nullptr;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseBinOpRHS2
+  :end-before: chapter2-ParseBinOpRHS2
+  :dedent: 4
 
 As such, this code eats (and remembers) the binary operator and then
 parses the primary expression that follows. This builds up the whole
 pair, the first of which is [+, b] for the running example.
 
 Now that we parsed the left-hand side of an expression and one pair of
 the RHS sequence, we have to decide which way the expression associates.
 In particular, we could have "(a+b) binop unparsed" or "a + (b binop

 precedence of "+" so the if condition will be entered.
 
 The critical question left here is "how can the if condition parse the
 right hand side in full"? In particular, to build the AST correctly for
 our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression
 variable. The code to do this is surprisingly simple (code from the
 above two blocks duplicated for context):
 
-.. code-block:: c++
-
-        // If BinOp binds less tightly with RHS than the operator after RHS, let
-        // the pending operator take RHS as its LHS.
-        int NextPrec = GetTokPrecedence();
-        if (TokPrec < NextPrec) {
-          RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));
-          if (!RHS)
-            return nullptr;
-        }
-        // Merge LHS/RHS.
-        LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
-                                               std::move(RHS));
-      }  // loop around to the top of the while loop.
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseBinOpRHS3
+  :end-before: chapter2-ParseBinOpRHS3
+  :dedent: 0
 
 At this point, we know that the binary operator to the RHS of our
 primary has higher precedence than the binop we are currently parsing.
 As such, we know that any sequence of pairs whose operators are all
 higher precedence than "+" should be parsed together and returned as
 "RHS". To do this, we recursively invoke the ``ParseBinOpRHS`` function
 specifying "TokPrec+1" as the minimum precedence required for it to
 continue. In our example above, this will cause it to return the AST

 ================
 
 The next thing missing is handling of function prototypes. In
 Kaleidoscope, these are used both for 'extern' function declarations as
 well as function body definitions. The code to do this is
 straight-forward and not very interesting (once you've survived
 expressions):
 
-.. code-block:: c++
-
-    /// prototype
-    ///   ::= id '(' id* ')'
-    static std::unique_ptr<PrototypeAST> ParsePrototype() {
-      if (CurTok != tok_identifier)
-        return LogErrorP("Expected function name in prototype");
-
-      std::string FnName = IdentifierStr;
-      getNextToken();
-
-      if (CurTok != '(')
-        return LogErrorP("Expected '(' in prototype");
-
-      // Read the list of argument names.
-      std::vector<std::string> ArgNames;
-      while (getNextToken() == tok_identifier)
-        ArgNames.push_back(IdentifierStr);
-      if (CurTok != ')')
-        return LogErrorP("Expected ')' in prototype");
-
-      // success.
-      getNextToken();  // eat ')'.
-
-      return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParsePrototype
+  :end-before: chapter2-ParsePrototype
+  :dedent: 0
 
 Given this, a function definition is very simple, just a prototype plus
 an expression to implement the body:
 
-.. code-block:: c++
-
-    /// definition ::= 'def' prototype expression
-    static std::unique_ptr<FunctionAST> ParseDefinition() {
-      getNextToken();  // eat def.
-      auto Proto = ParsePrototype();
-      if (!Proto) return nullptr;
-
-      if (auto E = ParseExpression())
-        return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
-      return nullptr;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseDefinition
+  :end-before: chapter2-ParseDefinition
+  :dedent: 0
 
 In addition, we support 'extern' to declare functions like 'sin' and
 'cos' as well as to support forward declaration of user functions. These
 'extern's are just prototypes with no body:
 
-.. code-block:: c++
-
-    /// external ::= 'extern' prototype
-    static std::unique_ptr<PrototypeAST> ParseExtern() {
-      getNextToken();  // eat extern.
-      return ParsePrototype();
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseExtern
+  :end-before: chapter2-ParseExtern
+  :dedent: 0
 
 Finally, we'll also let the user type in arbitrary top-level expressions
 and evaluate them on the fly. We will handle this by defining anonymous
 nullary (zero argument) functions for them:
 
-.. code-block:: c++
-
-    /// toplevelexpr ::= expression
-    static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
-      if (auto E = ParseExpression()) {
-        // Make an anonymous proto.
-        auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());
-        return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
-      }
-      return nullptr;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-ParseTopLevelExpr
+  :end-before: chapter2-ParseTopLevelExpr
+  :dedent: 0
 
 Now that we have all the pieces, let's build a little driver that will
 let us actually *execute* this code we've built!
 
 The Driver
 ==========
 
 The driver for this simply invokes all of the parsing pieces with a
 top-level dispatch loop. There isn't much interesting here, so I'll just
 include the top-level loop. See `below <#full-code-listing>`_ for full code in the
 "Top-Level Parsing" section.
 
-.. code-block:: c++
-
-    /// top ::= definition | external | expression | ';'
-    static void MainLoop() {
-      while (1) {
-        fprintf(stderr, "ready> ");
-        switch (CurTok) {
-        case tok_eof:
-          return;
-        case ';': // ignore top-level semicolons.
-          getNextToken();
-          break;
-        case tok_def:
-          HandleDefinition();
-          break;
-        case tok_extern:
-          HandleExtern();
-          break;
-        default:
-          HandleTopLevelExpression();
-          break;
-        }
-      }
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter2/toy.cpp
+  :language: c++
+  :start-after: chapter2-MainLoop
+  :end-before: chapter2-MainLoop
+  :dedent: 0
 
 The most interesting part of this is that we ignore top-level
 semicolons. Why is this, you ask? The basic reason is that if you type
 "4 + 5" at the command line, the parser doesn't know whether that is the
 end of what you will type or not. For example, on the next line you
 could type "def foo..." in which case 4+5 is the end of a top-level
 expression. Alternatively you could type "\* 6", which would continue
 the expression. Having top-level semicolons allows you to type "4+5;",

docs/tutorial/LangImpl03.rst

 documentation included with your release or on the `llvm.org releases
 page <http://llvm.org/releases/>`_.
 
 Code Generation Setup
 =====================
 
 In order to generate LLVM IR, we want some simple setup to get started.
 First we define virtual code generation (codegen) methods in each AST
-class:
+class (for brevity only the ExprAST and NumberExprAST classes are shown here):
 
-.. code-block:: c++
-
-    /// ExprAST - Base class for all expression nodes.
-    class ExprAST {
-    public:
-      virtual ~ExprAST() {}
-      virtual Value *codegen() = 0;
-    };
-
-    /// NumberExprAST - Expression class for numeric literals like "1.0".
-    class NumberExprAST : public ExprAST {
-      double Val;
-
-    public:
-      NumberExprAST(double Val) : Val(Val) {}
-      virtual Value *codegen();
-    };
-    ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-ExprAST-codegen
+  :end-before: chapter3-ExprAST-codegen
+  :emphasize-lines: 6,16
 
 The codegen() method says to emit IR for that AST node along with all
 the things it depends on, and they all return an LLVM Value object.
 "Value" is the class used to represent a "`Static Single Assignment
 (SSA) <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
 register" or "SSA value" in LLVM. The most distinct aspect of SSA values
 is that their value is computed as the related instruction executes, and
 it does not get a new value until (and if) the instruction re-executes.
 In other words, there is no way to "change" an SSA value. For more
 information, please read up on `Static Single
 Assignment <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
 - the concepts are really quite natural once you grok them.
 
 Note that instead of adding virtual methods to the ExprAST class
 hierarchy, it could also make sense to use a `visitor
 pattern <http://en.wikipedia.org/wiki/Visitor_pattern>`_ or some other
 way to model this. Again, this tutorial won't dwell on good software
 engineering practices: for our purposes, adding a virtual method is
 simplest.
 
 The second thing we want is an "LogError" method like we used for the
 parser, which will be used to report errors found during code generation
 (for example, use of an undeclared parameter):
 
-.. code-block:: c++
-
-    static LLVMContext TheContext;
-    static IRBuilder<> Builder(TheContext);
-    static std::unique_ptr<Module> TheModule;
-    static std::map<std::string, Value *> NamedValues;
-
-    Value *LogErrorV(const char *Str) {
-      LogError(Str);
-      return nullptr;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-globals
+  :end-before: chapter3-globals
 
 The static variables will be used during code generation. ``TheContext``
 is an opaque object that owns a lot of core LLVM data structures, such as
 the type and constant value tables. We don't need to understand it in
 detail, we just need a single instance to pass into APIs that require it.
 
 The ``Builder`` object is a helper object that makes it easy to generate
 LLVM instructions. Instances of the

 
 Expression Code Generation
 ==========================
 
 Generating LLVM code for expression nodes is very straightforward: less
 than 45 lines of commented code for all four of our expression nodes.
 First we'll do numeric literals:
 
-.. code-block:: c++
-
-    Value *NumberExprAST::codegen() {
-      return ConstantFP::get(TheContext, APFloat(Val));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-NumberExprAST-codegen
+  :end-before: chapter3-NumberExprAST-codegen
 
 In the LLVM IR, numeric constants are represented with the
 ``ConstantFP`` class, which holds the numeric value in an ``APFloat``
 internally (``APFloat`` has the capability of holding floating point
 constants of Arbitrary Precision). This code basically just creates
 and returns a ``ConstantFP``. Note that in the LLVM IR that constants
 are all uniqued together and shared. For this reason, the API uses the
 "foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".
 
-.. code-block:: c++
-
-    Value *VariableExprAST::codegen() {
-      // Look this variable up in the function.
-      Value *V = NamedValues[Name];
-      if (!V)
-        LogErrorV("Unknown variable name");
-      return V;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-VariableExprAST-codegen
+  :end-before: chapter3-VariableExprAST-codegen
 
 References to variables are also quite simple using LLVM. In the simple
 version of Kaleidoscope, we assume that the variable has already been
 emitted somewhere and its value is available. In practice, the only
 values that can be in the ``NamedValues`` map are function arguments.
 This code simply checks to see that the specified name is in the map (if
 not, an unknown variable is being referenced) and returns the value for
 it. In future chapters, we'll add support for `loop induction
 variables <LangImpl5.html#for-loop-expression>`_ in the symbol table, and for `local
 variables <LangImpl7.html#user-defined-local-variables>`_.
 
-.. code-block:: c++
-
-    Value *BinaryExprAST::codegen() {
-      Value *L = LHS->codegen();
-      Value *R = RHS->codegen();
-      if (!L || !R)
-        return nullptr;
-
-      switch (Op) {
-      case '+':
-        return Builder.CreateFAdd(L, R, "addtmp");
-      case '-':
-        return Builder.CreateFSub(L, R, "subtmp");
-      case '*':
-        return Builder.CreateFMul(L, R, "multmp");
-      case '<':
-        L = Builder.CreateFCmpULT(L, R, "cmptmp");
-        // Convert bool 0/1 to double 0.0 or 1.0
-        return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext),
-                                    "booltmp");
-      default:
-        return LogErrorV("invalid binary operator");
-      }
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-BinaryExprAST-codegen
+  :end-before: chapter3-BinaryExprAST-codegen
 
 Binary operators start to get more interesting. The basic idea here is
 that we recursively emit code for the left-hand side of the expression,
 then the right-hand side, then we compute the result of the binary
 expression. In this code, we do a simple switch on the opcode to create
 the right LLVM instruction.
 
 In the example above, the LLVM builder class is starting to show its

 value to be a 0.0 or 1.0 value. In order to get these semantics, we
 combine the fcmp instruction with a `uitofp
 instruction <../LangRef.html#uitofp-to-instruction>`_. This instruction converts its
 input integer into a floating point value by treating the input as an
 unsigned value. In contrast, if we used the `sitofp
 instruction <../LangRef.html#sitofp-to-instruction>`_, the Kaleidoscope '<' operator
 would return 0.0 and -1.0, depending on the input value.
 
-.. code-block:: c++
-
-    Value *CallExprAST::codegen() {
-      // Look up the name in the global module table.
-      Function *CalleeF = TheModule->getFunction(Callee);
-      if (!CalleeF)
-        return LogErrorV("Unknown function referenced");
-
-      // If argument mismatch error.
-      if (CalleeF->arg_size() != Args.size())
-        return LogErrorV("Incorrect # arguments passed");
-
-      std::vector<Value *> ArgsV;
-      for (unsigned i = 0, e = Args.size(); i != e; ++i) {
-        ArgsV.push_back(Args[i]->codegen());
-        if (!ArgsV.back())
-          return nullptr;
-      }
-
-      return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-CallExprAST-codegen
+  :end-before: chapter3-CallExprAST-codegen
 
 Code generation for function calls is quite straightforward with LLVM. The code
 above initially does a function name lookup in the LLVM Module's symbol table.
 Recall that the LLVM Module is the container that holds the functions we are
 JIT'ing. By giving each function the same name as what the user specifies, we
 can use the LLVM symbol table to resolve function names for us.
 
 Once we have the function to call, we recursively codegen each argument

 
 Code generation for prototypes and functions must handle a number of
 details, which make their code less beautiful than expression code
 generation, but allows us to illustrate some important points. First,
 lets talk about code generation for prototypes: they are used both for
 function bodies and external function declarations. The code starts
 with:
 
-.. code-block:: c++
-
-    Function *PrototypeAST::codegen() {
-      // Make the function type:  double(double,double) etc.
-      std::vector<Type*> Doubles(Args.size(),
-                                 Type::getDoubleTy(TheContext));
-      FunctionType *FT =
-        FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
-
-      Function *F =
-        Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-PrototypeAST-codegen1
+  :end-before: chapter3-PrototypeAST-codegen1
 
 This code packs a lot of power into a few lines. Note first that this
 function returns a "Function\*" instead of a "Value\*". Because a
 "prototype" really talks about the external interface for a function
 (not the value computed by an expression), it makes sense for it to
 return the LLVM Function it corresponds to when codegen'd.
 
 The call to ``FunctionType::get`` creates the ``FunctionType`` that

 the Prototype. This indicates the type, linkage and name to use, as
 well as which module to insert into. "`external
 linkage <../LangRef.html#linkage>`_" means that the function may be
 defined outside the current module and/or that it is callable by
 functions outside the module. The Name passed in is the name the user
 specified: since "``TheModule``" is specified, this name is registered
 in "``TheModule``"s symbol table.
 
-.. code-block:: c++
-
-  // Set names for all arguments.
-  unsigned Idx = 0;
-  for (auto &Arg : F->args())
-    Arg.setName(Args[Idx++]);
-
-  return F;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-PrototypeAST-codegen2
+  :end-before: chapter3-PrototypeAST-codegen2
 
 Finally, we set the name of each of the function's arguments according to the
 names given in the Prototype. This step isn't strictly necessary, but keeping
 the names consistent makes the IR more readable, and allows subsequent code to
 refer directly to the arguments for their names, rather than having to look up
 them up in the Prototype AST.
 
 At this point we have a function prototype with no body. This is how LLVM IR
 represents function declarations. For extern statements in Kaleidoscope, this
 is as far as we need to go. For function definitions however, we need to
 codegen and attach a function body.
 
-.. code-block:: c++
-
-  Function *FunctionAST::codegen() {
-      // First, check for an existing function from a previous 'extern' declaration.
-    Function *TheFunction = TheModule->getFunction(Proto->getName());
-
-    if (!TheFunction)
-      TheFunction = Proto->codegen();
-
-    if (!TheFunction)
-      return nullptr;
-
-    if (!TheFunction->empty())
-      return (Function*)LogErrorV("Function cannot be redefined.");
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-FunctionAST-codegen1
+  :end-before: chapter3-FunctionAST-codegen1
 
 
 For function definitions, we start by searching TheModule's symbol table for an
 existing version of this function, in case one has already been created using an
 'extern' statement. If Module::getFunction returns null then no previous version
-exists, so we'll codegen one from the Prototype. In either case, we want to
-assert that the function is empty (i.e. has no body yet) before we start.
+exists, so we'll codegen one from the Prototype.
 
-.. code-block:: c++
 
-  // Create a new basic block to start insertion into.
-  BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
-  Builder.SetInsertPoint(BB);
-
-  // Record the function arguments in the NamedValues map.
-  NamedValues.clear();
-  for (auto &Arg : TheFunction->args())
-    NamedValues[Arg.getName()] = &Arg;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-FunctionAST-codegen2
+  :end-before: chapter3-FunctionAST-codegen2
+  :dedent: 2
 
 Now we get to the point where the ``Builder`` is set up. The first line
 creates a new `basic block <http://en.wikipedia.org/wiki/Basic_block>`_
 (named "entry"), which is inserted into ``TheFunction``. The second line
 then tells the builder that new instructions should be inserted into the
 end of the new basic block. Basic blocks in LLVM are an important part
 of functions that define the `Control Flow
 Graph <http://en.wikipedia.org/wiki/Control_flow_graph>`_. Since we
 don't have any control flow, our functions will only contain one block
 at this point. We'll fix this in `Chapter 5 <LangImpl05.html>`_ :).
 
 Next we add the function arguments to the NamedValues map (after first clearing
 it out) so that they're accessible to ``VariableExprAST`` nodes.
 
-.. code-block:: c++
-
-      if (Value *RetVal = Body->codegen()) {
-        // Finish off the function.
-        Builder.CreateRet(RetVal);
-
-        // Validate the generated code, checking for consistency.
-        verifyFunction(*TheFunction);
 
-        return TheFunction;
-      }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-FunctionAST-codegen3
+  :end-before: chapter3-FunctionAST-codegen3
+  :dedent: 2
 
 Once the insertion point has been set up and the NamedValues map populated,
 we call the ``codegen()`` method for the root expression of the function. If no
 error happens, this emits code to compute the expression into the entry block
 and returns the value that was computed. Assuming no error, we then create an
 LLVM `ret instruction <../LangRef.html#ret-instruction>`_, which completes the function.
 Once the function is built, we call ``verifyFunction``, which is
 provided by LLVM. This function does a variety of consistency checks on
 the generated code, to determine if our compiler is doing everything
 right. Using this is important: it can catch a lot of bugs. Once the
 function is finished and validated, we return it.
 
-.. code-block:: c++
 
-      // Error reading body, remove function.
-      TheFunction->eraseFromParent();
-      return nullptr;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter3/toy.cpp
+  :language: c++
+  :start-after: chapter3-FunctionAST-codegen4
+  :end-before: chapter3-FunctionAST-codegen4
 
 The only piece left here is handling of the error case. For simplicity,
 we handle this by merely deleting the function we produced with the
 ``eraseFromParent`` method. This allows the user to redefine a function
 that they incorrectly typed in before: if we didn't delete it, it would
 live in the symbol table, with a body, preventing future redefinition.
 
 This code does have a bug, though: If the ``FunctionAST::codegen()`` method

docs/tutorial/LangImpl04.rst

 In order to get per-function optimizations going, we need to set up a
 `FunctionPassManager <../WritingAnLLVMPass.html#what-passmanager-doesr>`_ to hold
 and organize the LLVM optimizations that we want to run. Once we have
 that, we can add a set of optimizations to run. We'll need a new
 FunctionPassManager for each module that we want to optimize, so we'll
 write a function to create and initialize both the module and pass manager
 for us:
 
-.. code-block:: c++
-
-    void InitializeModuleAndPassManager(void) {
-      // Open a new module.
-      TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
-
-      // Create a new pass manager attached to it.
-      TheFPM = llvm::make_unique<FunctionPassManager>(TheModule.get());
-
-      // Do simple "peephole" optimizations and bit-twiddling optzns.
-      TheFPM->add(createInstructionCombiningPass());
-      // Reassociate expressions.
-      TheFPM->add(createReassociatePass());
-      // Eliminate Common SubExpressions.
-      TheFPM->add(createGVNPass());
-      // Simplify the control flow graph (deleting unreachable blocks, etc).
-      TheFPM->add(createCFGSimplificationPass());
-
-      TheFPM->doInitialization();
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-InitializeModuleAndPassManager
+  :end-before: chapter4-InitializeModuleAndPassManager
+  :lines: 1-3,5-
 
 This code initializes the global module ``TheModule``, and the function pass
 manager ``TheFPM``, which is attached to ``TheModule``. Once the pass manager is
 set up, we use a series of "add" calls to add a bunch of LLVM passes.
 
 In this case, we choose to add four optimization passes.
 The passes we choose here are a pretty standard set
 of "cleanup" optimizations that are useful for a wide variety of code. I won't
 delve into what they do but, believe me, they are a good starting place :).
 
 Once the PassManager is set up, we need to make use of it. We do this by
 running it after our newly created function is constructed (in
 ``FunctionAST::codegen()``), but before it is returned to the client:
 
-.. code-block:: c++
-
-      if (Value *RetVal = Body->codegen()) {
-        // Finish off the function.
-        Builder.CreateRet(RetVal);
-
-        // Validate the generated code, checking for consistency.
-        verifyFunction(*TheFunction);
-
-        // Optimize the function.
-        TheFPM->run(*TheFunction);
-
-        return TheFunction;
-      }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-run-passes
+  :end-before: chapter4-run-passes
+  :dedent: 2
 
 As you can see, this is pretty straightforward. The
 ``FunctionPassManager`` optimizes and updates the LLVM Function\* in
 place, improving (hopefully) its body. With this in place, we can try
 our test above again:
 
 ::
 

 be able to call it from the command line.
 
 In order to do this, we first prepare the environment to create code for
 the current native target and declare and initialize the JIT. This is
 done by calling some ``InitializeNativeTarget\*`` functions and
 adding a global variable ``TheJIT``, and initializing it in
 ``main``:
 
-.. code-block:: c++
-
-    static std::unique_ptr<KaleidoscopeJIT> TheJIT;
-    ...
-    int main() {
-      InitializeNativeTarget();
-      InitializeNativeTargetAsmPrinter();
-      InitializeNativeTargetAsmParser();
-
-      // Install standard binary operators.
-      // 1 is lowest precedence.
-      BinopPrecedence['<'] = 10;
-      BinopPrecedence['+'] = 20;
-      BinopPrecedence['-'] = 20;
-      BinopPrecedence['*'] = 40; // highest.
-
-      // Prime the first token.
-      fprintf(stderr, "ready> ");
-      getNextToken();
-
-      TheJIT = llvm::make_unique<KaleidoscopeJIT>();
-
-      // Run the main "interpreter loop" now.
-      MainLoop();
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-TheJIT
+  :end-before: chapter4-TheJIT
 
-      return 0;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-main
+  :end-before: chapter4-main
 
 We also need to setup the data layout for the JIT:
 
-.. code-block:: c++
-
-    void InitializeModuleAndPassManager(void) {
-      // Open a new module.
-      TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
-      TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
-
-      // Create a new pass manager attached to it.
-      TheFPM = llvm::make_unique<FunctionPassManager>(TheModule.get());
-      ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-InitializeModuleAndPassManager
+  :end-before: chapter4-InitializeModuleAndPassManager
+  :emphasize-lines: 4
+  :lines: -7
 
 The KaleidoscopeJIT class is a simple JIT built specifically for these
 tutorials, available inside the LLVM source code
 at llvm-src/examples/Kaleidoscope/include/KaleidoscopeJIT.h.
 In later chapters we will look at how it works and extend it with
 new features, but for now we will take it as given. Its API is very simple:
 ``addModule`` adds an LLVM IR module to the JIT, making its functions
 available for execution; ``removeModule`` removes a module, freeing any
 memory associated with the code in that module; and ``findSymbol`` allows us
 to look up pointers to the compiled code.
 
 We can take this simple API and change our code that parses top-level expressions to
 look like this:
 
-.. code-block:: c++
-
-    static void HandleTopLevelExpression() {
-      // Evaluate a top-level expression into an anonymous function.
-      if (auto FnAST = ParseTopLevelExpr()) {
-        if (FnAST->codegen()) {
-
-          // JIT the module containing the anonymous expression, keeping a handle so
-          // we can free it later.
-          auto H = TheJIT->addModule(std::move(TheModule));
-          InitializeModuleAndPassManager();
-
-          // Search the JIT for the __anon_expr symbol.
-          auto ExprSymbol = TheJIT->findSymbol("__anon_expr");
-          assert(ExprSymbol && "Function not found");
-
-          // Get the symbol's address and cast it to the right type (takes no
-          // arguments, returns a double) so we can call it as a native function.
-          double (*FP)() = (double (*)())(intptr_t)ExprSymbol.getAddress();
-          fprintf(stderr, "Evaluated to %f\n", FP());
-
-          // Delete the anonymous expression module from the JIT.
-          TheJIT->removeModule(H);
-        }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-HandleTopLevelExpression
+  :end-before: chapter4-HandleTopLevelExpression
 
 If parsing and codegen succeeed, the next step is to add the module containing
 the top-level expression to the JIT. We do this by calling addModule, which
 triggers code generation for all the functions in the module, and returns a
 handle that can be used to remove the module from the JIT later. Once the module
 has been added to the JIT it can no longer be modified, so we also open a new
 module to hold subsequent code by calling ``InitializeModuleAndPassManager()``.
 
::
 
     ready> foo(2);
     Evaluated to 4.000000
 
 
 To allow each function to live in its own module we'll need a way to
 re-generate previous function declarations into each new module we open:
 
-.. code-block:: c++
-
-    static std::unique_ptr<KaleidoscopeJIT> TheJIT;
-
-    ...
-
-    Function *getFunction(std::string Name) {
-      // First, see if the function has already been added to the current module.
-      if (auto *F = TheModule->getFunction(Name))
-        return F;
-
-      // If not, check whether we can codegen the declaration from some existing
-      // prototype.
-      auto FI = FunctionProtos.find(Name);
-      if (FI != FunctionProtos.end())
-        return FI->second->codegen();
-
-      // If no existing prototype exists, return null.
-      return nullptr;
-    }
-
-    ...
-
-    Value *CallExprAST::codegen() {
-      // Look up the name in the global module table.
-      Function *CalleeF = getFunction(Callee);
-
-    ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-getFunction
+  :end-before: chapter4-getFunction
 
-    Function *FunctionAST::codegen() {
-      // Transfer ownership of the prototype to the FunctionProtos map, but keep a
-      // reference to it for use below.
-      auto &P = *Proto;
-      FunctionProtos[Proto->getName()] = std::move(Proto);
-      Function *TheFunction = getFunction(P.getName());
-      if (!TheFunction)
-        return nullptr;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-CallExprAST-codegen
+  :end-before: chapter4-CallExprAST-codegen
+  :lines: 1-5
+  :emphasize-lines: 3
 
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-FunctionAST-codegen
+  :end-before: chapter4-FunctionAST-codegen
+  :lines: 1-8
 
 To enable this, we'll start by adding a new global, ``FunctionProtos``, that
 holds the most recent prototype for each function. We'll also add a convenience
 method, ``getFunction()``, to replace calls to ``TheModule->getFunction()``.
 Our convenience method searches ``TheModule`` for an existing function
 declaration, falling back to generating a new declaration from FunctionProtos if
 it doesn't find one. In ``CallExprAST::codegen()`` we just need to replace the
 call to ``TheModule->getFunction()``. In ``FunctionAST::codegen()`` we need to
 update the FunctionProtos map first, then call ``getFunction()``. With this
 done, we can always obtain a function declaration in the current module for any
 previously declared function.
 
 We also need to update HandleDefinition and HandleExtern:
 
-.. code-block:: c++
-
-    static void HandleDefinition() {
-      if (auto FnAST = ParseDefinition()) {
-        if (auto *FnIR = FnAST->codegen()) {
-          fprintf(stderr, "Read function definition:");
-          FnIR->print(errs());
-          fprintf(stderr, "\n");
-          TheJIT->addModule(std::move(TheModule));
-          InitializeModuleAndPassManager();
-        }
-      } else {
-        // Skip token for error recovery.
-         getNextToken();
-      }
-    }
-
-    static void HandleExtern() {
-      if (auto ProtoAST = ParseExtern()) {
-        if (auto *FnIR = ProtoAST->codegen()) {
-          fprintf(stderr, "Read extern: ");
-          FnIR->print(errs());
-          fprintf(stderr, "\n");
-          FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
-        }
-      } else {
-        // Skip token for error recovery.
-        getNextToken();
-      }
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-HandleDefinition+HandleExtern
+  :end-before: chapter4-HandleDefinition+HandleExtern
 
 In HandleDefinition, we add two lines to transfer the newly defined function to
 the JIT and open a new module. In HandleExtern, we just need to add one line to
 add the prototype to FunctionProtos.
 
 With these changes made, lets try our REPL again (I removed the dump of the
 anonymous functions this time, you should get the idea by now :) :
 

 enable all sorts of useful features, from security (restricting the set of
 symbols available to JIT'd code), to dynamic code generation based on symbol
 names, and even lazy compilation.
 
 One immediate benefit of the symbol resolution rule is that we can now extend
 the language by writing arbitrary C++ code to implement operations. For example,
 if we add:
 
-.. code-block:: c++
-
-    #ifdef LLVM_ON_WIN32
-    #define DLLEXPORT __declspec(dllexport)
-    #else
-    #define DLLEXPORT
-    #endif
-
-    /// putchard - putchar that takes a double and returns 0.
-    extern "C" DLLEXPORT double putchard(double X) {
-      fputc((char)X, stderr);
-      return 0;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter4/toy.cpp
+  :language: c++
+  :start-after: chapter4-extern
+  :end-before: chapter4-extern
 
 Note, that for Windows we need to actually export the functions because
 the dynamic symbol loader will use GetProcAddress to find the symbols.
 
 Now we can produce simple output to the console by using things like:
 "``extern putchard(x); putchard(120);``", which prints a lowercase 'x'
 on the console (120 is the ASCII code for 'x'). Similar code could be
 used to implement file I/O, console input, and many other capabilities

docs/tutorial/LangImpl05.rst

 constituent pieces.
 
 Lexer Extensions for If/Then/Else
 ---------------------------------
 
 The lexer extensions are straightforward. First we add new enum values
 for the relevant tokens:
 
-.. code-block:: c++
-
-      // control
-      tok_if = -6,
-      tok_then = -7,
-      tok_else = -8,
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-tokens1
+  :end-before: chapter5-tokens1
+  :lines: 1-4
+  :dedent: 2
 
 Once we have that, we recognize the new keywords in the lexer. This is
 pretty simple stuff:
 
-.. code-block:: c++
-
-        ...
-        if (IdentifierStr == "def")
-          return tok_def;
-        if (IdentifierStr == "extern")
-          return tok_extern;
-        if (IdentifierStr == "if")
-          return tok_if;
-        if (IdentifierStr == "then")
-          return tok_then;
-        if (IdentifierStr == "else")
-          return tok_else;
-        return tok_identifier;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-gettok
+  :end-before: chapter5-gettok
+  :lines: -10,15
+  :emphasize-lines: 5-10
+  :dedent: 4
 
 AST Extensions for If/Then/Else
 -------------------------------
 
 To represent the new expression we add a new AST node for it:
 
-.. code-block:: c++
-
-    /// IfExprAST - Expression class for if/then/else.
-    class IfExprAST : public ExprAST {
-      std::unique_ptr<ExprAST> Cond, Then, Else;
-
-    public:
-      IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,
-                std::unique_ptr<ExprAST> Else)
-        : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}
-
-      Value *codegen() override;
-    };
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-IfExprAST
+  :end-before: chapter5-IfExprAST
 
 The AST node just has pointers to the various subexpressions.
 
 Parser Extensions for If/Then/Else
 ----------------------------------
 
 Now that we have the relevant tokens coming from the lexer and we have
 the AST node to build, our parsing logic is relatively straightforward.
 First we define a new parsing function:
 
-.. code-block:: c++
-
-    /// ifexpr ::= 'if' expression 'then' expression 'else' expression
-    static std::unique_ptr<ExprAST> ParseIfExpr() {
-      getNextToken();  // eat the if.
-
-      // condition.
-      auto Cond = ParseExpression();
-      if (!Cond)
-        return nullptr;
-
-      if (CurTok != tok_then)
-        return LogError("expected then");
-      getNextToken();  // eat the then
-
-      auto Then = ParseExpression();
-      if (!Then)
-        return nullptr;
-
-      if (CurTok != tok_else)
-        return LogError("expected else");
-
-      getNextToken();
-
-      auto Else = ParseExpression();
-      if (!Else)
-        return nullptr;
-
-      return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),
-                                          std::move(Else));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ParseIfExpr
+  :end-before: chapter5-ParseIfExpr
 
 Next we hook it up as a primary expression:
 
-.. code-block:: c++
-
-    static std::unique_ptr<ExprAST> ParsePrimary() {
-      switch (CurTok) {
-      default:
-        return LogError("unknown token when expecting an expression");
-      case tok_identifier:
-        return ParseIdentifierExpr();
-      case tok_number:
-        return ParseNumberExpr();
-      case '(':
-        return ParseParenExpr();
-      case tok_if:
-        return ParseIfExpr();
-      }
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ParsePrimary
+  :end-before: chapter5-ParsePrimary
+  :lines: -12,15-
+  :emphasize-lines: 11-12
 
 LLVM IR for If/Then/Else
 ------------------------
 
 Now that we have it parsing and building the AST, the final piece is
 adding LLVM code generation support. This is the most interesting part
 of the if/then/else example, because this is where it starts to
 introduce new concepts. All of the code above has been thoroughly

 Okay, enough of the motivation and overview, lets generate code!
 
 Code Generation for If/Then/Else
 --------------------------------
 
 In order to generate code for this, we implement the ``codegen`` method
 for ``IfExprAST``:
 
-.. code-block:: c++
-
-    Value *IfExprAST::codegen() {
-      Value *CondV = Cond->codegen();
-      if (!CondV)
-        return nullptr;
-
-      // Convert condition to a bool by comparing non-equal to 0.0.
-      CondV = Builder.CreateFCmpONE(
-          CondV, ConstantFP::get(TheContext, APFloat(0.0)), "ifcond");
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-IfExprAST-codegen1
+  :end-before: chapter5-IfExprAST-codegen1
 
 This code is straightforward and similar to what we saw before. We emit
 the expression for the condition, then compare that value to zero to get
 a truth value as a 1-bit (bool) value.
 
-.. code-block:: c++
-
-      Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
-      // Create blocks for the then and else cases.  Insert the 'then' block at the
-      // end of the function.
-      BasicBlock *ThenBB =
-          BasicBlock::Create(TheContext, "then", TheFunction);
-      BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
-      BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
-
-      Builder.CreateCondBr(CondV, ThenBB, ElseBB);
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-IfExprAST-codegen2
+  :end-before: chapter5-IfExprAST-codegen2
+  :dedent: 2
 
 This code creates the basic blocks that are related to the if/then/else
 statement, and correspond directly to the blocks in the example above.
 The first line gets the current Function object that is being built. It
 gets this by asking the builder for the current BasicBlock, and asking
 that block for its "parent" (the function it is currently embedded
 into).
 
 Once it has that, it creates three blocks. Note that it passes
 "TheFunction" into the constructor for the "then" block. This causes the
 constructor to automatically insert the new block into the end of the
 specified function. The other two blocks are created, but aren't yet
 inserted into the function.
 
 Once the blocks are created, we can emit the conditional branch that
 chooses between them. Note that creating new blocks does not implicitly
 affect the IRBuilder, so it is still inserting into the block that the
 condition went into. Also note that it is creating a branch to the
 "then" block and the "else" block, even though the "else" block isn't
 inserted into the function yet. This is all ok: it is the standard way
 that LLVM supports forward references.
 
-.. code-block:: c++
-
-      // Emit then value.
-      Builder.SetInsertPoint(ThenBB);
-
-      Value *ThenV = Then->codegen();
-      if (!ThenV)
-        return nullptr;
-
-      Builder.CreateBr(MergeBB);
-      // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
-      ThenBB = Builder.GetInsertBlock();
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-IfExprAST-codegen3
+  :end-before: chapter5-IfExprAST-codegen3
+  :dedent: 2
 
 After the conditional branch is inserted, we move the builder to start
 inserting into the "then" block. Strictly speaking, this call moves the
 insertion point to be at the end of the specified block. However, since
 the "then" block is empty, it also starts out by inserting at the
 beginning of the block. :)
 
 Once the insertion point is set, we recursively codegen the "then"

 of the block in the CFG. Why then, are we getting the current block when
 we just set it to ThenBB 5 lines above? The problem is that the "Then"
 expression may actually itself change the block that the Builder is
 emitting into if, for example, it contains a nested "if/then/else"
 expression. Because calling ``codegen()`` recursively could arbitrarily change
 the notion of the current block, we are required to get an up-to-date
 value for code that will set up the Phi node.
 
-.. code-block:: c++
-
-      // Emit else block.
-      TheFunction->getBasicBlockList().push_back(ElseBB);
-      Builder.SetInsertPoint(ElseBB);
-
-      Value *ElseV = Else->codegen();
-      if (!ElseV)
-        return nullptr;
-
-      Builder.CreateBr(MergeBB);
-      // codegen of 'Else' can change the current block, update ElseBB for the PHI.
-      ElseBB = Builder.GetInsertBlock();
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-IfExprAST-codegen4
+  :end-before: chapter5-IfExprAST-codegen4
+  :dedent: 2
 
 Code generation for the 'else' block is basically identical to codegen
 for the 'then' block. The only significant difference is the first line,
 which adds the 'else' block to the function. Recall previously that the
 'else' block was created, but not added to the function. Now that the
 'then' and 'else' blocks are emitted, we can finish up with the merge
 code:
 
-.. code-block:: c++
-
-      // Emit merge block.
-      TheFunction->getBasicBlockList().push_back(MergeBB);
-      Builder.SetInsertPoint(MergeBB);
-      PHINode *PN =
-        Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");
-
-      PN->addIncoming(ThenV, ThenBB);
-      PN->addIncoming(ElseV, ElseBB);
-      return PN;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-IfExprAST-codegen5
+  :end-before: chapter5-IfExprAST-codegen5
 
 The first two lines here are now familiar: the first adds the "merge"
 block to the Function object (it was previously floating, like the else
 block above). The second changes the insertion point so that newly
 created code will go into the "merge" block. Once that is done, we need
 to create the PHI node and set up the block/value pairs for the PHI.
 
 Finally, the CodeGen function returns the phi node as the value computed

 As before, lets talk about the changes that we need to Kaleidoscope to
 support this.
 
 Lexer Extensions for the 'for' Loop
 -----------------------------------
 
 The lexer extensions are the same sort of thing as for if/then/else:
 
-.. code-block:: c++
+In the Token enum:
 
-      ... in enum Token ...
-      // control
-      tok_if = -6, tok_then = -7, tok_else = -8,
-      tok_for = -9, tok_in = -10
-
-      ... in gettok ...
-      if (IdentifierStr == "def")
-        return tok_def;
-      if (IdentifierStr == "extern")
-        return tok_extern;
-      if (IdentifierStr == "if")
-        return tok_if;
-      if (IdentifierStr == "then")
-        return tok_then;
-      if (IdentifierStr == "else")
-        return tok_else;
-      if (IdentifierStr == "for")
-        return tok_for;
-      if (IdentifierStr == "in")
-        return tok_in;
-      return tok_identifier;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-tokens1
+  :end-before: chapter5-tokens1
+  :emphasize-lines: 5-6
+  :dedent: 2
+
+In the gettok function:
+
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-gettok
+  :end-before: chapter5-gettok
+  :emphasize-lines: 11-14
+  :dedent: 4
 
 AST Extensions for the 'for' Loop
 ---------------------------------
 
 The AST node is just as simple. It basically boils down to capturing the
 variable name and the constituent expressions in the node.
 
-.. code-block:: c++
-
-    /// ForExprAST - Expression class for for/in.
-    class ForExprAST : public ExprAST {
-      std::string VarName;
-      std::unique_ptr<ExprAST> Start, End, Step, Body;
-
-    public:
-      ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,
-                 std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,
-                 std::unique_ptr<ExprAST> Body)
-        : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
-          Step(std::move(Step)), Body(std::move(Body)) {}
-
-      Value *codegen() override;
-    };
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST
+  :end-before: chapter5-ForExprAST
 
 Parser Extensions for the 'for' Loop
 ------------------------------------
 
 The parser code is also fairly standard. The only interesting thing here
 is handling of the optional step value. The parser code handles it by
 checking to see if the second comma is present. If not, it sets the step
 value to null in the AST node:
 
-.. code-block:: c++
-
-    /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
-    static std::unique_ptr<ExprAST> ParseForExpr() {
-      getNextToken();  // eat the for.
-
-      if (CurTok != tok_identifier)
-        return LogError("expected identifier after for");
-
-      std::string IdName = IdentifierStr;
-      getNextToken();  // eat identifier.
-
-      if (CurTok != '=')
-        return LogError("expected '=' after for");
-      getNextToken();  // eat '='.
-
-
-      auto Start = ParseExpression();
-      if (!Start)
-        return nullptr;
-      if (CurTok != ',')
-        return LogError("expected ',' after for start value");
-      getNextToken();
-
-      auto End = ParseExpression();
-      if (!End)
-        return nullptr;
-
-      // The step value is optional.
-      std::unique_ptr<ExprAST> Step;
-      if (CurTok == ',') {
-        getNextToken();
-        Step = ParseExpression();
-        if (!Step)
-          return nullptr;
-      }
-
-      if (CurTok != tok_in)
-        return LogError("expected 'in' after for");
-      getNextToken();  // eat 'in'.
-
-      auto Body = ParseExpression();
-      if (!Body)
-        return nullptr;
-
-      return llvm::make_unique<ForExprAST>(IdName, std::move(Start),
-                                           std::move(End), std::move(Step),
-                                           std::move(Body));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ParseForExpr
+  :end-before: chapter5-ParseForExpr
 
 And again we hook it up as a primary expression:
 
-.. code-block:: c++
-
-    static std::unique_ptr<ExprAST> ParsePrimary() {
-      switch (CurTok) {
-      default:
-        return LogError("unknown token when expecting an expression");
-      case tok_identifier:
-        return ParseIdentifierExpr();
-      case tok_number:
-        return ParseNumberExpr();
-      case '(':
-        return ParseParenExpr();
-      case tok_if:
-        return ParseIfExpr();
-      case tok_for:
-        return ParseForExpr();
-      }
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ParsePrimary
+  :end-before: chapter5-ParsePrimary
+  :emphasize-lines: 13-14
 
 LLVM IR for the 'for' Loop
 --------------------------
 
 Now we get to the good part: the LLVM IR we want to generate for this
 thing. With the simple example above, we get this LLVM IR (note that
 this dump is generated with optimizations disabled for clarity):
 

 together.
 
 Code Generation for the 'for' Loop
 ----------------------------------
 
 The first part of codegen is very simple: we just output the start
 expression for the loop value:
 
-.. code-block:: c++
-
-    Value *ForExprAST::codegen() {
-      // Emit the start code first, without 'variable' in scope.
-      Value *StartVal = Start->codegen();
-      if (!StartVal)
-        return nullptr;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST-codegen1
+  :end-before: chapter5-ForExprAST-codegen1
 
 With this out of the way, the next step is to set up the LLVM basic
 block for the start of the loop body. In the case above, the whole loop
 body is one block, but remember that the body code itself could consist
 of multiple blocks (e.g. if it contains an if/then/else or a for/in
 expression).
 
-.. code-block:: c++
-
-      // Make the new basic block for the loop header, inserting after current
-      // block.
-      Function *TheFunction = Builder.GetInsertBlock()->getParent();
-      BasicBlock *PreheaderBB = Builder.GetInsertBlock();
-      BasicBlock *LoopBB =
-          BasicBlock::Create(TheContext, "loop", TheFunction);
-
-      // Insert an explicit fall through from the current block to the LoopBB.
-      Builder.CreateBr(LoopBB);
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST-codegen2
+  :end-before: chapter5-ForExprAST-codegen2
+  :dedent: 2
 
 This code is similar to what we saw for if/then/else. Because we will
 need it to create the Phi node, we remember the block that falls through
 into the loop. Once we have that, we create the actual block that starts
 the loop and create an unconditional branch for the fall-through between
 the two blocks.
 
-.. code-block:: c++
-
-      // Start insertion in LoopBB.
-      Builder.SetInsertPoint(LoopBB);
-
-      // Start the PHI node with an entry for Start.
-      PHINode *Variable = Builder.CreatePHI(Type::getDoubleTy(TheContext),
-                                            2, VarName.c_str());
-      Variable->addIncoming(StartVal, PreheaderBB);
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST-codegen3
+  :end-before: chapter5-ForExprAST-codegen3
+  :dedent: 2
 
 Now that the "preheader" for the loop is set up, we switch to emitting
 code for the loop body. To begin with, we move the insertion point and
 create the PHI node for the loop induction variable. Since we already
 know the incoming value for the starting value, we add it to the Phi
 node. Note that the Phi will eventually get a second value for the
 backedge, but we can't set it up yet (because it doesn't exist!).
 
-.. code-block:: c++
-
-      // Within the loop, the variable is defined equal to the PHI node.  If it
-      // shadows an existing variable, we have to restore it, so save it now.
-      Value *OldVal = NamedValues[VarName];
-      NamedValues[VarName] = Variable;
-
-      // Emit the body of the loop.  This, like any other expr, can change the
-      // current BB.  Note that we ignore the value computed by the body, but don't
-      // allow an error.
-      if (!Body->codegen())
-        return nullptr;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST-codegen4
+  :end-before: chapter5-ForExprAST-codegen4
+  :dedent: 2
 
 Now the code starts to get more interesting. Our 'for' loop introduces a
 new variable to the symbol table. This means that our symbol table can
 now contain either function arguments or loop variables. To handle this,
 before we codegen the body of the loop, we add the loop variable as the
 current value for its name. Note that it is possible that there is a
 variable of the same name in the outer scope. It would be easy to make
 this an error (emit an error and return null if there is already an
 entry for VarName) but we choose to allow shadowing of variables. In
 order to handle this correctly, we remember the Value that we are
 potentially shadowing in ``OldVal`` (which will be null if there is no
 shadowed variable).
 
 Once the loop variable is set into the symbol table, the code
 recursively codegen's the body. This allows the body to use the loop
 variable: any references to it will naturally find it in the symbol
 table.
 
-.. code-block:: c++
-
-      // Emit the step value.
-      Value *StepVal = nullptr;
-      if (Step) {
-        StepVal = Step->codegen();
-        if (!StepVal)
-          return nullptr;
-      } else {
-        // If not specified, use 1.0.
-        StepVal = ConstantFP::get(TheContext, APFloat(1.0));
-      }
-
-      Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST-codegen5
+  :end-before: chapter5-ForExprAST-codegen5
+  :dedent: 2
 
 Now that the body is emitted, we compute the next value of the iteration
 variable by adding the step value, or 1.0 if it isn't present.
 '``NextVar``' will be the value of the loop variable on the next
 iteration of the loop.
 
-.. code-block:: c++
-
-      // Compute the end condition.
-      Value *EndCond = End->codegen();
-      if (!EndCond)
-        return nullptr;
-
-      // Convert condition to a bool by comparing non-equal to 0.0.
-      EndCond = Builder.CreateFCmpONE(
-          EndCond, ConstantFP::get(TheContext, APFloat(0.0)), "loopcond");
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST-codegen6
+  :end-before: chapter5-ForExprAST-codegen6
+  :dedent: 2
 
 Finally, we evaluate the exit value of the loop, to determine whether
 the loop should exit. This mirrors the condition evaluation for the
 if/then/else statement.
 
-.. code-block:: c++
-
-      // Create the "after loop" block and insert it.
-      BasicBlock *LoopEndBB = Builder.GetInsertBlock();
-      BasicBlock *AfterBB =
-          BasicBlock::Create(TheContext, "afterloop", TheFunction);
-
-      // Insert the conditional branch into the end of LoopEndBB.
-      Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
-
-      // Any new code will be inserted in AfterBB.
-      Builder.SetInsertPoint(AfterBB);
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST-codegen7
+  :end-before: chapter5-ForExprAST-codegen7
+  :dedent: 2
 
 With the code for the body of the loop complete, we just need to finish
 up the control flow for it. This code remembers the end block (for the
 phi node), then creates the block for the loop exit ("afterloop"). Based
 on the value of the exit condition, it creates a conditional branch that
 chooses between executing the loop again and exiting the loop. Any
 future code is emitted in the "afterloop" block, so it sets the
 insertion position to it.
 
-.. code-block:: c++
-
-      // Add a new entry to the PHI node for the backedge.
-      Variable->addIncoming(NextVar, LoopEndBB);
-
-      // Restore the unshadowed variable.
-      if (OldVal)
-        NamedValues[VarName] = OldVal;
-      else
-        NamedValues.erase(VarName);
-
-      // for expr always returns 0.0.
-      return Constant::getNullValue(Type::getDoubleTy(TheContext));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter5/toy.cpp
+  :language: c++
+  :start-after: chapter5-ForExprAST-codegen8
+  :end-before: chapter5-ForExprAST-codegen8
 
 The final code handles various cleanups: now that we have the "NextVar"
 value, we can add the incoming value to the loop PHI node. After that,
 we remove the loop variable from the symbol table, so that it isn't in
 scope after the for loop. Finally, code generation of the for loop
 always returns 0.0, so that is what we return from
 ``ForExprAST::codegen()``.
 

docs/tutorial/LangImpl06.rst

 On the other hand, we have to be able to represent the definitions of
 these new operators, in the "def binary\| 5" part of the function
 definition. In our grammar so far, the "name" for the function
 definition is parsed as the "prototype" production and into the
 ``PrototypeAST`` AST node. To represent our new user-defined operators
 as prototypes, we have to extend the ``PrototypeAST`` AST node like
 this:
 
-.. code-block:: c++
-
-    /// PrototypeAST - This class represents the "prototype" for a function,
-    /// which captures its argument names as well as if it is an operator.
-    class PrototypeAST {
-      std::string Name;
-      std::vector<std::string> Args;
-      bool IsOperator;
-      unsigned Precedence;  // Precedence if a binary op.
-
-    public:
-      PrototypeAST(const std::string &name, std::vector<std::string> Args,
-                   bool IsOperator = false, unsigned Prec = 0)
-      : Name(name), Args(std::move(Args)), IsOperator(IsOperator),
-        Precedence(Prec) {}
-
-      Function *codegen();
-      const std::string &getName() const { return Name; }
-
-      bool isUnaryOp() const { return IsOperator && Args.size() == 1; }
-      bool isBinaryOp() const { return IsOperator && Args.size() == 2; }
-
-      char getOperatorName() const {
-        assert(isUnaryOp() || isBinaryOp());
-        return Name[Name.size() - 1];
-      }
-
-      unsigned getBinaryPrecedence() const { return Precedence; }
-    };
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-PrototypeAST
+  :end-before: chapter6-PrototypeAST
 
 Basically, in addition to knowing a name for the prototype, we now keep
 track of whether it was an operator, and if it was, what precedence
 level the operator is at. The precedence is only used for binary
 operators (as you'll see below, it just doesn't apply for unary
 operators). Now that we have a way to represent the prototype for a
 user-defined operator, we need to parse it:
 
-.. code-block:: c++
-
-    /// prototype
-    ///   ::= id '(' id* ')'
-    ///   ::= binary LETTER number? (id, id)
-    static std::unique_ptr<PrototypeAST> ParsePrototype() {
-      std::string FnName;
-
-      unsigned Kind = 0;  // 0 = identifier, 1 = unary, 2 = binary.
-      unsigned BinaryPrecedence = 30;
-
-      switch (CurTok) {
-      default:
-        return LogErrorP("Expected function name in prototype");
-      case tok_identifier:
-        FnName = IdentifierStr;
-        Kind = 0;
-        getNextToken();
-        break;
-      case tok_binary:
-        getNextToken();
-        if (!isascii(CurTok))
-          return LogErrorP("Expected binary operator");
-        FnName = "binary";
-        FnName += (char)CurTok;
-        Kind = 2;
-        getNextToken();
-
-        // Read the precedence if present.
-        if (CurTok == tok_number) {
-          if (NumVal < 1 || NumVal > 100)
-            return LogErrorP("Invalid precedence: must be 1..100");
-          BinaryPrecedence = (unsigned)NumVal;
-          getNextToken();
-        }
-        break;
-      }
-
-      if (CurTok != '(')
-        return LogErrorP("Expected '(' in prototype");
-
-      std::vector<std::string> ArgNames;
-      while (getNextToken() == tok_identifier)
-        ArgNames.push_back(IdentifierStr);
-      if (CurTok != ')')
-        return LogErrorP("Expected ')' in prototype");
-
-      // success.
-      getNextToken();  // eat ')'.
-
-      // Verify right number of names for operator.
-      if (Kind && ArgNames.size() != Kind)
-        return LogErrorP("Invalid number of operands for operator");
-
-      return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames), Kind != 0,
-                                             BinaryPrecedence);
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-ParsePrototype
+  :end-before: chapter6-ParsePrototype
+  :lines: -18,28-
 
 This is all fairly straightforward parsing code, and we have already
 seen a lot of similar code in the past. One interesting part about the
 code above is the couple lines that set up ``FnName`` for binary
 operators. This builds names like "binary@" for a newly defined "@"
 operator. It then takes advantage of the fact that symbol names in the
 LLVM symbol table are allowed to have any character in them, including
 embedded nul characters.
 
 The next interesting thing to add, is codegen support for these binary
 operators. Given our current structure, this is a simple addition of a
 default case for our existing binary operator node:
 
-.. code-block:: c++
-
-    Value *BinaryExprAST::codegen() {
-      Value *L = LHS->codegen();
-      Value *R = RHS->codegen();
-      if (!L || !R)
-        return nullptr;
-
-      switch (Op) {
-      case '+':
-        return Builder.CreateFAdd(L, R, "addtmp");
-      case '-':
-        return Builder.CreateFSub(L, R, "subtmp");
-      case '*':
-        return Builder.CreateFMul(L, R, "multmp");
-      case '<':
-        L = Builder.CreateFCmpULT(L, R, "cmptmp");
-        // Convert bool 0/1 to double 0.0 or 1.0
-        return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext),
-                                    "booltmp");
-      default:
-        break;
-      }
-
-      // If it wasn't a builtin binary operator, it must be a user defined one. Emit
-      // a call to it.
-      Function *F = getFunction(std::string("binary") + Op);
-      assert(F && "binary operator not found!");
-
-      Value *Ops[2] = { L, R };
-      return Builder.CreateCall(F, Ops, "binop");
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-BinaryExprAST-codegen
+  :end-before: chapter6-BinaryExprAST-codegen
 
 As you can see above, the new code is actually really simple. It just
 does a lookup for the appropriate operator in the symbol table and
 generates a function call to it. Since user-defined operators are just
 built as normal functions (because the "prototype" boils down to a
 function with the right name) everything falls into place.
 
 The final piece of code we are missing, is a bit of top-level magic:
 
-.. code-block:: c++
-
-    Function *FunctionAST::codegen() {
-      // Transfer ownership of the prototype to the FunctionProtos map, but keep a
-      // reference to it for use below.
-      auto &P = *Proto;
-      FunctionProtos[Proto->getName()] = std::move(Proto);
-      Function *TheFunction = getFunction(P.getName());
-      if (!TheFunction)
-        return nullptr;
-
-      // If this is an operator, install it.
-      if (P.isBinaryOp())
-        BinopPrecedence[P.getOperatorName()] = P.getBinaryPrecedence();
-
-      // Create a new basic block to start insertion into.
-      BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
-      ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-FunctionAST-codegen
+  :end-before: chapter6-FunctionAST-codegen
 
 Basically, before codegening a function, if it is a user-defined
 operator, we register it in the precedence table. This allows the binary
 operator parsing logic we already have in place to handle it. Since we
 are working on a fully-general operator precedence parser, this is all
 we need to do to "extend the grammar".
 
 Now we have useful user-defined binary operators. This builds a lot on
 the previous framework we built for other operators. Adding unary
 operators is a bit more challenging, because we don't have any framework
 for it yet - lets see what it takes.
 
 User-defined Unary Operators
 ============================
 
 Since we don't currently support unary operators in the Kaleidoscope
 language, we'll need to add everything to support them. Above, we added
 simple support for the 'unary' keyword to the lexer. In addition to
 that, we need an AST node:
 
-.. code-block:: c++
-
-    /// UnaryExprAST - Expression class for a unary operator.
-    class UnaryExprAST : public ExprAST {
-      char Opcode;
-      std::unique_ptr<ExprAST> Operand;
-
-    public:
-      UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)
-        : Opcode(Opcode), Operand(std::move(Operand)) {}
-
-      Value *codegen() override;
-    };
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-UnaryExprAST
+  :end-before: chapter6-UnaryExprAST
 
 This AST node is very simple and obvious by now. It directly mirrors the
 binary operator AST node, except that it only has one child. With this,
 we need to add the parsing logic. Parsing a unary operator is pretty
 simple: we'll add a new function to do it:
 
-.. code-block:: c++
-
-    /// unary
-    ///   ::= primary
-    ///   ::= '!' unary
-    static std::unique_ptr<ExprAST> ParseUnary() {
-      // If the current token is not an operator, it must be a primary expr.
-      if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
-        return ParsePrimary();
-
-      // If this is a unary operator, read it.
-      int Opc = CurTok;
-      getNextToken();
-      if (auto Operand = ParseUnary())
-        return llvm::make_unique<UnaryExprAST>(Opc, std::move(Operand));
-      return nullptr;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-ParseUnary
+  :end-before: chapter6-ParseUnary
 
 The grammar we add is pretty straightforward here. If we see a unary
 operator when parsing a primary operator, we eat the operator as a
 prefix and parse the remaining piece as another unary operator. This
 allows us to handle multiple unary operators (e.g. "!!x"). Note that
 unary operators can't have ambiguous parses like binary operators can,
 so there is no need for precedence information.
 
static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
                                                   std::unique_ptr<ExprAST> LHS) {
       ...
         // Parse the unary expression after the binary operator.
         auto RHS = ParseUnary();
         if (!RHS)
           return nullptr;
       ...
     }
-    /// expression
-    ///   ::= unary binoprhs
-    ///
-    static std::unique_ptr<ExprAST> ParseExpression() {
-      auto LHS = ParseUnary();
-      if (!LHS)
-        return nullptr;
 
-      return ParseBinOpRHS(0, std::move(LHS));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-ParseExpression
+  :end-before: chapter6-ParseExpression
 
 With these two simple changes, we are now able to parse unary operators
 and build the AST for them. Next up, we need to add parser support for
 prototypes, to parse the unary operator prototype. We extend the binary
 operator code above with:
 
-.. code-block:: c++
-
-    /// prototype
-    ///   ::= id '(' id* ')'
-    ///   ::= binary LETTER number? (id, id)
-    ///   ::= unary LETTER (id)
-    static std::unique_ptr<PrototypeAST> ParsePrototype() {
-      std::string FnName;
-
-      unsigned Kind = 0;  // 0 = identifier, 1 = unary, 2 = binary.
-      unsigned BinaryPrecedence = 30;
-
-      switch (CurTok) {
-      default:
-        return LogErrorP("Expected function name in prototype");
-      case tok_identifier:
-        FnName = IdentifierStr;
-        Kind = 0;
-        getNextToken();
-        break;
-      case tok_unary:
-        getNextToken();
-        if (!isascii(CurTok))
-          return LogErrorP("Expected unary operator");
-        FnName = "unary";
-        FnName += (char)CurTok;
-        Kind = 1;
-        getNextToken();
-        break;
-      case tok_binary:
-        ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-ParsePrototype
+  :end-before: chapter6-ParsePrototype
+  :emphasize-lines: 19-27
+  :lines: -28
 
 As with binary operators, we name unary operators with a name that
 includes the operator character. This assists us at code generation
 time. Speaking of, the final piece we need to add is codegen support for
 unary operators. It looks like this:
 
-.. code-block:: c++
-
-    Value *UnaryExprAST::codegen() {
-      Value *OperandV = Operand->codegen();
-      if (!OperandV)
-        return nullptr;
-
-      Function *F = getFunction(std::string("unary") + Opcode);
-      if (!F)
-        return LogErrorV("Unknown unary operator");
-
-      return Builder.CreateCall(F, OperandV, "unop");
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter6/toy.cpp
+  :language: c++
+  :start-after: chapter6-UnaryExprAST-codegen
+  :end-before: chapter6-UnaryExprAST-codegen
 
 This code is similar to, but simpler than, the code for binary
 operators. It is simpler primarily because it doesn't need to handle any
 predefined operators.
 
 Kicking the Tires
 =================
 

docs/tutorial/LangImpl07.rst

 .. code-block:: c++
 
     static std::map<std::string, AllocaInst*> NamedValues;
 
 Also, since we will need to create these allocas, we'll use a helper
 function that ensures that the allocas are created in the entry block of
 the function:
 
-.. code-block:: c++
-
-    /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
-    /// the function.  This is used for mutable variables etc.
-    static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
-                                              const std::string &VarName) {
-      IRBuilder<> TmpB(&TheFunction->getEntryBlock(),
-                     TheFunction->getEntryBlock().begin());
-      return TmpB.CreateAlloca(Type::getDoubleTy(TheContext), 0,
-                               VarName.c_str());
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-CreateEntryBlockAlloca
+  :end-before: chapter7-CreateEntryBlockAlloca
 
 This funny looking code creates an IRBuilder object that is pointing at
 the first instruction (.begin()) of the entry block. It then creates an
 alloca with the expected name and returns it. Because all values in
 Kaleidoscope are doubles, there is no need to pass in a type to use.
 
 With this in place, the first functionality change we want to make belongs to
 variable references. In our new scheme, variables live on the stack, so
 code generating a reference to them actually needs to produce a load
 from the stack slot:
 
-.. code-block:: c++
-
-    Value *VariableExprAST::codegen() {
-      // Look this variable up in the function.
-      Value *V = NamedValues[Name];
-      if (!V)
-        return LogErrorV("Unknown variable name");
-
-      // Load the value.
-      return Builder.CreateLoad(V, Name.c_str());
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-VariableExprAST-codegen
+  :end-before: chapter7-VariableExprAST-codegen
 
 As you can see, this is pretty straightforward. Now we need to update
 the things that define the variables to set up the alloca. We'll start
 with ``ForExprAST::codegen()`` (see the `full code listing <#id1>`_ for
 the unabridged code):
 
-.. code-block:: c++
-
-      Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
-      // Create an alloca for the variable in the entry block.
-      AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
-
-      // Emit the start code first, without 'variable' in scope.
-      Value *StartVal = Start->codegen();
-      if (!StartVal)
-        return nullptr;
-
-      // Store the value into the alloca.
-      Builder.CreateStore(StartVal, Alloca);
-      ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-ForExprAST-codegen1
+  :end-before: chapter7-ForExprAST-codegen1
+  :dedent: 2
 
-      // Compute the end condition.
-      Value *EndCond = End->codegen();
-      if (!EndCond)
-        return nullptr;
-
-      // Reload, increment, and restore the alloca.  This handles the case where
-      // the body of the loop mutates the variable.
-      Value *CurVar = Builder.CreateLoad(Alloca);
-      Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
-      Builder.CreateStore(NextVar, Alloca);
-      ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-ForExprAST-codegen2
+  :end-before: chapter7-ForExprAST-codegen2
+  :dedent: 2
 
 This code is virtually identical to the code `before we allowed mutable
 variables <LangImpl5.html#code-generation-for-the-for-loop>`_. The big difference is that we
 no longer have to construct a PHI node, and we use load/store to access
 the variable as needed.
 
 To support mutable argument variables, we need to also make allocas for
 them. The code for this is also pretty simple:
 
-.. code-block:: c++
-
-    Function *FunctionAST::codegen() {
-      ...
-      Builder.SetInsertPoint(BB);
-
-      // Record the function arguments in the NamedValues map.
-      NamedValues.clear();
-      for (auto &Arg : TheFunction->args()) {
-        // Create an alloca for this variable.
-        AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, Arg.getName());
-
-        // Store the initial value into the alloca.
-        Builder.CreateStore(&Arg, Alloca);
-
-        // Add arguments to variable symbol table.
-        NamedValues[Arg.getName()] = Alloca;
-      }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-FunctionAST-codegen1
+  :end-before: chapter7-FunctionAST-codegen1
 
-      if (Value *RetVal = Body->codegen()) {
-        ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-FunctionAST-codegen2
+  :end-before: chapter7-FunctionAST-codegen2
 
 For each argument, we make an alloca, store the input value to the
 function into the alloca, and register the alloca as the memory location
 for the argument. This method gets invoked by ``FunctionAST::codegen()``
 right after it sets up the entry block for the function.
 
 The final missing piece is adding the mem2reg pass, which allows us to
 get good codegen once again:
 
-.. code-block:: c++
-
-        // Promote allocas to registers.
-        TheFPM->add(createPromoteMemoryToRegisterPass());
-        // Do simple "peephole" optimizations and bit-twiddling optzns.
-        TheFPM->add(createInstructionCombiningPass());
-        // Reassociate expressions.
-        TheFPM->add(createReassociatePass());
-        ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-passes
+  :end-before: chapter7-passes
+  :emphasize-lines: 1-2
+  :dedent: 2
 
 It is interesting to see what the code looks like before and after the
 mem2reg optimization runs. For example, this is the before/after code
 for our recursive fib function. Before the optimization:
 
 .. code-block:: llvm
 
     define double @fib(double %x) {
int main() {
        BinopPrecedence['<'] = 10;
        BinopPrecedence['+'] = 20;
        BinopPrecedence['-'] = 20;
 
 Now that the parser knows the precedence of the binary operator, it
 takes care of all the parsing and AST generation. We just need to
 implement codegen for the assignment operator. This looks like:
 
-.. code-block:: c++
-
-    Value *BinaryExprAST::codegen() {
-      // Special case '=' because we don't want to emit the LHS as an expression.
-      if (Op == '=') {
-        // Assignment requires the LHS to be an identifier.
-        VariableExprAST *LHSE = dynamic_cast<VariableExprAST*>(LHS.get());
-        if (!LHSE)
-          return LogErrorV("destination of '=' must be a variable");
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-BinaryExprAST-codegen1
+  :end-before: chapter7-BinaryExprAST-codegen1
 
 Unlike the rest of the binary operators, our assignment operator doesn't
 follow the "emit LHS, emit RHS, do computation" model. As such, it is
 handled as a special case before the other binary operators are handled.
 The other strange thing is that it requires the LHS to be a variable. It
 is invalid to have "(x+1) = expr" - only things like "x = expr" are
 allowed.
 
-.. code-block:: c++
-
-        // Codegen the RHS.
-        Value *Val = RHS->codegen();
-        if (!Val)
-          return nullptr;
-
-        // Look up the name.
-        Value *Variable = NamedValues[LHSE->getName()];
-        if (!Variable)
-          return LogErrorV("Unknown variable name");
-
-        Builder.CreateStore(Val, Variable);
-        return Val;
-      }
-      ...
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-BinaryExprAST-codegen2
+  :end-before: chapter7-BinaryExprAST-codegen2
+  :dedent: 2
 
 Once we have the variable, codegen'ing the assignment is
 straightforward: we emit the RHS of the assignment, create a store, and
 return the computed value. Returning a value allows for chained
 assignments like "X = (Y = Z)".
 
 Now that we have an assignment operator, we can mutate loop variables
 and arguments. For example, we can now run code like this:
...
         if (IdentifierStr == "var")
           return tok_var;
         return tok_identifier;
     ...
 
 The next step is to define the AST node that we will construct. For
 var/in, it looks like this:
 
-.. code-block:: c++
-
-    /// VarExprAST - Expression class for var/in
-    class VarExprAST : public ExprAST {
-      std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
-      std::unique_ptr<ExprAST> Body;
-
-    public:
-      VarExprAST(std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,
-                 std::unique_ptr<ExprAST> Body)
-        : VarNames(std::move(VarNames)), Body(std::move(Body)) {}
-
-      Value *codegen() override;
-    };
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-VarExprAST
+  :end-before: chapter7-VarExprAST
 
 var/in allows a list of names to be defined all at once, and each name
 can optionally have an initializer value. As such, we capture this
 information in the VarNames vector. Also, var/in has a body, this body
 is allowed to access the variables defined by the var/in.
 
 With this in place, we can define the parser pieces. The first thing we
 do is add it as a primary expression:
 
-.. code-block:: c++
-
-    /// primary
-    ///   ::= identifierexpr
-    ///   ::= numberexpr
-    ///   ::= parenexpr
-    ///   ::= ifexpr
-    ///   ::= forexpr
-    ///   ::= varexpr
-    static std::unique_ptr<ExprAST> ParsePrimary() {
-      switch (CurTok) {
-      default:
-        return LogError("unknown token when expecting an expression");
-      case tok_identifier:
-        return ParseIdentifierExpr();
-      case tok_number:
-        return ParseNumberExpr();
-      case '(':
-        return ParseParenExpr();
-      case tok_if:
-        return ParseIfExpr();
-      case tok_for:
-        return ParseForExpr();
-      case tok_var:
-        return ParseVarExpr();
-      }
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-ParsePrimary
+  :end-before: chapter7-ParsePrimary
+  :emphasize-lines: 22-23
 
 Next we define ParseVarExpr:
 
-.. code-block:: c++
-
-    /// varexpr ::= 'var' identifier ('=' expression)?
-    //                    (',' identifier ('=' expression)?)* 'in' expression
-    static std::unique_ptr<ExprAST> ParseVarExpr() {
-      getNextToken();  // eat the var.
-
-      std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
-
-      // At least one variable name is required.
-      if (CurTok != tok_identifier)
-        return LogError("expected identifier after var");
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-ParseVarExpr1
+  :end-before: chapter7-ParseVarExpr1
 
 The first part of this code parses the list of identifier/expr pairs
 into the local ``VarNames`` vector.
 
-.. code-block:: c++
-
-      while (1) {
-        std::string Name = IdentifierStr;
-        getNextToken();  // eat identifier.
-
-        // Read the optional initializer.
-        std::unique_ptr<ExprAST> Init;
-        if (CurTok == '=') {
-          getNextToken(); // eat the '='.
-
-          Init = ParseExpression();
-          if (!Init) return nullptr;
-        }
-
-        VarNames.push_back(std::make_pair(Name, std::move(Init)));
-
-        // End of var list, exit loop.
-        if (CurTok != ',') break;
-        getNextToken(); // eat the ','.
-
-        if (CurTok != tok_identifier)
-          return LogError("expected identifier list after var");
-      }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-ParseVarExpr2
+  :end-before: chapter7-ParseVarExpr2
+  :dedent: 2
 
 Once all the variables are parsed, we then parse the body and create the
 AST node:
 
-.. code-block:: c++
-
-      // At this point, we have to have 'in'.
-      if (CurTok != tok_in)
-        return LogError("expected 'in' keyword after 'var'");
-      getNextToken();  // eat 'in'.
-
-      auto Body = ParseExpression();
-      if (!Body)
-        return nullptr;
-
-      return llvm::make_unique<VarExprAST>(std::move(VarNames),
-                                           std::move(Body));
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-ParseVarExpr3
+  :end-before: chapter7-ParseVarExpr3
 
 Now that we can parse and represent the code, we need to support
 emission of LLVM IR for it. This code starts out with:
 
-.. code-block:: c++
-
-    Value *VarExprAST::codegen() {
-      std::vector<AllocaInst *> OldBindings;
-
-      Function *TheFunction = Builder.GetInsertBlock()->getParent();
-
-      // Register all variables and emit their initializer.
-      for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
-        const std::string &VarName = VarNames[i].first;
-        ExprAST *Init = VarNames[i].second.get();
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-VarExprAST-codegen1
+  :end-before: chapter7-VarExprAST-codegen1
 
 Basically it loops over all the variables, installing them one at a
 time. For each variable we put into the symbol table, we remember the
 previous value that we replace in OldBindings.
 
-.. code-block:: c++
-
-        // Emit the initializer before adding the variable to scope, this prevents
-        // the initializer from referencing the variable itself, and permits stuff
-        // like this:
-        //  var a = 1 in
-        //    var a = a in ...   # refers to outer 'a'.
-        Value *InitVal;
-        if (Init) {
-          InitVal = Init->codegen();
-          if (!InitVal)
-            return nullptr;
-        } else { // If not specified, use 0.0.
-          InitVal = ConstantFP::get(TheContext, APFloat(0.0));
-        }
-
-        AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
-        Builder.CreateStore(InitVal, Alloca);
-
-        // Remember the old variable binding so that we can restore the binding when
-        // we unrecurse.
-        OldBindings.push_back(NamedValues[VarName]);
-
-        // Remember this binding.
-        NamedValues[VarName] = Alloca;
-      }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-VarExprAST-codegen2
+  :end-before: chapter7-VarExprAST-codegen2
+  :dedent: 2
 
 There are more comments here than code. The basic idea is that we emit
 the initializer, create the alloca, then update the symbol table to
 point to it. Once all the variables are installed in the symbol table,
 we evaluate the body of the var/in expression:
 
-.. code-block:: c++
-
-      // Codegen the body, now that all vars are in scope.
-      Value *BodyVal = Body->codegen();
-      if (!BodyVal)
-        return nullptr;
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-VarExprAST-codegen3
+  :end-before: chapter7-VarExprAST-codegen3
+  :dedent: 2
 
 Finally, before returning, we restore the previous variable bindings:
 
-.. code-block:: c++
-
-      // Pop all our variables from scope.
-      for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
-        NamedValues[VarNames[i].first] = OldBindings[i];
-
-      // Return the body computation.
-      return BodyVal;
-    }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter7/toy.cpp
+  :language: c++
+  :start-after: chapter7-VarExprAST-codegen4
+  :end-before: chapter7-VarExprAST-codegen4
 
 The end result of all of this is that we get properly scoped variable
 definitions, and we even (trivially) allow mutation of them :).
 
 With this, we completed what we set out to do. Our nice iterative fib
 example from the intro compiles and runs just fine. The mem2reg pass
 optimizes all of our stack variables into SSA registers, inserting PHI
 nodes where needed, and our front-end remains simple: no "iterated

docs/tutorial/LangImpl08.rst

 
 Running this command may show something different on your machine as
 you might be using a different architecture or operating system to me.
 
 Fortunately, we don't need to hard-code a target triple to target the
 current machine. LLVM provides ``sys::getDefaultTargetTriple``, which
 returns the target triple of the current machine.
 
-.. code-block:: c++
-
-    auto TargetTriple = sys::getDefaultTargetTriple();
+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
+  :language: c++
+  :start-after: chapter8-TargetTriple
+  :end-before: chapter8-TargetTriple
+  :dedent: 2
 
 LLVM doesn't require us to link in all the target
 functionality. For example, if we're just using the JIT, we don't need
 the assembly printers. Similarly, if we're only targeting certain
 architectures, we can only link in the functionality for those
 architectures.
 
 For this example, we'll initialize all the targets for emitting object
 code.
 
-.. code-block:: c++
-
-    InitializeAllTargetInfos();
-    InitializeAllTargets();
-    InitializeAllTargetMCs();
-    InitializeAllAsmParsers();
-    InitializeAllAsmPrinters();
+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
+  :language: c++
+  :start-after: chapter8-initialize
+  :end-before: chapter8-initialize
+  :dedent: 2
 
 We can now use our target triple to get a ``Target``:
 
-.. code-block:: c++
-
-  std::string Error;
-  auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);
-
-  // Print an error and exit if we couldn't find the requested target.
-  // This generally occurs if we've forgotten to initialise the
-  // TargetRegistry or we have a bogus target triple.
-  if (!Target) {
-    errs() << Error;
-    return 1;
-  }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
+  :language: c++
+  :start-after: chapter8-lookup
+  :end-before: chapter8-lookup
+  :dedent: 2
 
 Target Machine
 ==============
 
 We will also need a ``TargetMachine``. This class provides a complete
 machine description of the machine we're targeting. If we want to
 target a specific feature (such as SSE) or a specific CPU (such as
 Intel's Sandylake), we do so now.
Available features for this target:
       32bit-mode            - 32-bit mode (80386).
       3dnow                 - Enable 3DNow! instructions.
       3dnowa                - Enable 3DNow! Athlon instructions.
       ...
 
 For our example, we'll use the generic CPU without any additional
 features, options or relocation model.
 
-.. code-block:: c++
-
-  auto CPU = "generic";
-  auto Features = "";
-
-  TargetOptions opt;
-  auto RM = Optional<Reloc::Model>();
-  auto TargetMachine = Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);
+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
+  :language: c++
+  :start-after: chapter8-target-machine
+  :end-before: chapter8-target-machine
+  :dedent: 2
 
 
 Configuring the Module
 ======================
 
 We're now ready to configure our module, to specify the target and
 data layout. This isn't strictly necessary, but the `frontend
 performance guide <../Frontend/PerformanceTips.html>`_ recommends
 this. Optimizations benefit from knowing about the target and data
 layout.
 
-.. code-block:: c++
-
-  TheModule->setDataLayout(TargetMachine->createDataLayout());
-  TheModule->setTargetTriple(TargetTriple);   
-  
+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
+  :language: c++
+  :start-after: chapter8-module
+  :end-before: chapter8-module
+  :dedent: 2
 Emit Object Code
 ================
 
 We're ready to emit object code! Let's define where we want to write
 our file to:
 
-.. code-block:: c++
-
-  auto Filename = "output.o";
-  std::error_code EC;
-  raw_fd_ostream dest(Filename, EC, sys::fs::F_None);
-
-  if (EC) {
-    errs() << "Could not open file: " << EC.message();
-    return 1;
-  }
+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
+  :language: c++
+  :start-after: chapter8-emit
+  :end-before: chapter8-emit
+  :dedent: 2
 
 Finally, we define a pass that emits object code, then we run that
 pass:
 
-.. code-block:: c++
-
-  legacy::PassManager pass;
-  auto FileType = TargetMachine::CGFT_ObjectFile;
-
-  if (TargetMachine->addPassesToEmitFile(pass, dest, FileType)) {
-    errs() << "TargetMachine can't emit a file of this type";
-    return 1;
-  }
-
-  pass.run(*TheModule);
-  dest.flush();
+.. literalinclude:: /../examples/Kaleidoscope/Chapter8/toy.cpp
+  :language: c++
+  :start-after: chapter8-pass
+  :end-before: chapter8-pass
+  :dedent: 2
 
 Putting It All Together
 =======================
 
 Does it work? Let's give it a try. We need to compile our code, but
 note that the arguments to ``llvm-config`` are different to the previous chapters.
 
 ::

examples/Kaleidoscope/Chapter2/toy.cpp

 #include "llvm/ADT/STLExtras.h"
 #include <algorithm>
 #include <cctype>
 #include <cstdio>
 #include <cstdlib>
 #include <map>
 #include <memory>
 #include <string>
 #include <vector>
 
 //===----------------------------------------------------------------------===//
 // Lexer
 //===----------------------------------------------------------------------===//
 
+/// [chapter1-token]
 // The lexer returns tokens [0-255] if it is an unknown character, otherwise one
 // of these for known things.
 enum Token {
   tok_eof = -1,
 
   // commands
   tok_def = -2,
   tok_extern = -3,
 
   // primary
   tok_identifier = -4,
   tok_number = -5
 };
 
 static std::string IdentifierStr; // Filled in if tok_identifier
 static double NumVal;             // Filled in if tok_number
+/// [chapter1-token]
 
+/// [chapter1-gettok1]
 /// gettok - Return the next token from standard input.
 static int gettok() {
   static int LastChar = ' ';
 
   // Skip any whitespace.
   while (isspace(LastChar))
     LastChar = getchar();
+  /// [chapter1-gettok1]
 
+  /// [chapter1-gettok2]
   if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
     IdentifierStr = LastChar;
     while (isalnum((LastChar = getchar())))
       IdentifierStr += LastChar;
 
     if (IdentifierStr == "def")
       return tok_def;
     if (IdentifierStr == "extern")
       return tok_extern;
     return tok_identifier;
   }
+  /// [chapter1-gettok2]
 
+  /// [chapter1-gettok3]
   if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
     std::string NumStr;
     do {
       NumStr += LastChar;
       LastChar = getchar();
     } while (isdigit(LastChar) || LastChar == '.');
 
     NumVal = strtod(NumStr.c_str(), nullptr);
     return tok_number;
   }
+  /// [chapter1-gettok3]
 
+  /// [chapter1-gettok4]
   if (LastChar == '#') {
     // Comment until end of line.
     do
       LastChar = getchar();
     while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
 
     if (LastChar != EOF)
       return gettok();
   }
+  /// [chapter1-gettok4]
 
+  /// [chapter1-gettok5]
   // Check for end of file.  Don't eat the EOF.
   if (LastChar == EOF)
     return tok_eof;
 
   // Otherwise, just return the character as its ascii value.
   int ThisChar = LastChar;
   LastChar = getchar();
   return ThisChar;
 }
+/// [chapter1-gettok5]
 
 //===----------------------------------------------------------------------===//
 // Abstract Syntax Tree (aka Parse Tree)
 //===----------------------------------------------------------------------===//
 
 namespace {
 
+/// [chapter2-ExprAST]
 /// ExprAST - Base class for all expression nodes.
 class ExprAST {
 public:
   virtual ~ExprAST() = default;
 };
 
 /// NumberExprAST - Expression class for numeric literals like "1.0".
 class NumberExprAST : public ExprAST {
   double Val;
 
 public:
   NumberExprAST(double Val) : Val(Val) {}
 };
+/// [chapter2-ExprAST]
 
+/// [chapter2-VariableExprAST]
 /// VariableExprAST - Expression class for referencing a variable, like "a".
 class VariableExprAST : public ExprAST {
   std::string Name;
 
 public:
   VariableExprAST(const std::string &Name) : Name(Name) {}
 };
 
class CallExprAST : public ExprAST {
   std::string Callee;
   std::vector<std::unique_ptr<ExprAST>> Args;
 
 public:
   CallExprAST(const std::string &Callee,
               std::vector<std::unique_ptr<ExprAST>> Args)
       : Callee(Callee), Args(std::move(Args)) {}
 };
+/// [chapter2-VariableExprAST]
 
+/// [chapter2-PrototypeAST]
 /// PrototypeAST - This class represents the "prototype" for a function,
 /// which captures its name, and its argument names (thus implicitly the number
 /// of arguments the function takes).
 class PrototypeAST {
   std::string Name;
   std::vector<std::string> Args;
 
 public:
   PrototypeAST(const std::string &Name, std::vector<std::string> Args)
       : Name(Name), Args(std::move(Args)) {}
 
   const std::string &getName() const { return Name; }
 };
 
 /// FunctionAST - This class represents a function definition itself.
 class FunctionAST {
   std::unique_ptr<PrototypeAST> Proto;
   std::unique_ptr<ExprAST> Body;
 
 public:
   FunctionAST(std::unique_ptr<PrototypeAST> Proto,
               std::unique_ptr<ExprAST> Body)
       : Proto(std::move(Proto)), Body(std::move(Body)) {}
 };
+/// [chapter2-PrototypeAST]
 
 } // end anonymous namespace
 
 //===----------------------------------------------------------------------===//
 // Parser
 //===----------------------------------------------------------------------===//
 
+/// [chapter2-CurTok]
 /// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
 /// token the parser is looking at.  getNextToken reads another token from the
 /// lexer and updates CurTok with its results.
 static int CurTok;
 static int getNextToken() { return CurTok = gettok(); }
+/// [chapter2-CurTok]
 
+/// [chapter2-BinopPrecedence]
 /// BinopPrecedence - This holds the precedence for each binary operator that is
 /// defined.
 static std::map<char, int> BinopPrecedence;
 
 /// GetTokPrecedence - Get the precedence of the pending binary operator token.
 static int GetTokPrecedence() {
   if (!isascii(CurTok))
     return -1;
 
   // Make sure it's a declared binop.
   int TokPrec = BinopPrecedence[CurTok];
   if (TokPrec <= 0)
     return -1;
   return TokPrec;
 }
+/// [chapter2-BinopPrecedence]
 
+/// [chapter2-logging]
 /// LogError* - These are little helper functions for error handling.
 std::unique_ptr<ExprAST> LogError(const char *Str) {
   fprintf(stderr, "Error: %s\n", Str);
   return nullptr;
 }
 std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {
   LogError(Str);
   return nullptr;
 }
+/// [chapter2-logging]
 
 static std::unique_ptr<ExprAST> ParseExpression();
 
+/// [chapter2-ParseNumberExpr]
 /// numberexpr ::= number
 static std::unique_ptr<ExprAST> ParseNumberExpr() {
   auto Result = llvm::make_unique<NumberExprAST>(NumVal);
   getNextToken(); // consume the number
   return std::move(Result);
 }
+/// [chapter2-ParseNumberExpr]
 
+/// [chapter2-ParseParenExpr]
 /// parenexpr ::= '(' expression ')'
 static std::unique_ptr<ExprAST> ParseParenExpr() {
   getNextToken(); // eat (.
   auto V = ParseExpression();
   if (!V)
     return nullptr;
 
   if (CurTok != ')')
     return LogError("expected ')'");
   getNextToken(); // eat ).
   return V;
 }
+/// [chapter2-ParseParenExpr]
 
+/// [chapter2-ParseIdentifierExpr]
 /// identifierexpr
 ///   ::= identifier
 ///   ::= identifier '(' expression* ')'
 static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
   std::string IdName = IdentifierStr;
 
   getNextToken(); // eat identifier.
 
if (CurTok != ')') {
     }
   }
 
   // Eat the ')'.
   getNextToken();
 
   return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
 }
+/// [chapter2-ParseIdentifierExpr]
 
+/// [chapter2-ParsePrimary]
 /// primary
 ///   ::= identifierexpr
 ///   ::= numberexpr
 ///   ::= parenexpr
 static std::unique_ptr<ExprAST> ParsePrimary() {
   switch (CurTok) {
   default:
     return LogError("unknown token when expecting an expression");
   case tok_identifier:
     return ParseIdentifierExpr();
   case tok_number:
     return ParseNumberExpr();
   case '(':
     return ParseParenExpr();
   }
 }
+/// [chapter2-ParsePrimary]
 
+/// [chapter2-ParseBinOpRHS1]
 /// binoprhs
 ///   ::= ('+' primary)*
 static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
                                               std::unique_ptr<ExprAST> LHS) {
   // If this is a binop, find its precedence.
   while (true) {
     int TokPrec = GetTokPrecedence();
 
     // If this is a binop that binds at least as tightly as the current binop,
     // consume it, otherwise we are done.
     if (TokPrec < ExprPrec)
       return LHS;
+    /// [chapter2-ParseBinOpRHS1]
 
+    /// [chapter2-ParseBinOpRHS2]
     // Okay, we know this is a binop.
     int BinOp = CurTok;
     getNextToken(); // eat binop
 
     // Parse the primary expression after the binary operator.
     auto RHS = ParsePrimary();
     if (!RHS)
       return nullptr;
+    /// [chapter2-ParseBinOpRHS2]
 
+    /// [chapter2-ParseBinOpRHS3]
     // If BinOp binds less tightly with RHS than the operator after RHS, let
     // the pending operator take RHS as its LHS.
     int NextPrec = GetTokPrecedence();
     if (TokPrec < NextPrec) {
       RHS = ParseBinOpRHS(TokPrec + 1, std::move(RHS));
       if (!RHS)
         return nullptr;
     }
 
     // Merge LHS/RHS.
     LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
                                            std::move(RHS));
   }
 }
+/// [chapter2-ParseBinOpRHS3]
 
+/// [chapter2-ParseExpression]
 /// expression
 ///   ::= primary binoprhs
 ///
 static std::unique_ptr<ExprAST> ParseExpression() {
   auto LHS = ParsePrimary();
   if (!LHS)
     return nullptr;
 
   return ParseBinOpRHS(0, std::move(LHS));
 }
+/// [chapter2-ParseExpression]
 
+/// [chapter2-ParsePrototype]
 /// prototype
 ///   ::= id '(' id* ')'
 static std::unique_ptr<PrototypeAST> ParsePrototype() {
   if (CurTok != tok_identifier)
     return LogErrorP("Expected function name in prototype");
 
   std::string FnName = IdentifierStr;
   getNextToken();
 
   if (CurTok != '(')
     return LogErrorP("Expected '(' in prototype");
 
   std::vector<std::string> ArgNames;
   while (getNextToken() == tok_identifier)
     ArgNames.push_back(IdentifierStr);
   if (CurTok != ')')
     return LogErrorP("Expected ')' in prototype");
 
   // success.
   getNextToken(); // eat ')'.
 
   return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));
 }
+/// [chapter2-ParsePrototype]
 
+/// [chapter2-ParseDefinition]
 /// definition ::= 'def' prototype expression
 static std::unique_ptr<FunctionAST> ParseDefinition() {
   getNextToken(); // eat def.
   auto Proto = ParsePrototype();
   if (!Proto)
     return nullptr;
 
   if (auto E = ParseExpression())
     return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
   return nullptr;
 }
+/// [chapter2-ParseDefinition]
 
+/// [chapter2-ParseTopLevelExpr]
 /// toplevelexpr ::= expression
 static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
   if (auto E = ParseExpression()) {
     // Make an anonymous proto.
     auto Proto = llvm::make_unique<PrototypeAST>("__anon_expr",
                                                  std::vector<std::string>());
     return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
   }
   return nullptr;
 }
+/// [chapter2-ParseTopLevelExpr]
 
+/// [chapter2-ParseExtern]
 /// external ::= 'extern' prototype
 static std::unique_ptr<PrototypeAST> ParseExtern() {
   getNextToken(); // eat extern.
   return ParsePrototype();
 }
+/// [chapter2-ParseExtern]
 
 //===----------------------------------------------------------------------===//
 // Top-Level parsing
 //===----------------------------------------------------------------------===//
 
 static void HandleDefinition() {
   if (ParseDefinition()) {
     fprintf(stderr, "Parsed a function definition.\n");
static void HandleTopLevelExpression() {
   if (ParseTopLevelExpr()) {
     fprintf(stderr, "Parsed a top-level expr\n");
   } else {
     // Skip token for error recovery.
     getNextToken();
   }
 }
 
+/// [chapter2-MainLoop]
 /// top ::= definition | external | expression | ';'
 static void MainLoop() {
   while (true) {
     fprintf(stderr, "ready> ");
     switch (CurTok) {
     case tok_eof:
       return;
     case ';': // ignore top-level semicolons.
       getNextToken();
       break;
     case tok_def:
       HandleDefinition();
       break;
     case tok_extern:
       HandleExtern();
       break;
     default:
       HandleTopLevelExpression();
       break;
     }
   }
 }
+/// [chapter2-MainLoop]
 
 //===----------------------------------------------------------------------===//
 // Main driver code.
 //===----------------------------------------------------------------------===//
 
+/// [chapter2-SetBinopPrecedence]
 int main() {
   // Install standard binary operators.
   // 1 is lowest precedence.
   BinopPrecedence['<'] = 10;
   BinopPrecedence['+'] = 20;
   BinopPrecedence['-'] = 20;
   BinopPrecedence['*'] = 40; // highest.
+  /// [chapter2-SetBinopPrecedence]
 
   // Prime the first token.
   fprintf(stderr, "ready> ");
   getNextToken();
 
   // Run the main "interpreter loop" now.
   MainLoop();
 
   return 0;
 }

examples/Kaleidoscope/Chapter3/toy.cpp

 }
 
 //===----------------------------------------------------------------------===//
 // Abstract Syntax Tree (aka Parse Tree)
 //===----------------------------------------------------------------------===//
 
 namespace {
 
+/// [chapter3-ExprAST-codegen]
 /// ExprAST - Base class for all expression nodes.
 class ExprAST {
 public:
   virtual ~ExprAST() = default;
 
   virtual Value *codegen() = 0;
 };
 
 /// NumberExprAST - Expression class for numeric literals like "1.0".
 class NumberExprAST : public ExprAST {
   double Val;
 
 public:
   NumberExprAST(double Val) : Val(Val) {}
 
   Value *codegen() override;
 };
+/// [chapter3-ExprAST-codegen]
 
 /// VariableExprAST - Expression class for referencing a variable, like "a".
 class VariableExprAST : public ExprAST {
   std::string Name;
 
 public:
   VariableExprAST(const std::string &Name) : Name(Name) {}
 
static std::unique_ptr<PrototypeAST> ParseExtern() {
   getNextToken(); // eat extern.
   return ParsePrototype();
 }
 
 //===----------------------------------------------------------------------===//
 // Code Generation
 //===----------------------------------------------------------------------===//
 
+/// [chapter3-globals]
 static LLVMContext TheContext;
 static IRBuilder<> Builder(TheContext);
 static std::unique_ptr<Module> TheModule;
 static std::map<std::string, Value *> NamedValues;
 
 Value *LogErrorV(const char *Str) {
   LogError(Str);
   return nullptr;
 }
+/// [chapter3-globals]
 
+/// [chapter3-NumberExprAST-codegen]
 Value *NumberExprAST::codegen() {
   return ConstantFP::get(TheContext, APFloat(Val));
 }
+/// [chapter3-NumberExprAST-codegen]
 
+/// [chapter3-VariableExprAST-codegen]
 Value *VariableExprAST::codegen() {
   // Look this variable up in the function.
   Value *V = NamedValues[Name];
   if (!V)
     return LogErrorV("Unknown variable name");
   return V;
 }
+/// [chapter3-VariableExprAST-codegen]
 
+/// [chapter3-BinaryExprAST-codegen]
 Value *BinaryExprAST::codegen() {
   Value *L = LHS->codegen();
   Value *R = RHS->codegen();
   if (!L || !R)
     return nullptr;
 
   switch (Op) {
   case '+':
     return Builder.CreateFAdd(L, R, "addtmp");
   case '-':
     return Builder.CreateFSub(L, R, "subtmp");
   case '*':
     return Builder.CreateFMul(L, R, "multmp");
   case '<':
     L = Builder.CreateFCmpULT(L, R, "cmptmp");
     // Convert bool 0/1 to double 0.0 or 1.0
     return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext), "booltmp");
   default:
     return LogErrorV("invalid binary operator");
   }
 }
+/// [chapter3-BinaryExprAST-codegen]
 
+/// [chapter3-CallExprAST-codegen]
 Value *CallExprAST::codegen() {
   // Look up the name in the global module table.
   Function *CalleeF = TheModule->getFunction(Callee);
   if (!CalleeF)
     return LogErrorV("Unknown function referenced");
 
   // If argument mismatch error.
   if (CalleeF->arg_size() != Args.size())
     return LogErrorV("Incorrect # arguments passed");
 
   std::vector<Value *> ArgsV;
   for (unsigned i = 0, e = Args.size(); i != e; ++i) {
     ArgsV.push_back(Args[i]->codegen());
     if (!ArgsV.back())
       return nullptr;
   }
 
   return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
 }
+/// [chapter3-CallExprAST-codegen]
 
+/// [chapter3-PrototypeAST-codegen1]
 Function *PrototypeAST::codegen() {
   // Make the function type:  double(double,double) etc.
   std::vector<Type *> Doubles(Args.size(), Type::getDoubleTy(TheContext));
   FunctionType *FT =
       FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
 
   Function *F =
       Function::Create(FT, Function::ExternalLinkage, Name, TheModule.get());
+  /// [chapter3-PrototypeAST-codegen1]
 
+  /// [chapter3-PrototypeAST-codegen2]
   // Set names for all arguments.
   unsigned Idx = 0;
   for (auto &Arg : F->args())
     Arg.setName(Args[Idx++]);
 
   return F;
 }
+/// [chapter3-PrototypeAST-codegen2]
 
+/// [chapter3-FunctionAST-codegen1]
 Function *FunctionAST::codegen() {
   // First, check for an existing function from a previous 'extern' declaration.
   Function *TheFunction = TheModule->getFunction(Proto->getName());
 
   if (!TheFunction)
     TheFunction = Proto->codegen();
 
   if (!TheFunction)
     return nullptr;
 
+  /// [chapter3-FunctionAST-codegen1]
+  /// [chapter3-FunctionAST-codegen2]
   // Create a new basic block to start insertion into.
   BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
   Builder.SetInsertPoint(BB);
 
   // Record the function arguments in the NamedValues map.
   NamedValues.clear();
   for (auto &Arg : TheFunction->args())
     NamedValues[Arg.getName()] = &Arg;
+  /// [chapter3-FunctionAST-codegen2]
 
+  /// [chapter3-FunctionAST-codegen3]
   if (Value *RetVal = Body->codegen()) {
     // Finish off the function.
     Builder.CreateRet(RetVal);
 
     // Validate the generated code, checking for consistency.
     verifyFunction(*TheFunction);
 
     return TheFunction;
   }
+  /// [chapter3-FunctionAST-codegen3]
 
+  /// [chapter3-FunctionAST-codegen4]
   // Error reading body, remove function.
   TheFunction->eraseFromParent();
   return nullptr;
 }
+/// [chapter3-FunctionAST-codegen4]
 
 //===----------------------------------------------------------------------===//
 // Top-Level parsing and JIT Driver
 //===----------------------------------------------------------------------===//
 
 static void HandleDefinition() {
   if (auto FnAST = ParseDefinition()) {
     if (auto *FnIR = FnAST->codegen()) {

examples/Kaleidoscope/Chapter4/toy.cpp

 // Code Generation
 //===----------------------------------------------------------------------===//
 
 static LLVMContext TheContext;
 static IRBuilder<> Builder(TheContext);
 static std::unique_ptr<Module> TheModule;
 static std::map<std::string, Value *> NamedValues;
 static std::unique_ptr<legacy::FunctionPassManager> TheFPM;
+/// [chapter4-TheJIT]
 static std::unique_ptr<KaleidoscopeJIT> TheJIT;
+/// [chapter4-TheJIT]
 static std::map<std::string, std::unique_ptr<PrototypeAST>> FunctionProtos;
 
 Value *LogErrorV(const char *Str) {
   LogError(Str);
   return nullptr;
 }
 
+/// [chapter4-getFunction]
 Function *getFunction(std::string Name) {
   // First, see if the function has already been added to the current module.
   if (auto *F = TheModule->getFunction(Name))
     return F;
 
   // If not, check whether we can codegen the declaration from some existing
   // prototype.
   auto FI = FunctionProtos.find(Name);
   if (FI != FunctionProtos.end())
     return FI->second->codegen();
 
   // If no existing prototype exists, return null.
   return nullptr;
 }
+/// [chapter4-getFunction]
 
 Value *NumberExprAST::codegen() {
   return ConstantFP::get(TheContext, APFloat(Val));
 }
 
 Value *VariableExprAST::codegen() {
   // Look this variable up in the function.
   Value *V = NamedValues[Name];
case '<':
     L = Builder.CreateFCmpULT(L, R, "cmptmp");
     // Convert bool 0/1 to double 0.0 or 1.0
     return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext), "booltmp");
   default:
     return LogErrorV("invalid binary operator");
   }
 }
 
+/// [chapter4-CallExprAST-codegen]
 Value *CallExprAST::codegen() {
   // Look up the name in the global module table.
   Function *CalleeF = getFunction(Callee);
   if (!CalleeF)
     return LogErrorV("Unknown function referenced");
 
   // If argument mismatch error.
   if (CalleeF->arg_size() != Args.size())
     return LogErrorV("Incorrect # arguments passed");
 
   std::vector<Value *> ArgsV;
   for (unsigned i = 0, e = Args.size(); i != e; ++i) {
     ArgsV.push_back(Args[i]->codegen());
     if (!ArgsV.back())
       return nullptr;
   }
 
   return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
 }
+/// [chapter4-CallExprAST-codegen]
 
 Function *PrototypeAST::codegen() {
   // Make the function type:  double(double,double) etc.
   std::vector<Type *> Doubles(Args.size(), Type::getDoubleTy(TheContext));
   FunctionType *FT =
       FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
 
   Function *F =
       Function::Create(FT, Function::ExternalLinkage, Name, TheModule.get());
 
   // Set names for all arguments.
   unsigned Idx = 0;
   for (auto &Arg : F->args())
     Arg.setName(Args[Idx++]);
 
   return F;
 }
 
+/// [chapter4-FunctionAST-codegen]
 Function *FunctionAST::codegen() {
   // Transfer ownership of the prototype to the FunctionProtos map, but keep a
   // reference to it for use below.
   auto &P = *Proto;
   FunctionProtos[Proto->getName()] = std::move(Proto);
   Function *TheFunction = getFunction(P.getName());
   if (!TheFunction)
     return nullptr;
 
   // Create a new basic block to start insertion into.
   BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
   Builder.SetInsertPoint(BB);
 
   // Record the function arguments in the NamedValues map.
   NamedValues.clear();
   for (auto &Arg : TheFunction->args())
     NamedValues[Arg.getName()] = &Arg;
 
+  /// [chapter4-run-passes]
   if (Value *RetVal = Body->codegen()) {
     // Finish off the function.
     Builder.CreateRet(RetVal);
 
     // Validate the generated code, checking for consistency.
     verifyFunction(*TheFunction);
 
     // Run the optimizer on the function.
     TheFPM->run(*TheFunction);
 
     return TheFunction;
   }
+  /// [chapter4-run-passes]
 
   // Error reading body, remove function.
   TheFunction->eraseFromParent();
   return nullptr;
 }
+/// [chapter4-FunctionAST-codegen]
 
 //===----------------------------------------------------------------------===//
 // Top-Level parsing and JIT Driver
 //===----------------------------------------------------------------------===//
 
+/// [chapter4-InitializeModuleAndPassManager]
 static void InitializeModuleAndPassManager() {
   // Open a new module.
   TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
   TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
 
   // Create a new pass manager attached to it.
   TheFPM = llvm::make_unique<legacy::FunctionPassManager>(TheModule.get());
 
   // Do simple "peephole" optimizations and bit-twiddling optzns.
   TheFPM->add(createInstructionCombiningPass());
   // Reassociate expressions.
   TheFPM->add(createReassociatePass());
   // Eliminate Common SubExpressions.
   TheFPM->add(createGVNPass());
   // Simplify the control flow graph (deleting unreachable blocks, etc).
   TheFPM->add(createCFGSimplificationPass());
 
   TheFPM->doInitialization();
 }
+/// [chapter4-InitializeModuleAndPassManager]
 
+/// [chapter4-HandleDefinition+HandleExtern]
 static void HandleDefinition() {
   if (auto FnAST = ParseDefinition()) {
     if (auto *FnIR = FnAST->codegen()) {
       fprintf(stderr, "Read function definition:");
       FnIR->print(errs());
       fprintf(stderr, "\n");
       TheJIT->addModule(std::move(TheModule));
       InitializeModuleAndPassManager();
if (auto *FnIR = ProtoAST->codegen()) {
       fprintf(stderr, "\n");
       FunctionProtos[ProtoAST->getName()] = std::move(ProtoAST);
     }
   } else {
     // Skip token for error recovery.
     getNextToken();
   }
 }
+/// [chapter4-HandleDefinition+HandleExtern]
 
+/// [chapter4-HandleTopLevelExpression]
 static void HandleTopLevelExpression() {
   // Evaluate a top-level expression into an anonymous function.
   if (auto FnAST = ParseTopLevelExpr()) {
     if (FnAST->codegen()) {
       // JIT the module containing the anonymous expression, keeping a handle so
       // we can free it later.
       auto H = TheJIT->addModule(std::move(TheModule));
       InitializeModuleAndPassManager();
if (FnAST->codegen()) {
       // Delete the anonymous expression module from the JIT.
       TheJIT->removeModule(H);
     }
   } else {
     // Skip token for error recovery.
     getNextToken();
   }
 }
+/// [chapter4-HandleTopLevelExpression]
 
 /// top ::= definition | external | expression | ';'
 static void MainLoop() {
   while (true) {
     fprintf(stderr, "ready> ");
     switch (CurTok) {
     case tok_eof:
       return;
while (true) {
     }
   }
 }
 
 //===----------------------------------------------------------------------===//
 // "Library" functions that can be "extern'd" from user code.
 //===----------------------------------------------------------------------===//
 
+/// [chapter4-extern]
 #ifdef LLVM_ON_WIN32
 #define DLLEXPORT __declspec(dllexport)
 #else
 #define DLLEXPORT
 #endif
 
 /// putchard - putchar that takes a double and returns 0.
 extern "C" DLLEXPORT double putchard(double X) {
   fputc((char)X, stderr);
   return 0;
 }
 
 /// printd - printf that takes a double prints it as "%f\n", returning 0.
 extern "C" DLLEXPORT double printd(double X) {
   fprintf(stderr, "%f\n", X);
   return 0;
 }
+/// [chapter4-extern]
 
 //===----------------------------------------------------------------------===//
 // Main driver code.
 //===----------------------------------------------------------------------===//
 
+/// [chapter4-main]
 int main() {
   InitializeNativeTarget();
   InitializeNativeTargetAsmPrinter();
   InitializeNativeTargetAsmParser();
 
   // Install standard binary operators.
   // 1 is lowest precedence.
   BinopPrecedence['<'] = 10;
int main() {
 
   InitializeModuleAndPassManager();
 
   // Run the main "interpreter loop" now.
   MainLoop();
 
   return 0;
 }
+/// [chapter4-main]

examples/Kaleidoscope/Chapter5/toy.cpp

enum Token {
   // commands
   tok_def = -2,
   tok_extern = -3,
 
   // primary
   tok_identifier = -4,
   tok_number = -5,
 
+  /// [chapter5-tokens1]
   // control
   tok_if = -6,
   tok_then = -7,
   tok_else = -8,
   tok_for = -9,
   tok_in = -10
+  /// [chapter5-tokens1]
 };
 
 static std::string IdentifierStr; // Filled in if tok_identifier
 static double NumVal;             // Filled in if tok_number
 
 /// gettok - Return the next token from standard input.
 static int gettok() {
   static int LastChar = ' ';
 
   // Skip any whitespace.
   while (isspace(LastChar))
     LastChar = getchar();
 
   if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
     IdentifierStr = LastChar;
     while (isalnum((LastChar = getchar())))
       IdentifierStr += LastChar;
 
+    /// [chapter5-gettok]
     if (IdentifierStr == "def")
       return tok_def;
     if (IdentifierStr == "extern")
       return tok_extern;
     if (IdentifierStr == "if")
       return tok_if;
     if (IdentifierStr == "then")
       return tok_then;
     if (IdentifierStr == "else")
       return tok_else;
     if (IdentifierStr == "for")
       return tok_for;
     if (IdentifierStr == "in")
       return tok_in;
     return tok_identifier;
+    /// [chapter5-gettok]
   }
 
   if (isdigit(LastChar) || LastChar == '.') { // Number: [0-9.]+
     std::string NumStr;
     do {
       NumStr += LastChar;
       LastChar = getchar();
     } while (isdigit(LastChar) || LastChar == '.');

 public:
   CallExprAST(const std::string &Callee,
               std::vector<std::unique_ptr<ExprAST>> Args)
       : Callee(Callee), Args(std::move(Args)) {}
 
   Value *codegen() override;
 };
 
+/// [chapter5-IfExprAST]
 /// IfExprAST - Expression class for if/then/else.
 class IfExprAST : public ExprAST {
   std::unique_ptr<ExprAST> Cond, Then, Else;
 
 public:
   IfExprAST(std::unique_ptr<ExprAST> Cond, std::unique_ptr<ExprAST> Then,
             std::unique_ptr<ExprAST> Else)
       : Cond(std::move(Cond)), Then(std::move(Then)), Else(std::move(Else)) {}
 
   Value *codegen() override;
 };
+/// [chapter5-IfExprAST]
 
+/// [chapter5-ForExprAST]
 /// ForExprAST - Expression class for for/in.
 class ForExprAST : public ExprAST {
   std::string VarName;
   std::unique_ptr<ExprAST> Start, End, Step, Body;
 
 public:
   ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,
              std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,
              std::unique_ptr<ExprAST> Body)
       : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
         Step(std::move(Step)), Body(std::move(Body)) {}
 
   Value *codegen() override;
 };
+/// [chapter5-ForExprAST]
 
 /// PrototypeAST - This class represents the "prototype" for a function,
 /// which captures its name, and its argument names (thus implicitly the number
 /// of arguments the function takes).
 class PrototypeAST {
   std::string Name;
   std::vector<std::string> Args;
 
static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
   }
 
   // Eat the ')'.
   getNextToken();
 
   return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
 }
 
+/// [chapter5-ParseIfExpr]
 /// ifexpr ::= 'if' expression 'then' expression 'else' expression
 static std::unique_ptr<ExprAST> ParseIfExpr() {
   getNextToken(); // eat the if.
 
   // condition.
   auto Cond = ParseExpression();
   if (!Cond)
     return nullptr;
static std::unique_ptr<ExprAST> ParseIfExpr() {
 
   auto Else = ParseExpression();
   if (!Else)
     return nullptr;
 
   return llvm::make_unique<IfExprAST>(std::move(Cond), std::move(Then),
                                       std::move(Else));
 }
+/// [chapter5-ParseIfExpr]
 
+/// [chapter5-ParseForExpr]
 /// forexpr ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression
 static std::unique_ptr<ExprAST> ParseForExpr() {
   getNextToken(); // eat the for.
 
   if (CurTok != tok_identifier)
     return LogError("expected identifier after for");
 
   std::string IdName = IdentifierStr;
static std::unique_ptr<ExprAST> ParseForExpr() {
 
   auto Body = ParseExpression();
   if (!Body)
     return nullptr;
 
   return llvm::make_unique<ForExprAST>(IdName, std::move(Start), std::move(End),
                                        std::move(Step), std::move(Body));
 }
+/// [chapter5-ParseForExpr]
 
 /// primary
 ///   ::= identifierexpr
 ///   ::= numberexpr
 ///   ::= parenexpr
 ///   ::= ifexpr
 ///   ::= forexpr
+/// [chapter5-ParsePrimary]
 static std::unique_ptr<ExprAST> ParsePrimary() {
   switch (CurTok) {
   default:
     return LogError("unknown token when expecting an expression");
   case tok_identifier:
     return ParseIdentifierExpr();
   case tok_number:
     return ParseNumberExpr();
   case '(':
     return ParseParenExpr();
   case tok_if:
     return ParseIfExpr();
   case tok_for:
     return ParseForExpr();
   }
 }
+/// [chapter5-ParsePrimary]
 
 /// binoprhs
 ///   ::= ('+' primary)*
 static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
                                               std::unique_ptr<ExprAST> LHS) {
   // If this is a binop, find its precedence.
   while (true) {
     int TokPrec = GetTokPrecedence();
for (unsigned i = 0, e = Args.size(); i != e; ++i) {
     ArgsV.push_back(Args[i]->codegen());
     if (!ArgsV.back())
       return nullptr;
   }
 
   return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
 }
 
+/// [chapter5-IfExprAST-codegen1]
 Value *IfExprAST::codegen() {
   Value *CondV = Cond->codegen();
   if (!CondV)
     return nullptr;
 
   // Convert condition to a bool by comparing non-equal to 0.0.
   CondV = Builder.CreateFCmpONE(
       CondV, ConstantFP::get(TheContext, APFloat(0.0)), "ifcond");
+  /// [chapter5-IfExprAST-codegen1]
 
+  /// [chapter5-IfExprAST-codegen2]
   Function *TheFunction = Builder.GetInsertBlock()->getParent();
 
   // Create blocks for the then and else cases.  Insert the 'then' block at the
   // end of the function.
   BasicBlock *ThenBB = BasicBlock::Create(TheContext, "then", TheFunction);
   BasicBlock *ElseBB = BasicBlock::Create(TheContext, "else");
   BasicBlock *MergeBB = BasicBlock::Create(TheContext, "ifcont");
 
   Builder.CreateCondBr(CondV, ThenBB, ElseBB);
+  /// [chapter5-IfExprAST-codegen2]
 
+  /// [chapter5-IfExprAST-codegen3]
   // Emit then value.
   Builder.SetInsertPoint(ThenBB);
 
   Value *ThenV = Then->codegen();
   if (!ThenV)
     return nullptr;
 
   Builder.CreateBr(MergeBB);
   // Codegen of 'Then' can change the current block, update ThenBB for the PHI.
   ThenBB = Builder.GetInsertBlock();
+  /// [chapter5-IfExprAST-codegen3]
 
+  /// [chapter5-IfExprAST-codegen4]
   // Emit else block.
   TheFunction->getBasicBlockList().push_back(ElseBB);
   Builder.SetInsertPoint(ElseBB);
 
   Value *ElseV = Else->codegen();
   if (!ElseV)
     return nullptr;
 
   Builder.CreateBr(MergeBB);
   // Codegen of 'Else' can change the current block, update ElseBB for the PHI.
   ElseBB = Builder.GetInsertBlock();
+  /// [chapter5-IfExprAST-codegen4]
 
+  /// [chapter5-IfExprAST-codegen5]
   // Emit merge block.
   TheFunction->getBasicBlockList().push_back(MergeBB);
   Builder.SetInsertPoint(MergeBB);
   PHINode *PN = Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, "iftmp");
 
   PN->addIncoming(ThenV, ThenBB);
   PN->addIncoming(ElseV, ElseBB);
   return PN;
 }
+/// [chapter5-IfExprAST-codegen5]
 
 // Output for-loop as:
 //   ...
 //   start = startexpr
 //   goto loop
 // loop:
 //   variable = phi [start, loopheader], [nextvariable, loopend]
 //   ...
 //   bodyexpr
 //   ...
 // loopend:
 //   step = stepexpr
 //   nextvariable = variable + step
 //   endcond = endexpr
 //   br endcond, loop, endloop
 // outloop:
+/// [chapter5-ForExprAST-codegen1]
 Value *ForExprAST::codegen() {
   // Emit the start code first, without 'variable' in scope.
   Value *StartVal = Start->codegen();
   if (!StartVal)
     return nullptr;
 
+  /// [chapter5-ForExprAST-codegen1]
+  /// [chapter5-ForExprAST-codegen2]
   // Make the new basic block for the loop header, inserting after current
   // block.
   Function *TheFunction = Builder.GetInsertBlock()->getParent();
   BasicBlock *PreheaderBB = Builder.GetInsertBlock();
   BasicBlock *LoopBB = BasicBlock::Create(TheContext, "loop", TheFunction);
 
   // Insert an explicit fall through from the current block to the LoopBB.
   Builder.CreateBr(LoopBB);
+  /// [chapter5-ForExprAST-codegen2]
 
+  /// [chapter5-ForExprAST-codegen3]
   // Start insertion in LoopBB.
   Builder.SetInsertPoint(LoopBB);
 
   // Start the PHI node with an entry for Start.
   PHINode *Variable =
       Builder.CreatePHI(Type::getDoubleTy(TheContext), 2, VarName);
   Variable->addIncoming(StartVal, PreheaderBB);
+  /// [chapter5-ForExprAST-codegen3]
 
+  /// [chapter5-ForExprAST-codegen4]
   // Within the loop, the variable is defined equal to the PHI node.  If it
   // shadows an existing variable, we have to restore it, so save it now.
   Value *OldVal = NamedValues[VarName];
   NamedValues[VarName] = Variable;
 
   // Emit the body of the loop.  This, like any other expr, can change the
   // current BB.  Note that we ignore the value computed by the body, but don't
   // allow an error.
   if (!Body->codegen())
     return nullptr;
+  /// [chapter5-ForExprAST-codegen4]
 
+  /// [chapter5-ForExprAST-codegen5]
   // Emit the step value.
   Value *StepVal = nullptr;
   if (Step) {
     StepVal = Step->codegen();
     if (!StepVal)
       return nullptr;
   } else {
     // If not specified, use 1.0.
     StepVal = ConstantFP::get(TheContext, APFloat(1.0));
   }
 
   Value *NextVar = Builder.CreateFAdd(Variable, StepVal, "nextvar");
+  /// [chapter5-ForExprAST-codegen5]
 
+  /// [chapter5-ForExprAST-codegen6]
   // Compute the end condition.
   Value *EndCond = End->codegen();
   if (!EndCond)
     return nullptr;
 
   // Convert condition to a bool by comparing non-equal to 0.0.
   EndCond = Builder.CreateFCmpONE(
       EndCond, ConstantFP::get(TheContext, APFloat(0.0)), "loopcond");
+  /// [chapter5-ForExprAST-codegen6]
 
+  /// [chapter5-ForExprAST-codegen7]
   // Create the "after loop" block and insert it.
   BasicBlock *LoopEndBB = Builder.GetInsertBlock();
   BasicBlock *AfterBB =
       BasicBlock::Create(TheContext, "afterloop", TheFunction);
 
   // Insert the conditional branch into the end of LoopEndBB.
   Builder.CreateCondBr(EndCond, LoopBB, AfterBB);
 
   // Any new code will be inserted in AfterBB.
   Builder.SetInsertPoint(AfterBB);
+  /// [chapter5-ForExprAST-codegen7]
 
+  /// [chapter5-ForExprAST-codegen8]
   // Add a new entry to the PHI node for the backedge.
   Variable->addIncoming(NextVar, LoopEndBB);
 
   // Restore the unshadowed variable.
   if (OldVal)
     NamedValues[VarName] = OldVal;
   else
     NamedValues.erase(VarName);
 
   // for expr always returns 0.0.
   return Constant::getNullValue(Type::getDoubleTy(TheContext));
 }
+/// [chapter5-ForExprAST-codegen8]
 
 Function *PrototypeAST::codegen() {
   // Make the function type:  double(double,double) etc.
   std::vector<Type *> Doubles(Args.size(), Type::getDoubleTy(TheContext));
   FunctionType *FT =
       FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
 
   Function *F =

examples/Kaleidoscope/Chapter6/toy.cpp

class VariableExprAST : public ExprAST {
   std::string Name;
 
 public:
   VariableExprAST(const std::string &Name) : Name(Name) {}
 
   Value *codegen() override;
 };
 
+/// [chapter6-UnaryExprAST]
 /// UnaryExprAST - Expression class for a unary operator.
 class UnaryExprAST : public ExprAST {
   char Opcode;
   std::unique_ptr<ExprAST> Operand;
 
 public:
   UnaryExprAST(char Opcode, std::unique_ptr<ExprAST> Operand)
       : Opcode(Opcode), Operand(std::move(Operand)) {}
 
   Value *codegen() override;
 };
+/// [chapter6-UnaryExprAST]
 
 /// BinaryExprAST - Expression class for a binary operator.
 class BinaryExprAST : public ExprAST {
   char Op;
   std::unique_ptr<ExprAST> LHS, RHS;
 
 public:
   BinaryExprAST(char Op, std::unique_ptr<ExprAST> LHS,
ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,
              std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,
              std::unique_ptr<ExprAST> Body)
       : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
         Step(std::move(Step)), Body(std::move(Body)) {}
 
   Value *codegen() override;
 };
 
+/// [chapter6-PrototypeAST]
 /// PrototypeAST - This class represents the "prototype" for a function,
 /// which captures its name, and its argument names (thus implicitly the number
 /// of arguments the function takes), as well as if it is an operator.
 class PrototypeAST {
   std::string Name;
   std::vector<std::string> Args;
   bool IsOperator;
   unsigned Precedence; // Precedence if a binary op.
public:
 
   char getOperatorName() const {
     assert(isUnaryOp() || isBinaryOp());
     return Name[Name.size() - 1];
   }
 
   unsigned getBinaryPrecedence() const { return Precedence; }
 };
+/// [chapter6-PrototypeAST]
 
 /// FunctionAST - This class represents a function definition itself.
 class FunctionAST {
   std::unique_ptr<PrototypeAST> Proto;
   std::unique_ptr<ExprAST> Body;
 
 public:
   FunctionAST(std::unique_ptr<PrototypeAST> Proto,
case '(':
     return ParseParenExpr();
   case tok_if:
     return ParseIfExpr();
   case tok_for:
     return ParseForExpr();
   }
 }
 
+/// [chapter6-ParseUnary]
 /// unary
 ///   ::= primary
 ///   ::= '!' unary
 static std::unique_ptr<ExprAST> ParseUnary() {
   // If the current token is not an operator, it must be a primary expr.
   if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
     return ParsePrimary();
 
   // If this is a unary operator, read it.
   int Opc = CurTok;
   getNextToken();
   if (auto Operand = ParseUnary())
     return llvm::make_unique<UnaryExprAST>(Opc, std::move(Operand));
   return nullptr;
 }
+/// [chapter6-ParseUnary]
 
 /// binoprhs
 ///   ::= ('+' unary)*
 static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
                                               std::unique_ptr<ExprAST> LHS) {
   // If this is a binop, find its precedence.
   while (true) {
     int TokPrec = GetTokPrecedence();
while (true) {
     }
 
     // Merge LHS/RHS.
     LHS =
         llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS), std::move(RHS));
   }
 }
 
+/// [chapter6-ParseExpression]
 /// expression
 ///   ::= unary binoprhs
 ///
 static std::unique_ptr<ExprAST> ParseExpression() {
   auto LHS = ParseUnary();
   if (!LHS)
     return nullptr;
 
   return ParseBinOpRHS(0, std::move(LHS));
 }
+/// [chapter6-ParseExpression]
 
+/// [chapter6-ParsePrototype]
 /// prototype
 ///   ::= id '(' id* ')'
 ///   ::= binary LETTER number? (id, id)
 ///   ::= unary LETTER (id)
 static std::unique_ptr<PrototypeAST> ParsePrototype() {
   std::string FnName;
 
   unsigned Kind = 0; // 0 = identifier, 1 = unary, 2 = binary.
static std::unique_ptr<PrototypeAST> ParsePrototype() {
 
   // Verify right number of names for operator.
   if (Kind && ArgNames.size() != Kind)
     return LogErrorP("Invalid number of operands for operator");
 
   return llvm::make_unique<PrototypeAST>(FnName, ArgNames, Kind != 0,
                                          BinaryPrecedence);
 }
+/// [chapter6-ParsePrototype]
 
 /// definition ::= 'def' prototype expression
 static std::unique_ptr<FunctionAST> ParseDefinition() {
   getNextToken(); // eat def.
   auto Proto = ParsePrototype();
   if (!Proto)
     return nullptr;
 

 Value *VariableExprAST::codegen() {
   // Look this variable up in the function.
   Value *V = NamedValues[Name];
   if (!V)
     return LogErrorV("Unknown variable name");
   return V;
 }
 
+/// [chapter6-UnaryExprAST-codegen]
 Value *UnaryExprAST::codegen() {
   Value *OperandV = Operand->codegen();
   if (!OperandV)
     return nullptr;
 
   Function *F = getFunction(std::string("unary") + Opcode);
   if (!F)
     return LogErrorV("Unknown unary operator");
 
   return Builder.CreateCall(F, OperandV, "unop");
 }
+/// [chapter6-UnaryExprAST-codegen]
 
+/// [chapter6-BinaryExprAST-codegen]
 Value *BinaryExprAST::codegen() {
   Value *L = LHS->codegen();
   Value *R = RHS->codegen();
   if (!L || !R)
     return nullptr;
 
   switch (Op) {
   case '+':
Value *BinaryExprAST::codegen() {
   // If it wasn't a builtin binary operator, it must be a user defined one. Emit
   // a call to it.
   Function *F = getFunction(std::string("binary") + Op);
   assert(F && "binary operator not found!");
 
   Value *Ops[] = {L, R};
   return Builder.CreateCall(F, Ops, "binop");
 }
+/// [chapter6-BinaryExprAST-codegen]
 
 Value *CallExprAST::codegen() {
   // Look up the name in the global module table.
   Function *CalleeF = getFunction(Callee);
   if (!CalleeF)
     return LogErrorV("Unknown function referenced");
 
   // If argument mismatch error.
Function *PrototypeAST::codegen() {
   // Set names for all arguments.
   unsigned Idx = 0;
   for (auto &Arg : F->args())
     Arg.setName(Args[Idx++]);
 
   return F;
 }
 
+/// [chapter6-FunctionAST-codegen]
 Function *FunctionAST::codegen() {
   // Transfer ownership of the prototype to the FunctionProtos map, but keep a
   // reference to it for use below.
   auto &P = *Proto;
   FunctionProtos[Proto->getName()] = std::move(Proto);
   Function *TheFunction = getFunction(P.getName());
   if (!TheFunction)
     return nullptr;
 
   // If this is an operator, install it.
   if (P.isBinaryOp())
     BinopPrecedence[P.getOperatorName()] = P.getBinaryPrecedence();
 
   // Create a new basic block to start insertion into.
   BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
+  /// [chapter6-FunctionAST-codegen]
   Builder.SetInsertPoint(BB);
 
   // Record the function arguments in the NamedValues map.
   NamedValues.clear();
   for (auto &Arg : TheFunction->args())
     NamedValues[Arg.getName()] = &Arg;
 
   if (Value *RetVal = Body->codegen()) {

examples/Kaleidoscope/Chapter7/toy.cpp

ForExprAST(const std::string &VarName, std::unique_ptr<ExprAST> Start,
              std::unique_ptr<ExprAST> End, std::unique_ptr<ExprAST> Step,
              std::unique_ptr<ExprAST> Body)
       : VarName(VarName), Start(std::move(Start)), End(std::move(End)),
         Step(std::move(Step)), Body(std::move(Body)) {}
 
   Value *codegen() override;
 };
 
+/// [chapter7-VarExprAST]
 /// VarExprAST - Expression class for var/in
 class VarExprAST : public ExprAST {
   std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
   std::unique_ptr<ExprAST> Body;
 
 public:
   VarExprAST(
       std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames,
       std::unique_ptr<ExprAST> Body)
       : VarNames(std::move(VarNames)), Body(std::move(Body)) {}
 
   Value *codegen() override;
 };
+/// [chapter7-VarExprAST]
 
 /// PrototypeAST - This class represents the "prototype" for a function,
 /// which captures its name, and its argument names (thus implicitly the number
 /// of arguments the function takes), as well as if it is an operator.
 class PrototypeAST {
   std::string Name;
   std::vector<std::string> Args;
   bool IsOperator;
static std::unique_ptr<ExprAST> ParseForExpr() {
   auto Body = ParseExpression();
   if (!Body)
     return nullptr;
 
   return llvm::make_unique<ForExprAST>(IdName, std::move(Start), std::move(End),
                                        std::move(Step), std::move(Body));
 }
 
+/// [chapter7-ParseVarExpr1]
 /// varexpr ::= 'var' identifier ('=' expression)?
 //                    (',' identifier ('=' expression)?)* 'in' expression
 static std::unique_ptr<ExprAST> ParseVarExpr() {
   getNextToken(); // eat the var.
 
   std::vector<std::pair<std::string, std::unique_ptr<ExprAST>>> VarNames;
 
   // At least one variable name is required.
   if (CurTok != tok_identifier)
     return LogError("expected identifier after var");
+  /// [chapter7-ParseVarExpr1]
 
+  /// [chapter7-ParseVarExpr2]
   while (true) {
     std::string Name = IdentifierStr;
     getNextToken(); // eat identifier.
 
     // Read the optional initializer.
     std::unique_ptr<ExprAST> Init = nullptr;
     if (CurTok == '=') {
       getNextToken(); // eat the '='.
 
       Init = ParseExpression();
       if (!Init)
         return nullptr;
     }
 
     VarNames.push_back(std::make_pair(Name, std::move(Init)));
 
     // End of var list, exit loop.
     if (CurTok != ',')
       break;
     getNextToken(); // eat the ','.
 
     if (CurTok != tok_identifier)
       return LogError("expected identifier list after var");
   }
+  /// [chapter7-ParseVarExpr2]
 
+  /// [chapter7-ParseVarExpr3]
   // At this point, we have to have 'in'.
   if (CurTok != tok_in)
     return LogError("expected 'in' keyword after 'var'");
   getNextToken(); // eat 'in'.
 
   auto Body = ParseExpression();
   if (!Body)
     return nullptr;
 
   return llvm::make_unique<VarExprAST>(std::move(VarNames), std::move(Body));
 }
+/// [chapter7-ParseVarExpr3]
 
+/// [chapter7-ParsePrimary]
 /// primary
 ///   ::= identifierexpr
 ///   ::= numberexpr
 ///   ::= parenexpr
 ///   ::= ifexpr
 ///   ::= forexpr
 ///   ::= varexpr
 static std::unique_ptr<ExprAST> ParsePrimary() {
static std::unique_ptr<ExprAST> ParsePrimary() {
   case tok_if:
     return ParseIfExpr();
   case tok_for:
     return ParseForExpr();
   case tok_var:
     return ParseVarExpr();
   }
 }
+/// [chapter7-ParsePrimary]
 
 /// unary
 ///   ::= primary
 ///   ::= '!' unary
 static std::unique_ptr<ExprAST> ParseUnary() {
   // If the current token is not an operator, it must be a primary expr.
   if (!isascii(CurTok) || CurTok == '(' || CurTok == ',')
     return ParsePrimary();
Function *getFunction(std::string Name) {
   auto FI = FunctionProtos.find(Name);
   if (FI != FunctionProtos.end())
     return FI->second->codegen();
 
   // If no existing prototype exists, return null.
   return nullptr;
 }
 
+/// [chapter7-CreateEntryBlockAlloca]
 /// CreateEntryBlockAlloca - Create an alloca instruction in the entry block of
 /// the function.  This is used for mutable variables etc.
 static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
                                           const std::string &VarName) {
   IRBuilder<> TmpB(&TheFunction->getEntryBlock(),
                    TheFunction->getEntryBlock().begin());
   return TmpB.CreateAlloca(Type::getDoubleTy(TheContext), nullptr, VarName);
 }
+/// [chapter7-CreateEntryBlockAlloca]
 
 Value *NumberExprAST::codegen() {
   return ConstantFP::get(TheContext, APFloat(Val));
 }
 
+/// [chapter7-VariableExprAST-codegen]
 Value *VariableExprAST::codegen() {
   // Look this variable up in the function.
   Value *V = NamedValues[Name];
   if (!V)
     return LogErrorV("Unknown variable name");
 
   // Load the value.
   return Builder.CreateLoad(V, Name.c_str());
 }
+/// [chapter7-VariableExprAST-codegen]
 
 Value *UnaryExprAST::codegen() {
   Value *OperandV = Operand->codegen();
   if (!OperandV)
     return nullptr;
 
   Function *F = getFunction(std::string("unary") + Opcode);
   if (!F)
     return LogErrorV("Unknown unary operator");
 
   return Builder.CreateCall(F, OperandV, "unop");
 }
 
+/// [chapter7-BinaryExprAST-codegen1]
 Value *BinaryExprAST::codegen() {
   // Special case '=' because we don't want to emit the LHS as an expression.
   if (Op == '=') {
     // Assignment requires the LHS to be an identifier.
     // This assume we're building without RTTI because LLVM builds that way by
     // default.  If you build LLVM with RTTI this can be changed to a
     // dynamic_cast for automatic error checking.
     VariableExprAST *LHSE = static_cast<VariableExprAST *>(LHS.get());
     if (!LHSE)
       return LogErrorV("destination of '=' must be a variable");
+    /// [chapter7-BinaryExprAST-codegen1]
+    /// [chapter7-BinaryExprAST-codegen2]
     // Codegen the RHS.
     Value *Val = RHS->codegen();
     if (!Val)
       return nullptr;
 
     // Look up the name.
     Value *Variable = NamedValues[LHSE->getName()];
     if (!Variable)
       return LogErrorV("Unknown variable name");
 
     Builder.CreateStore(Val, Variable);
     return Val;
   }
+  /// [chapter7-BinaryExprAST-codegen2]
 
   Value *L = LHS->codegen();
   Value *R = RHS->codegen();
   if (!L || !R)
     return nullptr;
 
   switch (Op) {
   case '+':

 //   endcond = endexpr
 //
 //   curvar = load var
 //   nextvar = curvar + step
 //   store nextvar -> var
 //   br endcond, loop, endloop
 // outloop:
 Value *ForExprAST::codegen() {
+  /// [chapter7-ForExprAST-codegen1]
   Function *TheFunction = Builder.GetInsertBlock()->getParent();
 
   // Create an alloca for the variable in the entry block.
   AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
 
   // Emit the start code first, without 'variable' in scope.
   Value *StartVal = Start->codegen();
   if (!StartVal)
     return nullptr;
 
   // Store the value into the alloca.
   Builder.CreateStore(StartVal, Alloca);
+  /// [chapter7-ForExprAST-codegen1]
 
   // Make the new basic block for the loop header, inserting after current
   // block.
   BasicBlock *LoopBB = BasicBlock::Create(TheContext, "loop", TheFunction);
 
   // Insert an explicit fall through from the current block to the LoopBB.
   Builder.CreateBr(LoopBB);
 
if (Step) {
     StepVal = Step->codegen();
     if (!StepVal)
       return nullptr;
   } else {
     // If not specified, use 1.0.
     StepVal = ConstantFP::get(TheContext, APFloat(1.0));
   }
 
+  /// [chapter7-ForExprAST-codegen2]
   // Compute the end condition.
   Value *EndCond = End->codegen();
   if (!EndCond)
     return nullptr;
 
   // Reload, increment, and restore the alloca.  This handles the case where
   // the body of the loop mutates the variable.
   Value *CurVar = Builder.CreateLoad(Alloca, VarName.c_str());
   Value *NextVar = Builder.CreateFAdd(CurVar, StepVal, "nextvar");
   Builder.CreateStore(NextVar, Alloca);
+  /// [chapter7-ForExprAST-codegen2]
 
   // Convert condition to a bool by comparing non-equal to 0.0.
   EndCond = Builder.CreateFCmpONE(
       EndCond, ConstantFP::get(TheContext, APFloat(0.0)), "loopcond");
 
   // Create the "after loop" block and insert it.
   BasicBlock *AfterBB =
       BasicBlock::Create(TheContext, "afterloop", TheFunction);
if (OldVal)
     NamedValues[VarName] = OldVal;
   else
     NamedValues.erase(VarName);
 
   // for expr always returns 0.0.
   return Constant::getNullValue(Type::getDoubleTy(TheContext));
 }
 
+/// [chapter7-VarExprAST-codegen1]
 Value *VarExprAST::codegen() {
   std::vector<AllocaInst *> OldBindings;
 
   Function *TheFunction = Builder.GetInsertBlock()->getParent();
 
   // Register all variables and emit their initializer.
   for (unsigned i = 0, e = VarNames.size(); i != e; ++i) {
     const std::string &VarName = VarNames[i].first;
     ExprAST *Init = VarNames[i].second.get();
+    /// [chapter7-VarExprAST-codegen1]
 
+    /// [chapter7-VarExprAST-codegen2]
     // Emit the initializer before adding the variable to scope, this prevents
     // the initializer from referencing the variable itself, and permits stuff
     // like this:
     //  var a = 1 in
     //    var a = a in ...   # refers to outer 'a'.
     Value *InitVal;
     if (Init) {
       InitVal = Init->codegen();
       if (!InitVal)
         return nullptr;
     } else { // If not specified, use 0.0.
       InitVal = ConstantFP::get(TheContext, APFloat(0.0));
     }
 
     AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, VarName);
     Builder.CreateStore(InitVal, Alloca);
 
     // Remember the old variable binding so that we can restore the binding when
     // we unrecurse.
     OldBindings.push_back(NamedValues[VarName]);
 
     // Remember this binding.
     NamedValues[VarName] = Alloca;
   }
+  /// [chapter7-VarExprAST-codegen2]
 
+  /// [chapter7-VarExprAST-codegen3]
   // Codegen the body, now that all vars are in scope.
   Value *BodyVal = Body->codegen();
   if (!BodyVal)
     return nullptr;
+  /// [chapter7-VarExprAST-codegen3]
 
+  /// [chapter7-VarExprAST-codegen4]
   // Pop all our variables from scope.
   for (unsigned i = 0, e = VarNames.size(); i != e; ++i)
     NamedValues[VarNames[i].first] = OldBindings[i];
 
   // Return the body computation.
   return BodyVal;
 }
+/// [chapter7-VarExprAST-codegen4]
 
 Function *PrototypeAST::codegen() {
   // Make the function type:  double(double,double) etc.
   std::vector<Type *> Doubles(Args.size(), Type::getDoubleTy(TheContext));
   FunctionType *FT =
       FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
 
   Function *F =
       Function::Create(FT, Function::ExternalLinkage, Name, TheModule.get());
 
   // Set names for all arguments.
   unsigned Idx = 0;
   for (auto &Arg : F->args())
     Arg.setName(Args[Idx++]);
 
   return F;
 }
 
+/// [chapter7-FunctionAST-codegen1]
 Function *FunctionAST::codegen() {
+  /// [chapter7-FunctionAST-codegen1]
   // Transfer ownership of the prototype to the FunctionProtos map, but keep a
   // reference to it for use below.
   auto &P = *Proto;
   FunctionProtos[Proto->getName()] = std::move(Proto);
   Function *TheFunction = getFunction(P.getName());
   if (!TheFunction)
     return nullptr;
 
   // If this is an operator, install it.
   if (P.isBinaryOp())
     BinopPrecedence[P.getOperatorName()] = P.getBinaryPrecedence();
 
   // Create a new basic block to start insertion into.
   BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
+  /// [chapter7-FunctionAST-codegen2]
   Builder.SetInsertPoint(BB);
 
   // Record the function arguments in the NamedValues map.
   NamedValues.clear();
   for (auto &Arg : TheFunction->args()) {
     // Create an alloca for this variable.
     AllocaInst *Alloca = CreateEntryBlockAlloca(TheFunction, Arg.getName());
 
     // Store the initial value into the alloca.
     Builder.CreateStore(&Arg, Alloca);
 
     // Add arguments to variable symbol table.
     NamedValues[Arg.getName()] = Alloca;
   }
 
   if (Value *RetVal = Body->codegen()) {
+    /// [chapter7-FunctionAST-codegen2]
     // Finish off the function.
     Builder.CreateRet(RetVal);
 
     // Validate the generated code, checking for consistency.
     verifyFunction(*TheFunction);
 
     // Run the optimizer on the function.
     TheFPM->run(*TheFunction);

 static void InitializeModuleAndPassManager() {
   // Open a new module.
   TheModule = llvm::make_unique<Module>("my cool jit", TheContext);
   TheModule->setDataLayout(TheJIT->getTargetMachine().createDataLayout());
 
   // Create a new pass manager attached to it.
   TheFPM = llvm::make_unique<legacy::FunctionPassManager>(TheModule.get());
 
+  /// [chapter7-passes]
   // Promote allocas to registers.
   TheFPM->add(createPromoteMemoryToRegisterPass());
   // Do simple "peephole" optimizations and bit-twiddling optzns.
   TheFPM->add(createInstructionCombiningPass());
   // Reassociate expressions.
   TheFPM->add(createReassociatePass());
+  /// [chapter7-passes]
   // Eliminate Common SubExpressions.
   TheFPM->add(createGVNPass());
   // Simplify the control flow graph (deleting unreachable blocks, etc).
   TheFPM->add(createCFGSimplificationPass());
 
   TheFPM->doInitialization();
 }
 

examples/Kaleidoscope/Chapter8/toy.cpp

int main() {
   getNextToken();
 
   InitializeModuleAndPassManager();
 
   // Run the main "interpreter loop" now.
   MainLoop();
 
   // Initialize the target registry etc.
+  /// [chapter8-initialize]
   InitializeAllTargetInfos();
   InitializeAllTargets();
   InitializeAllTargetMCs();
   InitializeAllAsmParsers();
   InitializeAllAsmPrinters();
+  /// [chapter8-initialize]
 
+  /// [chapter8-TargetTriple]
   auto TargetTriple = sys::getDefaultTargetTriple();
-  TheModule->setTargetTriple(TargetTriple);
+  /// [chapter8-TargetTriple]
 
+  /// [chapter8-lookup]
   std::string Error;
   auto Target = TargetRegistry::lookupTarget(TargetTriple, Error);
 
   // Print an error and exit if we couldn't find the requested target.
   // This generally occurs if we've forgotten to initialise the
   // TargetRegistry or we have a bogus target triple.
   if (!Target) {
     errs() << Error;
     return 1;
   }
+  /// [chapter8-lookup]
 
+  /// [chapter8-target-machine]
   auto CPU = "generic";
   auto Features = "";
 
   TargetOptions opt;
   auto RM = Optional<Reloc::Model>();
   auto TheTargetMachine =
       Target->createTargetMachine(TargetTriple, CPU, Features, opt, RM);
+  /// [chapter8-target-machine]
 
+  /// [chapter8-module]
   TheModule->setDataLayout(TheTargetMachine->createDataLayout());
+  TheModule->setTargetTriple(TargetTriple);
+  /// [chapter8-module]
 
+  /// [chapter8-emit]
   auto Filename = "output.o";
   std::error_code EC;
   raw_fd_ostream dest(Filename, EC, sys::fs::F_None);
 
   if (EC) {
     errs() << "Could not open file: " << EC.message();
     return 1;
   }
+  /// [chapter8-emit]
 
+  /// [chapter8-pass]
   legacy::PassManager pass;
   auto FileType = TargetMachine::CGFT_ObjectFile;
 
   if (TheTargetMachine->addPassesToEmitFile(pass, dest, FileType)) {
     errs() << "TheTargetMachine can't emit a file of this type";
     return 1;
   }
 
   pass.run(*TheModule);
   dest.flush();
+  /// [chapter8-pass]
 
   outs() << "Wrote " << Filename << "\n";
 
   return 0;
 }