Add Path type

[straight-shoota]

It has already been proposed in other discussions to add a Path type which essentially holds a filesystem path and turns current static methods of File into an object oriented interface.

The benefits of this approach are:

• type safe encapsulation
• one dedicated place for path operations
• clear separation: File and Dir handle file system access, Path performs only syntactic operations.

Prominent implementations of this type are Java's java.nio.file.Path (API docs, tutorial) and Python's pathlib (API docs).

Pathlib actually comes in two flavours: pure paths provide only syntactical operations while conrete paths also do IO operations. IMHO it makes more sense to keep that separated like the Java approach.

Paths are implemented differently depending on operating system. Namely, we need to respect POSIX paths (like /foo/bar/baz) as well as windows paths (like C:\foo\bar\baz). The major difference are the primary directory separator (/ vs. \) and designators for absolute paths ( /foo vs C:\foo).

Pythons pathlib offers two classes for this, PurePosixPath and PureWindowsPath, Java's Path by default use the variant supported by the default file system but you can use different providers (Path is just an interface).

I don't think this needs to be implemented in separate types but it would certainly be nice to not be limited to the system's native path model. This could be achieved by an ivar flag. But it's debateable if this is worth it, the most common use case by far will be working with native paths.

The following methods would migrate from File to Path.

File.basename(path)         => Path#basename
File.basename(path, suffix) => Path#basename(suffix)
File.dirname(path)          => Path#dirname
File.expand_path(path, dir) => Path#epxand_path(dir)
File.extname(filename)      => Path#extname
File.join(*paths)           => Path#resolve(*paths), Path#<<(path)

Proposed additionals instance methods for Path:

#<=>(Path | String) : Int
#== (String) : Bool
#[](Int) : Path # access path member by index
#[](Int, Int) : Path # access path members by index
#[](Range) : Path # access path members by index
#absolute? : Bool
#ends_with?(Path | String) : Bool
#normalize : Path # remove `./` and `foo/..` segments
#parent : Path?
#root : Path?
#relative_to(Path | String) : Path
#resolve_sibling(Path | String) : Path
#starts_with(Path | String) : Bool
#to_s : String
#to_uri : URI

The type could probably also include Enumerable(Path).

All methods currently accepting a path as String would now expect Path | String argument.

[asterite]

So instead of:

File.basename(path)

I'll have to write:

Path.new(path).basename

and so on for every method?

What about File.open(...), do we need to change it to also accept a Path? And possibly every method that accepts a String would need to also take into consideration accepting a Path?

I don't oppose having a Path (or Pathname) module to have class methods, to do Path.basename(...) instead of File.basename, but this proposal looks like we'll going to have multiple ways of doing the same thing.

[asterite]

It would also be nice to know why the people that want Path want it: what code they have now and how it will become better with a Path type.

[asterite]

As another note: ruby has a Pathname class. I never used it, and never seen it in code I read.

[asterite]

More questions: what about Dir.glob? Would it return Path instead of String? Will I need to invoke to_s on each of its entries? How will a Path be represented, is it just a String wrapper or an array of pieces (so less performant)?

[j8r]

I like the idea of a Path module (not a class) for String manipulations related to pathes. The File class will only be related to operations requiring to read/write to the filesystem. I agree with @asterite , I see more disadvantages than advantages to create a Path type, this appears to become more cumbersome if we want to manipulate them.

[bew]

I would go for class methods for all path-related methods that are currently on File, but having a Path object might be handy for those who want to check specific segments of the path, or do some other segment manipulation.
In my view Path as an object would be rarely used, and File.open(...) should stay with String only, the user must convert its Path object with Path#to_s if he used one.

[RX14]

If we look at the average piece of path-handling code it rarely just does one operation in isolation so looking at File.basename(str) vs Path.new(str).basename is I think misleading.

For example, this code

All those File.exists? calls will become absolute_filename.exists?. Those make_relative_unless_absolute calls are actually fairly common, there would definitely be a mathod on path for those, for example just path.to_absolute (which is much shorter).

I'd go much further and remove most File class methods and nuke Dir entirely. Place it all on Path. We don't have to think about that in this proposal, but at least I'd like File's class methods to simply be aliases for Path.new(string).foo in any future PR. (path can be a struct because it's immutable, so little if any performance penalty)

[straight-shoota]

@asterite

How will a Path be represented, is it just a String wrapper or an array of pieces (so less performant)?

Most certainly it should just be a wrapper around String (plus an ivar for path type: posix/windows).

What about File.open(...), do we need to change it to also accept a Path? And possibly every method that accepts a String would need to also take into consideration accepting a Path?

All methods receiving a path like File.open should accept both Path and String.
If we have Path objects, all methods receiving a path should accept an instance of Path, not just String (@bew).

this proposal looks like we'll going to have multiple ways of doing the same thing.

In the long term there should only be one way of doing path manipulation, that is using a Path object.

It would already be an improvement to move all path-related class methods from File to Path (as a module) but I think it would be benefitial to have specific type representing a path. This makes it actually easier to perform path operations. Instead of File.basename(path) you'll just use path.basename - because path should already be a Path.
As far as I can tell, it is not very common to perform ordinary string operations on paths so the added benefit has zero to little downside from an API perspective.

[asterite]

I guess the only way to know is by actually implementing something like this and using it across the std and the compiler (probably even more also testing this on a few shards, maybe prax is a good one). I just worry about duplicating logic having to handle both String and Path across the std and Possible shards, plus having to wrap single calls like File.basenane into Path.new(...).basename

[j8r]

If we go for a Path class, we can remove basename and dirname:

Dir.current         #=> "/my/current/dir"  (Path)
Dir.current[0..-2]  #=> "/my/current" (String) == dirname
Dir.current[-1]     #=> "dir" (String) == basename

[RX14]

@asterite it's simple: we just make sure to call to_s then restrict on String | Path. String#to_s and Path#to_s will both return the string representations of paths so everything that takes a string currently will need just a minor change.

Plus, we can always go the whole way and just flat-out remove File.basename in any Path PR if you're worried...

[RX14]

Most of the path-handling methods on File need a rewrite for windows, so this is a good time to implement Path. An initial PR to add Path with support for windows and unix-style paths, initially without any support for performing filesystem operations, would be great.

[straight-shoota]

I'm happy to start working on that.