Allow using .. (range operator) as a means to refer to the parent directory

Author: dennisdoomen

Pathy.ApiVerificationTests/ApprovedApi/pathy.net8.0.verified.txt

@@ -37,6 +37,7 @@ namespace Pathy
         public static string op_Implicit(Pathy.ChainablePath chainablePath) { }
         public static Pathy.ChainablePath op_Implicit(string path) { }
         public static Pathy.ChainablePath operator +(Pathy.ChainablePath leftPath, string additionalPath) { }
+        public static Pathy.ChainablePath operator /(Pathy.ChainablePath leftPath, System.Range range) { }
         public static Pathy.ChainablePath operator /(Pathy.ChainablePath leftPath, string subPath) { }
         public static Pathy.ChainablePath operator /(Pathy.ChainablePath? leftPath, string subPath) { }
     }

Pathy.ApiVerificationTests/ApprovedApi/pathy.netstandard2.1.verified.txt

@@ -37,6 +37,7 @@ namespace Pathy
         public static string op_Implicit(Pathy.ChainablePath chainablePath) { }
         public static Pathy.ChainablePath op_Implicit(string path) { }
         public static Pathy.ChainablePath operator +(Pathy.ChainablePath leftPath, string additionalPath) { }
+        public static Pathy.ChainablePath operator /(Pathy.ChainablePath leftPath, System.Range range) { }
         public static Pathy.ChainablePath operator /(Pathy.ChainablePath leftPath, string subPath) { }
         public static Pathy.ChainablePath operator /(Pathy.ChainablePath? leftPath, string subPath) { }
     }

Pathy.Specs/ChainablePathSpecs.cs

@@ -1085,4 +1085,95 @@ public void Returns_min_value_for_non_existing_path()
         // Assert
         actualTime.Should().Be(DateTime.MinValue);
     }
+
+#if NET6_0_OR_GREATER
+    [Fact]
+    public void Can_navigate_to_parent_using_range_operator()
+    {
+        // Arrange
+        var path = testFolder / "dir1" / "dir2" / "dir3";
+        path.CreateDirectoryRecursively();
+
+        // Act
+        var result = path / .. / "file.txt";
+
+        // Assert
+        result.DirectoryName.Should().Be(testFolder + Slash + "dir1" + Slash + "dir2");
+        result.Name.Should().Be("file.txt");
+    }
+
+    [Fact]
+    public void Can_chain_multiple_range_operators_for_parent_navigation()
+    {
+        // Arrange
+        var path = testFolder / "level1" / "level2" / "level3" / "level4";
+        path.CreateDirectoryRecursively();
+
+        // Act
+        var result = path / .. / .. / .. / "file.txt";
+
+        // Assert
+        result.DirectoryName.Should().Be(testFolder + Slash + "level1");
+        result.Name.Should().Be("file.txt");
+    }
+
+    [Fact]
+    public void Range_operator_is_equivalent_to_using_the_parent_property()
+    {
+        // Arrange
+        var path = testFolder / "dir1" / "dir2" / "dir3";
+        path.CreateDirectoryRecursively();
+
+        // Act
+        var usingRangeOperator = path / .. / .. / "file.txt";
+        var usingParentProperty = path.Parent.Parent / "file.txt";
+
+        // Assert
+        usingRangeOperator.Should().Be(usingParentProperty);
+    }
+
+    [Fact]
+    public void Can_mix_range_operator_with_regular_path_operations()
+    {
+        // Arrange
+        var baseDir = testFolder / "project" / "src" / "core";
+        baseDir.CreateDirectoryRecursively();
+
+        var testDir = testFolder / "project" / "tests";
+        testDir.CreateDirectoryRecursively();
+
+        // Act - Navigate from core to tests using range operator
+        var result = baseDir / .. / .. / "tests" / "CoreTests.cs";
+
+        // Assert
+        result.ToString().Should().Be(testFolder + Slash + "project" + Slash + "tests" + Slash + "CoreTests.cs");
+    }
+
+    [Fact]
+    public void Range_operator_works_with_current_path()
+    {
+        // Act
+        var result = ChainablePath.Current / .. / .. / "file.txt";
+
+        // Assert
+        result.DirectoryName.Should().Be(Environment.CurrentDirectory.ToPath().Parent.Parent.ToString());
+        result.Name.Should().Be("file.txt");
+    }
+
+    [Fact]
+    public void Only_two_dots_are_allowed()
+    {
+        // Arrange
+        var path = testFolder / "dir1" / "dir2";
+        path.CreateDirectoryRecursively();
+
+        // Act
+        Action act = () => { var _ = path / 1..3; };
+
+        // Assert
+        act.Should().Throw<ArgumentException>()
+            .WithMessage("*Only the '..' range operator is supported*")
+            .WithParameterName("range");
+    }
+#endif
 }

Pathy/ChainablePath.cs

@@ -214,6 +214,47 @@ private static string NormalizeSlashes(string path)
             return From(Path.Combine(leftPath.GetValueOrDefault(New), subPath));
         }
 
+#if NET6_0_OR_GREATER || NETSTANDARD2_1_OR_GREATER
+        /// <summary>
+        /// Navigates to the parent directory of the specified <see cref="ChainablePath"/> when using the range operator <c>..</c>.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// var path = ChainablePath.Current / .. / .. / "file.txt";
+        /// // Equivalent to: ChainablePath.Current.Parent.Parent / "file.txt"
+        /// </code>
+        /// </example>
+        /// <param name="leftPath">
+        /// The base <see cref="ChainablePath"/> from which to navigate to the parent.
+        /// </param>
+        /// <param name="range">
+        /// The range operator. Only the <c>..</c> range operator (representing all elements) is supported.
+        /// </param>
+        /// <returns>
+        /// A new <see cref="ChainablePath"/> instance representing the parent directory of <paramref name="leftPath"/>.
+        /// </returns>
+        /// <exception cref="ArgumentException">
+        /// Thrown if <paramref name="range"/> is not the <c>..</c> range operator.
+        /// </exception>
+        /// <remarks>
+        /// This operator is designed to work specifically with the <c>..</c> range operator to provide
+        /// a more intuitive syntax for navigating to parent directories.
+        /// </remarks>
+        public static ChainablePath operator /(ChainablePath leftPath, Range range)
+        {
+            // Validate that the range is the '..' operator (which is Range.All)
+            if (!Range.All.Equals(range))
+            {
+                throw new ArgumentException(
+                    "Only the '..' range operator is supported for parent directory navigation. " +
+                    "The range operator should be '..' (not a specific range like '1..3').",
+                    nameof(range));
+            }
+
+            return leftPath.Parent;
+        }
+#endif
+
         /// <summary>
         /// Adds a raw string to the end of a <see cref="ChainablePath"/> instance.
         /// </summary>
@@ -359,7 +400,7 @@ public DateTime LastWriteTimeUtc
                 {
                     return System.IO.Directory.GetLastWriteTimeUtc(path);
                 }
-                
+
                 return DateTime.MinValue;
             }
         }

README.md

@@ -114,6 +114,7 @@ Know that `ChainablePath` overrides `Equals` and `GetHashCode`, so you can alway
 Given an instance of `ChainablePath`, you can get a lot of useful information:
 * `Name` returns the full name, but without the directory, whereas `Extension` gives you the extension _including_ the dot.
 * `Directory`, `Parent` or `DirectoryName` give you the (parent) directory of a file or directory.
+* The range operator `..` in newer versions of .NET serves a similar purpose, e.g. `path / .. / "file.txt"`
 * To see if a path is absolute, use `IsRooted`
 * Not sure if a path points to an actual file system entry? Use `IsFile`, `IsDirectory` or `Exists`
 * Want to know the delta between two paths? Use `AsRelativeTo`.
@@ -127,6 +128,28 @@ Other features
 * Build an absolute path from a relative path using `ToAbsolute` to use the current directory as the base or `ToAbsolute(parentPath)` to use something else as the base.
 * Finding the closest parent directory containing a file matching one or more wildcards. For example, given you have a `ChainablePath` pointing to a `.csproj` file, you can then use `FindParentWithFileMatching("*.sln", "*.slnx")` to find the directory containing the `.sln` or `.slnx` file.
 
+### Resolving files
+
+If you have a `ChainablePath` that could represent either a file or a directory, and you want to resolve a specific file name, you can use the `ResolveFile` extension method:
+
+```csharp
+// When the path is a directory containing the file
+var directory = ChainablePath.From("c:/projects/myapp");
+var configFile = directory.ResolveFile("appsettings.json");
+// Returns: c:/projects/myapp/appsettings.json (if it exists)
+
+// When the path is already the file itself
+var filePath = ChainablePath.From("c:/projects/myapp/appsettings.json");
+var resolved = filePath.ResolveFile("appsettings.json");
+// Returns: c:/projects/myapp/appsettings.json (if it exists)
+
+// When the file doesn't exist
+var missing = directory.ResolveFile("missing.txt");
+// Returns: ChainablePath.Empty
+```
+
+The method performs case-insensitive file name matching, so `ResolveFile("CONFIG.JSON")` will match `config.json`.
+
 ### Globbing
 
 If you add the `Pathy.Globbing` NuGet source-only package as well, you'll get access to the `GlobFiles` method. With that, you can fetch a collection of files like this:
@@ -164,28 +187,6 @@ var filesToMove = (ChainablePath.Current / "source").GlobFiles("*.txt");
 filesToMove.MoveFileOrDirectory(ChainablePath.Current / "destination");
 ```
 
-### Resolving files
-
-If you have a `ChainablePath` that could represent either a file or a directory, and you want to resolve a specific file name, you can use the `ResolveFile` extension method:
-
-```csharp
-// When the path is a directory containing the file
-var directory = ChainablePath.From("c:/projects/myapp");
-var configFile = directory.ResolveFile("appsettings.json");
-// Returns: c:/projects/myapp/appsettings.json (if it exists)
-
-// When the path is already the file itself
-var filePath = ChainablePath.From("c:/projects/myapp/appsettings.json");
-var resolved = filePath.ResolveFile("appsettings.json");
-// Returns: c:/projects/myapp/appsettings.json (if it exists)
-
-// When the file doesn't exist
-var missing = directory.ResolveFile("missing.txt");
-// Returns: ChainablePath.Empty
-```
-
-The method performs case-insensitive file name matching, so `ResolveFile("CONFIG.JSON")` will match `config.json`.
-
 ## Building
 
 To build this repository locally so you can contribute to it, you need the following: