User-defined functions

Author: nblumhardt

README.md

@@ -250,3 +250,40 @@ convert the result to plain-old-.NET-types like `string`, `bool`, `Dictionary<K,
         Console.WriteLine("The event matched.");
     }
 ```
+
+## Implementing user-defined functions
+
+User-defined functions can be plugged in by implementing static methods that:
+
+ * Return `LogEventPropertyValue?`,
+ * Have arguments of type `LogEventPropertyValue?`, and
+ * If the `ci` modifier is supported, accept a `StringComparison` in the first argument position.
+ 
+For example:
+
+```csharp
+public static class MyFunctions
+{    
+    public static LogEventPropertyValue? IsFoo(
+        StringComparison comparison,
+        LogEventPropertyValue? maybeFoo)
+    {
+        if (maybeFoo is ScalarValue sv && sv.Value is string s)
+            return new ScalarValue(s.Equals("Foo", comparison));
+
+        // Undefined - argument was not a string.
+        return null;
+    }
+}
+```
+
+In the example, `IsFoo('Foo')` will evaluate to `true`, `IsFoo('FOO')` will be `false`, `IsFoo('FOO') ci`
+will be `true`, and `IsFoo(42)` will be undefined.
+
+User-defined functions are supplied through an instance of `NameResolver`:
+
+```csharp
+var myFunctions = new StaticMemberNameResolver(typeof(MyFunctions));
+var expr = SerilogExpression.Compile("IsFoo(User.Name)", new[] { myFunctions });
+// Filter events based on whether `User.Name` is `'Foo'` :-)
+```

src/Serilog.Expressions/Expressions/Compilation/Arrays/ConstantArrayEvaluator.cs

@@ -2,7 +2,6 @@
 using Serilog.Events;
 using Serilog.Expressions.Ast;
 using Serilog.Expressions.Compilation.Transformations;
-using Serilog.Expressions.Runtime;
 
 namespace Serilog.Expressions.Compilation.Arrays
 {

src/Serilog.Expressions/Expressions/Compilation/DefaultFunctionNameResolver.cs

@@ -0,0 +1,18 @@
+using System.Collections.Generic;
+using System.Linq;
+using Serilog.Expressions.Runtime;
+
+namespace Serilog.Expressions.Compilation
+{
+    static class DefaultFunctionNameResolver
+    {
+        public static NameResolver Build(IEnumerable<NameResolver>? orderedResolvers)
+        {
+            var defaultResolver = new StaticMemberNameResolver(typeof(RuntimeOperators));
+            return orderedResolvers == null
+                ? (NameResolver) defaultResolver
+                : new OrderedNameResolver(
+                    new NameResolver[] {defaultResolver}.Concat(orderedResolvers));
+        }
+    }
+}

src/Serilog.Expressions/Expressions/Compilation/ExpressionCompiler.cs

@@ -10,7 +10,7 @@ namespace Serilog.Expressions.Compilation
 {
     static class ExpressionCompiler
     {
-        public static CompiledExpression Compile(Expression expression)
+        public static CompiledExpression Compile(Expression expression, NameResolver nameResolver)
         {
             var actual = expression;
             actual = VariadicCallRewriter.Rewrite(actual);
@@ -20,7 +20,7 @@ public static CompiledExpression Compile(Expression expression)
             actual = ConstantArrayEvaluator.Evaluate(actual);
             actual = WildcardComprehensionTransformer.Expand(actual);
 
-            return LinqExpressionCompiler.Compile(actual);
+            return LinqExpressionCompiler.Compile(actual, nameResolver);
         }
     }
 }

src/Serilog.Expressions/Expressions/Compilation/Linq/Intrinsics.cs

@@ -4,7 +4,6 @@
 using System.Linq;
 using System.Text.RegularExpressions;
 using Serilog.Events;
-using Serilog.Expressions.Runtime;
 using Serilog.Formatting.Display;
 
 namespace Serilog.Expressions.Compilation.Linq

src/Serilog.Expressions/Expressions/Compilation/Linq/LinqExpressionCompiler.cs

@@ -6,7 +6,6 @@
 using Serilog.Events;
 using Serilog.Expressions.Ast;
 using Serilog.Expressions.Compilation.Transformations;
-using Serilog.Expressions.Runtime;
 using ConstantExpression = Serilog.Expressions.Ast.ConstantExpression;
 using Expression = Serilog.Expressions.Ast.Expression;
 using ParameterExpression = System.Linq.Expressions.ParameterExpression;
@@ -17,10 +16,7 @@ namespace Serilog.Expressions.Compilation.Linq
 {
     class LinqExpressionCompiler : SerilogExpressionTransformer<ExpressionBody>
     {
-        static readonly IDictionary<string, MethodInfo> OperatorMethods = typeof(RuntimeOperators)
-            .GetTypeInfo()
-            .GetMethods(BindingFlags.Static | BindingFlags.Public)
-            .ToDictionary(m => m.Name, StringComparer.OrdinalIgnoreCase);
+        readonly NameResolver _nameResolver;
 
         static readonly MethodInfo ConstructSequenceValueMethod = typeof(Intrinsics)
             .GetMethod(nameof(Intrinsics.ConstructSequenceValue), BindingFlags.Static | BindingFlags.Public)!;
@@ -38,11 +34,16 @@ class LinqExpressionCompiler : SerilogExpressionTransformer<ExpressionBody>
             .GetMethod(nameof(Intrinsics.TryGetStructurePropertyValue), BindingFlags.Static | BindingFlags.Public)!;
 
         ParameterExpression Context { get; } = LX.Variable(typeof(LogEvent), "evt");
+
+        public LinqExpressionCompiler(NameResolver nameResolver)
+        {
+            _nameResolver = nameResolver;
+        }
 
-        public static CompiledExpression Compile(Expression expression)
+        public static CompiledExpression Compile(Expression expression, NameResolver nameResolver)
         {
             if (expression == null) throw new ArgumentNullException(nameof(expression));
-            var compiler = new LinqExpressionCompiler();
+            var compiler = new LinqExpressionCompiler(nameResolver);
             var body = compiler.Transform(expression); 
             return LX.Lambda<CompiledExpression>(body, compiler.Context).Compile();
         }
@@ -54,8 +55,8 @@ ExpressionBody Splice(Expression<CompiledExpression> lambda)
 
         protected override ExpressionBody Transform(CallExpression lx)
         {
-            if (!OperatorMethods.TryGetValue(lx.OperatorName, out var m))
-                throw new ArgumentException($"The function name `{lx.OperatorName}` was not recognised.");
+            if (!_nameResolver.TryResolveFunctionName(lx.OperatorName, out var m))
+                throw new ArgumentException($"The function name `{lx.OperatorName}` was not recognized.");
 
             var parameterCount = m.GetParameters().Count(pi => pi.ParameterType == typeof(LogEventPropertyValue));
             if (parameterCount != lx.Operands.Length)

src/Serilog.Expressions/Expressions/Compilation/OrderedNameResolver.cs

@@ -0,0 +1,29 @@
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Reflection;
+
+namespace Serilog.Expressions.Compilation
+{
+    class OrderedNameResolver : NameResolver
+    {
+        readonly NameResolver[] _orderedResolvers;
+
+        public OrderedNameResolver(IEnumerable<NameResolver> orderedResolvers)
+        {
+            _orderedResolvers = orderedResolvers.ToArray();
+        }
+
+        public override bool TryResolveFunctionName(string name, [MaybeNullWhen(false)] out MethodInfo implementation)
+        {
+            foreach (var resolver in _orderedResolvers)
+            {
+                if (resolver.TryResolveFunctionName(name, out implementation))
+                    return true;
+            }
+
+            implementation = null;
+            return false;
+        }
+    }
+}

src/Serilog.Expressions/Expressions/NameResolver.cs

@@ -0,0 +1,24 @@
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Reflection;
+using Serilog.Events;
+
+namespace Serilog.Expressions
+{
+    /// <summary>
+    /// Looks up the implementations of functions that appear in expressions.
+    /// </summary>
+    public abstract class NameResolver
+    {
+        /// <summary>
+        /// Match a function name to a method that implements it.
+        /// </summary>
+        /// <param name="name">The function name as it appears in the expression source. Names are not case-sensitive.</param>
+        /// <param name="implementation">A <see cref="MethodInfo"/> implementing the function.</param>
+        /// <returns><c>True</c> if the name could be resolved; otherwise, <c>false</c>.</returns>
+        /// <remarks>The method implementing a function should be <c>static</c>, return <see cref="LogEventPropertyValue"/>,
+        /// and accept parameters of type <see cref="LogEventPropertyValue"/>. If the <c>ci</c> modifier is supported,
+        /// a <see cref="StringComparison"/> should be in the first argument position.</remarks>
+        public abstract bool TryResolveFunctionName(string name, [MaybeNullWhen(false)] out MethodInfo implementation);
+    }
+}

src/Serilog.Expressions/Expressions/SerilogExpression.cs

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 using System;
+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using Serilog.Expressions.Compilation;
@@ -31,10 +32,15 @@ public static class SerilogExpression
         /// Create an evaluation function based on the provided expression.
         /// </summary>
         /// <param name="expression">An expression.</param>
+        /// <param name="orderedResolvers">Optionally, an ordered list of <see cref="NameResolver"/>s
+        /// from which to resolve function names that appear in the template.</param>
         /// <returns>A function that evaluates the expression in the context of a log event.</returns>
-        public static CompiledExpression Compile(string expression)
+        public static CompiledExpression Compile(
+            string expression,
+            IEnumerable<NameResolver>? orderedResolvers = null)
         {
-            if (!TryCompile(expression, out var filter, out var error))
+            if (expression == null) throw new ArgumentNullException(nameof(expression));
+            if (!TryCompileImpl(expression, orderedResolvers, out var filter, out var error))
                 throw new ArgumentException(error);
 
             return filter;
@@ -53,14 +59,46 @@ public static bool TryCompile(
             string expression,
             [MaybeNullWhen(false)] out CompiledExpression result,
             [MaybeNullWhen(true)] out string error)
+        {
+            if (expression == null) throw new ArgumentNullException(nameof(expression));
+            return TryCompileImpl(expression, null, out result, out error);
+        }
+
+        /// <summary>
+        /// Create an evaluation function based on the provided expression.
+        /// </summary>
+        /// <param name="expression">An expression.</param>
+        /// <param name="result">A function that evaluates the expression in the context of a log event.</param>
+        /// <param name="error">The reported error, if compilation was unsuccessful.</param>
+        /// <param name="orderedResolvers">An ordered list of <see cref="NameResolver"/>s
+        /// from which to resolve function names that appear in the template.</param>
+        /// <returns>True if the function could be created; otherwise, false.</returns>
+        /// <remarks>Regular expression syntax errors currently generate exceptions instead of producing friendly
+        /// errors.</remarks>
+        public static bool TryCompile(
+            string expression,
+            IEnumerable<NameResolver> orderedResolvers,
+            [MaybeNullWhen(false)] out CompiledExpression result,
+            [MaybeNullWhen(true)] out string error)
+        {
+            if (expression == null) throw new ArgumentNullException(nameof(expression));
+            if (orderedResolvers == null) throw new ArgumentNullException(nameof(orderedResolvers));
+            return TryCompileImpl(expression, orderedResolvers, out result, out error);
+        }
+        
+        static bool TryCompileImpl(
+            string expression,
+            IEnumerable<NameResolver>? orderedResolvers,
+            [MaybeNullWhen(false)] out CompiledExpression result,
+            [MaybeNullWhen(true)] out string error)
         {
             if (!ExpressionParser.TryParse(expression, out var root, out error))
             {
                 result = null;
                 return false;
             }
 
-            result = ExpressionCompiler.Compile(root);
+            result = ExpressionCompiler.Compile(root, DefaultFunctionNameResolver.Build(orderedResolvers));
             error = null;
             return true;
         }

src/Serilog.Expressions/Expressions/StaticMemberNameResolver.cs

@@ -0,0 +1,35 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+
+namespace Serilog.Expressions
+{
+    /// <summary>
+    /// A <see cref="NameResolver"/> that matches public static members of a class by name.
+    /// </summary>
+    public class StaticMemberNameResolver : NameResolver
+    {
+        readonly IReadOnlyDictionary<string, MethodInfo> _methods;
+
+        /// <summary>
+        /// Create a <see cref="StaticMemberNameResolver"/> that returns members of the specified <see cref="Type"/>.
+        /// </summary>
+        /// <param name="type">A <see cref="Type"/> with public static members implementing runtime functions.</param>
+        public StaticMemberNameResolver(Type type)
+        {
+            if (type == null) throw new ArgumentNullException(nameof(type));
+
+            _methods = type
+                .GetTypeInfo()
+                .GetMethods(BindingFlags.Static | BindingFlags.Public)
+                .ToDictionary(m => m.Name, StringComparer.OrdinalIgnoreCase);
+        }
+        
+        /// <inheritdoc />
+        public override bool TryResolveFunctionName(string name, out MethodInfo implementation)
+        {
+            return _methods.TryGetValue(name, out implementation);
+        }
+    }
+}