Changes to support time range queries and operations (#196)

* TimeRange code

* Upgrade recognisers

* Avoid infinite recursion when self-references used in scripts

* Hopefully make time tests cross-platform

* code tidy

* Remove faulty test

* Improve example

* Add documentation

Author: NeilMacMullen

Engine/Application/ApplicationEngine.cs

@@ -16,7 +16,7 @@ public class RuntimeInfo
 
         public void AddModel(string name, ModelFormat format)
         {
-            Models = Models.Append(new ModelInfo {Name = name, Format = format.ToString()}).ToArray();
+            Models = Models.Append(new ModelInfo { Name = name, Format = format.ToString() }).ToArray();
         }
 
         public class ModelInfo
@@ -43,33 +43,27 @@ public class ModelInfo
     /// </remarks>
     public class ApplicationEngine
     {
+        private readonly CancellationToken _cancel;
         private readonly RunTimeEnvironment _environment;
 
-        private readonly RuntimeInfo _info = new RuntimeInfo();
+        private readonly RuntimeInfo _info = new();
 
         /// <summary>
         ///     provides generic scriban Template operations
         /// </summary>
         private readonly TemplateManager _templateManager;
 
-        private readonly CancellationToken Cancel;
-
-        /// <summary>
-        ///     Used to automatically name models as they are added
-        /// </summary>
-        private int _modelCount;
-
         /// <summary>
         ///     Create a new application engine
         /// </summary>
-        public ApplicationEngine(RunTimeEnvironment environment, CancellationToken cancel = new CancellationToken())
+        public ApplicationEngine(RunTimeEnvironment environment, CancellationToken cancel = new())
         {
             _environment = environment;
             _templateManager = new TemplateManager(environment.FileSystem);
             //we always add the location of the application executable as an include path for 
             //scripts. This allows us to easily ship a library of standard scripts
             _templateManager.AddIncludePath(environment.ApplicationFolder());
-            Cancel = cancel;
+            _cancel = cancel;
         }
 
         /// <summary>
@@ -106,13 +100,12 @@ public ApplicationEngine WithModel(string name, string modelText, ModelFormat fo
         {
             try
             {
-                Cancel.ThrowIfCancellationRequested();
+                _cancel.ThrowIfCancellationRequested();
                 //parse the text and create a model
                 var serializer = ModelDeserializerFactory.Fetch(format);
                 var model = serializer.Deserialize(modelText);
                 _templateManager.AddVariable(name, model.Untyped);
                 _info.AddModel(name, model.SourceFormat);
-                _modelCount++;
             }
             catch (Exception e)
             {
@@ -149,7 +142,7 @@ public ApplicationEngine WithDefinitions(IEnumerable<string> definitionAssignmen
             try
             {
                 var definitions = DefinitionParser.CreateDefinitions(definitionAssignments)
-                    .ToDictionary(kv => kv.Key, kv => (object) kv.Value);
+                    .ToDictionary(kv => kv.Key, kv => (object)kv.Value);
                 _templateManager.AddVariable(ScribanNamespaces.DefinitionsNamespace, definitions);
             }
             catch (ArgumentException e)
@@ -183,7 +176,7 @@ public ApplicationEngine Render()
             try
             {
                 _templateManager.AddVariable("_runtime", _info);
-                Output = _templateManager.Render(Cancel);
+                Output = _templateManager.Render(_cancel);
             }
             catch (Exception e)
             {
@@ -218,10 +211,9 @@ void Add(ExtensionCache.KnownAssemblies name, ScriptObject scriptObject)
 
             Add(ExtensionCache.KnownAssemblies.Group,
                 ExtensionCache.GetGroupingMethods());
-/*
+
             Add(ExtensionCache.KnownAssemblies.TimeComparison,
                 ExtensionCache.GetTimeComparisonMethods());
-*/
             return this;
         }
 

Engine/Application/TemplateManager.cs

@@ -43,6 +43,7 @@ public TemplateManager(IFileSystemOperations ops)
         {
             _context.StrictVariables = true;
             _context.LoopLimit = int.MaxValue;
+            _context.ObjectRecursionLimit = 100;
             _scriptLoader = new ScriptLoader(ops);
             _context.TemplateLoader = _scriptLoader;
             _context.PushGlobal(_top);
@@ -137,7 +138,7 @@ public bool TryGetVariableObject<T>(string variableName, out T val)
             var scribanVariable = new ScriptVariableGlobal(variableName);
             try
             {
-                val = (T) _context.GetValue(scribanVariable);
+                val = (T)_context.GetValue(scribanVariable);
                 return true;
             }
             catch
@@ -177,7 +178,7 @@ public static ImmutableArray<ModelPath> PathsForObjectTree(IDictionary<string, o
         public ImmutableArray<ModelPath> GetBuiltIns() => PathsForObjectTree(_context.BuiltinObject, ModelPath.Empty);
         public ImmutableArray<ModelPath> GetObjectTree() => PathsForObjectTree(_top, ModelPath.Empty);
 
-        public ImmutableArray<ModelPath> GetKeywords()
+        public static ImmutableArray<ModelPath> GetKeywords()
         {
             var keywords =
                 @"func end if else for break continue

Engine/Engine.csproj

@@ -2,11 +2,25 @@
 
   <PropertyGroup>
     <TargetFramework>net5.0</TargetFramework>
+    <PackageId>textrude.engine</PackageId>
+    <Description>The engine for Textrude</Description>
+    <Authors>Neil MacMullen</Authors>
+    <Copyright>Copyright Neil MacMullen 2021</Copyright>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageProjectUrl>https://github.com/NeilMacMullen/Textrude</PackageProjectUrl>
+    <PackageReleaseNotes>First release</PackageReleaseNotes>
+    <PackageTags></PackageTags>
+    <IncludeSymbols>true</IncludeSymbols>
+    <RepositoryUrl>https://github.com/NeilMacMullen/Textrude.git</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <RepositoryBranch>main</RepositoryBranch>
   </PropertyGroup>
 
   <ItemGroup>
     <PackageReference Include="CsvHelper" Version="27.1.1" />
     <PackageReference Include="Humanizer" Version="2.11.10" />
+    <PackageReference Include="Microsoft.Recognizers.Text" Version="1.8.0" />
+    <PackageReference Include="Microsoft.Recognizers.Text.DateTime" Version="1.8.0" />
     <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
     <PackageReference Include="Scriban" Version="5.0.0" />
     <PackageReference Include="System.Collections.Immutable" Version="5.0.0" />

Engine/Extensions/ExtensionCache.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using Engine.Extensions.TimeRange;
 using Humanizer;
 using Scriban.Runtime;
 
@@ -14,7 +15,8 @@ public enum KnownAssemblies
             Humanizr,
             Misc,
             Textrude,
-            Group
+            Group,
+            TimeComparison
         }
 
         private static readonly Dictionary<KnownAssemblies, ScriptObject> CachedResults =
@@ -62,5 +64,8 @@ public static ScriptObject GetTextrudeMethods() =>
 
         public static ScriptObject GetGroupingMethods() =>
             GetOrCreate(KnownAssemblies.Group, () => new[] {typeof(Group)});
+
+        public static ScriptObject GetTimeComparisonMethods() =>
+            GetOrCreate(KnownAssemblies.TimeComparison, () => new[] {typeof(TimeRangeMethods)});
     }
 }

Engine/Extensions/TimeRange/DateTimeExtensions.cs

@@ -0,0 +1,22 @@
+using System;
+
+namespace Engine.Extensions.TimeRange
+{
+    public static class DateTimeExtensions
+    {
+        public static readonly DateTime UnixEpoch = new(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+
+        public static DateTime FromUnixTime(this long unixTime) => UnixEpoch.AddSeconds(unixTime);
+
+        public static long ToUnixTime(this DateTime date) => Convert.ToInt64((date - UnixEpoch).TotalSeconds);
+
+        public static DateTime Min(DateTime a, DateTime b) => a < b ? a : b;
+
+
+        public static DateTime Max(DateTime a, DateTime b) => a > b ? a : b;
+
+        public static DateTime FromUnixTimeString(string sourceTimeSecondsSinceEpoch) =>
+            long.Parse(sourceTimeSecondsSinceEpoch)
+                .FromUnixTime();
+    }
+}

Engine/Extensions/TimeRange/MyRecogniser.cs

@@ -0,0 +1,33 @@
+using System;
+
+namespace Engine.Extensions.TimeRange
+{
+    public static class MyRecogniser
+    {
+        public static DateTime RecogniseFromObject(object o)
+        {
+            switch (o)
+            {
+                case null:
+                    throw new ArgumentException("Unable to treat NULL as a DateTime");
+                case DateTime d:
+                    return d;
+                case int unixTimeShort:
+                    return ((long) unixTimeShort).FromUnixTime();
+                case long unixTime:
+                    return unixTime.FromUnixTime();
+                case string str when long.TryParse(str, out var unixTime2):
+                    return unixTime2.FromUnixTime();
+                case string str:
+                {
+                    var val = TimeRangeRecogniser.Recognise(str);
+                    if (val is DateTime t)
+                        return t;
+                    throw new ArgumentException($"Unable to interpret '{str}' as a DateTime");
+                }
+                default:
+                    throw new ArgumentException("Unable to treat argument as DateTime");
+            }
+        }
+    }
+}

Engine/Extensions/TimeRange/TimeRange.cs

@@ -0,0 +1,31 @@
+using System;
+using System.Linq;
+
+namespace Engine.Extensions.TimeRange
+{
+    /// <summary>
+    /// Represents a range of time... Start to End
+    /// </summary>
+    public class TimeRange
+    {
+        public static readonly TimeRange Zero = new(DateTime.MinValue, DateTime.MinValue);
+
+        public DateTime End { get; set; }
+
+        public DateTime Start { get; set; }
+
+        public TimeRange(DateTime t, TimeSpan span) : this(t, t + span)
+        {
+        }
+
+        public TimeRange(DateTime t, DateTime end)
+        {
+            Start = t;
+            End = end;
+        }
+
+        public TimeSpan Duration => End - Start;
+
+        public static TimeRange CreateEnclosingRange(DateTime[] startDates) => new(startDates.Min(), startDates.Max());
+    }
+}

Engine/Extensions/TimeRange/TimeRangeMethods.cs

@@ -0,0 +1,29 @@
+using System;
+
+namespace Engine.Extensions.TimeRange
+{
+    /// <summary>
+    ///     Provides some helpful functions for templates
+    /// </summary>
+    public static class TimeRangeMethods
+    {
+        public static bool After(object a, object b) => Recognise(a) > Recognise(b);
+
+        public static bool Before(object a, object b) => Recognise(a) < Recognise(b);
+
+        public static bool Within(object a, string b)
+        {
+            if (TimeRangeRecogniser.Recognise(b) is TimeRange range)
+            {
+                var da = Recognise(a);
+                return da >= range.Start && da <= range.End;
+            }
+
+            throw new ArgumentException($"Unable to interpret '{b}' as a range of time");
+        }
+
+
+        public static DateTime Recognise(object o) =>
+            MyRecogniser.RecogniseFromObject(o);
+    }
+}