Helper classes doc

docs/helper_classes.rst

@@ -0,0 +1,73 @@
+Helper Classes
+##############
+
+PathFactory
+===========
+
+``parse()``
+-----------
+
+.. code-block:: php
+
+    <?php
+    PathFactory::parse(
+        string $path,
+        array $urlSchemes = [],
+        array $streamSchemes = []
+    ): PathInterface;
+
+The ``parse`` function tries to detect the type of the given string path in the following order:
+
+* Unix path
+* Windows path
+* Url/Scheme paths:
+
+  * If both ``$urlSchemes`` and ``$streamSchemes`` are empty, all scheme prefixed paths are parsed as URLs.
+  * If at least one of the lists is non-empty, all unknown schemes throw an exception.
+  * Known schemes are parsed according to which list they belong.
+* Relative path of the current OS type.
+
+  * Since there is no way to separate root relative path from Unix path, root relative paths are never returned.
+
+All paths are returned by the ``parse()`` constructor in a non strict mode.
+
+PathUtils
+=========
+
+``resolveRelativePath()``
+-------------------------
+
+.. code-block:: php
+
+    <?php
+    PathUtils::resolveRelativePath(
+        string|PathInterface $basePath,
+        string|PathInterface $relativePath
+    ): string;
+
+Resolves relative path from the base path.
+
+If a string is passed: it goes through ``PathFactory::parse()``.
+
+If ``relativePath`` is an absolute path, it is converted to string and returned.
+
+Otherwise ``$basePath->resolveRelative($relativePath)->toString()`` is returned.
+
+``makeRelativePath()``
+----------------------
+
+.. code-block:: php
+
+    <?php
+    PathUtils::makeRelativePath(
+        string|AbsolutePathInterface $basePath,
+        string|AbsolutePathInterface $targetPath
+    ): string;
+
+Makes relative path from two absolute paths.
+
+If a string is passed: it goes through ``PathFactory::parse()``.
+
+If any of the paths is a relative path, an exception is thrown.
+
+Otherwise ``$basePath->makeRelative($targetPath)->toString()`` is returned.

docs/index.rst

@@ -20,6 +20,7 @@ Documentation
 
    path_interfaces
    path_classes
+   helper_classes
 
 License
 =======

docs/path_classes.rst

@@ -7,12 +7,14 @@ RelativePath
 The only concrete implementation of ``RelativePathInterface``.
 In non-root relative paths first component returned by ``getComponents()`` is either ``'.'`` or ``'..'``.
 
+When resolving relative, windows-ness of the resulting relative will be inherited from the base path.
+
 Available constructors:
 
 .. code-block:: php
 
     <?php
-    public function __construct(string $path, bool $windows = false);
+    new RelativePath(string $path, bool $windows = false);
 
 ``$windows = false``: Unix-like path. Path separators are slashes.
 
@@ -22,21 +24,21 @@ When exporting a string, backslashes are used.
 .. code-block:: php
 
     <?php
-    public static function unix(string $path): self;
+    RelativePath::unix(string $path): self;
 
 Same as ``new RelativePath($path, windows: false)``
 
 .. code-block:: php
 
     <?php
-    public static function windows(string $path): self;
+    RelativePath::windows(string $path): self;
 
 Same as ``new RelativePath($path, windows: true)``
 
 .. code-block:: php
 
     <?php
-    public static function currentOS(string $path): self;
+    RelativePath::currentOS(string $path): self;
 
 If Windows is detected, create a Windows-like path, otherwise create Unix-like path.
 
@@ -45,7 +47,7 @@ If Windows is detected, create a Windows-like path, otherwise create Unix-like p
 .. code-block:: php
 
     <?php
-    public static function parse(string $path): self;
+    RelativePath::parse(string $path): self;
 
 Alias of ``currentOS()``.
 
@@ -59,7 +61,7 @@ No default constructor, only a named constructor is available:
 .. code-block:: php
 
     <?php
-    public static function parse(string $path, bool $strict = false): self
+    FilesystemPath::parse(string $path, bool $strict = false): self;
 
 If Windows is detected, create a Windows path, otherwise create a Unix path.
 Strict mode does not allow to have relative components that traverse beyond root.
@@ -85,8 +87,8 @@ The prefix is ``'/'``
 
     <?php
     // these are equal
-    public function __construct(string $path, bool $strict = false);
-    public static function parse(string $path, bool $strict = false): self;
+    new UnixPath(string $path, bool $strict = false);
+    UnixPath::parse(string $path, bool $strict = false): self;
 
 WindowsPath
 -----------
@@ -97,6 +99,7 @@ WindowsPath
     The library doesn't check for that even in strict mode.
 
 A class for Windows paths.
+``makeRelative()`` returns relatives of the Windows-like type.
 
 Supported paths:
 
@@ -121,8 +124,8 @@ Supported paths:
 
     <?php
     // these are equal
-    public function __construct(string $path, bool $strict = false);
-    public static function parse(string $path, bool $strict = false): self;
+    new WindowsPath(string $path, bool $strict = false);
+    WindowsPath::parse(string $path, bool $strict = false): self;
 
 UrlPath
 =======
@@ -134,8 +137,8 @@ The prefix is scheme + hostname.
 
     <?php
     // these are equal
-    public function __construct(string $path, bool $strict = false);
-    public static function parse(string $path, bool $strict = false): self;
+    new UrlPath(string $path, bool $strict = false);
+    UrlPath::parse(string $path, bool $strict = false): self;
 
 StreamPath
 ==========
@@ -152,5 +155,5 @@ The prefix is scheme.
 
     <?php
     // these are equal
-    public function __construct(string $path, bool $strict = false);
-    public static function parse(string $path, bool $strict = false): self;
+    new StreamPath(string $path, bool $strict = false);
+    StreamPath::parse(string $path, bool $strict = false): self;

src/PathFactory.php

@@ -20,7 +20,7 @@ final class PathFactory
             return self::parseUrlLike($path, $matches[1], $urlSchemes, $streamSchemes);
         }
 
-        return DIRECTORY_SEPARATOR === '\\' ? RelativePath::windows($path) : RelativePath::unix($path);
+        return RelativePath::currentOS($path);
     }
 
     private static function parseUrlLike(