| =========================================== |
| Kaleidoscope: Implementing a Parser and AST |
| =========================================== |
| |
| .. contents:: |
| :local: |
| |
| Chapter 2 Introduction |
| ====================== |
| |
| Welcome to Chapter 2 of the "`Implementing a language with LLVM in |
| Objective Caml <index.html>`_" tutorial. This chapter shows you how to |
| use the lexer, built in `Chapter 1 <OCamlLangImpl1.html>`_, to build a |
| full `parser <http://en.wikipedia.org/wiki/Parsing>`_ for our |
| Kaleidoscope language. Once we have a parser, we'll define and build an |
| `Abstract Syntax |
| Tree <http://en.wikipedia.org/wiki/Abstract_syntax_tree>`_ (AST). |
| |
| The parser we will build uses a combination of `Recursive Descent |
| Parsing <http://en.wikipedia.org/wiki/Recursive_descent_parser>`_ and |
| `Operator-Precedence |
| Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_ to |
| parse the Kaleidoscope language (the latter for binary expressions and |
| the former for everything else). Before we get to parsing though, lets |
| talk about the output of the parser: the Abstract Syntax Tree. |
| |
| The Abstract Syntax Tree (AST) |
| ============================== |
| |
| 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:: ocaml |
| |
| (* expr - Base type for all expression nodes. *) |
| type expr = |
| (* variant for numeric literals like "1.0". *) |
| | Number of float |
| |
| 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 Number variant 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 functions on |
| them. It would be very easy to add a function 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:: ocaml |
| |
| (* variant for referencing a variable, like "a". *) |
| | Variable of string |
| |
| (* variant for a binary operator. *) |
| | Binary of char * expr * expr |
| |
| (* variant for function calls. *) |
| | Call of string * expr array |
| |
| 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:: ocaml |
| |
| (* proto - This type represents the "prototype" for a function, which captures |
| * its name, and its argument names (thus implicitly the number of arguments the |
| * function takes). *) |
| type proto = Prototype of string * string array |
| |
| (* func - This type represents a function definition itself. *) |
| type func = Function of proto * expr |
| |
| 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 "expr" variants would probably |
| have a type field. |
| |
| With this scaffolding, we can now talk about parsing expressions and |
| function bodies in Kaleidoscope. |
| |
| Parser Basics |
| ============= |
| |
| Now that we have an AST to build, we need to define the parser code to |
| build it. The idea here is that we want to parse something like "x+y" |
| (which is returned as three tokens by the lexer) into an AST that could |
| be generated with calls like this: |
| |
| .. code-block:: ocaml |
| |
| let x = Variable "x" in |
| let y = Variable "y" in |
| let result = Binary ('+', x, y) in |
| ... |
| |
| The error handling routines make use of the builtin ``Stream.Failure`` |
| and ``Stream.Error``s. ``Stream.Failure`` is raised when the parser is |
| unable to find any matching token in the first position of a pattern. |
| ``Stream.Error`` is raised when the first token matches, but the rest do |
| not. 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 |
| exceptions make it easier to handle errors in routines that have various |
| return types. |
| |
| With these basic types and exceptions, 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. We call this class of expressions |
| "primary" expressions, for reasons that will become more clear `later in |
| the tutorial <OCamlLangImpl6.html#user-defined-unary-operators>`_. In order to parse an |
| arbitrary primary expression, we need to determine what sort of |
| expression it is. For numeric literals, we have: |
| |
| .. code-block:: ocaml |
| |
| (* primary |
| * ::= identifier |
| * ::= numberexpr |
| * ::= parenexpr *) |
| parse_primary = parser |
| (* numberexpr ::= number *) |
| | [< 'Token.Number n >] -> Ast.Number n |
| |
| This routine is very simple: it expects to be called when the current |
| token is a ``Token.Number`` token. It takes the current number value, |
| creates a ``Ast.Number`` 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:: ocaml |
| |
| (* parenexpr ::= '(' expression ')' *) |
| | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e |
| |
| This function illustrates a number of interesting things about the |
| parser: |
| |
| 1) It shows how we use the ``Stream.Error`` exception. 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 use the camlp4 |
| shortcut syntax ``token ?? "parse error"``, where if the token before |
| the ``??`` does not match, then ``Stream.Error "parse error"`` will be |
| raised. |
| |
| 2) Another interesting aspect of this function is that it uses recursion |
| by calling ``Parser.parse_primary`` (we will soon see that |
| ``Parser.parse_primary`` can call ``Parser.parse_primary``). 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:: ocaml |
| |
| (* identifierexpr |
| * ::= identifier |
| * ::= identifier '(' argumentexpr ')' *) |
| | [< 'Token.Ident id; stream >] -> |
| let rec parse_args accumulator = parser |
| | [< e=parse_expr; stream >] -> |
| begin parser |
| | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e |
| | [< >] -> e :: accumulator |
| end stream |
| | [< >] -> accumulator |
| in |
| let rec parse_ident id = parser |
| (* Call. *) |
| | [< 'Token.Kwd '('; |
| args=parse_args []; |
| 'Token.Kwd ')' ?? "expected ')'">] -> |
| Ast.Call (id, Array.of_list (List.rev args)) |
| |
| (* Simple variable ref. *) |
| | [< >] -> Ast.Variable id |
| in |
| parse_ident id stream |
| |
| This routine follows the same style as the other routines. (It expects |
| to be called if the current token is a ``Token.Ident`` 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 ``Ast.Variable`` or ``Ast.Call`` node |
| as appropriate. |
| |
| We finish up by raising an exception if we received a token we didn't |
| expect: |
| |
| .. code-block:: ocaml |
| |
| | [< >] -> raise (Stream.Error "unknown token when expecting an expression.") |
| |
| 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:: ocaml |
| |
| (* binop_precedence - This holds the precedence for each binary operator that is |
| * defined *) |
| let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10 |
| |
| (* precedence - Get the precedence of the pending binary operator token. *) |
| let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1 |
| |
| ... |
| |
| let main () = |
| (* Install standard binary operators. |
| * 1 is the lowest precedence. *) |
| Hashtbl.add Parser.binop_precedence '<' 10; |
| Hashtbl.add Parser.binop_precedence '+' 20; |
| Hashtbl.add Parser.binop_precedence '-' 20; |
| Hashtbl.add Parser.binop_precedence '*' 40; (* highest. *) |
| ... |
| |
| 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 ``Parser.precedence`` function returns the precedence for |
| the current token, or -1 if the token is not a binary operator. Having a |
| ``Hashtbl.t`` 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 ``Hashtbl.t`` and do the |
| comparisons in the ``Parser.precedence`` 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:: ocaml |
| |
| (* expression |
| * ::= primary binoprhs *) |
| and parse_expr = parser |
| | [< lhs=parse_primary; stream >] -> parse_bin_rhs 0 lhs stream |
| |
| ``Parser.parse_bin_rhs`` 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 ``Parser.parse_bin_rhs`` and the |
| current token is "+". |
| |
| The precedence value passed into ``Parser.parse_bin_rhs`` indicates the |
| *minimal operator precedence* that the function is allowed to eat. For |
| example, if the current pair stream is [+, x] and |
| ``Parser.parse_bin_rhs`` is passed in a precedence of 40, it will not |
| consume any tokens (because the precedence of '+' is only 20). With this |
| in mind, ``Parser.parse_bin_rhs`` starts with: |
| |
| .. code-block:: ocaml |
| |
| (* binoprhs |
| * ::= ('+' primary)* *) |
| and parse_bin_rhs expr_prec lhs stream = |
| match Stream.peek stream with |
| (* If this is a binop, find its precedence. *) |
| | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c -> |
| let token_prec = precedence c in |
| |
| (* If this is a binop that binds at least as tightly as the current binop, |
| * consume it, otherwise we are done. *) |
| if token_prec < expr_prec then lhs else begin |
| |
| 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:: ocaml |
| |
| (* Eat the binop. *) |
| Stream.junk stream; |
| |
| (* Parse the primary expression after the binary operator *) |
| let rhs = parse_primary stream in |
| |
| (* Okay, we know this is a binop. *) |
| let rhs = |
| match Stream.peek stream with |
| | Some (Token.Kwd c2) -> |
| |
| 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 |
| unparsed)". To determine this, we look ahead at "binop" to determine its |
| precedence and compare it to BinOp's precedence (which is '+' in this |
| case): |
| |
| .. code-block:: ocaml |
| |
| (* If BinOp binds less tightly with rhs than the operator after |
| * rhs, let the pending operator take rhs as its lhs. *) |
| let next_prec = precedence c2 in |
| if token_prec < next_prec |
| |
| If the precedence of the binop to the right of "RHS" is lower or equal |
| to the precedence of our current operator, then we know that the |
| parentheses associate as "(a+b) binop ...". In our example, the current |
| operator is "+" and the next operator is "+", we know that they have the |
| same precedence. In this case we'll create the AST node for "a+b", and |
| then continue parsing: |
| |
| .. code-block:: ocaml |
| |
| ... if body omitted ... |
| in |
| |
| (* Merge lhs/rhs. *) |
| let lhs = Ast.Binary (c, lhs, rhs) in |
| parse_bin_rhs expr_prec lhs stream |
| end |
| |
| In our example above, this will turn "a+b+" into "(a+b)" and execute the |
| next iteration of the loop, with "+" as the current token. The code |
| above will eat, remember, and parse "(c+d)" as the primary expression, |
| which makes the current pair equal to [+, (c+d)]. It will then evaluate |
| the 'if' conditional above with "\*" as the binop to the right of the |
| primary. In this case, the precedence of "\*" is higher than the |
| 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:: ocaml |
| |
| match Stream.peek stream with |
| | Some (Token.Kwd c2) -> |
| (* If BinOp binds less tightly with rhs than the operator after |
| * rhs, let the pending operator take rhs as its lhs. *) |
| if token_prec < precedence c2 |
| then parse_bin_rhs (token_prec + 1) rhs stream |
| else rhs |
| | _ -> rhs |
| in |
| |
| (* Merge lhs/rhs. *) |
| let lhs = Ast.Binary (c, lhs, rhs) in |
| parse_bin_rhs expr_prec lhs stream |
| end |
| |
| 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 ``Parser.parse_bin_rhs`` |
| function specifying "token\_prec+1" as the minimum precedence required |
| for it to continue. In our example above, this will cause it to return |
| the AST node for "(c+d)\*e\*f" as RHS, which is then set as the RHS of |
| the '+' expression. |
| |
| Finally, on the next iteration of the while loop, the "+g" piece is |
| parsed and added to the AST. With this little bit of code (14 |
| non-trivial lines), we correctly handle fully general binary expression |
| parsing in a very elegant way. This was a whirlwind tour of this code, |
| and it is somewhat subtle. I recommend running through it with a few |
| tough examples to see how it works. |
| |
| This wraps up handling of expressions. At this point, we can point the |
| parser at an arbitrary token stream and build an expression from it, |
| stopping at the first token that is not part of the expression. Next up |
| we need to handle function definitions, etc. |
| |
| Parsing the Rest |
| ================ |
| |
| 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:: ocaml |
| |
| (* prototype |
| * ::= id '(' id* ')' *) |
| let parse_prototype = |
| let rec parse_args accumulator = parser |
| | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e |
| | [< >] -> accumulator |
| in |
| |
| parser |
| | [< 'Token.Ident id; |
| 'Token.Kwd '(' ?? "expected '(' in prototype"; |
| args=parse_args []; |
| 'Token.Kwd ')' ?? "expected ')' in prototype" >] -> |
| (* success. *) |
| Ast.Prototype (id, Array.of_list (List.rev args)) |
| |
| | [< >] -> |
| raise (Stream.Error "expected function name in prototype") |
| |
| Given this, a function definition is very simple, just a prototype plus |
| an expression to implement the body: |
| |
| .. code-block:: ocaml |
| |
| (* definition ::= 'def' prototype expression *) |
| let parse_definition = parser |
| | [< 'Token.Def; p=parse_prototype; e=parse_expr >] -> |
| Ast.Function (p, e) |
| |
| 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:: ocaml |
| |
| (* external ::= 'extern' prototype *) |
| let parse_extern = parser |
| | [< 'Token.Extern; e=parse_prototype >] -> e |
| |
| 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:: ocaml |
| |
| (* toplevelexpr ::= expression *) |
| let parse_toplevel = parser |
| | [< e=parse_expr >] -> |
| (* Make an anonymous proto. *) |
| Ast.Function (Ast.Prototype ("", [||]), e) |
| |
| 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:: ocaml |
| |
| (* top ::= definition | external | expression | ';' *) |
| let rec main_loop stream = |
| match Stream.peek stream with |
| | None -> () |
| |
| (* ignore top-level semicolons. *) |
| | Some (Token.Kwd ';') -> |
| Stream.junk stream; |
| main_loop stream |
| |
| | Some token -> |
| begin |
| try match token with |
| | Token.Def -> |
| ignore(Parser.parse_definition stream); |
| print_endline "parsed a function definition."; |
| | Token.Extern -> |
| ignore(Parser.parse_extern stream); |
| print_endline "parsed an extern."; |
| | _ -> |
| (* Evaluate a top-level expression into an anonymous function. *) |
| ignore(Parser.parse_toplevel stream); |
| print_endline "parsed a top-level expr"; |
| with Stream.Error s -> |
| (* Skip token for error recovery. *) |
| Stream.junk stream; |
| print_endline s; |
| end; |
| print_string "ready> "; flush stdout; |
| main_loop stream |
| |
| 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;", |
| and the parser will know you are done. |
| |
| Conclusions |
| =========== |
| |
| With just under 300 lines of commented code (240 lines of non-comment, |
| non-blank code), we fully defined our minimal language, including a |
| lexer, parser, and AST builder. With this done, the executable will |
| validate Kaleidoscope code and tell us if it is grammatically invalid. |
| For example, here is a sample interaction: |
| |
| .. code-block:: bash |
| |
| $ ./toy.byte |
| ready> def foo(x y) x+foo(y, 4.0); |
| Parsed a function definition. |
| ready> def foo(x y) x+y y; |
| Parsed a function definition. |
| Parsed a top-level expr |
| ready> def foo(x y) x+y ); |
| Parsed a function definition. |
| Error: unknown token when expecting an expression |
| ready> extern sin(a); |
| ready> Parsed an extern |
| ready> ^D |
| $ |
| |
| There is a lot of room for extension here. You can define new AST nodes, |
| extend the language in many ways, etc. In the `next |
| installment <OCamlLangImpl3.html>`_, we will describe how to generate |
| LLVM Intermediate Representation (IR) from the AST. |
| |
| Full Code Listing |
| ================= |
| |
| Here is the complete code listing for this and the previous chapter. |
| Note that it is fully self-contained: you don't need LLVM or any |
| external libraries at all for this. (Besides the ocaml standard |
| libraries, of course.) To build this, just compile with: |
| |
| .. code-block:: bash |
| |
| # Compile |
| ocamlbuild toy.byte |
| # Run |
| ./toy.byte |
| |
| Here is the code: |
| |
| \_tags: |
| :: |
| |
| <{lexer,parser}.ml>: use_camlp4, pp(camlp4of) |
| |
| token.ml: |
| .. code-block:: ocaml |
| |
| (*===----------------------------------------------------------------------=== |
| * Lexer Tokens |
| *===----------------------------------------------------------------------===*) |
| |
| (* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of |
| * these others for known things. *) |
| type token = |
| (* commands *) |
| | Def | Extern |
| |
| (* primary *) |
| | Ident of string | Number of float |
| |
| (* unknown *) |
| | Kwd of char |
| |
| lexer.ml: |
| .. code-block:: ocaml |
| |
| (*===----------------------------------------------------------------------=== |
| * Lexer |
| *===----------------------------------------------------------------------===*) |
| |
| let rec lex = parser |
| (* Skip any whitespace. *) |
| | [< ' (' ' | '\n' | '\r' | '\t'); stream >] -> lex stream |
| |
| (* identifier: [a-zA-Z][a-zA-Z0-9] *) |
| | [< ' ('A' .. 'Z' | 'a' .. 'z' as c); stream >] -> |
| let buffer = Buffer.create 1 in |
| Buffer.add_char buffer c; |
| lex_ident buffer stream |
| |
| (* number: [0-9.]+ *) |
| | [< ' ('0' .. '9' as c); stream >] -> |
| let buffer = Buffer.create 1 in |
| Buffer.add_char buffer c; |
| lex_number buffer stream |
| |
| (* Comment until end of line. *) |
| | [< ' ('#'); stream >] -> |
| lex_comment stream |
| |
| (* Otherwise, just return the character as its ascii value. *) |
| | [< 'c; stream >] -> |
| [< 'Token.Kwd c; lex stream >] |
| |
| (* end of stream. *) |
| | [< >] -> [< >] |
| |
| and lex_number buffer = parser |
| | [< ' ('0' .. '9' | '.' as c); stream >] -> |
| Buffer.add_char buffer c; |
| lex_number buffer stream |
| | [< stream=lex >] -> |
| [< 'Token.Number (float_of_string (Buffer.contents buffer)); stream >] |
| |
| and lex_ident buffer = parser |
| | [< ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream >] -> |
| Buffer.add_char buffer c; |
| lex_ident buffer stream |
| | [< stream=lex >] -> |
| match Buffer.contents buffer with |
| | "def" -> [< 'Token.Def; stream >] |
| | "extern" -> [< 'Token.Extern; stream >] |
| | id -> [< 'Token.Ident id; stream >] |
| |
| and lex_comment = parser |
| | [< ' ('\n'); stream=lex >] -> stream |
| | [< 'c; e=lex_comment >] -> e |
| | [< >] -> [< >] |
| |
| ast.ml: |
| .. code-block:: ocaml |
| |
| (*===----------------------------------------------------------------------=== |
| * Abstract Syntax Tree (aka Parse Tree) |
| *===----------------------------------------------------------------------===*) |
| |
| (* expr - Base type for all expression nodes. *) |
| type expr = |
| (* variant for numeric literals like "1.0". *) |
| | Number of float |
| |
| (* variant for referencing a variable, like "a". *) |
| | Variable of string |
| |
| (* variant for a binary operator. *) |
| | Binary of char * expr * expr |
| |
| (* variant for function calls. *) |
| | Call of string * expr array |
| |
| (* proto - This type represents the "prototype" for a function, which captures |
| * its name, and its argument names (thus implicitly the number of arguments the |
| * function takes). *) |
| type proto = Prototype of string * string array |
| |
| (* func - This type represents a function definition itself. *) |
| type func = Function of proto * expr |
| |
| parser.ml: |
| .. code-block:: ocaml |
| |
| (*===---------------------------------------------------------------------=== |
| * Parser |
| *===---------------------------------------------------------------------===*) |
| |
| (* binop_precedence - This holds the precedence for each binary operator that is |
| * defined *) |
| let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10 |
| |
| (* precedence - Get the precedence of the pending binary operator token. *) |
| let precedence c = try Hashtbl.find binop_precedence c with Not_found -> -1 |
| |
| (* primary |
| * ::= identifier |
| * ::= numberexpr |
| * ::= parenexpr *) |
| let rec parse_primary = parser |
| (* numberexpr ::= number *) |
| | [< 'Token.Number n >] -> Ast.Number n |
| |
| (* parenexpr ::= '(' expression ')' *) |
| | [< 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" >] -> e |
| |
| (* identifierexpr |
| * ::= identifier |
| * ::= identifier '(' argumentexpr ')' *) |
| | [< 'Token.Ident id; stream >] -> |
| let rec parse_args accumulator = parser |
| | [< e=parse_expr; stream >] -> |
| begin parser |
| | [< 'Token.Kwd ','; e=parse_args (e :: accumulator) >] -> e |
| | [< >] -> e :: accumulator |
| end stream |
| | [< >] -> accumulator |
| in |
| let rec parse_ident id = parser |
| (* Call. *) |
| | [< 'Token.Kwd '('; |
| args=parse_args []; |
| 'Token.Kwd ')' ?? "expected ')'">] -> |
| Ast.Call (id, Array.of_list (List.rev args)) |
| |
| (* Simple variable ref. *) |
| | [< >] -> Ast.Variable id |
| in |
| parse_ident id stream |
| |
| | [< >] -> raise (Stream.Error "unknown token when expecting an expression.") |
| |
| (* binoprhs |
| * ::= ('+' primary)* *) |
| and parse_bin_rhs expr_prec lhs stream = |
| match Stream.peek stream with |
| (* If this is a binop, find its precedence. *) |
| | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c -> |
| let token_prec = precedence c in |
| |
| (* If this is a binop that binds at least as tightly as the current binop, |
| * consume it, otherwise we are done. *) |
| if token_prec < expr_prec then lhs else begin |
| (* Eat the binop. *) |
| Stream.junk stream; |
| |
| (* Parse the primary expression after the binary operator. *) |
| let rhs = parse_primary stream in |
| |
| (* Okay, we know this is a binop. *) |
| let rhs = |
| match Stream.peek stream with |
| | Some (Token.Kwd c2) -> |
| (* If BinOp binds less tightly with rhs than the operator after |
| * rhs, let the pending operator take rhs as its lhs. *) |
| let next_prec = precedence c2 in |
| if token_prec < next_prec |
| then parse_bin_rhs (token_prec + 1) rhs stream |
| else rhs |
| | _ -> rhs |
| in |
| |
| (* Merge lhs/rhs. *) |
| let lhs = Ast.Binary (c, lhs, rhs) in |
| parse_bin_rhs expr_prec lhs stream |
| end |
| | _ -> lhs |
| |
| (* expression |
| * ::= primary binoprhs *) |
| and parse_expr = parser |
| | [< lhs=parse_primary; stream >] -> parse_bin_rhs 0 lhs stream |
| |
| (* prototype |
| * ::= id '(' id* ')' *) |
| let parse_prototype = |
| let rec parse_args accumulator = parser |
| | [< 'Token.Ident id; e=parse_args (id::accumulator) >] -> e |
| | [< >] -> accumulator |
| in |
| |
| parser |
| | [< 'Token.Ident id; |
| 'Token.Kwd '(' ?? "expected '(' in prototype"; |
| args=parse_args []; |
| 'Token.Kwd ')' ?? "expected ')' in prototype" >] -> |
| (* success. *) |
| Ast.Prototype (id, Array.of_list (List.rev args)) |
| |
| | [< >] -> |
| raise (Stream.Error "expected function name in prototype") |
| |
| (* definition ::= 'def' prototype expression *) |
| let parse_definition = parser |
| | [< 'Token.Def; p=parse_prototype; e=parse_expr >] -> |
| Ast.Function (p, e) |
| |
| (* toplevelexpr ::= expression *) |
| let parse_toplevel = parser |
| | [< e=parse_expr >] -> |
| (* Make an anonymous proto. *) |
| Ast.Function (Ast.Prototype ("", [||]), e) |
| |
| (* external ::= 'extern' prototype *) |
| let parse_extern = parser |
| | [< 'Token.Extern; e=parse_prototype >] -> e |
| |
| toplevel.ml: |
| .. code-block:: ocaml |
| |
| (*===----------------------------------------------------------------------=== |
| * Top-Level parsing and JIT Driver |
| *===----------------------------------------------------------------------===*) |
| |
| (* top ::= definition | external | expression | ';' *) |
| let rec main_loop stream = |
| match Stream.peek stream with |
| | None -> () |
| |
| (* ignore top-level semicolons. *) |
| | Some (Token.Kwd ';') -> |
| Stream.junk stream; |
| main_loop stream |
| |
| | Some token -> |
| begin |
| try match token with |
| | Token.Def -> |
| ignore(Parser.parse_definition stream); |
| print_endline "parsed a function definition."; |
| | Token.Extern -> |
| ignore(Parser.parse_extern stream); |
| print_endline "parsed an extern."; |
| | _ -> |
| (* Evaluate a top-level expression into an anonymous function. *) |
| ignore(Parser.parse_toplevel stream); |
| print_endline "parsed a top-level expr"; |
| with Stream.Error s -> |
| (* Skip token for error recovery. *) |
| Stream.junk stream; |
| print_endline s; |
| end; |
| print_string "ready> "; flush stdout; |
| main_loop stream |
| |
| toy.ml: |
| .. code-block:: ocaml |
| |
| (*===----------------------------------------------------------------------=== |
| * Main driver code. |
| *===----------------------------------------------------------------------===*) |
| |
| let main () = |
| (* Install standard binary operators. |
| * 1 is the lowest precedence. *) |
| Hashtbl.add Parser.binop_precedence '<' 10; |
| Hashtbl.add Parser.binop_precedence '+' 20; |
| Hashtbl.add Parser.binop_precedence '-' 20; |
| Hashtbl.add Parser.binop_precedence '*' 40; (* highest. *) |
| |
| (* Prime the first token. *) |
| print_string "ready> "; flush stdout; |
| let stream = Lexer.lex (Stream.of_channel stdin) in |
| |
| (* Run the main "interpreter loop" now. *) |
| Toplevel.main_loop stream; |
| ;; |
| |
| main () |
| |
| `Next: Implementing Code Generation to LLVM IR <OCamlLangImpl3.html>`_ |
| |
