From: resperat@... Date: 2020-09-05T13:18:40+00:00 Subject: [ruby-core:99942] [Ruby master Misc#17154] Update Pathname Documentation to Clarify Expected Behavior 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: