Kaleidoscope Chapter 5 docs (#56)

Author: smaillet

Samples/Kaleidoscope/Chapter5/CodeGenerator.cs

@@ -29,17 +29,19 @@ internal sealed class CodeGenerator
         , IDisposable
         , IKaleidoscopeCodeGenerator<Value>
     {
+        // <Initialization>
         public CodeGenerator( DynamicRuntimeState globalState )
         {
             RuntimeState = globalState;
             Context = new Context( );
+            JIT = new KaleidoscopeJIT( );
             InitializeModuleAndPassManager( );
             InstructionBuilder = new InstructionBuilder( Context );
-            JIT = new KaleidoscopeJIT( );
             FunctionPrototypes = new PrototypeCollection( );
             FunctionModuleMap = new Dictionary<string, IJitModuleHandle>( );
             NamedValues = new ScopeStack<Value>( );
         }
+        // </Initialization>
 
         public bool DisableOptimizations { get; set; }
 
@@ -82,7 +84,7 @@ public override Value VisitVariableExpression( [NotNull] VariableExpressionConte
 
         public override Value VisitFunctionCallExpression( [NotNull] FunctionCallExpressionContext context )
         {
-            var function = GetFunction( context.CaleeName );
+            var function = FindCallTarget( context.CaleeName );
             if( function == null )
             {
                 throw new CodeGeneratorException( $"function '{context.CaleeName}' is unknown" );
@@ -102,13 +104,16 @@ public override Value VisitFunctionPrototype( [NotNull] FunctionPrototypeContext
             return GetOrDeclareFunction( new Prototype( context ) );
         }
 
+        // <VisitFunctionDefinition>
         public override Value VisitFunctionDefinition( [NotNull] FunctionDefinitionContext context )
         {
             return DefineFunction( ( Function )context.Signature.Accept( this )
                                  , context.BodyExpression
                                  ).Function;
         }
+        // </VisitFunctionDefinition>
 
+        // <VisitTopLevelExpression>
         public override Value VisitTopLevelExpression( [NotNull] TopLevelExpressionContext context )
         {
             var proto = new Prototype( $"anon_expr_{AnonNameIndex++}" );
@@ -118,9 +123,11 @@ public override Value VisitTopLevelExpression( [NotNull] TopLevelExpressionConte
 
             var nativeFunc = JIT.GetDelegateForFunction<AnonExpressionFunc>( proto.Identifier.Name );
             var retVal = Context.CreateConstant( nativeFunc( ) );
+            FunctionModuleMap.Remove( function.Name );
             JIT.RemoveModule( jitHandle );
             return retVal;
         }
+        // </VisitTopLevelExpression>
 
         public override Value VisitExpression( [NotNull] ExpressionContext context )
         {
@@ -135,6 +142,7 @@ public override Value VisitExpression( [NotNull] ExpressionContext context )
             return lhs;
         }
 
+        // <VisitConditionalExpression>
         public override Value VisitConditionalExpression( [NotNull] ConditionalExpressionContext context )
         {
             var condition = context.Condition.Accept( this );
@@ -163,7 +171,7 @@ public override Value VisitConditionalExpression( [NotNull] ConditionalExpressio
 
             InstructionBuilder.Branch( phiMergeBlock );
 
-            // capture the insert in case generating thenExpression adds new blocks
+            // capture the insert in case generating else adds new blocks
             thenBlock = InstructionBuilder.InsertBlock;
 
             // generate else block
@@ -188,24 +196,9 @@ public override Value VisitConditionalExpression( [NotNull] ConditionalExpressio
             phiNode.AddIncoming( elseValue, elseBlock );
             return phiNode;
         }
+        // </VisitConditionalExpression>
 
-        /*
-        // 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:
-        */
+        // <VisitForExpression>
         public override Value VisitForExpression( [NotNull] ForExpressionContext context )
         {
             var function = InstructionBuilder.InsertBlock.ContainingFunction;
@@ -297,6 +290,7 @@ public override Value VisitForExpression( [NotNull] ForExpressionContext context
                 return Context.DoubleType.GetNullValue( );
             }
         }
+        // </VisitForExpression>
 
         protected override Value DefaultResult => null;
 
@@ -342,19 +336,25 @@ private Value EmitBinaryOperator( Value lhs, BinaryopContext op, IParseTree righ
             }
         }
 
+        // <InitializeModuleAndPassManager>
         private void InitializeModuleAndPassManager( )
         {
             Module = Context.CreateBitcodeModule( );
+            Module.Layout = JIT.TargetMachine.TargetData;
             FunctionPassManager = new FunctionPassManager( Module );
             FunctionPassManager.AddInstructionCombiningPass( )
                                .AddReassociatePass( )
                                .AddGVNPass( )
                                .AddCFGSimplificationPass( )
                                .Initialize( );
         }
+        // </InitializeModuleAndPassManager>
 
-        private Function GetFunction( string name )
+        // <FindCallTarget>
+        private Function FindCallTarget( string name )
         {
+            // lookup the prototype for the function to get the signature
+            // and create a declaration in this module
             if( FunctionPrototypes.TryGetValue( name, out var signature ) )
             {
                 return GetOrDeclareFunction( signature );
@@ -368,7 +368,9 @@ private Function GetFunction( string name )
 
             return null;
         }
+        // </FindCallTarget>
 
+        // <GetOrDeclareFunction>
         private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = false )
         {
             var function = Module.GetFunction( prototype.Identifier.Name );
@@ -396,7 +398,9 @@ private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = f
 
             return retVal;
         }
+        // </GetOrDeclareFunction>
 
+        // <DefineFunction>
         private (Function Function, IJitModuleHandle JitHandle) DefineFunction( Function function, ExpressionContext body )
         {
             if( !function.IsDeclaration )
@@ -409,7 +413,7 @@ private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = f
             // implementation. This is needed, otherwise both the MCJIT
             // and OrcJit engines will resolve to the original module, despite
             // claims to the contrary in the official tutorial text. (Though,
-            // to be fare it may have been true in the original JIT and might
+            // to be fair it may have been true in the original JIT and might
             // still be true for the interpreter)
             if( FunctionModuleMap.Remove( function.Name, out IJitModuleHandle handle ) )
             {
@@ -446,6 +450,7 @@ private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = f
             InitializeModuleAndPassManager( );
             return (function, jitHandle);
         }
+        // </DefineFunction>
 
         // <PrivateMembers>
         private readonly DynamicRuntimeState RuntimeState;

Samples/Kaleidoscope/Chapter5/Program.cs

@@ -14,6 +14,8 @@
 
 [assembly: SuppressMessage( "StyleCop.CSharp.DocumentationRules", "SA1652:Enable XML documentation output", Justification = "Sample application" )]
 
+#pragma warning disable SA1512, SA1513, SA1515 // single line comments used to tag regions for extraction into docs
+
 namespace Kaleidoscope
 {
     public static class Program
@@ -35,6 +37,8 @@ public static void Main( string[ ] args )
             using( InitializeLLVM( ) )
             {
                 RegisterNative( );
+
+                // <generatorloop>
                 var parser = new ReplParserStack( LanguageLevel.ControlFlow );
                 using( var generator = new CodeGenerator( parser.GlobalState ) )
                 {
@@ -43,12 +47,31 @@ public static void Main( string[ ] args )
                     var replLoop = new ReplLoop<Value>( generator, parser );
                     replLoop.ReadyStateChanged += ( s, e ) => Console.Write( e.PartialParse ? ">" : "Ready>" );
                     replLoop.GeneratedResultAvailable += OnGeneratedResultAvailable;
+                    replLoop.CodeGenerationError += OnGeneratorError;
 
                     replLoop.Run( );
                 }
+                // </generatorloop>
+            }
+        }
+
+        // <ErrorHandling>
+        private static void OnGeneratorError( object sender, CodeGenerationExceptionArgs e )
+        {
+            var color = Console.ForegroundColor;
+            Console.ForegroundColor = ConsoleColor.Red;
+            try
+            {
+                Console.Error.WriteLine( e.Exception.Message );
+            }
+            finally
+            {
+                Console.ForegroundColor = color;
             }
         }
+        // </ErrorHandling>
 
+        // <ResultProcessing>
         private static void OnGeneratedResultAvailable( object sender, GeneratedResultAvailableArgs<Value> e )
         {
             var source = ( ReplLoop<Value> )sender;
@@ -69,5 +92,6 @@ private static void OnGeneratedResultAvailable( object sender, GeneratedResultAv
                 break;
             }
         }
+        // </ResultProcessing>
     }
 }

Samples/Kaleidoscope/Kaleidoscope.Runtime/ScopeStack.cs

@@ -15,7 +15,7 @@ namespace Kaleidoscope.Runtime
     /// <remarks>
     /// In essence, this is a stack of Dictionaries that is intended for use in code generation.
     /// Most languages have some sort of notion of symbol scopes and name lookups. This implements
-    /// the common case of nested scopes where a new 'local scope may override some of the symbols
+    /// the common case of nested scopes where a new 'local scope' may override some of the symbols
     /// in a parent scope. Any values in any parent not overridden by the child are visible to the
     /// child scope.
     /// </remarks>

docfx/articles/Samples/Kaleidoscope-ch2.md

@@ -211,7 +211,7 @@ binaryop
     ;
 ```
 
-##### Initializers
+### Initializers
 Initializers are a useful re-usable rule to handle a common sequence in the language in multiple different contexts.
 (sort of like a function in most programming languages, in fact, ANTLR rules are implemented in the generated parser
 as methods). 
@@ -225,7 +225,7 @@ initializer
 
 ```
 
-##### Primary Expressions (Atoms)
+### Primary Expressions (Atoms)
 There are a number of primary expressions (also known as 'Atoms') that are not left recursive in their definition.
 These are split out to a distinct rule to aid in the support of left recursion and the need for user defined operator
 precedence.
@@ -246,7 +246,7 @@ primaryExpression
 
 Let's look at each of these in turn to get a better understanding of the language.
 
-###### ParenExpression
+### ParenExpression
 ```antlr
 LPAREN expression[0] RPAREN
 ```
@@ -256,7 +256,7 @@ tree for that expression looks like this:
 
 ![Parse Tree](parsetree-paren-expr.svg)
 
-###### FunctionCallExpression
+### FunctionCallExpression
 ```antlr
 Identifier LPAREN (expression[0] (COMMA expression[0])*)? RPAREN
 ```
@@ -265,7 +265,7 @@ for the call `foo(1, 2, 3);` is:
 
 ![Parse Tree](parsetree-func-call.svg)
 
-###### VarInExpression
+### VarInExpression
 ```antlr
 VAR initializer (COMMA initializer)* IN expression[0]
 ```
@@ -274,7 +274,7 @@ variables is that of the expression on the right of the `in` keyword. The `var .
 in many ways like a declaration of an inline function. The variables declared are scoped to the internal
 implementation of the function. Once the function produces the return value the variables no longer exist.
 
-###### ConditionalExpression
+### ConditionalExpression
 ```antlr
 IF expression[0] THEN expression[0] ELSE expression[0]
 ```
@@ -296,7 +296,7 @@ def fib(x)
   else
     fib(x-1)+fib(x-2);
 ```
-##### ForInExpression
+### ForInExpression
 The ForInExpression provides support for classic for loop constructs. In particular it provides a variable scope for a loop
 value, a condition to test when to exit the loop and an optional step value for incrementing the loop value (default is 1.0).