Allow exceptions to be thrown with an exit status

- Add `ExceptionInterface::getExitStatus()` and implement via
  `ExceptionTrait::withExitStatus()`
- In `ErrorHandler::handleException()`, use the value returned by
  `ExceptionInterface::getExitStatus()` if not `null`

Also:
- `Console`: indent fenced code blocks
- Adopt 16 instead of 15 as `ErrorHandler`'s default exit status to
  better accommodate bitmasks as return values

Author: lkrms

src/Cli/CliCommand.php

@@ -66,8 +66,8 @@ abstract protected function getLongDescription(): ?string;
      * ```php
      * [
      *     CliHelpSectionName::EXIT_STATUS => <<<EOF
-     * `{{command}}` returns 0 when the operation succeeds, 1 when invalid arguments
-     * are given, and 15 when an unhandled exception is thrown. Other non-zero values
+     * `{{program}}` returns 0 when the operation succeeds, 1 when invalid arguments
+     * are given, and 16 when an unhandled exception is thrown. Other non-zero values
      * may be returned for other failures.
      * EOF,
      * ];

src/Console/Support/ConsoleFormat.php

@@ -52,8 +52,9 @@ public function apply(?string $text, array $attributes = []): string
             return '';
         }
 
-        // Remove indentation from the first line of code in fenced code blocks
-        // to prevent doubling up
+        // In fenced code blocks:
+        // - remove indentation from the first line of code
+        // - add a level of indentation to the block
         $tagId = $attributes[Attribute::TAG_ID] ?? null;
         if ($tagId === Tag::CODE_BLOCK) {
             $indent = $attributes[Attribute::INDENT] ?? '';
@@ -63,6 +64,7 @@ public function apply(?string $text, array $attributes = []): string
                     $text = substr($text, $length);
                 }
             }
+            $text = '    ' . str_replace("\n", "\n    ", $text);
         }
 
         if ($this->Replace) {

src/Exception/Concern/ExceptionTrait.php

@@ -12,13 +12,30 @@
  */
 trait ExceptionTrait
 {
+    protected ?int $ExitStatus = null;
+
     public function __construct(
         string $message = '',
-        ?Throwable $previous = null
+        ?Throwable $previous = null,
+        ?int $exitStatus = null
     ) {
+        $this->ExitStatus = $exitStatus;
         parent::__construct($message, 0, $previous);
     }
 
+    /**
+     * Set the exit status to return if the exception is not caught on the
+     * command line
+     *
+     * @return static
+     */
+    public function withExitStatus(?int $exitStatus)
+    {
+        $clone = clone $this;
+        $clone->ExitStatus = $exitStatus;
+        return $clone;
+    }
+
     /**
      * Get an array that maps names to formatted content
      *
@@ -29,6 +46,14 @@ public function getDetail(): array
         return [];
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function getExitStatus(): ?int
+    {
+        return $this->ExitStatus;
+    }
+
     /**
      * @inheritDoc
      */

src/Exception/Contract/ExceptionInterface.php

@@ -12,4 +12,10 @@ interface ExceptionInterface extends Throwable
      * @return array<string,string>
      */
     public function getDetail(): array;
+
+    /**
+     * Get the exit status to return if the exception is not caught on the
+     * command line
+     */
+    public function getExitStatus(): ?int;
 }

src/Support/ErrorHandler.php

@@ -4,6 +4,7 @@
 
 use Lkrms\Contract\IFacade;
 use Lkrms\Contract\ReceivesFacade;
+use Lkrms\Exception\Contract\ExceptionInterface;
 use Lkrms\Facade\Console;
 use Lkrms\Utility\File;
 use Lkrms\Utility\Pcre;
@@ -29,7 +30,7 @@ final class ErrorHandler implements ReceivesFacade
      */
     private array $Silenced = [];
 
-    private int $ExitStatus = 15;
+    private int $ExitStatus = 16;
 
     private bool $IsRegistered = false;
 
@@ -197,6 +198,12 @@ public function handleException(Throwable $exception): void
         Console::exception($exception);
 
         if (!$this->IsShuttingDown) {
+            if ($exception instanceof ExceptionInterface) {
+                $exitStatus = $exception->getExitStatus();
+                if ($exitStatus !== null) {
+                    exit ($exitStatus);
+                }
+            }
             exit ($this->ExitStatus);
         }
     }

src/Sync/Command/CheckSyncProviderHeartbeat.php

@@ -93,7 +93,7 @@ public function getLongDescription(): ?string
         return
             ($description ?? '') . <<<EOF
                 If a heartbeat request fails, __{{command}}__ continues to the next
-                provider unless --fail-early is given, in which case it exits
+                provider unless `-f/--fail-early` is given, in which case it exits
                 immediately.
 
                 The command exits with a non-zero status if a provider backend is

tests/unit/Console/ConsoleFormatterTest.php

@@ -68,7 +68,7 @@ public static function formatProvider(): array
             *0*   escapes \
             *1*   with \
             *2*   adjacent \
-            *15*  tags
+            *16*  tags
             EOF;
 
         return [
@@ -84,19 +84,19 @@ public static function formatProvider(): array
 
                 Low-priority information with embedded tags.
 
-                <?php
-                /**Preformatted code block**/
-                $a = b($c);
+                    <?php
+                    /**Preformatted code block**/
+                    $a = b($c);
 
                 HEADING 3
 
                     Indented paragraph.
 
                     Indented _code span_
 
-                    <?php
-                    /**Indented code block**/
-                    $a = b($c);
+                        <?php
+                        /**Indented code block**/
+                        $a = b($c);
 
                 Bold, italic and underline.
 
@@ -108,7 +108,7 @@ public static function formatProvider(): array
                 0   escapes
                 1   with
                 2   adjacent
-                15  tags
+                16  tags
                 EOF,
                 $default,
                 $input,
@@ -153,7 +153,7 @@ public static function formatProvider(): array
                 *0*   escapes \
                 *1*   with \
                 *2*   adjacent \
-                *15*  tags
+                *16*  tags
                 EOF,
                 $loopback,
                 $input,