Switch the nativeSignals boolean to true by default (#971)

terminal/src/main/java/org/jline/terminal/Terminal.java

@@ -43,6 +43,9 @@ public interface Terminal extends Closeable, Flushable {
     // Signal support
     //
 
+    /**
+     * Types of signals.
+     */
     enum Signal {
         INT,
         QUIT,
@@ -52,11 +55,29 @@ enum Signal {
         WINCH
     }
 
+    /**
+     * The SignalHandler defines the interface used to trap signals and perform specific behaviors.
+     * @see Terminal.Signal
+     * @see Terminal#handle(Signal, SignalHandler)
+     */
     interface SignalHandler {
 
+        /**
+         * The {@code SIG_DFL} value can be used to specify that the JVM default behavior
+         * should be used to handle this signal.
+         */
         SignalHandler SIG_DFL = NativeSignalHandler.SIG_DFL;
+
+        /**
+         * The {@code SIG_IGN} value can be used to ignore this signal and not perform
+         * any special processing.
+         */
         SignalHandler SIG_IGN = NativeSignalHandler.SIG_IGN;
 
+        /**
+         * Handle the signal.
+         * @param signal the signal
+         */
         void handle(Signal signal);
     }
 
@@ -72,6 +93,17 @@ interface SignalHandler {
      */
     SignalHandler handle(Signal signal, SignalHandler handler);
 
+    /**
+     * Raise the specific signal.
+     * This is not method usually called by non system terminals.
+     * When accessing a terminal through a SSH or Telnet connection, signals may be
+     * conveyed by the protocol and thus need to be raised when reaching the terminal code.
+     * The terminals do that automatically when the terminal input stream has a character
+     * mapped to {@link Attributes.ControlChar#VINTR}, {@link Attributes.ControlChar#VQUIT},
+     * or {@link Attributes.ControlChar#VSUSP}.
+     *
+     * @param signal the signal to raise
+     */
     void raise(Signal signal);
 
     //

terminal/src/main/java/org/jline/terminal/TerminalBuilder.java

@@ -171,7 +171,7 @@ public static TerminalBuilder builder() {
     private Boolean color;
     private Attributes attributes;
     private Size size;
-    private boolean nativeSignals = false;
+    private boolean nativeSignals = true;
     private Terminal.SignalHandler signalHandler = Terminal.SignalHandler.SIG_DFL;
     private boolean paused = false;
 
@@ -347,6 +347,12 @@ public TerminalBuilder nativeSignals(boolean nativeSignals) {
         return this;
     }
 
+    /**
+     * Determines the default value for signal handlers.
+     * All signals will be mapped to the given handler.
+     * @param signalHandler the default signal handler
+     * @return The builder
+     */
     public TerminalBuilder signalHandler(Terminal.SignalHandler signalHandler) {
         this.signalHandler = signalHandler;
         return this;
@@ -367,6 +373,11 @@ public TerminalBuilder paused(boolean paused) {
         return this;
     }
 
+    /**
+     * Builds the terminal.
+     * @return the newly created terminal, never {@code null}
+     * @throws IOException if an error occurs
+     */
     public Terminal build() throws IOException {
         Terminal override = TERMINAL_OVERRIDE.get();
         Terminal terminal = override != null ? override : doBuild();
@@ -645,6 +656,13 @@ public Charset computeEncoding() {
         return encoding;
     }
 
+    /**
+     * Get the list of available terminal providers.
+     * This list is sorted according to the {@link #PROP_PROVIDERS} system property.
+     * @param provider if not {@code null}, only this provider will be checked
+     * @param exception if a provider throws an exception, it will be added to this exception as a suppressed exception
+     * @return a list of terminal providers
+     */
     public List<TerminalProvider> getProviders(String provider, IllegalStateException exception) {
         List<TerminalProvider> providers = new ArrayList<>();
         // Check ffm provider