[FEATURE]: Add foreach looping

README.md

@@ -141,6 +141,38 @@ var result = parser.Render(template);
 Console.WriteLine(result); // Output: 012. 
 ```
 
+### Each Statement
+
+```csharp
+var template = "{{each n:x => x.list.Split( \",\" )}}World {{n}},{{/each}}";
+
+var parser = new TemplateParser
+{
+    Variables = { ["list"] = "John,James,Sarah" }
+};
+
+var result = parser.Render(template);
+Console.WriteLine(result); // hello World John,World James,World Sarah,. 
+```
+
+```csharp
+
+var template = "{{each n:x => x.Where( t => Regex.IsMatch( t.Key, \"people*\" ) ).Select( t => t.Value )}}hello {{n}}. {{/each}}";
+
+var parser = new TemplateParser
+{
+    Variables = 
+        {
+            ["people[0]"] = "John",
+            ["people[1]"] = "Jane",
+            ["people[2]"] = "Doe"
+        }
+};
+
+var result = parser.Render(template);
+Console.WriteLine(result); // hello John. hello Jane. hello Doe. 
+```
+
 ### Methods
 
 You can invoke methods within token expressions.

docs/syntax/examples.md

@@ -116,6 +116,38 @@ var result = parser.Render(template);
 Console.WriteLine(result); // Output: 012. 
 ```
 
+### Each Statement
+
+```csharp
+var template = "{{each n:x => x.list.Split( \",\" )}}World {{n}},{{/each}}";
+
+var parser = new TemplateParser
+{
+    Variables = { ["list"] = "John,James,Sarah" }
+};
+
+var result = parser.Render(template);
+Console.WriteLine(result); // hello World John,World James,World Sarah,. 
+```
+
+```csharp
+
+var template = "{{each n:x => x.Where( t => Regex.IsMatch( t.Key, \"people*\" ) ).Select( t => t.Value )}}hello {{n}}. {{/each}}";
+
+var parser = new TemplateParser
+{
+    Variables = 
+        {
+            ["people[0]"] = "John",
+            ["people[1]"] = "Jane",
+            ["people[2]"] = "Doe"
+        }
+};
+
+var result = parser.Render(template);
+Console.WriteLine(result); // hello John. hello Jane. hello Doe. 
+```
+
 ## Inline Definitions
 
 ```csharp

docs/syntax/overview.md

@@ -64,6 +64,12 @@ The `while` statement repeats a template block while a condition is true.
 
 `{{ while condition }} ... {{ /while }}`
 
+### Each Statement
+
+The `each` statement repeats a template block for each a condition.
+
+`{{ each condition }} ... {{ /each }}`
+
 ## Inline Declarations
 
 You can declare variable tokens inline within the template.

docs/syntax/syntax.md

@@ -7,5 +7,18 @@ nav_order: 1
 
 # Templating Syntax
 
-Hyperbee Templating provides a variety of token syntaxes for different use cases. This section provides a
-guide to to the available syntax forms.
+Hyperbee Templating is a lightweight templating and variable substitution syntax engine. The library supports value replacements, 
+code expressions, token nesting, in-line definitions, conditional flow, and looping. It is designed to be lightweight and fast, 
+and does not rely on any external dependencies.
+
+## Features
+
+* Variable substitution syntax engine
+* Value replacements
+* Expression replacements
+* Token nesting
+* Conditional tokens
+* Conditional flow
+* Iterators
+* User-defined methods
+

src/Hyperbee.Templating/Compiler/RoslynTokenExpressionProvider.cs

@@ -1,8 +1,10 @@
-using System.Collections.Concurrent;
+using System.Collections;
+using System.Collections.Concurrent;
 using System.Collections.Immutable;
-using System.Diagnostics;
 using System.Reflection;
 using System.Runtime.CompilerServices;
+using System.Text.Json.Serialization;
+using System.Text.RegularExpressions;
 using Hyperbee.Templating.Text;
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp;
@@ -16,10 +18,14 @@ internal sealed class RoslynTokenExpressionProvider : ITokenExpressionProvider
     private static readonly ImmutableArray<MetadataReference> MetadataReferences =
     [
         MetadataReference.CreateFromFile( typeof( object ).Assembly.Location ),
-        MetadataReference.CreateFromFile( typeof( object ).Assembly.Location.Replace( "System.Private.CoreLib", "System.Runtime" ) ),
         MetadataReference.CreateFromFile( typeof( RuntimeBinderException ).Assembly.Location ),
         MetadataReference.CreateFromFile( typeof( DynamicAttribute ).Assembly.Location ),
-        MetadataReference.CreateFromFile( typeof( RoslynTokenExpressionProvider ).Assembly.Location )
+        MetadataReference.CreateFromFile( typeof( RoslynTokenExpressionProvider ).Assembly.Location ),
+        MetadataReference.CreateFromFile( typeof( Regex ).Assembly.Location ),
+        MetadataReference.CreateFromFile( typeof( Enumerable ).Assembly.Location ),
+
+        MetadataReference.CreateFromFile( typeof( object ).Assembly.Location.Replace( "System.Private.CoreLib", "System.Runtime" ) ),
+        MetadataReference.CreateFromFile( typeof( IList ).Assembly.Location.Replace( "System.Private.CoreLib", "System.Collections" ) )
     ];
 
     private sealed class RuntimeContext( ImmutableArray<MetadataReference> metadataReferences )
@@ -35,33 +41,40 @@ private sealed class RuntimeContext( ImmutableArray<MetadataReference> metadataR
         new( OutputKind.DynamicallyLinkedLibrary, optimizationLevel: OptimizationLevel.Release );
 
     [MethodImpl( MethodImplOptions.AggressiveInlining )]
-    public TokenExpression GetTokenExpression( string codeExpression )
+    public TokenExpression GetTokenExpression( string codeExpression, MemberDictionary members )
     {
-        return __runtimeContext.TokenExpressions.GetOrAdd( codeExpression, Compile );
+        return __runtimeContext.TokenExpressions.GetOrAdd( codeExpression, Compile( codeExpression, members ) );
     }
 
     public static void Reset()
     {
         __runtimeContext = new RuntimeContext( MetadataReferences );
     }
 
-    private static TokenExpression Compile( string codeExpression )
+    private static TokenExpression Compile( string codeExpression, MemberDictionary members )
     {
         // Create a shim to compile the expression
+        //AF: I added the linq and regular Expression usings
+        //AF: the error is in the Regex as it doesn't know what the people are.  
         var codeShim =
-            $$"""
-              using Hyperbee.Templating.Text;
-              using Hyperbee.Templating.Compiler;
-
-              public static class TokenExpressionInvoker
-              {
-                  public static object Invoke( {{nameof( IReadOnlyMemberDictionary )}} members ) 
-                  {
-                      TokenExpression expr = {{codeExpression}};
-                      return expr( members );
-                  }
-              }
-              """;
+            $$$"""
+               using System;
+               using System.Linq;
+               using System.Text.RegularExpressions;
+               using System.Collections;
+               using System.Collections.Generic;
+               using Hyperbee.Templating.Text;
+               using Hyperbee.Templating.Compiler;
+
+               public static class TokenExpressionInvoker
+               {
+                   public static object Invoke( {{{nameof( IReadOnlyMemberDictionary )}}} members ) 
+                   {
+                       TokenExpression expr = {{{codeExpression}}};
+                       return expr( members );
+                   }
+               }
+               """;
 
         // Parse the code expression
         var syntaxTree = CSharpSyntaxTree.ParseText( codeShim );
@@ -80,10 +93,10 @@ public static object Invoke( {{nameof( IReadOnlyMemberDictionary )}} members )
         };
 
         // Rewrite the lambda expression to use the dictionary lookup
-        var rewriter = new TokenExpressionRewriter( parameterName );
+        var rewriter = new TokenExpressionRewriter( parameterName, members );
         var rewrittenSyntaxTree = rewriter.Visit( root );
 
-        //var rewrittenCode = rewrittenSyntaxTree.ToFullString(); // Keep for debugging
+        var rewrittenCode = rewrittenSyntaxTree.ToFullString(); // Keep for debugging
 
         // Compile the rewritten code
         var counter = Interlocked.Increment( ref __counter );
@@ -101,9 +114,9 @@ public static object Invoke( {{nameof( IReadOnlyMemberDictionary )}} members )
         {
             var failures = result.Diagnostics.Where( diagnostic =>
                 diagnostic.IsWarningAsError ||
-                diagnostic.Severity == DiagnosticSeverity.Error );
+                diagnostic.Severity == DiagnosticSeverity.Error ).ToArray();
 
-            throw new InvalidOperationException( "Compilation failed: " + string.Join( "\n", failures.Select( diagnostic => diagnostic.GetMessage() ) ) );
+            throw new TokenExpressionProviderException( "Compilation failed: " + failures[0]?.GetMessage(), failures );
         }
 
         peStream.Seek( 0, SeekOrigin.Begin );
@@ -118,16 +131,36 @@ public static object Invoke( {{nameof( IReadOnlyMemberDictionary )}} members )
     }
 }
 
+[Serializable]
+internal class TokenExpressionProviderException : Exception
+{
+    public Diagnostic[] Diagnostic { get; }
+    public string Id => Diagnostic != null && Diagnostic.Length > 0 ? Diagnostic[0].Id : string.Empty;
+
+    public TokenExpressionProviderException( string message, Diagnostic[] diagnostic )
+    : base( message )
+    {
+        Diagnostic = diagnostic;
+    }
+
+    public TokenExpressionProviderException( string message, Diagnostic[] diagnostic, Exception innerException )
+        : base( message, innerException )
+    {
+        Diagnostic = diagnostic;
+    }
+
+}
+
 // This rewriter will transform the lambda expression to use dictionary lookup
 // for property access, method invocation, and 'generic' property casting.
 //
 // we want to transform these syntactic-sugar patterns:
 //
 // 1. x => x.someProp to x["someProp"]
 // 2. x => x.someProp<T> to x.GetValueAs<T>("someProp")
-// 3. x => x.someMethod(..) to x.InvokeMethod("someMethod", ..)
+// 3. x => x.someMethod(..) to x.Invoke("someMethod", ..)
 
-internal class TokenExpressionRewriter( string parameterName ) : CSharpSyntaxRewriter
+internal class TokenExpressionRewriter( string parameterName, MemberDictionary members ) : CSharpSyntaxRewriter
 {
     private readonly HashSet<string> _aliases = [parameterName];
 
@@ -151,7 +184,12 @@ memberAccess.Expression is IdentifierNameSyntax identifier &&
              _aliases.Contains( identifier.Identifier.Text ) )
         {
             // Handle method invocation rewrite
-            return RewriteMethodInvocation( memberAccess, node );
+
+            if ( members.Methods.ContainsKey( memberAccess.Name.Identifier.Text ) )
+                return RewriteMethodInvocation( memberAccess, node );
+
+            return node.Update( node.Expression, (ArgumentListSyntax) VisitArgumentList( node.ArgumentList )! );
+            //return RewriteMethodInvocation( memberAccess, node ); //BF this rewrite causes the error. we need to disambiguate calls to template lambdas methods
         }
 
         return base.VisitInvocationExpression( node );
@@ -232,12 +270,12 @@ private InvocationExpressionSyntax RewriteMethodInvocation( MemberAccessExpressi
             .Select( arg => (ExpressionSyntax) Visit( arg.Expression ) )
             .ToArray();
 
-        // Create the InvokeMethod call: x.InvokeMethod("MethodName", arg1, arg2, ...)
+        // Create the InvokeMethod call: x.Invoke("MethodName", arg1, arg2, ...)
         var invokeMethodCall = SyntaxFactory.InvocationExpression(
             SyntaxFactory.MemberAccessExpression(
                 SyntaxKind.SimpleMemberAccessExpression,
                 memberAccess.Expression, // This is `x`
-                SyntaxFactory.IdentifierName( "InvokeMethod" )
+                SyntaxFactory.IdentifierName( "Invoke" )
             ),
             SyntaxFactory.ArgumentList(
                 SyntaxFactory.SeparatedList(

src/Hyperbee.Templating/Compiler/TokenExpression.cs

@@ -6,5 +6,5 @@ namespace Hyperbee.Templating.Compiler;
 
 public interface ITokenExpressionProvider
 {
-    public TokenExpression GetTokenExpression( string codeExpression );
+    public TokenExpression GetTokenExpression( string codeExpression, MemberDictionary members );
 }

src/Hyperbee.Templating/Configure/TemplateOptions.cs

@@ -1,6 +1,7 @@
 using System.ComponentModel;
 using System.Reflection;
 using Hyperbee.Templating.Compiler;
+using Hyperbee.Templating.Core;
 using Hyperbee.Templating.Text;
 
 namespace Hyperbee.Templating.Configure;
@@ -13,7 +14,7 @@ public class TemplateOptions
     public IDictionary<string, string> Variables { get; init; }
 
     public TokenStyle TokenStyle { get; set; } = TokenStyle.Default;
-    public KeyValidator Validator { get; set; } = TemplateHelper.ValidateKey;
+    public KeyValidator Validator { get; set; } = KeyHelper.ValidateKey;
 
     public bool IgnoreMissingTokens { get; set; }
     public bool SubstituteEnvironmentVariables { get; set; }

src/Hyperbee.Templating/Core/EnumeratorAdapter.cs

@@ -0,0 +1,27 @@
+using System.Collections;
+
+namespace Hyperbee.Templating.Core;
+
+internal sealed class EnumeratorAdapter : IEnumerator<string>
+{
+    private readonly IEnumerator _inner;
+
+    internal EnumeratorAdapter( IEnumerable enumerable )
+    {
+        if ( enumerable is not IEnumerable<IConvertible> typedEnumerable )
+            throw new ArgumentException( "The enumerable must be of type IEnumerable<IConvertible>.", nameof( enumerable ) );
+
+        // take a snapshot of the enumerable to prevent changes during enumeration
+        var snapshot = new List<IConvertible>( typedEnumerable );
+
+        // ReSharper disable once GenericEnumeratorNotDisposed
+        _inner = snapshot.GetEnumerator();
+    }
+
+    public string Current => (string) _inner.Current;
+    object IEnumerator.Current => _inner.Current;
+
+    public bool MoveNext() => _inner.MoveNext();
+    public void Reset() => _inner.Reset();
+    public void Dispose() => (_inner as IDisposable)?.Dispose();
+}

src/Hyperbee.Templating/Core/KeyHelper.cs

@@ -0,0 +1,55 @@
+namespace Hyperbee.Templating.Core;
+
+public delegate bool KeyValidator( ReadOnlySpan<char> key );
+
+internal static class KeyHelper
+{
+    public static bool ValidateKey( string key )
+    {
+        // do-not-remove this method.
+        //
+        // this method is required despite code analysis claiming the method isn't referenced.
+        //
+        // this overload is required (and used) by generic delegates which don't support
+        // ReadOnlySpan<char> as a generic argument.
+
+        return ValidateKey( key.AsSpan() );
+    }
+
+    public static bool ValidateKey( ReadOnlySpan<char> key )
+    {
+        if ( key.IsEmpty || !char.IsLetter( key[0] ) )
+        {
+            return false;
+        }
+
+        var length = key.Length;
+
+        for ( var i = 1; i < length; i++ )
+        {
+            var current = key[i];
+
+            if ( current == '[' )
+            {
+                if ( ++i >= length || !char.IsDigit( key[i] ) )
+                    return false;
+
+                while ( i < length && char.IsDigit( key[i] ) )
+                    i++;
+
+                if ( i >= length || key[i] != ']' )
+                    return false;
+
+                // Ensure that the bracket is at the end of the string
+                if ( i != length - 1 )
+                    return false;
+            }
+            else if ( !char.IsLetterOrDigit( current ) && current != '_' )
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}