Implemented every expression to return an enumerable for a given interval.

Author: StynH

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2025-11-21
+
+- Implemented `every` expression to return an enumerable for a given interval.
+
 ## [0.2.1] - 2025-10-07
 
 - Fixed a bug with `and` throwing an exception.

README.md

@@ -97,6 +97,37 @@ Output:
 2020-01-03T19:00:00
 ```
 
+### Recurring schedules
+
+You can generate a lazy sequence of future dates using `every`. The sequence is infinite, so add your own break condition.
+
+```csharp
+using STYME;
+
+var baseTime = new DateTime(2025, 1, 1, 0, 0, 0);
+var parser = NaturalDateTime.From(baseTime);
+var schedule = parser.Enumerate("every 2 weeks");
+
+foreach (var occurrence in schedule)
+{
+    Console.WriteLine(occurrence);
+    // Break when you reach the point you care about.
+    if (occurrence >= new DateTime(2025, 2, 12))
+    {
+        break;
+    }
+}
+```
+
+Output:
+
+```
+2025-01-01T00:00:00
+2025-01-15T00:00:00
+2025-01-29T00:00:00
+2025-02-12T00:00:00
+```
+
 ### Supported units with `add` and `deduct`
 
 The `add` and `deduct` expressions support the following units (singular and plural forms):

src/STYME.UnitTests/NaturalDateTimeTests/NaturalDateTimeEveryTests.cs

@@ -0,0 +1,62 @@
+namespace STYME.UnitTests.NaturalDateTimeTests;
+
+[TestClass]
+public sealed class NaturalDateTimeEveryTests
+{
+    [TestMethod]
+    public void Given_2025_01_01T00_00_00_When_Every_2_Weeks_Then_Yields_Expected_Sequence()
+    {
+        var baseDate = new DateTime(2025, 1, 1, 0, 0, 0);
+        var sut = NaturalDateTime.From(baseDate);
+
+        var results = new List<DateTime>();
+        foreach (var occurrence in sut.Enumerate("every 2 weeks"))
+        {
+            results.Add(occurrence);
+
+            if (occurrence >= new DateTime(2025, 2, 12, 0, 0, 0))
+            {
+                break;
+            }
+        }
+
+        var expected = new[]
+        {
+            new DateTime(2025, 1, 1, 0, 0, 0),
+            new DateTime(2025, 1, 15, 0, 0, 0),
+            new DateTime(2025, 1, 29, 0, 0, 0),
+            new DateTime(2025, 2, 12, 0, 0, 0),
+        };
+
+        CollectionAssert.AreEqual(expected, results);
+    }
+
+    [TestMethod]
+    public void Given_2025_01_01T10_00_00_When_Every_3_Days_Then_Yields_Expected_Sequence()
+    {
+        var baseDate = new DateTime(2025, 1, 1, 10, 0, 0);
+        var sut = NaturalDateTime.From(baseDate);
+
+        var results = new List<DateTime>();
+        foreach (var occurrence in sut.Enumerate("every 3 days"))
+        {
+            results.Add(occurrence);
+
+            if (occurrence >= new DateTime(2025, 1, 7, 10, 0, 0))
+            {
+                break;
+            }
+        }
+
+        var expected = new[]
+        {
+            new DateTime(2025, 1, 1, 10, 0, 0),
+            new DateTime(2025, 1, 4, 10, 0, 0),
+            new DateTime(2025, 1, 7, 10, 0, 0),
+        };
+
+        CollectionAssert.AreEqual(expected, results);
+    }
+}
+
+

src/STYME/Expressions/Implementations/EveryExpression.cs

@@ -0,0 +1,61 @@
+using System.Collections;
+using STYME.Handling;
+using STYME.Values.TimeShifts;
+
+namespace STYME.Expressions.Implementations;
+
+internal sealed class EveryExpression : IExpression
+{
+    private readonly IExpression _right;
+
+    public EveryExpression(IExpression right)
+    {
+        _right = right;
+    }
+
+    public ExpressionResult ExecuteExpression(IMutableTime time)
+    {
+        var result = _right.ExecuteExpression(time);
+
+        if (result.TryGet<ITimeShift>(out var shift))
+        {
+            return new ExpressionResult(new RecurringDateTimeEnumerable(time.ToExternal(), shift));
+        }
+
+        return ExpressionResult.Empty;
+    }
+
+    private sealed class RecurringDateTimeEnumerable : IEnumerable<DateTime>
+    {
+        private readonly DateTime _start;
+        private readonly ITimeShift _shift;
+
+        public RecurringDateTimeEnumerable(DateTime start, ITimeShift shift)
+        {
+            _start = start;
+            _shift = shift;
+        }
+
+        public IEnumerator<DateTime> GetEnumerator()
+        {
+            return Enumerate().GetEnumerator();
+        }
+
+        IEnumerator IEnumerable.GetEnumerator()
+        {
+            return GetEnumerator();
+        }
+
+        private IEnumerable<DateTime> Enumerate()
+        {
+            IMutableTime current = new MutableDateTime(_start);
+
+            while (true)
+            {
+                yield return current.ToExternal();
+                current = _shift.Shift(current);
+            }
+        }
+    }
+}
+

src/STYME/Locale/English/EnglishParserRules.cs

@@ -25,6 +25,7 @@ public EnglishParserRules()
         _constructors = new(StringComparer.OrdinalIgnoreCase);
         AddConstructorAliases(new AddExpressionConstructor(), "add");
         AddConstructorAliases(new DeductExpressionConstructor(), "deduct", "subtract");
+        AddConstructorAliases(new EveryExpressionConstructor(), "every");
     }
 
     private void AddConstructorAliases(IExpressionConstructor constructor, params string[] names)

src/STYME/NaturalDateTime.cs

@@ -37,4 +37,18 @@ public DateTime Parse(string value)
         //TODO: Placeholder.
         return DateTime.Now;
     }
+
+    public IEnumerable<DateTime> Enumerate(string value)
+    {
+        var tokens = new Queue<string>(value.Split(' '));
+        var root = _expressionParser.ParseExpressionTree(tokens) ?? throw new InvalidOperationException("Expression expected.");
+
+        var result = root.ExecuteExpression(_mutableTime);
+        if (result.TryGet<IEnumerable<DateTime>>(out var sequence) && sequence is not null)
+        {
+            return sequence;
+        }
+
+        throw new InvalidOperationException("Expression did not produce a recurring sequence.");
+    }
 }

src/STYME/Parser/Expressions/Constructors/EveryExpressionConstructor.cs

@@ -0,0 +1,14 @@
+using STYME.Expressions;
+using STYME.Expressions.Implementations;
+
+namespace STYME.Parser.Expressions.Constructors;
+
+internal sealed class EveryExpressionConstructor : IExpressionConstructor
+{
+    public IExpression Construct(string token, Queue<string> tokens, IExpressionParser parser)
+    {
+        var right = parser.ParsePrimary(tokens) ?? throw new InvalidOperationException($"Expected expression after keyword '{token}'.");
+        return new EveryExpression(right);
+    }
+}
+

src/STYME/STYME.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-        <Version>0.2.1</Version>
+        <Version>0.3.0</Version>
         <Summary>A zero-dependency library that allows for manipulating dates and times using natural language.</Summary>
         <Description>A zero-dependency library that allows for manipulating dates and times using natural language, for example "add 1 day" or "deduct 3 hours".</Description>
         <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
@@ -29,9 +29,9 @@
     </ItemGroup>
 
     <PropertyGroup>
-        <Version>0.2.1</Version>
+        <Version>0.3.0</Version>
         <PackageReleaseNotes>
-            - Fixed a bug with `and` throwing an exception.
+            - Implemented `every` expression to return an enumerable for a given interval.
         </PackageReleaseNotes>
     </PropertyGroup>