Add text position support in Then() (#267)

* New Then() overload to use start/end of a result

* Add text position support in Then()

Author: sebastienros

docs/parsers.md

@@ -796,6 +796,7 @@ Convert the result of a parser. This is usually used to create custom data struc
 ```c#
 Parser<U> Then<U>(Func<T, U> conversion)
 Parser<U> Then<U>(Func<ParseContext, T, U> conversion)
+Parser<U> Then<U>(Func<ParseContext, int, int, T, U> conversion)
 Parser<U> Then<U>(U value)
 Parser<U?> Then<U>() // Converts the result to `U`
 ```
@@ -827,6 +828,28 @@ var parser = OneOf(
 );
 ```
 
+#### Accessing Start and End Positions
+
+The `Func<ParseContext, int, int, T, U>` overload provides access to the start and end offsets of the parsed result:
+
+```c#
+var parser = Literals.Identifier().Then((context, start, end, value) =>
+{
+    var length = end - start;
+    return $"Parsed '{value}' at offset {start}, length {length}";
+});
+
+parser.Parse("hello");
+```
+
+Result:
+
+```
+"Parsed 'hello' at offset 0, length 5"
+```
+
+> **Note:** The start and end parameters are integer offsets (positions in the input buffer), not `TextPosition` objects. For `Literals` parsers, these offsets correspond exactly to where the parser matched. For `Terms` parsers (which skip whitespace), the behavior differs slightly between compiled and non-compiled modes due to how whitespace skipping is handled in the compilation process.
+
 ### Else
 
 Returns a value if the previous parser failed.

src/Parlot/Fluent/Parser.cs

@@ -19,6 +19,11 @@ public abstract partial class Parser<T>
     /// </summary>
     public Parser<U> Then<U>(Func<ParseContext, T, U> conversion) => new Then<T, U>(this, conversion);
 
+    /// <summary>
+    /// Builds a parser that converts the previous result, and can use the <see cref="ParseContext"/> and the start and end offsets.
+    /// </summary>
+    public Parser<U> Then<U>(Func<ParseContext, int, int, T, U> conversion) => new Then<T, U>(this, conversion);
+
     /// <summary>
     /// Builds a parser that converts the previous result.
     /// </summary>

src/Parlot/Fluent/SkipWhiteSpace.cs

@@ -60,7 +60,7 @@ public CompilationResult Compile(CompilationContext context)
     {
         var result = context.CreateCompilationResult<T>();
 
-        var start = context.DeclarePositionVariable(result);
+        var startBeforeWhitespace = context.DeclarePositionVariable(result);
 
         var parserCompileResult = Parser.Build(context);
 
@@ -78,7 +78,7 @@ public CompilationResult Compile(CompilationContext context)
                                 Expression.Assign(result.Value, parserCompileResult.Value),
                             Expression.Assign(result.Success, Expression.Constant(true, typeof(bool)))
                             ),
-                        context.ResetPosition(start)
+                        context.ResetPosition(startBeforeWhitespace)
                         )
                     )
                 )

src/Parlot/Fluent/Then.cs

@@ -16,6 +16,7 @@ public sealed class Then<T, U> : Parser<U>, ICompilable, ISeekable
 {
     private readonly Func<T, U>? _action1;
     private readonly Func<ParseContext, T, U>? _action2;
+    private readonly Func<ParseContext, int, int, T, U>? _action3;
     private readonly U? _value;
     private readonly Parser<T> _parser;
 
@@ -41,6 +42,11 @@ public Then(Parser<T> parser, Func<ParseContext, T, U> action) : this(parser)
         _action2 = action ?? throw new ArgumentNullException(nameof(action));
     }
 
+    public Then(Parser<T> parser, Func<ParseContext, int, int, T, U> action) : this(parser)
+    {
+        _action3 = action ?? throw new ArgumentNullException(nameof(action));
+    }
+
     public Then(Parser<T> parser, U value) : this(parser)
     {
         _value = value;
@@ -68,9 +74,13 @@ public override bool Parse(ParseContext context, ref ParseResult<U> result)
             {
                 result.Set(parsed.Start, parsed.End, _action2.Invoke(context, parsed.Value));
             }
+            else if (_action3 != null)
+            {
+                result.Set(parsed.Start, parsed.End, _action3.Invoke(context, parsed.Start, parsed.End, parsed.Value));
+            }
             else
             {
-                // _value can't be null if action1 and action2 are null
+                // _value can't be null if action1, action2, and action3 are null
                 result.Set(parsed.Start, parsed.End, _value!);
             }
 
@@ -88,12 +98,27 @@ public CompilationResult Compile(CompilationContext context)
 
         // parse1 instructions
         // 
+        // var startOffset = context.Scanner.Cursor.Offset; // Only for _action3
+        // parser1 body (which may include whitespace skipping for Terms)
         // if (parser1.Success)
         // {
+        //    var endOffset = context.Scanner.Cursor.Offset;  // Only for _action3
         //    success = true;
-        //    value = action(parse1.Value);
+        //    value = action(parse1.Value) // or action(context, start, end, parse1.Value) for _action3
         // }
 
+        ParameterExpression? startOffset = null;
+        ParameterExpression? endOffset = null;
+
+        if (_action3 != null)
+        {
+            // Capture the start offset before the parser runs
+            // Note: For Terms parsers (which skip whitespace), this will be before whitespace is skipped
+            // This differs from non-compiled mode where parsed.Start is after whitespace skipping
+            startOffset = result.DeclareVariable<int>($"startOffset{context.NextNumber}", context.Offset());
+            endOffset = result.DeclareVariable<int>($"endOffset{context.NextNumber}");
+        }
+
         var parserCompileResult = _parser.Build(context, requireResult: true);
 
         Expression assignValue;
@@ -110,6 +135,16 @@ public CompilationResult Compile(CompilationContext context)
                 ? Expression.Invoke(Expression.Constant(_action2), [context.ParseContext, parserCompileResult.Value])
                 : Expression.Assign(result.Value, Expression.Invoke(Expression.Constant(_action2), [context.ParseContext, parserCompileResult.Value]));
         }
+        else if (_action3 != null)
+        {
+            // Capture end offset when parser succeeds, then invoke the action
+            assignValue = Expression.Block(
+                Expression.Assign(endOffset!, context.Offset()),
+                context.DiscardResult
+                    ? Expression.Invoke(Expression.Constant(_action3), [context.ParseContext, startOffset!, endOffset!, parserCompileResult.Value])
+                    : Expression.Assign(result.Value, Expression.Invoke(Expression.Constant(_action3), [context.ParseContext, startOffset!, endOffset!, parserCompileResult.Value]))
+            );
+        }
         else
         {
             assignValue = context.DiscardResult

test/Parlot.Tests/FluentTests.cs

@@ -169,6 +169,24 @@ public void ThenShouldOnlyBeInvokedIfParserSucceeded()
         Assert.True(invoked);
     }
 
+    [Fact]
+    public void ThenShouldProvideStartAndEndOffsets()
+    {
+        // Use Literals for consistent behavior between compiled and non-compiled modes
+        var parser = Literals.Identifier().Then((context, start, end, value) =>
+        {
+            return $"{value}:{start}-{end}";
+        });
+
+        Assert.True(parser.TryParse("hello", out var result));
+        Assert.Equal("hello:0-5", result);
+
+        // Test with compiled parser - should have the same behavior
+        var compiled = parser.Compile();
+        Assert.True(compiled.TryParse("world", out var result2));
+        Assert.Equal("world:0-5", result2);
+    }
+
     [Fact]
     public void BetweenShouldParseBetweenTwoString()
     {