Print source chains for errors.

When an error is printed, if that error has a source, print the source. Then repeat that process until there are no more sources.

For an error with no source:

    the error message

For an error with a single source:

    the error message

    caused by:
        the source's error message

For an error message with chained sources:

    the error message

    caused by:
        the immediate source's error message
        the first transitive source's error message
        the second transitive source's error message
        …
        the ultimate source's error message

That is, sources are printed from the outermost inwards, terminating with the lowest-level source.

This printing occurs in two places: when pilcrow starts, and whenever it processes an internal server error. For internal server errors, the error message is prefixed with the error ID, as before, to allow operators to correlate log messages with responses if they choose to do so:

    [E1234] the error message

    caused by:
        the immediate source's error message
        the first transitive source's error message
        the second transitive source's error message
        …
        the ultimate source's error message

Both call sites lock stderr to try to prevent interleaving messages. No promises about how well it works.

I've not made any effort to ensure that multi-line error messages are correctly indented. So far as I know, pilcrow never emits a multi-line error message (except for long messages which are wrapped), so this likely isn't necessary. It's also surprisingly hard to do well, though there is [a crate for it][indenter].

[indenter]: https://docs.rs/indenter/latest/indenter/

There's a widespread convention for unix tools to prefix stderr output with the name of the program. For example, cat on my system prints the following when asked to open a nonexistent file:

    cat: nope: No such file or directory

I've opted not to do that for Pilcrow. By my understanding, that convention is intended to help users identify which of several programs emitted a message when several programs share a stderr channel, for example when a program is used as part of a shell pipeline.

Programs that are largely intended to be freestanding do not consistently follow the same convention - Cargo, clang, and gcc all write diagnostics to stderr with no prefix, for example. Pilcrow is, similarly, meant to be run in isolation, either as the single thing a user is running interactively, or because it's being run as a service. In either case, the prefix is not necessary to identify Pilcrow as the source of a message.

I debated making the new `Exit` type crate-private, and having `cli::Args::run` return `impl Termination` to handle the interface between the crate and the outside world. For now, I've opted to instead return a result, so that any ill-advised callers trying to use Pilcrow as a library can at least attempt to understand the structure of its return value; this entails making `Exit` public as well, so that the CLI entry point (`main.rs`) can import it.

This is an enabling change, with little immediate impact on its own. It probably makes some error messages print less than perfectly, but Pilcrow generates errors so rarely in development that it's hard to check. I'll be revising individual errors in later

1 files changed, 54 insertions, 0 deletions

diff --git a/src/exit.rs b/src/exit.rs
new file mode 100644
index 0000000..3c7b724
--- /dev/null
+++ b/src/exit.rs
@@ -0,0 +1,54 @@
+use std::{
+    error::Error,
+    io,
+    process::{ExitCode, Termination},
+};
+
+use crate::error::chain;
+
+/// Formats errors for display before exiting the program.
+///
+/// When this is used as the return type of a program's `main`, it can be used to capture any errors
+/// during the execution of the program and to display them in a readable format at exit time:
+///
+/// ```no_run
+/// # use std::{error::Error, io};
+/// fn main() -> pilcrow::cli::Exit<impl Error> {
+///     my_complicated_task().into()
+/// }
+///
+/// fn my_complicated_task() -> Result<(), impl Error> {
+///     Err(io::Error::other("stand-in for a real failure"))
+/// }
+/// ```
+///
+/// If constructed with an `Ok(())`, the resulting `Exit` indicates successful execution, and, when
+/// returned from `main`, will cause the program to exit with a successful exit status. If constructed
+/// with any `Err(…)` value, the resulting `Exit` indicates unsuccessful execution, and, when
+/// returned from `main`, will cause the program to print the error (along with its `source()`
+/// chain, if any) before exiting with an unsuccessful exit status.
+pub struct Exit<E>(pub Result<(), E>);
+
+impl<E> From<Result<(), E>> for Exit<E> {
+    fn from(result: Result<(), E>) -> Self {
+        Self(result)
+    }
+}
+
+impl<E> Termination for Exit<E>
+where
+    E: Error,
+{
+    fn report(self) -> ExitCode {
+        let Self(result) = self;
+        match result {
+            Ok(()) => ExitCode::SUCCESS,
+            Err(err) => {
+                // if we can't write the error message to stderr, there's nothing else we can do
+                // instead, and we're about to exit with a failure anyway.
+                let _ = chain::format(&mut io::stderr().lock(), &err);
+                ExitCode::FAILURE
+            }
+        }
+    }
+}