feat(Result): value is noe explicitly nullable, use null-safe operator.

This allows for managing errors inline, see Error Management.md changes.

Author: razshare

docs/Custom Attributes.md

@@ -26,17 +26,11 @@ function handler(#[HelloWorldAttribute] string $greeting){
 }
 
 function main(ServerInterface $server, RouterInterface $router):Result {
-  $router->addHandler("GET", "/", handler(...))->unwrap($error);
+  $router->addHandler("GET", "/", handler(...))
+    ->unwrap($error) ?? die($error);
 
-  if ($error) {
-    die($error)
-  }
-
-  $server->start()->unwrap($error);
-
-  if ($error) {
-    die($error)
-  }
+  $server->start()
+    ->unwrap($error) ?? die($error);
 }
 ```
 

docs/Error Management.md

@@ -56,6 +56,26 @@ if($error){
 
 The first advantage over throwing exceptions is that your control flow is linear and easier to understand because you are not required to use `try/catch` syntax.
 
+Another advantage of representing errors as values is that you can use expressions and pattern matching to manage logic
+
+```php
+use function CatPaw\Core\error;
+
+class Error1 {}
+class Error2 {}
+
+$result = error(new Error1)
+
+$value = $result->unwrap($error) ?? match($error::class){
+  Error1::class => "fallback value 1",
+  Error2::class => "fallback value 2",
+  default       => "default value"
+};
+```
+
+Note that php's match expression is exhaustive, meaning it forces you to provide a default value, which is good because it leaves no margin for ambiguous values.
+
+
 But the most important advantage is probably type safety.\
 While it is true you can check for native thrown exceptions using development tools like phpstan, psalm and so on, these tools don't guarantee your code is safely checked for errors, they are mere linting solutions.\
 Using results, the php type system itself will force you to `unwrap()` the value.

docs/RaspberryPi.md

@@ -27,11 +27,8 @@ function main(GpioInterface $gpio):void {
     $writer = $gpio->createWriter('12');
     $active = true;
     while (true) {
-        $writer->write($active?'1':'0')->unwrap($error);
-        
-        if ($error) {
-            die($error)
-        }
+        $writer->write($active?'1':'0')
+            ->unwrap($error) ?? die($error);
 
         $active = !$active;
         delay(1);

docs/Server Router.md

@@ -18,17 +18,11 @@ function main(
     ServerInterface $server, 
     RouterInterface $router,
 ):void {
-    $router->addHandler("GET", "/cats", handler(...))->unwrap($error);
+    $router->addHandler("GET", "/cats", handler(...))
+        ->unwrap($error) ?? die($error);
 
-    if ($error) {
-        die($error)
-    }
-
-    $server->start()->unwrap($error);
-
-    if ($error) {
-        die($error)
-    }
+    $server->start()
+        ->unwrap($error) ?? die($error);
 }
 ```
 
@@ -53,17 +47,11 @@ function main(
     ServerInterface $server, 
     RouterInterface $router,
 ):void {
-    $router->addHandler("POST", "/cats", handler(...))->unwrap($error);
-
-    if ($error) {
-        die($error)
-    }
-
-    $server->start()->unwrap($error);
+    $router->addHandler("POST", "/cats", handler(...))
+        ->unwrap($error) ?? die($error);
 
-    if ($error) {
-        die($error)
-    }
+    $server->start()
+        ->unwrap($error) ?? die($error);
 }
 ```
 
@@ -82,11 +70,7 @@ function main(ServerInterface $server):void {
         ->withApiLocation("src/api")
         ->withApiPrefix("/api/v1")
         ->start()
-        ->unwrap($error);
-    
-    if ($error) {
-        die($error)
-    }
+        ->unwrap($error) ?? die($error);
 }
 ```
 

src/lib/Core/Directory.php

@@ -74,23 +74,23 @@ public static function create(string $directoryName, int $mode = 0777):Result {
      */
     public static function flat(string $directoryName):Result {
         try {
-            $result = [];
-            $list   = Directory::list($directoryName)->unwrap($error);
+            $items = [];
+            $list  = Directory::list($directoryName)->unwrap($error);
             if ($error) {
                 return error($error);
             }
             foreach ($list as $fileName) {
                 if (isFile($fileName)) {
-                    $result[] = $fileName;
+                    $items[] = $fileName;
                 } else {
-                    $flatList = Directory::flat($fileName)->unwrap($error);
+                    $flatList = Directory::flat($fileName)->unwrap($error) ?? [];
                     if ($error) {
                         return error($error);
                     }
-                    $result = [...$result, ...$flatList];
+                    $items = [...$items, ...$flatList];
                 }
             }
-            return ok($result);
+            return ok($items);
         } catch(Throwable $e) {
             return error($e);
         }

src/lib/Core/File.php

@@ -214,7 +214,7 @@ public static function readFile(string $fileName):Result {
         if ($error) {
             return error($error);
         }
-        $contents = $file->readAll()->unwrap($error);
+        $contents = $file->readAll()->unwrap($error) ?? "";
         if ($error) {
             return error($error);
         }

src/lib/Core/Result.php

@@ -15,7 +15,7 @@
  */
 readonly class Result {
     /**
-     * @param T          $value
+     * @param null|T     $value
      * @param null|Error $error
      */
     public function __construct(
@@ -65,13 +65,12 @@ public function logError():void {
 
     /**
      *
-     * @param  Error $error
-     * @return T
+     * @param  Error  $error
+     * @return null|T
      */
     public function unwrap(&$error = null) {
         if ($this->error) {
             $error = $this->error;
-            /** @var T */
             return null;
         }
         $error = null;

src/lib/Web/Implementations/ByteRange/SimpleByteRange.php

@@ -234,7 +234,7 @@ public function contentType():Result {
                 }
 
                 public function contentLength():Result {
-                    $size = File::size($this->fileName)->unwrap($error);
+                    $size = File::size($this->fileName)->unwrap($error) ?? 0;
                     if ($error) {
                         return error($error);
                     }