Kaleidoscope Chapter 6 docs and comment updates. (#57)

smaillet · web-flow · commit 9d198ee01672 · 2018-03-25T12:56:14.000-07:00
diff --git a/Samples/Kaleidoscope/Chapter6/CodeGenerator.cs b/Samples/Kaleidoscope/Chapter6/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,7 +290,9 @@ public override Value VisitForExpression( [NotNull] ForExpressionContext context
                 return Context.DoubleType.GetNullValue( );
             }
         }
+        // </VisitForExpression>
 
+        // <VisitUserOperators>
         public override Value VisitUnaryOpExpression( [NotNull] UnaryOpExpressionContext context )
         {
             // verify the operator was previously defined
@@ -308,7 +303,7 @@ public override Value VisitUnaryOpExpression( [NotNull] UnaryOpExpressionContext
             }
 
             string calleeName = UnaryPrototypeContext.GetOperatorFunctionName( context.OpToken );
-            var function = GetFunction( calleeName );
+            var function = FindCallTarget( calleeName );
             if( function == null )
             {
                 throw new CodeGeneratorException( $"Unknown function reference {calleeName}" );
@@ -338,6 +333,7 @@ public override Value VisitUnaryPrototype( [NotNull] UnaryPrototypeContext conte
 
             return GetOrDeclareFunction( new Prototype( context, context.Name ) );
         }
+        // </VisitUserOperators>
 
         protected override Value DefaultResult => null;
 
@@ -378,6 +374,7 @@ private Value EmitBinaryOperator( Value lhs, BinaryopContext op, IParseTree righ
             case SLASH:
                 return InstructionBuilder.FDiv( lhs, rhs ).RegisterName( "divtmp" );
 
+            // <EmitUserOperator>
             default:
                 {
                     // User defined op?
@@ -388,30 +385,37 @@ private Value EmitBinaryOperator( Value lhs, BinaryopContext op, IParseTree righ
                     }
 
                     string calleeName = BinaryPrototypeContext.GetOperatorFunctionName( op.Token );
-                    var function = GetFunction( calleeName );
+                    var function = FindCallTarget( calleeName );
                     if( function == null )
                     {
                         throw new CodeGeneratorException( $"Unknown function reference {calleeName}" );
                     }
 
                     return InstructionBuilder.Call( function, lhs, rhs ).RegisterName( "calltmp" );
                 }
+            // </EmitUserOperator>
             }
         }
 
+        // <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 );
@@ -425,7 +429,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 );
@@ -453,7 +459,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 )
@@ -466,7 +474,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 ) )
             {
@@ -503,6 +511,7 @@ private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = f
             InitializeModuleAndPassManager( );
             return (function, jitHandle);
         }
+        // </DefineFunction>
 
         // <PrivateMembers>
         private readonly DynamicRuntimeState RuntimeState;
diff --git a/Samples/Kaleidoscope/Chapter6/Program.cs b/Samples/Kaleidoscope/Chapter6/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.UserDefinedOperators );
                 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>
     }
 }
diff --git a/Samples/Kaleidoscope/Kaleidoscope.Parser/BlockDiagGenerator.cs b/Samples/Kaleidoscope/Kaleidoscope.Parser/BlockDiagGenerator.cs
@@ -16,7 +16,7 @@ namespace Kaleidoscope.Grammar
     /// The resulting ".diag" file is convertible to SVG form for documentation.</para>
     /// <para>
     /// The generated diagrams include a numbered element for binary operator expressions
-    /// to indicate the precedence value that is diyamically evaluated for the expression.
+    /// to indicate the precedence value that is dynamically evaluated for the expression.
     /// This is particularly useful for debugging custom operator precedence problems.
     /// </para>
     /// </remarks>
diff --git a/Samples/Kaleidoscope/Kaleidoscope.Parser/DynamicRuntimeState.cs b/Samples/Kaleidoscope/Kaleidoscope.Parser/DynamicRuntimeState.cs
@@ -19,8 +19,8 @@ namespace Kaleidoscope.Grammar
     ///
     /// This provides storage and support methods for the runtime global state.
     /// In particular, it maintains the language level to use and the current set
-    /// of operators, including any user defined operators so the parser know how
-    /// to resolve complex expressions with precednece.
+    /// of operators, including any user defined operators so the parser knows how
+    /// to resolve complex expressions with user defined operators and precedence.
     /// </remarks>
     public class DynamicRuntimeState
     {
@@ -106,7 +106,7 @@ internal int GetNextPrecedence( int tokenType )
 
         private bool TryAddOperator( int tokenType, OperatorKind kind, int precedence )
         {
-            // internally operators are stored as token type integers to accomodate
+            // internally operators are stored as token type integers to accommodate
             // simpler condition checks and switching on operator types in code generation
             switch( kind )
             {
diff --git a/Samples/Kaleidoscope/Kaleidoscope.Parser/Identifier.cs b/Samples/Kaleidoscope/Kaleidoscope.Parser/Identifier.cs
@@ -11,8 +11,8 @@ namespace Kaleidoscope
 {
     /// <summary>Description of an identifier in Kaleidoscope code generation</summary>
     /// <remarks>
-    /// This is distinct from te parse tree nodes as code generation sometimes needs to
-    /// synthesize an identifier (i.e. Building function the definition for an anonymous
+    /// This is distinct from the parse tree nodes as code generation sometimes needs to
+    /// synthesize an identifier (i.e. Building the function definition for an anonymous
     /// top level expression)
     /// </remarks>
     public struct Identifier
diff --git a/Samples/Kaleidoscope/Kaleidoscope.Parser/KaleidoscopeLexer.cs b/Samples/Kaleidoscope/Kaleidoscope.Parser/KaleidoscopeLexer.cs
@@ -5,7 +5,7 @@
 namespace Kaleidoscope.Grammar
 {
     // partial extension to handle creating virtual tokens/Identifiers depending
-    // on language feaures enabled.
+    // on language features enabled.
     public partial class KaleidoscopeLexer
     {
         public LanguageLevel LanguageLevel { get; set; }
diff --git a/Samples/Kaleidoscope/Kaleidoscope.Runtime/IKaleidoscopeParser.cs b/Samples/Kaleidoscope/Kaleidoscope.Runtime/IKaleidoscopeParser.cs
@@ -30,7 +30,7 @@ public interface IKaleidoscopeParser
         /// <remarks>
         /// If the parse fails then the resulting tuple is the default value ( in this case, both items <see langword="null"/>
         /// Errors from the parse are reported through error listeners provided
-        /// to the parser. Normally this is done via the contructor of a type
+        /// to the parser. Normally this is done via the constructor of a type
         /// implementing this interface.
         /// </remarks>
         (IParseTree parseTree, Parser recognizer) Parse( string txt, DiagnosticRepresentations additionalDiagnostics );
diff --git a/Samples/Kaleidoscope/Kaleidoscope.Runtime/TextReaderExtensions.cs b/Samples/Kaleidoscope/Kaleidoscope.Runtime/TextReaderExtensions.cs
@@ -43,7 +43,7 @@ public static IEnumerable<string> ReadLines( this TextReader reader )
         /// <returns>Enumerable set of lines that may be partial statements</returns>
         /// <remarks>
         /// Each value enumerated includes the full text since the last complete statement.
-        /// That is the Txt from multiple partial statements will include the text of the
+        /// That is the text from multiple partial statements will include the text of the
         /// preceding partial. Once a complete statement is found the entire string is provided
         /// with the IsPartial property set to <see langword="false"/>
         /// </remarks>
@@ -57,7 +57,7 @@ public static IEnumerable<string> ReadLines( this TextReader reader )
         /// <returns>Enumerable set of lines that may be partial statements</returns>
         /// <remarks>
         /// Each value enumerated includes the full text since the last complete statement.
-        /// That is the Txt from multiple partial statements will include the text of the
+        /// That is the text from multiple partial statements will include the text of the
         /// preceding partial. Once a complete statement is found the entire string is provided
         /// with the IsPartial property set to <see langword="false"/>
         /// </remarks>
@@ -66,7 +66,7 @@ public static IEnumerable<string> ReadLines( this TextReader reader )
             var bldr = new StringBuilder( );
             foreach( string line in lines )
             {
-                var statements = line.Split( ';' );
+                string[ ] statements = line.Split( ';' );
 
                 // if the last line in the group was terminated with a ; the
                 // the last entry is an empty string, but a single blank line
diff --git a/Samples/Kaleidoscope/Kaleidoscope.Runtime/Utilities.cs b/Samples/Kaleidoscope/Kaleidoscope.Runtime/Utilities.cs
@@ -54,7 +54,7 @@ public static void WaitForDebugger( bool condition )
         public static string GetSafeFileName( string name )
         {
             var bldr = new StringBuilder( name.Length );
-            var invalidChars = Path.GetInvalidFileNameChars( );
+            char[ ] invalidChars = Path.GetInvalidFileNameChars( );
             foreach( char c in name )
             {
                 bldr.Append( invalidChars.Contains( c ) ? '_' : c );
diff --git a/docfx/articles/Samples/Kaleidoscope-ch6.md b/docfx/articles/Samples/Kaleidoscope-ch6.md

Original file line number	Diff line number	Diff line change
`@@ -29,17 +29,19 @@ internal sealed class CodeGenerator`
`29`	`29`	`, IDisposable`
`30`	`30`	`, IKaleidoscopeCodeGenerator<Value>`
`31`	`31`	`{`
	`32`	`+ // <Initialization>`
`32`	`33`	`public CodeGenerator( DynamicRuntimeState globalState )`
`33`	`34`	`{`
`34`	`35`	`RuntimeState = globalState;`
`35`	`36`	`Context = new Context( );`
	`37`	`+ JIT = new KaleidoscopeJIT( );`
`36`	`38`	`InitializeModuleAndPassManager( );`
`37`	`39`	`InstructionBuilder = new InstructionBuilder( Context );`
`38`		`- JIT = new KaleidoscopeJIT( );`
`39`	`40`	`FunctionPrototypes = new PrototypeCollection( );`
`40`	`41`	`FunctionModuleMap = new Dictionary<string, IJitModuleHandle>( );`
`41`	`42`	`NamedValues = new ScopeStack<Value>( );`
`42`	`43`	`}`
	`44`	`+ // </Initialization>`
`43`	`45`
`44`	`46`	`public bool DisableOptimizations { get; set; }`
`45`	`47`
`@@ -82,7 +84,7 @@ public override Value VisitVariableExpression( [NotNull] VariableExpressionConte`
`82`	`84`
`83`	`85`	`public override Value VisitFunctionCallExpression( [NotNull] FunctionCallExpressionContext context )`
`84`	`86`	`{`
`85`		`- var function = GetFunction( context.CaleeName );`
	`87`	`+ var function = FindCallTarget( context.CaleeName );`
`86`	`88`	`if( function == null )`
`87`	`89`	`{`
`88`	`90`	`throw new CodeGeneratorException( $"function '{context.CaleeName}' is unknown" );`
`@@ -102,13 +104,16 @@ public override Value VisitFunctionPrototype( [NotNull] FunctionPrototypeContext`
`102`	`104`	`return GetOrDeclareFunction( new Prototype( context ) );`
`103`	`105`	`}`
`104`	`106`
	`107`	`+ // <VisitFunctionDefinition>`
`105`	`108`	`public override Value VisitFunctionDefinition( [NotNull] FunctionDefinitionContext context )`
`106`	`109`	`{`
`107`	`110`	`return DefineFunction( ( Function )context.Signature.Accept( this )`
`108`	`111`	`, context.BodyExpression`
`109`	`112`	`).Function;`
`110`	`113`	`}`
	`114`	`+ // </VisitFunctionDefinition>`
`111`	`115`
	`116`	`+ // <VisitTopLevelExpression>`
`112`	`117`	`public override Value VisitTopLevelExpression( [NotNull] TopLevelExpressionContext context )`
`113`	`118`	`{`
`114`	`119`	`var proto = new Prototype( $"anon_expr_{AnonNameIndex++}" );`
`@@ -118,9 +123,11 @@ public override Value VisitTopLevelExpression( [NotNull] TopLevelExpressionConte`
`118`	`123`
`119`	`124`	`var nativeFunc = JIT.GetDelegateForFunction<AnonExpressionFunc>( proto.Identifier.Name );`
`120`	`125`	`var retVal = Context.CreateConstant( nativeFunc( ) );`
	`126`	`+ FunctionModuleMap.Remove( function.Name );`
`121`	`127`	`JIT.RemoveModule( jitHandle );`
`122`	`128`	`return retVal;`
`123`	`129`	`}`
	`130`	`+ // </VisitTopLevelExpression>`
`124`	`131`
`125`	`132`	`public override Value VisitExpression( [NotNull] ExpressionContext context )`
`126`	`133`	`{`
`@@ -135,6 +142,7 @@ public override Value VisitExpression( [NotNull] ExpressionContext context )`
`135`	`142`	`return lhs;`
`136`	`143`	`}`
`137`	`144`
	`145`	`+ // <VisitConditionalExpression>`
`138`	`146`	`public override Value VisitConditionalExpression( [NotNull] ConditionalExpressionContext context )`
`139`	`147`	`{`
`140`	`148`	`var condition = context.Condition.Accept( this );`
`@@ -163,7 +171,7 @@ public override Value VisitConditionalExpression( [NotNull] ConditionalExpressio`
`163`	`171`
`164`	`172`	`InstructionBuilder.Branch( phiMergeBlock );`
`165`	`173`
`166`		`- // capture the insert in case generating thenExpression adds new blocks`
	`174`	`+ // capture the insert in case generating else adds new blocks`
`167`	`175`	`thenBlock = InstructionBuilder.InsertBlock;`
`168`	`176`
`169`	`177`	`// generate else block`
`@@ -188,24 +196,9 @@ public override Value VisitConditionalExpression( [NotNull] ConditionalExpressio`
`188`	`196`	`phiNode.AddIncoming( elseValue, elseBlock );`
`189`	`197`	`return phiNode;`
`190`	`198`	`}`
	`199`	`+ // </VisitConditionalExpression>`
`191`	`200`
`192`		`- /*`
`193`		`- // Output for-loop as:`
`194`		`- // ...`
`195`		`- // start = startexpr`
`196`		`- // goto loop`
`197`		`- // loop:`
`198`		`- // variable = phi [start, loopheader], [nextvariable, loopend]`
`199`		`- // ...`
`200`		`- // bodyexpr`
`201`		`- // ...`
`202`		`- // loopend:`
`203`		`- // step = stepexpr`
`204`		`- // nextvariable = variable + step`
`205`		`- // endcond = endexpr`
`206`		`- // br endcond, loop, endloop`
`207`		`- // outloop:`
`208`		`- */`
	`201`	`+ // <VisitForExpression>`
`209`	`202`	`public override Value VisitForExpression( [NotNull] ForExpressionContext context )`
`210`	`203`	`{`
`211`	`204`	`var function = InstructionBuilder.InsertBlock.ContainingFunction;`
`@@ -297,7 +290,9 @@ public override Value VisitForExpression( [NotNull] ForExpressionContext context`
`297`	`290`	`return Context.DoubleType.GetNullValue( );`
`298`	`291`	`}`
`299`	`292`	`}`
	`293`	`+ // </VisitForExpression>`
`300`	`294`
	`295`	`+ // <VisitUserOperators>`
`301`	`296`	`public override Value VisitUnaryOpExpression( [NotNull] UnaryOpExpressionContext context )`
`302`	`297`	`{`
`303`	`298`	`// verify the operator was previously defined`
`@@ -308,7 +303,7 @@ public override Value VisitUnaryOpExpression( [NotNull] UnaryOpExpressionContext`
`308`	`303`	`}`
`309`	`304`
`310`	`305`	`string calleeName = UnaryPrototypeContext.GetOperatorFunctionName( context.OpToken );`
`311`		`- var function = GetFunction( calleeName );`
	`306`	`+ var function = FindCallTarget( calleeName );`
`312`	`307`	`if( function == null )`
`313`	`308`	`{`
`314`	`309`	`throw new CodeGeneratorException( $"Unknown function reference {calleeName}" );`
`@@ -338,6 +333,7 @@ public override Value VisitUnaryPrototype( [NotNull] UnaryPrototypeContext conte`
`338`	`333`
`339`	`334`	`return GetOrDeclareFunction( new Prototype( context, context.Name ) );`
`340`	`335`	`}`
	`336`	`+ // </VisitUserOperators>`
`341`	`337`
`342`	`338`	`protected override Value DefaultResult => null;`
`343`	`339`
`@@ -378,6 +374,7 @@ private Value EmitBinaryOperator( Value lhs, BinaryopContext op, IParseTree righ`
`378`	`374`	`case SLASH:`
`379`	`375`	`return InstructionBuilder.FDiv( lhs, rhs ).RegisterName( "divtmp" );`
`380`	`376`
	`377`	`+ // <EmitUserOperator>`
`381`	`378`	`default:`
`382`	`379`	`{`
`383`	`380`	`// User defined op?`
`@@ -388,30 +385,37 @@ private Value EmitBinaryOperator( Value lhs, BinaryopContext op, IParseTree righ`
`388`	`385`	`}`
`389`	`386`
`390`	`387`	`string calleeName = BinaryPrototypeContext.GetOperatorFunctionName( op.Token );`
`391`		`- var function = GetFunction( calleeName );`
	`388`	`+ var function = FindCallTarget( calleeName );`
`392`	`389`	`if( function == null )`
`393`	`390`	`{`
`394`	`391`	`throw new CodeGeneratorException( $"Unknown function reference {calleeName}" );`
`395`	`392`	`}`
`396`	`393`
`397`	`394`	`return InstructionBuilder.Call( function, lhs, rhs ).RegisterName( "calltmp" );`
`398`	`395`	`}`
	`396`	`+ // </EmitUserOperator>`
`399`	`397`	`}`
`400`	`398`	`}`
`401`	`399`
	`400`	`+ // <InitializeModuleAndPassManager>`
`402`	`401`	`private void InitializeModuleAndPassManager( )`
`403`	`402`	`{`
`404`	`403`	`Module = Context.CreateBitcodeModule( );`
	`404`	`+ Module.Layout = JIT.TargetMachine.TargetData;`
`405`	`405`	`FunctionPassManager = new FunctionPassManager( Module );`
`406`	`406`	`FunctionPassManager.AddInstructionCombiningPass( )`
`407`	`407`	`.AddReassociatePass( )`
`408`	`408`	`.AddGVNPass( )`
`409`	`409`	`.AddCFGSimplificationPass( )`
`410`	`410`	`.Initialize( );`
`411`	`411`	`}`
	`412`	`+ // </InitializeModuleAndPassManager>`
`412`	`413`
`413`		`- private Function GetFunction( string name )`
	`414`	`+ // <FindCallTarget>`
	`415`	`+ private Function FindCallTarget( string name )`
`414`	`416`	`{`
	`417`	`+ // lookup the prototype for the function to get the signature`
	`418`	`+ // and create a declaration in this module`
`415`	`419`	`if( FunctionPrototypes.TryGetValue( name, out var signature ) )`
`416`	`420`	`{`
`417`	`421`	`return GetOrDeclareFunction( signature );`
`@@ -425,7 +429,9 @@ private Function GetFunction( string name )`
`425`	`429`
`426`	`430`	`return null;`
`427`	`431`	`}`
	`432`	`+ // </FindCallTarget>`
`428`	`433`
	`434`	`+ // <GetOrDeclareFunction>`
`429`	`435`	`private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = false )`
`430`	`436`	`{`
`431`	`437`	`var function = Module.GetFunction( prototype.Identifier.Name );`
`@@ -453,7 +459,9 @@ private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = f`
`453`	`459`
`454`	`460`	`return retVal;`
`455`	`461`	`}`
	`462`	`+ // </GetOrDeclareFunction>`
`456`	`463`
	`464`	`+ // <DefineFunction>`
`457`	`465`	`private (Function Function, IJitModuleHandle JitHandle) DefineFunction( Function function, ExpressionContext body )`
`458`	`466`	`{`
`459`	`467`	`if( !function.IsDeclaration )`
`@@ -466,7 +474,7 @@ private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = f`
`466`	`474`	`// implementation. This is needed, otherwise both the MCJIT`
`467`	`475`	`// and OrcJit engines will resolve to the original module, despite`
`468`	`476`	`// claims to the contrary in the official tutorial text. (Though,`
`469`		`- // to be fare it may have been true in the original JIT and might`
	`477`	`+ // to be fair it may have been true in the original JIT and might`
`470`	`478`	`// still be true for the interpreter)`
`471`	`479`	`if( FunctionModuleMap.Remove( function.Name, out IJitModuleHandle handle ) )`
`472`	`480`	`{`
`@@ -503,6 +511,7 @@ private Function GetOrDeclareFunction( Prototype prototype, bool isAnonymous = f`
`503`	`511`	`InitializeModuleAndPassManager( );`
`504`	`512`	`return (function, jitHandle);`
`505`	`513`	`}`
	`514`	`+ // </DefineFunction>`
`506`	`515`
`507`	`516`	`// <PrivateMembers>`
`508`	`517`	`private readonly DynamicRuntimeState RuntimeState;`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,8 @@`
`14`	`14`
`15`	`15`	`[assembly: SuppressMessage( "StyleCop.CSharp.DocumentationRules", "SA1652:Enable XML documentation output", Justification = "Sample application" )]`
`16`	`16`
	`17`	`+#pragma warning disable SA1512, SA1513, SA1515 // single line comments used to tag regions for extraction into docs`
	`18`	`+`
`17`	`19`	`namespace Kaleidoscope`
`18`	`20`	`{`
`19`	`21`	`public static class Program`
`@@ -35,6 +37,8 @@ public static void Main( string[ ] args )`
`35`	`37`	`using( InitializeLLVM( ) )`
`36`	`38`	`{`
`37`	`39`	`RegisterNative( );`
	`40`	`+`
	`41`	`+ // <generatorloop>`
`38`	`42`	`var parser = new ReplParserStack( LanguageLevel.UserDefinedOperators );`
`39`	`43`	`using( var generator = new CodeGenerator( parser.GlobalState ) )`
`40`	`44`	`{`
`@@ -43,12 +47,31 @@ public static void Main( string[ ] args )`
`43`	`47`	`var replLoop = new ReplLoop<Value>( generator, parser );`
`44`	`48`	`replLoop.ReadyStateChanged += ( s, e ) => Console.Write( e.PartialParse ? ">" : "Ready>" );`
`45`	`49`	`replLoop.GeneratedResultAvailable += OnGeneratedResultAvailable;`
	`50`	`+ replLoop.CodeGenerationError += OnGeneratorError;`
`46`	`51`
`47`	`52`	`replLoop.Run( );`
`48`	`53`	`}`
	`54`	`+ // </generatorloop>`
	`55`	`+ }`
	`56`	`+ }`
	`57`	`+`
	`58`	`+ // <ErrorHandling>`
	`59`	`+ private static void OnGeneratorError( object sender, CodeGenerationExceptionArgs e )`
	`60`	`+ {`
	`61`	`+ var color = Console.ForegroundColor;`
	`62`	`+ Console.ForegroundColor = ConsoleColor.Red;`
	`63`	`+ try`
	`64`	`+ {`
	`65`	`+ Console.Error.WriteLine( e.Exception.Message );`
	`66`	`+ }`
	`67`	`+ finally`
	`68`	`+ {`
	`69`	`+ Console.ForegroundColor = color;`
`49`	`70`	`}`
`50`	`71`	`}`
	`72`	`+ // </ErrorHandling>`
`51`	`73`
	`74`	`+ // <ResultProcessing>`
`52`	`75`	`private static void OnGeneratedResultAvailable( object sender, GeneratedResultAvailableArgs<Value> e )`
`53`	`76`	`{`
`54`	`77`	`var source = ( ReplLoop<Value> )sender;`
`@@ -69,5 +92,6 @@ private static void OnGeneratedResultAvailable( object sender, GeneratedResultAv`
`69`	`92`	`break;`
`70`	`93`	`}`
`71`	`94`	`}`
	`95`	`+ // </ResultProcessing>`
`72`	`96`	`}`
`73`	`97`	`}`
Original file line number	Diff line number	Diff line change
`@@ -19,8 +19,8 @@ namespace Kaleidoscope.Grammar`
`19`	`19`	`///`
`20`	`20`	`/// This provides storage and support methods for the runtime global state.`
`21`	`21`	`/// In particular, it maintains the language level to use and the current set`
`22`		`- /// of operators, including any user defined operators so the parser know how`
`23`		`- /// to resolve complex expressions with precednece.`
	`22`	`+ /// of operators, including any user defined operators so the parser knows how`
	`23`	`+ /// to resolve complex expressions with user defined operators and precedence.`
`24`	`24`	`/// </remarks>`
`25`	`25`	`public class DynamicRuntimeState`
`26`	`26`	`{`
`@@ -106,7 +106,7 @@ internal int GetNextPrecedence( int tokenType )`
`106`	`106`
`107`	`107`	`private bool TryAddOperator( int tokenType, OperatorKind kind, int precedence )`
`108`	`108`	`{`
`109`		`- // internally operators are stored as token type integers to accomodate`
	`109`	`+ // internally operators are stored as token type integers to accommodate`
`110`	`110`	`// simpler condition checks and switching on operator types in code generation`
`111`	`111`	`switch( kind )`
`112`	`112`	`{`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@`
`5`	`5`	`namespace Kaleidoscope.Grammar`
`6`	`6`	`{`
`7`	`7`	`// partial extension to handle creating virtual tokens/Identifiers depending`
`8`		`- // on language feaures enabled.`
	`8`	`+ // on language features enabled.`
`9`	`9`	`public partial class KaleidoscopeLexer`
`10`	`10`	`{`
`11`	`11`	`public LanguageLevel LanguageLevel { get; set; }`
Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ public static void WaitForDebugger( bool condition )`
`54`	`54`	`public static string GetSafeFileName( string name )`
`55`	`55`	`{`
`56`	`56`	`var bldr = new StringBuilder( name.Length );`
`57`		`- var invalidChars = Path.GetInvalidFileNameChars( );`
	`57`	`+ char[ ] invalidChars = Path.GetInvalidFileNameChars( );`
`58`	`58`	`foreach( char c in name )`
`59`	`59`	`{`
`60`	`60`	`bldr.Append( invalidChars.Contains( c ) ? '_' : c );`