feat: Allow passing StackTrace to helper functions

mcmah309 · Nov 25, 2024 · cd993c2 · cd993c2
1 parent 25f1eac
commit cd993c2
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 12 deletions.
diff --git a/lib/src/error.dart b/lib/src/error.dart
@@ -18,11 +18,15 @@ class Error implements Exception {
       StackTraceDisplayFormat.one;
 
   /// Modifies the stacktrace during display. Useful for adjusting number of frames to include during
-  /// display/logging. Stacktraces that are captured internally through "bail", "context", etc. or directly by calling
-  /// "Error", are always captured as
-  /// soon as possible - one stack frame below your calling code. Therefore, if you decide to prune during display,
-  /// you can comfortably prune 1 off the root and then leave as many other frames as you desire. See also the
-  /// [stack_trace] package.
+  /// display/logging. Stacktraces that are captured internally through [bail], [anyhow], 
+  /// [AnyhowResultExtension.context], etc. 
+  /// or directly by calling [Error.new], are always captured as soon as possible - one stack frame 
+  /// below the calling code. Therefore, if pruning during display is desired,
+  /// one can comfortably prune 1 off the root and then leave as many other frames as you desire.
+  /// Note passing the optional stackTrace param for functions like [bail] obviously will not hold
+  /// this guarantee.
+  /// 
+  /// See also the [stack_trace](https://pub.dev/packages/stack_trace) package.
   /// Requires [hasStackTrace] = true
   static StackTrace Function(StackTrace) stackTraceDisplayModifier = (s) => s;
 

diff --git a/lib/src/functions.dart b/lib/src/functions.dart
@@ -1,10 +1,14 @@
 part of 'error.dart';
 
 /// Convenience function for turning an object into an anyhow [Err] Result.
-Err<S> bail<S>(Object err) {
+/// [stackTrace] will be ignored if [Error.hasStackTrace] is false.
+Err<S> bail<S>(Object err, [StackTrace? stackTrace]) {
   assert(err is! Error, _isAlreadyErrorAssertionMessage);
   if (Error.hasStackTrace) {
-    return Err(Error._withStackTrace(err, StackTrace.current));
+    if (stackTrace == null) {
+      return Err(Error._withStackTrace(err, StackTrace.current));
+    }
+    return Err(Error._withStackTrace(err, stackTrace));
   }
   return Err(Error(err));
 }
@@ -15,22 +19,30 @@ Err<S> bail<S>(Object err) {
 /// final check = ensure(() => x > 1, "x should be greater than 1");
 /// if(check.isErr()) return check;
 /// ```
-Result<()> ensure(bool Function() fn, Object err) {
+/// [stackTrace] will be ignored if [Error.hasStackTrace] is false.
+Result<()> ensure(bool Function() fn, Object err, [StackTrace? stackTrace]) {
   assert(err is! Error, _isAlreadyErrorAssertionMessage);
   if (fn()) {
     return const Ok(());
   }
   if (Error.hasStackTrace) {
-    return Err(Error._withStackTrace(err, StackTrace.current));
+    if (stackTrace == null) {
+      return Err(Error._withStackTrace(err, StackTrace.current));
+    }
+    return Err(Error._withStackTrace(err, stackTrace));
   }
   return Err(Error(err));
 }
 
-/// Convenience function for turning an object into an [Error]. Same as the original "anyhow" macro.
-Error anyhow<S>(Object err) {
+/// Convenience function for turning an object into an [Error].
+/// [stackTrace] will be ignored if [Error.hasStackTrace] is false.
+Error anyhow<S>(Object err, [StackTrace? stackTrace]) {
   assert(err is! Error, _isAlreadyErrorAssertionMessage);
   if (Error.hasStackTrace) {
-    return Error._withStackTrace(err, StackTrace.current);
+    if (stackTrace == null) {
+      return Error._withStackTrace(err, StackTrace.current);
+    }
+    return Error._withStackTrace(err, stackTrace);
   }
   return Error(err);
 }