README and refactor

Author: nblumhardt

README.md

@@ -1,7 +1,7 @@
 # _Serilog.Expressions_
 
-A mini-language for filtering, enriching, and formatting Serilog 
-events, ideal for embedding in JSON or XML configuration.
+An embeddable mini-language for filtering, enriching, and formatting Serilog 
+events, ideal for use in JSON or XML configuration.
 
 ## Getting started
 
@@ -31,6 +31,13 @@ Log.Logger = new LoggerConfiguration()
 Events with a `RequestPath` property that matches the expression
 will be excluded by the filter.
 
+> Note that if the expression syntax is invalid, an `ArgumentException` will
+be thrown from the `ByExcluding()` method, and by similar methods elsewhere
+in the package. To check expression syntax without throwing, see the
+`Try*()` methods in the `SerilogExpression` class.
+
+#### An `appSettings.json` JSON configuration example
+
 In [`appSettings.json` 
 configuration](https://github.com/serilog/serilog-settings-configuration) 
 this is written as:
@@ -51,10 +58,62 @@ this is written as:
 }
 ```
 
+#### An `<appSettings>` XML configuration example
+
+In [XML configuration files](https://github.com/serilog/serilog-settings-appsettings),
+this is written as:
+
+```xml
+  <appSettings>
+    <add key="serilog:using:Expressions" value="Serilog.Expressions" />
+    <add key="serilog:filter:ByExcluding.expression" value="RequestPath like '/health%'" />
+  </appSettings>
+``` 
+
 ### Enriching
 
 ### Formatting
 
 ## Language reference
 
+## Working with the raw API
+
+The package provides the class `SerilogExpression` in the `Serilog.Expressions` namespace
+for working with expressions.
 
+```csharp
+if (SerilogExpression.TryCompile("RequestPath like '/health%'", out var compiled, out var error)
+{
+    // `compiled` is a function that can be executed against `LogEvent`s:
+    var result = compiled(someEvent);
+
+    // `result` will contain a `LogEventPropertyValue`, or `null` if the result of evaluating the
+    // expression is undefined (for example if the event has no `RequestPath` property).
+    if (result is ScalarValue value &&
+        value.Value is bool matches &&
+        matches)
+    {
+        Console.WriteLine("The event matched.");
+    }
+}
+else
+{
+    // `error` describes a syntax error.
+    Console.WriteLine($"Couldn't compile the expression; {error}.");
+}
+```
+
+Compiled expression delegates return `LogEventPropertyValue` because this is the most
+convenient type to work with in many Serilog scenarios (enrichers, sinks, ...). To
+convert the result to plain-old-.NET-types like `string`, `bool`, `Dictionary<K,V>` and
+ `Array`, use the functions in the `Serilog.Expressions.ExpressionResult` class:
+ 
+```csharp
+    var result = compiled(someEvent);
+
+    // `true` only if `result` is a scalar Boolean `true`; `false` otherwise:
+    if (ExpressionResult.IsTrue(result))
+    {
+        Console.WriteLine("The event matched.");
+    }
+```

example/Sample/Program.cs

@@ -12,13 +12,11 @@ public static void Main()
         {
             SelfLog.Enable(Console.Error);
 
-            const string expr = "@l = 'Information' and AppId is not null and Items[?] like 'C%'";
-
             using var log = new LoggerConfiguration()
                 .Enrich.WithProperty("AppId", 10)
                 .Enrich.WithComputed("FirstItem", "Items[0]")
                 .Enrich.WithComputed("SourceContext", "coalesce(Substring(SourceContext, LastIndexOf(SourceContext, '.') + 1), SourceContext, '<no source>')")
-                .Filter.ByIncludingOnly(expr)
+                .Filter.ByIncludingOnly("@l = 'Information' and AppId is not null and Items[?] like 'C%'")
                 .WriteTo.Console(outputTemplate:
                     "[{Timestamp:HH:mm:ss} {Level:u3} ({SourceContext})] {Message:lj} (first item is {FirstItem}){NewLine}{Exception}")
                 .WriteTo.Console(new OutputTemplate(

src/Serilog.Expressions/Expressions/CompiledExpression.cs

@@ -1,4 +1,18 @@
-using Serilog.Events;
+// Copyright Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using Serilog.Events;
 
 #nullable enable
 

src/Serilog.Expressions/Expressions/ExpressionResult.cs

@@ -0,0 +1,38 @@
+// Copyright Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using Serilog.Events;
+using Serilog.Expressions.Runtime;
+
+namespace Serilog.Expressions
+{
+    /// <summary>
+    /// Helper functions for working with the results of <see cref="CompiledExpression"/>s.
+    /// </summary>
+    public static class ExpressionResult
+    {
+        /// <summary>
+        /// Test whether <paramref name="value"/> is <c langword="true">true</c>.
+        /// </summary>
+        /// <param name="value">The value to test, which may be <c langword="null">null</c>
+        /// if the result of evaluating an expression was undefined.</param>
+        /// <returns>Returns <c langword="true">true</c> if and only if the
+        /// <paramref name="value"/> is a scalar Boolean with the
+        /// value <c langword="true">true</c>. Returns <c langword="false">false</c>, otherwise.</returns>
+        public static bool IsTrue(LogEventPropertyValue value)
+        {
+            return Coerce.IsTrue(value);
+        }
+    }
+}

src/Serilog.Expressions/Expressions/LoggingFilterSwitch.cs

@@ -82,7 +82,7 @@ public bool IsEnabled(LogEvent logEvent)
             if (filter == null)
                 return true;
 
-            return Coerce.True(filter.Item2(logEvent));
+            return Coerce.IsTrue(filter.Item2(logEvent));
         }
 
         /// <inheritdoc/>

src/Serilog.Expressions/Expressions/Runtime/Coerce.cs

@@ -38,7 +38,7 @@ public static bool Boolean(LogEventPropertyValue value, out bool boolean)
             return false;
         }
 
-        public static bool True(LogEventPropertyValue value)
+        public static bool IsTrue(LogEventPropertyValue value)
         {
             return Boolean(value, out var b) && b;
         }

src/Serilog.Expressions/Expressions/Runtime/RuntimeOperators.cs

@@ -322,12 +322,12 @@ public static LogEventPropertyValue _Internal_Any(LogEventPropertyValue items, L
 
             if (items is SequenceValue arr)
             {
-                return ScalarBoolean(arr.Elements.Any(e => Coerce.True(pred(e))));
+                return ScalarBoolean(arr.Elements.Any(e => Coerce.IsTrue(pred(e))));
             }
 
             if (items is StructureValue structure)
             {
-                return ScalarBoolean(structure.Properties.Any(e => Coerce.True(pred(e.Value))));
+                return ScalarBoolean(structure.Properties.Any(e => Coerce.IsTrue(pred(e.Value))));
             }
 
             return null;
@@ -340,12 +340,12 @@ public static LogEventPropertyValue _Internal_All(LogEventPropertyValue items, L
 
             if (items is SequenceValue arr)
             {
-                return ScalarBoolean(arr.Elements.All(e => Coerce.True(pred(e))));
+                return ScalarBoolean(arr.Elements.All(e => Coerce.IsTrue(pred(e))));
             }
 
             if (items is StructureValue structure)
             {
-                return ScalarBoolean(structure.Properties.All(e => Coerce.True(pred(e.Value))));
+                return ScalarBoolean(structure.Properties.All(e => Coerce.IsTrue(pred(e.Value))));
             }
 
             return null;

src/Serilog.Expressions/Expressions/SerilogExpression.cs

@@ -1,4 +1,18 @@
-using System;
+// Copyright Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
 using System.Linq;
 using Serilog.Expressions.Compilation;
 using Serilog.Expressions.Parsing;

src/Serilog.Expressions/LoggerEnrichmentConfigurationExtensions.cs

@@ -43,7 +43,7 @@ public static LoggerConfiguration When(
             if (configureEnricher == null) throw new ArgumentNullException(nameof(configureEnricher));
 
             var compiled = SerilogExpression.Compile(expression);
-            return loggerEnrichmentConfiguration.When(e => Coerce.True(compiled(e)), configureEnricher);
+            return loggerEnrichmentConfiguration.When(e => Coerce.IsTrue(compiled(e)), configureEnricher);
         }
 
         /// <summary>

src/Serilog.Expressions/LoggerFilterConfigurationExtensions.cs

@@ -24,7 +24,7 @@ public static LoggerConfiguration ByIncludingOnly(this LoggerFilterConfiguration
             if (expression == null) throw new ArgumentNullException(nameof(expression));
 
             var compiled = SerilogExpression.Compile(expression);
-            return loggerFilterConfiguration.ByIncludingOnly(e => Coerce.True(compiled(e)));
+            return loggerFilterConfiguration.ByIncludingOnly(e => Coerce.IsTrue(compiled(e)));
         }
 
         /// <summary>
@@ -39,7 +39,7 @@ public static LoggerConfiguration ByExcluding(this LoggerFilterConfiguration log
             if (expression == null) throw new ArgumentNullException(nameof(expression));
 
             var compiled = SerilogExpression.Compile(expression);
-            return loggerFilterConfiguration.ByExcluding(e => Coerce.True(compiled(e)));
+            return loggerFilterConfiguration.ByExcluding(e => Coerce.IsTrue(compiled(e)));
         }
 
         /// <summary>