Issue #17154 has been updated by resperat (Ralph Esperat).


Oh, and I would be happy to submit the necessary patches if this if a feature that will be accepted.

----------------------------------------
Misc #17154: Update Pathname Documentation to Clarify Expected Behavior
https://bugs.ruby-lang.org/issues/17154#change-87482

* Author: resperat (Ralph Esperat)
* Status: Open
* Priority: Normal
* Assignee: akr (Akira Tanaka)
----------------------------------------
I would like to suggest adding a sentence to the documentation for [Pathname](https://ruby-doc.org/stdlib-2.7.1/libdoc/pathname/rdoc/Pathname.html) to make clear the unusual behavior of `Pathname#+` when an absolute path is included in the arguments. In such a situation, `Pathname#+` drops the paths prior to the last absolute path which I understand to be the intended behavior, but it is not obviously intended, only showing up tangentially as an example in the documentation. 

```
p3 = p1 + "/etc/passwd"        # Pathname:/etc/passwd
```

The Pathname documentation states that " **All functionality** from File, FileTest, and some from Dir and FileUtils is included, **in an unsurprising way** ..." and later when referring to core methods such as `Pathname#+` "These methods are **effectively manipulating a String** , because that's all a path is." However, similar uses of both [File](https://ruby-doc.org/core-2.7.1/File.html) and [String](https://ruby-doc.org/core-2.7.1/String.html) would produce the expected result of including all of the arguments:

```
s1 = "/usr"
s2 = s1 + "/etc/passwd" # "/usr/etc/passwd"

f1 = File.new("/usr" + "/etc/passwd") # (No such file or directory @ rb_sysopen - /usr/etc/passwd)
```

A bug report was previously filed to "fix" this functionality (##15564), not understanding it to be intentional. Other common help websites such as [Stack Overflow](https://stackoverflow.com/questions/12464361/concatenating-absolute-paths-with-the-pathname-class) also show users who do not expect this behavior from this method. Adding a statement to the documentation for the [Pathname#+](https://ruby-doc.org/stdlib-2.7.1/libdoc/pathname/rdoc/Pathname.html#method-i-2B) method will make it clear to users exactly what to expect and that this is the intended behavior. I would suggest simply the following, the first sentence of which is already present:

`Appends a pathname fragment to self to produce a new Pathname object. If an absolute path is provided as any of the arguments, discards all arguments prior to the last absolute path provided.`

I appreciate your consideration of this request.

ruby -v: ruby 2.7.1p83 (2020-03-31 revision a0c7c23c9c) [x86_64-linux]



-- 
https://bugs.ruby-lang.org/

Unsubscribe: <mailto:ruby-core-request / ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>