Add relative path method and normalize parent references

[elliottwilliams]

I added a method which computes the relative path which goes between two paths. I added this downstream to yonaskolb/XcodeGen#524, but since it seems generally useful I figured I'd try to add it back to PathKit. This is similar to Pathname#relative_path_from in the ruby stdlib and PurePath.relative_to in python. Let me know if this is something you'd be interested in adding, and if there's anything I can do to help!

Declaration

  /// Returns the relative path necessary to go from `base` to `self`.
  ///
  /// Both paths must be absolute or relative paths.
  /// - throws: Throws an error when the path types do not match, or when `base` has so many parent path components
  ///           that it refers to an unknown parent directory.
  public func relativePath(from base: Path) throws -> Path

Examples

Path("a/b").relativePath(from: Path("a/c"))       == Path("../b")
Path("/a/b/c/d").relativePath(from: Path("/a/b")) == Path("c/d")
Path("/a/../../b").relativePath(from: Path("/b")) == Path(".")

Changes to normalize()

One would expect that a path like "a/../../b" could normalize to "b". Foundation's standardizingPath method only removes redundant parent directory references if the path is absolute, so "/a/../../b" normalizes to "/b" but the former case doesn't normalize at all. I realized that PathKit already has logic to remove redundant ".."s in its + operator, so I added a case to normalize() that adds up all the path components if the path is relative.

[kylef]

Hi Elliott,

Thanks for proposing these changes to make computing relative paths easier. This looks great!

It's been a while so I'm not sure if your still interested in picking this back up, but if I could take over, rebase/update and get this merged in. I'll give you some time to weight in on some of the comments I've added. I'm not sure they are really blocking the merge, I've put them up mostly for discussion and would love to hear your thoughts on them.

[kylef]

Suggested change

	public func relativePath(from base: Path) throws -> Path {
	public func relative(from base: Path) throws -> Path {

What do you think about naming this relative(from:), I'm thinking about the consistency with abbreviate(), symlinkDestination(), symlink(_:), link(:), home, temporary etc for which the "Path" isn't explicitly in the name.

[kylef]

I'm also slightly wondering if it might be better to do it the other way (which is how Python's pathlib has it PurePath.relative_to(*other)). I think it may be a bit easier to reason about and understand as a user of PathKit.

This is how you've instinctively written the tests and made a function which reversed the order.

Suggested change

	public func relativePath(from base: Path) throws -> Path {
	public func relative(to other: Path) throws -> Path {

[kylef]

Path conforms to ExpressibleByStringLiteral I think that could allow us to use Path types here which automatically get handled from a string.

Here's some examples:

let path: Path = "a"

When passed into a function:

func relativePath(to path: Path, from base; Path) throws -> Path {
  return try path.relativePath(from: base)
}

relativePath(to: "a", from: "b") == "../a"

[kylef]

As extension we might be able to do away with this utility function and use tests directly:

- try expect(relativePath(to: "a", from: "b")) == "../a"
+ try expect(Path("b").relative(from: "a")) == "../a"

[kylef]

As this is specific for relative paths, should we name it as such?

Suggested change

	enum PathArgumentError: Error {
	enum RelativePathError: Error {