Project

General

Profile

Misc #17154

Update Pathname Documentation to Clarify Expected Behavior

Added by resperat (Ralph Esperat) about 2 months ago. Updated about 2 months ago.

Status:
Open
Priority:
Normal
[ruby-core:99934]

Description

I would like to suggest adding a sentence to the documentation for Pathname 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 and String 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 (Bug #15564: Pathname#+(pathpart) returns pathpart when pathpart is absolute), not understanding it to be intentional. Other common help websites such as Stack Overflow also show users who do not expect this behavior from this method. Adding a statement to the documentation for the Pathname#+ 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]

#1

Updated by resperat (Ralph Esperat) about 2 months ago

  • Subject changed from Update Filepath Documentation to Clarify Expected Behavior to Update Pathname Documentation to Clarify Expected Behavior

Updated by resperat (Ralph Esperat) about 2 months ago

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

Also available in: Atom PDF