Merge pull request #2 from andrej-dyck/feature/make-expectation-messa…

…ge-optional

Make expectation message optional

DotNet.Extensions.Require.Test/ChecksTests.cs

@@ -11,6 +11,12 @@ public void Check_ThrowsCheckFailed_WhenRequirementIsNotSatisfied() =>
             () => 1.Check(v => v != 1, expectation: "message")
         )?.WithMessage("message");
 
+    [Test]
+    public void Check_UsesArgumentExpressionAsExpectation_WhenNoMessageIsGiven() =>
+        Assert.Throws<CheckFailed>(
+            () => 1.Check(v => v != 1)
+        )?.WithMessage("expected: v => v != 1");
+
     [Test]
     public void Check_DoesNotThrow_WhenRequirementIsSatisfied() =>
         Assert.DoesNotThrow(

DotNet.Extensions.Require.Test/PreconditionsTests.cs

@@ -32,6 +32,12 @@ public sealed class BasicRequire : PreconditionsTests
 {
     protected override T Require<T>(T subject, bool condition, string expectation = "") =>
         subject.Require(condition, expectation);
+
+    [Test]
+    public void Require_UsesArgumentExpressionAsExpectation_WhenNoMessageIsGiven() =>
+        Assert.Throws<ArgumentException>(
+            () => 1.Require(condition: 1 < 0)
+        )?.WithMessage("expected: 1 < 0");
 }
 
 public sealed class RequireWithLazyMessage : PreconditionsTests
@@ -83,6 +89,12 @@ public sealed class RequireWithPredicateAndConstantMessage : RequireWithPredicat
 {
     protected override T Require<T>(T subject, Predicate<T> requirement, string expectation = "") =>
         subject.Require(requirement, expectation);
+
+    [Test]
+    public void Require_UsesArgumentExpression_WhenNoExpectationMessageIsGiven() =>
+        Assert.Throws<ArgumentException>(
+            () => 1.Require(requirement: n => n < 0)
+        )?.WithMessage("expected: n => n < 0");
 }
 
 public sealed class RequireWithPredicateAndLazyMessage : RequireWithPredicate
@@ -111,6 +123,8 @@ public void Require_CanUseTheValue_ToConstructTheExpectation() =>
     [Test]
     public void Require_DoesNotBuildExpectationMessage_WhenRequirementIsSatisfied() =>
         Assert.DoesNotThrow(
-            () => 1.Require(requirement: _ => true, value => throw new NUnitException($"must not be called for {value}"))
+            () => 1.Require(
+                requirement: _ => true,
+                value => throw new NUnitException($"must not be called for {value}"))
         );
 }

DotNet.Extensions.Require/Checks.cs

@@ -1,9 +1,17 @@
-namespace DotNet.Extensions.Require;
+using System.Runtime.CompilerServices;
+
+namespace DotNet.Extensions.Require;
 
 public static class Checks
 {
-    public static T Check<T>(this T @this, Predicate<T> requirement, string expectation) =>
-        requirement(@this) ? @this : throw new CheckFailed(expectation);
+    public static T Check<T>(
+        this T @this,
+        Predicate<T> requirement,
+        string? expectation = null,
+        [CallerArgumentExpression("requirement")]
+        string argExpr = "?"
+    ) =>
+        requirement(@this) ? @this : throw new CheckFailed(expectation ?? $"expected: {argExpr}");
 
     public static T Check<T>(this T @this, Predicate<T> requirement, Func<string> expectation) =>
         requirement(@this) ? @this : throw new CheckFailed(expectation());

DotNet.Extensions.Require/Preconditions.cs

@@ -1,18 +1,32 @@
-namespace DotNet.Extensions.Require;
+using System.Runtime.CompilerServices;
+
+namespace DotNet.Extensions.Require;
 
 public static class Preconditions
 {
-    public static T Require<T>(this T @this, bool condition, string expectation) =>
-        condition ? @this : throw new ArgumentException(expectation);
+    public static T Require<T>(
+        this T @this,
+        bool condition,
+        string? expectation = null,
+        [CallerArgumentExpression("condition")]
+        string argExpr = "?"
+    ) =>
+        condition ? @this : throw new ArgumentException(expectation ?? $"expected: {argExpr}");
 
     public static T Require<T>(this T @this, bool condition, Func<string> expectation) =>
         condition ? @this : throw new ArgumentException(expectation());
 
     public static T Require<T>(this T @this, bool condition, Func<T, string> expectation) =>
         condition ? @this : throw new ArgumentException(expectation(@this));
 
-    public static T Require<T>(this T @this, Predicate<T> requirement, string expectation) =>
-        requirement(@this) ? @this : throw new ArgumentException(expectation);
+    public static T Require<T>(
+        this T @this,
+        Predicate<T> requirement,
+        string? expectation = null,
+        [CallerArgumentExpression("requirement")]
+        string argExpr = "?"
+    ) =>
+        requirement(@this) ? @this : throw new ArgumentException(expectation ?? $"expected: {argExpr}");
 
     public static T Require<T>(this T @this, Predicate<T> requirement, Func<string> expectation) =>
         requirement(@this) ? @this : throw new ArgumentException(expectation());

README.md

@@ -4,7 +4,7 @@
 [![codecov](https://codecov.io/gh/andrej-dyck/dotnet-extensions-require/branch/main/graph/badge.svg?token=9IL6K5CX37)](https://codecov.io/gh/andrej-dyck/dotnet-extensions-require)
 [![NuGet](https://badgen.net/nuget/v/Require-Expressions)](https://www.nuget.org/packages/Require-Expressions/)
 
-A small library that provides _pre-condition_ checks as an extension method on types. 
+A small library that provides _pre-condition_ checks as an extension method on types.
 This allows the client code to check a condition on arguments and use the value directly if no exception is thrown.
 
 ```csharp
@@ -24,18 +24,23 @@ dotnet add package Require-Expressions
 ## Examples for `Require`
 
 Basic `Require` function
+
 ```csharp
+var requestedSeats = seats.Require(condition: seats > 0);
+// throws ArgumentException with "expected: seats > 0" as message when condition is not met
+
 var requestedSeats = seats.Require(
     condition: seats > 0,
-    expectation: "expected: seats > 0"
-); // throws ArgumentException with expectation as message when condition is not met
+    expectation: "Expected positive number of seats" // or with custom expectation message
+);
 ```
 
 `Require` functions with lazily constructed expectation messages
+
 ```csharp
 var requestedSeats = seats.Require(
     condition: seats > 0,
-    expectation: () => "expected: seats > 0"
+    expectation: () => "Expected positive number of seats"
 );
 
 var requestedDate = reservationDate.Require(
@@ -45,10 +50,14 @@ var requestedDate = reservationDate.Require(
 ```
 
 `Require` functions with predicate for convenience
+
 ```csharp
+var requestedSeats = seats.Require(condition: s => s > 0);
+// throws ArgumentException with "expected: s => s > 0" as message when condition is not met
+
 var requestedSeats = seats.Require(
     condition: s => s > 0,
-    expectation: "expected: seats > 0"
+    expectation: "Expected positive number of seats" // or with custom expectation message
 );
 
 var requestedDate = reservationDate.Require(
@@ -60,14 +69,16 @@ var requestedDate = reservationDate.Require(
 ## Examples for `Check`
 
 For checks other than on arguments, the `Check` function can be used
+
 ```csharp
 var reservationRequest = JsonSerializer.Deserialize<Reservation>(request)
-    .Check(requirement: r => r.Seats > 0, expectation: "expected: seats > 0")
+    .Check(requirement: r => r.Seats > 0) // expectation message will be "expected r => r.Seats > 0"
     .Check(r => r.Date > now, r => $"Reservation date {r.Date} must be in the future")
     // throws CheckFailed with expectation as message when requirement is not satisfied
 ```
 
 With `Check`, custom exceptions can be constructed
+
 ```csharp
 var reservationRequest = JsonSerializer.Deserialize<Reservation>(request)
     .Check(r => r.Seats > 0, exception: () => new SeatsMustBePositive())
@@ -78,28 +89,34 @@ var reservationRequest = JsonSerializer.Deserialize<Reservation>(request)
 
 **Why yet another preconditions library?**
 
-Most libraries I found use precondition _statements_, while I found preconditions as _expressions_ more useful. For example, the latter allows for [_expression-bodied_ functions](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/statements-expressions-operators/expression-bodied-members).
+Most libraries I found use precondition _statements_, while I found preconditions as _expressions_ more useful.
+For example, the latter allows for [_expression-bodied_ functions](
+https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/statements-expressions-operators/expression-bodied-members
+).
 
 **I don't like extension methods**
 
-No problem, there are many other great precondition libraries. Have a look at [.Net's contracts](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.contracts?view=net-6.0).
+No problem, there are many other great precondition libraries. Have a look
+at [.Net's contracts](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.contracts?view=net-6.0).
 
 **I don't want yet another dependency**
 
 No problem, just copy&paste the code you need into your project. Or use the build-in .Net contracts.
 
 **Can you add this function too?**
 
-Probably not as I want to keep this library small and focused. But you are very welcome to post a PR. 
+Probably not as I want to keep this library small and focused. But you are very welcome to post a PR.
 
 ## Build & Test
 
 **Build project**
+
 ```shell
 dotnet build 
 ```
 
 **Run unit tests**
+
 ```shell
 dotnet test
 ```