feat(file): introduce File component

CHANGELOG.md

@@ -12,3 +12,6 @@
 * **BC** - signature of `Psl\Type\object` function changed from `object<T of object>(classname<T> $classname): TypeInterface<T>` to `object(): TypeInterface<object>` ( to preserve the old behavior, use `Psl\Type\instance_of` )
 * introduced `Psl\Type\instance_of` function, with the signature of `instance_of<T of object>(classname<T> $classname): TypeInterface<T>`.
 * introduced a new `Psl\Async` component.
+* introduced a new `Psl\IO\Stream` component.
+* refactored `Psl\IO` handles API.
+* introduced a new `Psl\File` component.

config/.phpcs.xml

@@ -5,6 +5,8 @@
     <file>../src</file>
     <file>../tests</file>
 
+    <exclude-pattern>*/src/Psl/File/(WriteMode|LockType).php</exclude-pattern>
+
     <arg name="basepath" value="."/>
     <arg name="colors"/>
     <arg name="parallel" value="75"/>

config/psalm.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<psalm totallyTyped="true" forbidEcho="true" strictBinaryOperands="true" phpVersion="8.0" allowStringToStandInForClass="true" rememberPropertyAssignmentsAfterCall="false" checkForThrowsDocblock="true" checkForThrowsInGlobalScope="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://getpsalm.org/schema/config" xsi:schemaLocation="https://getpsalm.org/schema/config ../vendor/vimeo/psalm/config.xsd" errorBaseline="psalm-baseline.xml">
+<psalm totallyTyped="true" forbidEcho="true" strictBinaryOperands="true" phpVersion="8.1" allowStringToStandInForClass="true" rememberPropertyAssignmentsAfterCall="false" checkForThrowsDocblock="true" checkForThrowsInGlobalScope="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="https://getpsalm.org/schema/config" xsi:schemaLocation="https://getpsalm.org/schema/config ../vendor/vimeo/psalm/config.xsd" errorBaseline="psalm-baseline.xml">
     <projectFiles>
         <directory name="../src" />
         <directory name="../tests/benchmark" />

docs/README.md

@@ -15,11 +15,13 @@
 - [Psl\Encoding\Base64](./component/encoding-base64.md)
 - [Psl\Encoding\Hex](./component/encoding-hex.md)
 - [Psl\Env](./component/env.md)
+- [Psl\File](./component/file.md)
 - [Psl\Filesystem](./component/filesystem.md)
 - [Psl\Fun](./component/fun.md)
 - [Psl\Hash](./component/hash.md)
 - [Psl\Html](./component/html.md)
 - [Psl\IO](./component/io.md)
+- [Psl\IO\Stream](./component/io-stream.md)
 - [Psl\Interface](./component/interface.md)
 - [Psl\Iter](./component/iter.md)
 - [Psl\Json](./component/json.md)

docs/component/file.md

@@ -0,0 +1,39 @@
+<!--
+    This markdown file was generated using `docs/documenter.php`.
+
+    Any edits to it will likely be lost.
+-->
+
+[*index](./../README.md)
+
+---
+
+### `Psl\File` Component
+
+#### `Functions`
+
+- [open_read_only](./../../src/Psl/File/open_read_only.php#L16)
+- [open_read_write](./../../src/Psl/File/open_read_write.php#L18)
+- [open_write_only](./../../src/Psl/File/open_write_only.php#L18)
+- [temporary](./../../src/Psl/File/temporary.php#L19)
+
+#### `Interfaces`
+
+- [HandleInterface](./../../src/Psl/File/HandleInterface.php#L9)
+- [ReadHandleInterface](./../../src/Psl/File/ReadHandleInterface.php#L9)
+- [ReadWriteHandleInterface](./../../src/Psl/File/ReadWriteHandleInterface.php#L9)
+- [WriteHandleInterface](./../../src/Psl/File/WriteHandleInterface.php#L9)
+
+#### `Classes`
+
+- [Lock](./../../src/Psl/File/Lock.php#L9)
+- [ReadHandle](./../../src/Psl/File/ReadHandle.php#L11)
+- [ReadWriteHandle](./../../src/Psl/File/ReadWriteHandle.php#L11)
+- [WriteHandle](./../../src/Psl/File/WriteHandle.php#L11)
+
+#### `Enums`
+
+- [LockType](./../../src/Psl/File/LockType.php#L7)
+- [WriteMode](./../../src/Psl/File/WriteMode.php#L7)
+
+

docs/component/io-stream.md

@@ -0,0 +1,35 @@
+<!--
+    This markdown file was generated using `docs/documenter.php`.
+
+    Any edits to it will likely be lost.
+-->
+
+[*index](./../README.md)
+
+---
+
+### `Psl\IO\Stream` Component
+
+#### `Functions`
+
+- [pipe](./../../src/Psl/IO/Stream/pipe.php#L25)
+
+#### `Classes`
+
+- [StreamCloseHandle](./../../src/Psl/IO/Stream/StreamCloseHandle.php#L13)
+- [StreamCloseReadHandle](./../../src/Psl/IO/Stream/StreamCloseReadHandle.php#L13)
+- [StreamCloseReadWriteHandle](./../../src/Psl/IO/Stream/StreamCloseReadWriteHandle.php#L13)
+- [StreamCloseSeekHandle](./../../src/Psl/IO/Stream/StreamCloseSeekHandle.php#L13)
+- [StreamCloseSeekReadHandle](./../../src/Psl/IO/Stream/StreamCloseSeekReadHandle.php#L13)
+- [StreamCloseSeekReadWriteHandle](./../../src/Psl/IO/Stream/StreamCloseSeekReadWriteHandle.php#L13)
+- [StreamCloseSeekWriteHandle](./../../src/Psl/IO/Stream/StreamCloseSeekWriteHandle.php#L13)
+- [StreamCloseWriteHandle](./../../src/Psl/IO/Stream/StreamCloseWriteHandle.php#L13)
+- [StreamReadHandle](./../../src/Psl/IO/Stream/StreamReadHandle.php#L13)
+- [StreamReadWriteHandle](./../../src/Psl/IO/Stream/StreamReadWriteHandle.php#L13)
+- [StreamSeekHandle](./../../src/Psl/IO/Stream/StreamSeekHandle.php#L13)
+- [StreamSeekReadHandle](./../../src/Psl/IO/Stream/StreamSeekReadHandle.php#L13)
+- [StreamSeekReadWriteHandle](./../../src/Psl/IO/Stream/StreamSeekReadWriteHandle.php#L13)
+- [StreamSeekWriteHandle](./../../src/Psl/IO/Stream/StreamSeekWriteHandle.php#L13)
+- [StreamWriteHandle](./../../src/Psl/IO/Stream/StreamWriteHandle.php#L13)
+
+

docs/documenter.php

@@ -136,6 +136,7 @@ function document_component(string $component, string $index_link): void
             $generator($directory, $symbols, Loader::TYPE_INTERFACE),
             $generator($directory, $symbols, Loader::TYPE_CLASS),
             $generator($directory, $symbols, Loader::TYPE_TRAIT),
+            $generator($directory, $symbols, Loader::TYPE_ENUM),
             ['']
         ), "\n"),
     ]);
@@ -155,7 +156,7 @@ function get_component_members(string $component): array
         $list,
         static function (string $member) use ($component): bool {
 
-            if (!Str\starts_with_ci($member, $component)) {
+            if (!Str\starts_with_ci($member, $component . '\\')) {
                 return false;
             }
 
@@ -171,6 +172,7 @@ static function (string $member) use ($component): bool {
         Loader::TYPE_INTERFACE => $filter(Loader::INTERFACES),
         Loader::TYPE_CLASS => $filter(Loader::CLASSES),
         Loader::TYPE_TRAIT => $filter(Loader::TRAITS),
+        Loader::TYPE_ENUM => $filter(Loader::ENUMS),
     ];
 }
 
@@ -189,12 +191,14 @@ function get_all_components(): array
         'Psl\\Encoding\\Base64',
         'Psl\\Encoding\\Hex',
         'Psl\\Env',
+        'Psl\\File',
         'Psl\\Filesystem',
         'Psl\\Fun',
         'Psl\\Hash',
         'Psl\\Html',
         'Psl\\Interface',
         'Psl\\IO',
+        'Psl\\IO\\Stream',
         'Psl\\Iter',
         'Psl\\Json',
         'Psl\\Math',
@@ -233,6 +237,8 @@ function get_symbol_type_name(int $type): string
             return 'Classes';
         case Loader::TYPE_TRAIT:
             return 'Traits';
+        case Loader::TYPE_ENUM:
+            return 'Enums';
     }
 }
 
@@ -247,6 +253,8 @@ function get_symbol_definition_line(string $symbol, int $type): int
 
     if (Loader::TYPE_FUNCTION === $type) {
         $reflection = new ReflectionFunction($symbol);
+    } else if (Loader::TYPE_ENUM === $type) {
+        $reflection = new ReflectionEnum($symbol);
     } else {
         $reflection = new ReflectionClass($symbol);
     }

src/Psl/File/Exception/AlreadyLockedException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\File\Exception;
+
+final class AlreadyLockedException extends RuntimeException
+{
+}

src/Psl/File/Exception/ExceptionInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\File\Exception;
+
+use Psl\Exception;
+
+interface ExceptionInterface extends Exception\ExceptionInterface
+{
+
+}

src/Psl/File/Exception/RuntimeException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\File\Exception;
+
+use Psl\Exception;
+
+class RuntimeException extends Exception\RuntimeException implements ExceptionInterface
+{
+}

src/Psl/File/HandleInterface.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\File;
+
+use Psl\IO;
+
+interface HandleInterface extends IO\CloseSeekHandleInterface
+{
+    /**
+     * Gets the path to the file.
+     */
+    public function getPath(): string;
+
+    /**
+     * Get the size of the file.
+     *
+     * @throws IO\Exception\AlreadyClosedException If the handle has been already closed.
+     * @throws Exception\RuntimeException If an error occurred during the operation.
+     */
+    public function getSize(): int;
+
+    /**
+     * Get a shared or exclusive lock on the file.
+     *
+     * This will block until it acquires the lock, which may be forever.
+     *
+     * This involves a blocking syscall; async code will not execute while
+     * waiting for a lock.
+     *
+     * @throws IO\Exception\AlreadyClosedException If the handle has been already closed.
+     * @throws Exception\RuntimeException If an error occurred during the operation.     *
+     *
+     * Example:
+     *
+     * ```php
+     * $lock = $file->lock(LockType::SHARED);
+     * // lock has been acquired.
+     * $lock->release();
+     * ```
+     */
+    public function lock(LockType $type): Lock;
+
+    /**
+     * Immediately get a shared or exclusive lock on a file, or throw.
+     *
+     * @throws IO\Exception\AlreadyClosedException If the handle has been already closed.
+     * @throws Exception\RuntimeException If an error occurred during the operation.
+     * @throws Exception\AlreadyLockedException if `lock()` would block.
+     *
+     * Example:
+     *
+     * ```php
+     * try {
+     *   $lock = $file->tryLock(LockType::SHARED);
+     *   // lock has been acquired.
+     *   $lock->release();
+     * } catch(AlreadyLockedException) {
+     *   // cannot acquire lock.
+     * }
+     * ```
+     */
+    public function tryLock(LockType $type): Lock;
+}

src/Psl/File/Internal/AbstractHandleWrapper.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\File\Internal;
+
+use Psl\File;
+use Psl\File\Lock;
+use Psl\File\LockType;
+
+abstract class AbstractHandleWrapper implements File\HandleInterface
+{
+    public function __construct(private File\HandleInterface $handle)
+    {
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getPath(): string
+    {
+        return $this->handle->getPath();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getSize(): int
+    {
+        return $this->handle->getSize();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function lock(LockType $type): Lock
+    {
+        return $this->handle->lock($type);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function tryLock(LockType $type): Lock
+    {
+        return $this->handle->tryLock($type);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function seek(int $offset): void
+    {
+        $this->handle->seek($offset);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function tell(): int
+    {
+        return $this->handle->tell();
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function close(): void
+    {
+        $this->handle->close();
+    }
+}