Add UncaughtExceptionHandler, improve README

Author: DavidGregory084

README.md

@@ -26,7 +26,117 @@ Maven (pom.xml):
 </dependency>
 ```
 
-## Usage
+To use the `GraphicalReportHandler` and other features of the package `com.opencastsoftware.yvette.handlers.graphical`, the [jansi](https://github.com/fusesource/jansi) library is also needed:
+
+Gradle (build.gradle / build.gradle.kts):
+```groovy
+implementation("org.fusesource.jansi:jansi:2.4.0")
+```
+
+Maven (pom.xml):
+```xml
+<dependency>
+    <groupId>org.fusesource.jansi</groupId>
+    <artifactId>jansi</artifactId>
+    <version>2.4.0</version>
+</dependency>
+```
+
+## Displaying diagnostics
+
+In order to display diagnostics with *yvette*, your application's error messages must implement the abstract class [Diagnostic](./src/main/java/com/opencastsoftware/yvette/Diagnostic.java). All of the methods of this class may return `null`, but bear in mind that your diagnostics may not be very helpful without a `message`.
+
+A [BasicDiagnostic](./src/main/java/com/opencastsoftware/yvette/BasicDiagnostic.java) implementation is provided, which can be used to wrap exceptions:
+
+```java
+Diagnostic err = new BasicDiagnostic(e.getMessage(), e.getCause());
+```
+
+You can then implement a [ReportHandler](./src/main/java/com/opencastsoftware/yvette/handlers/ReportHandler.java) to display your diagnostics using the [Appendable](https://docs.oracle.com/javase/8/docs/api/java/lang/Appendable.html) instance you wish to use for output, for example [System.out](https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#out), [System.err](https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#err) or a [StringBuilder](https://docs.oracle.com/javase/8/docs/api/java/lang/StringBuilder.html).
+
+*yvette* provides a [GraphicalReportHandler](./src/main/java/com/opencastsoftware/yvette/handlers/graphical/GraphicalReportHandler.java) which produces output like the screenshot above. You can create one of these using the `GraphicalReportHandler.builder()` static method:
+
+```java
+ReportHandler reportHandler = GraphicalReportHandler.builder()
+    .withRgbColours(RgbColours.PREFERRED)
+    .buildFor(System.err);
+```
+
+There are some terminal feature detection features in *yvette*. If you wish to bypass these, use the `withColours`, `withTerminalWidth` and `withUnicode` methods of the builder to enable or disable those features explicitly. However, please bear in mind that using `withColours` to force enable colour output will override the [NO_COLOR](https://no-color.org/) detection implemented by this library.
+
+Once you have a [ReportHandler](./src/main/java/com/opencastsoftware/yvette/handlers/ReportHandler.java), it can be used to output diagnostics:
+
+```java
+Diagnostic diagnostic = ???; // A diagnostic from your application
+reportHandler.display(diagnostic, System.err);
+```
+
+## Uncaught exception handler
+
+*yvette* provides an implementation of [Thread.UncaughtExceptionHandler](https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.UncaughtExceptionHandler.html) which can be used to replace the default handler for all threads.
+
+```java
+import com.opencastsoftware.yvette.UncaughtExceptionHandler;
+
+ReportHandler handler = ???; // Your report handler, obtained as described above
+
+try {
+    UncaughtExceptionHandler.install(handler, System.err); // Installs the new handler
+} finally {
+    UncaughtExceptionHandler.uninstall(); // Restores the default handler
+}
+```
+
+The setup above will print diagnostics to STDERR:
+
+```java
+new Thread(() -> {
+    Throwable exc = new FileNotFoundException("Couldn't find the file BadFile.java");
+    exc.initCause(new AccessDeniedException("Access denied to file BadFile.java"));
+    throw new RuntimeException("Whoops!", exc);
+}).start();
+
+/*
+Uncaught exception in thread Thread-5:
+    x Whoops!
+    |-> Couldn't find the file BadFile.java
+    `-> Access denied to file BadFile.java
+
+java.lang.RuntimeException: Whoops!
+    at com.opencastsoftware.yvette.UncaughtExceptionHandlerTest.lambda$replacesThreadPoolHandler$2(UncaughtExceptionHandlerTest.java:87)
+    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
+    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
+    at java.lang.Thread.run(Thread.java:750)
+Caused by: java.io.FileNotFoundException: Couldn't find the file BadFile.java
+    at com.opencastsoftware.yvette.UncaughtExceptionHandlerTest.lambda$replacesThreadPoolHandler$2(UncaughtExceptionHandlerTest.java:85)
+    ... 3 more
+Caused by: java.nio.file.AccessDeniedException: Access denied to file BadFile.java
+    at com.opencastsoftware.yvette.UncaughtExceptionHandlerTest.lambda$replacesThreadPoolHandler$2(UncaughtExceptionHandlerTest.java:86)
+    ... 3 more
+*/
+```
+
+It can also be set as the uncaught exception handler for new threads in a thread pool by using a [ThreadFactory](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadFactory.html):
+
+```java
+Thread.UncaughtExceptionHandler excHandler = UncaughtExceptionHandler.create(handler, System.err);
+
+ThreadFactory threadFactory = runnable -> {
+    Thread thread = new Thread(runnable);
+    thread.setUncaughtExceptionHandler(excHandler);
+    thread.setDaemon(true);
+    return newThread;
+};
+```
+
+## Deviations and Limitations
+
+This is not an exact port of *miette* - there are some differences and unported features:
+
+* Where *miette* and the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/)'s definitions deviate, we have erred on the side of alignment with LSP. This is for ease of integrating *yvette* with language server applications. For example, *miette* uses `SourceSpan` to keep track of the byte offset and length of a span within a source file. However, *yvette*'s equivalent of `SourceSpan` is called `Range`, and specifies a start and end `Position`, each of which refers to a zero-indexed line and character position within a document. The upside of this is alignment with LSP, but the downside is that we can no longer efficiently read arbitrary offsets of a source file in order to get the span contents.
+* Only the `GraphicalReportHandler` and `ToStringReportHandler` are currently implemented, there is no `NarratableReportHandler` or `JSONReportHandler` as yet.
+* There is no special handling of tab characters or [unicode character width](https://crates.io/crates/unicode-width) in *yvette* yet, which may mean that your highlights are misaligned with the source code they are supposed to underline.
+* Related diagnostics are not currently implemented in *yvette*, since the definition of `DiagnosticRelatedInformation` is sufficiently different in the Language Server Protocol that we haven't decided how to implement it yet.
 
 ## Acknowlegements
 

build.gradle.kts

@@ -106,7 +106,7 @@ nexusPublishing {
 }
 
 tasks.named<Test>("test") {
-    useJUnitPlatform() {
+    useJUnitPlatform {
         includeEngines("junit-jupiter", "jqwik")
     }
 }

src/main/java/com/opencastsoftware/yvette/BasicDiagnostic.java

@@ -0,0 +1,87 @@
+package com.opencastsoftware.yvette;
+
+import java.net.URI;
+import java.util.Collection;
+
+public class BasicDiagnostic extends Diagnostic {
+    public String code;
+    public Severity severity;
+    public String help;
+    public URI url;
+    public SourceCode sourceCode;
+    public Collection<LabelledRange> labels;
+
+    public BasicDiagnostic(String message) {
+        this(null, Severity.Error, message, null, null, null, null);
+    }
+
+    public BasicDiagnostic(
+            String message,
+            Throwable cause) {
+        this(null, Severity.Error, message, cause, null, null, null, null);
+    }
+
+    public BasicDiagnostic(
+            String message,
+            Throwable cause,
+            URI url) {
+        this(null, Severity.Error, message, cause, null, url, null, null);
+    }
+
+    public BasicDiagnostic(
+            String code,
+            Severity severity,
+            String message,
+            String help,
+            URI url,
+            SourceCode sourceCode,
+            Collection<LabelledRange> labels) {
+        super(message);
+    }
+
+    public BasicDiagnostic(
+            String code,
+            Severity severity,
+            String message, Throwable cause,
+            String help,
+            URI url,
+            SourceCode sourceCode,
+            Collection<LabelledRange> labels) {
+        super(message, cause);
+    }
+
+    @Override
+    public String code() {
+        return code;
+    }
+
+    @Override
+    public Severity severity() {
+        return severity;
+    }
+
+    @Override
+    public String message() {
+        return getMessage();
+    }
+
+    @Override
+    public String help() {
+        return help;
+    }
+
+    @Override
+    public URI url() {
+        return url;
+    }
+
+    @Override
+    public SourceCode sourceCode() {
+        return sourceCode;
+    }
+
+    @Override
+    public Collection<LabelledRange> labels() {
+        return labels;
+    }
+}

src/main/java/com/opencastsoftware/yvette/UncaughtExceptionHandler.java

@@ -0,0 +1,43 @@
+package com.opencastsoftware.yvette;
+
+import java.io.IOException;
+import java.io.PrintStream;
+
+import com.opencastsoftware.yvette.handlers.ReportHandler;
+
+public class UncaughtExceptionHandler {
+    private static volatile Thread.UncaughtExceptionHandler previous;
+
+    private UncaughtExceptionHandler() {
+    }
+
+    static {
+        previous = Thread.getDefaultUncaughtExceptionHandler();
+    }
+
+    public static Thread.UncaughtExceptionHandler create(ReportHandler handler, PrintStream output) {
+        return (thread, exc) -> {
+            Diagnostic diagnostic = new BasicDiagnostic(exc.getMessage(), exc.getCause());
+
+            output.format("Uncaught exception in thread %s: ", thread.getName());
+
+            try {
+                handler.display(diagnostic, output);
+                output.println();
+                exc.printStackTrace(output);
+            } catch (IOException ioe) {
+                ioe.addSuppressed(exc);
+                ioe.printStackTrace(output);
+            }
+        };
+    }
+
+    public static void install(ReportHandler handler, PrintStream output) {
+        previous = Thread.getDefaultUncaughtExceptionHandler();
+        Thread.setDefaultUncaughtExceptionHandler(create(handler, output));
+    }
+
+    public static void uninstall() {
+        Thread.setDefaultUncaughtExceptionHandler(previous);
+    }
+}

src/main/java/com/opencastsoftware/yvette/handlers/graphical/ColourSupport.java

@@ -8,7 +8,7 @@ public enum ColourSupport {
 
     private final int level;
 
-    private ColourSupport(int level) {
+    ColourSupport(int level) {
         this.level = level;
     }
 

src/main/java/com/opencastsoftware/yvette/handlers/graphical/GraphicalReportHandler.java

@@ -27,7 +27,7 @@ public class GraphicalReportHandler implements ReportHandler {
     private final int contextLines;
     private final boolean renderCauseChain;
 
-    private final Pattern ansiEscapePattern = Pattern.compile("\\u001B\\[[;\\d]*m");
+    private static final Pattern ansiEscapePattern = Pattern.compile("\\u001B\\[[;\\d]*m");
 
     public GraphicalReportHandler(LinkStyle linkStyle, int terminalWidth, GraphicalTheme theme, String footer,
             int contextLines, boolean renderCauseChain) {
@@ -557,7 +557,7 @@ void renderHelp(Ansi ansi, Diagnostic diagnostic) throws IOException {
     }
 
     void renderRelated(Ansi ansi, Diagnostic diagnostic, SourceCode source) {
-
+        // TODO: Figure out how to align this with LSP
     }
 
     void renderFooter(Ansi ansi) throws IOException {
@@ -604,7 +604,6 @@ public int hashCode() {
         result = prime * result + ((footer == null) ? 0 : footer.hashCode());
         result = prime * result + contextLines;
         result = prime * result + (renderCauseChain ? 1231 : 1237);
-        result = prime * result + ((ansiEscapePattern == null) ? 0 : ansiEscapePattern.hashCode());
         return result;
     }
 
@@ -635,11 +634,6 @@ public boolean equals(Object obj) {
             return false;
         if (renderCauseChain != other.renderCauseChain)
             return false;
-        if (ansiEscapePattern == null) {
-            if (other.ansiEscapePattern != null)
-                return false;
-        } else if (!ansiEscapePattern.equals(other.ansiEscapePattern))
-            return false;
         return true;
     }
 
@@ -711,13 +705,7 @@ public Builder withContextLines(int contextLines) {
         }
 
         public GraphicalReportHandler buildFor(Appendable output) {
-            int width;
-
-            if (terminalWidth.isPresent()) {
-                width = terminalWidth.get();
-            } else {
-                width = TerminalSupport.terminalWidth(output);
-            }
+            int width = terminalWidth.orElseGet(() -> TerminalSupport.terminalWidth(output));
 
             LinkStyle linkStyle;
             if (enableTerminalLinks.isPresent()) {

src/main/java/com/opencastsoftware/yvette/handlers/graphical/RgbColours.java

@@ -3,5 +3,5 @@
 public enum RgbColours {
     NEVER,
     PREFERRED,
-    ALWAYS;
+    ALWAYS
 }

src/main/java/com/opencastsoftware/yvette/handlers/graphical/RgbThemeStyles.java

@@ -49,7 +49,7 @@ public UnaryOperator<Ansi> lineNumber() {
 
     @Override
     public UnaryOperator<Ansi> reset() {
-        return ansi -> ansi.reset();
+        return Ansi::reset;
     }
 
     @Override

src/main/java/com/opencastsoftware/yvette/handlers/graphical/TerminalSupport.java

@@ -204,12 +204,12 @@ static boolean envVarSet(String varName) {
 
     static boolean envVarIn(String varName, String... values) {
         String varValue = System.getenv(varName);
-        return varValue != null && Arrays.stream(values).anyMatch(v -> v.equals(varValue));
+        return varValue != null && Arrays.asList(values).contains(varValue);
     }
 
     static boolean envVarNotIn(String varName, String... values) {
         String varValue = System.getenv(varName);
-        return varValue != null && Arrays.stream(values).noneMatch(v -> v.equals(varValue));
+        return varValue != null && !Arrays.asList(values).contains(varValue);
     }
 
     static boolean envVarMatches(String varName, Predicate<String> valueFn) {
@@ -219,7 +219,7 @@ static boolean envVarMatches(String varName, Predicate<String> valueFn) {
 
     static boolean envVarEquals(String varName, String onValue) {
         String varValue = System.getenv(varName);
-        return varValue != null && onValue.equals(varValue);
+        return onValue.equals(varValue);
     }
 
     static boolean envVarNotEquals(String varName, String offValue) {

src/main/java/com/opencastsoftware/yvette/handlers/graphical/ThemeStyles.java

@@ -47,23 +47,6 @@ default UnaryOperator<Ansi> forSeverity(Severity severity) {
         return style;
     }
 
-    static ThemeStyles forColourLevel(ColourSupport level) {
-        ThemeStyles styles = null;
-
-        switch (level) {
-            case COLOUR_16:
-                styles = ansi();
-            case COLOUR_256:
-                styles = ansi();
-            case COLOUR_16M:
-                styles = rgb();
-            case NONE:
-                styles = none();
-        }
-
-        return styles;
-    }
-
     static ThemeStyles ansi() {
         return new AnsiThemeStyles();
     }