[asdf-devel] patch for component-relative-pathname

[Robert Goldman]

On 2/19/10 Feb 19 -1:10 PM, Faré wrote:
> On 19 February 2010 10:50, Robert Goldman <rpgoldman at sift.info> wrote:
>> Would anyone object to augmenting the docstring for
>> COMPONENT-RELATIVE-PATHNAME?
>>
>> Currently it's:
>>
>> "Extracts the relative pathname applicable for a particular component."
>>
>> How about something like:
>>
>> "Returns a pathname for the component argument relative to the pathname
>> of that component's parent."
>>
>> ?
>>
>> I think the most important thing for the reader to know is what the
>> return value is relative to.
>>
>> The above isn't ideal, either, because sometimes what this returns is
>> NOT a relative pathname (at least as far as I can tell by reading the
>> source) --- it extracts the value that the system definer sets using
>> :pathname so that the "relative" pathname may well be absolute!
>>
>> Perhaps:
>>
>> "Returns a pathname for the component argument intended to be
>> interpreted relative to the pathname of that component's parent.
>> Despite the function's name, the return value may be an absolute
>> pathname, because an absolute pathname may be interpreted relative to
>> another pathname in a degenerate way."
>>
>> A little long-winded.  I'm open to suggestions for improvement.
>>
>> What about adding a docstring for SPLIT-PATH-STRING, too --- any
>> function that returns three values is worth a docstring!
>>
>>  "Splits the path string S, returning three values:
>> A flag that is either :absolute or :relative, indicating
>>   how the rest of the values are to be interpreted.
>> A directory path --- a list of strings, suitable for
>>   use with MAKE-PATHNAME when prepended with the flag
>>   value.
>> A filename with type extension, possibly NIL in the
>>   case of a directory pathname.
>> FORCE-DIRECTORY forces S to be interpreted as a directory
>> pathname \(third return value will be NIL, final component
>> of S will be treated as part of the directory path."
>>
>> By the way, is there any danger that SPLIT-PATH-STRING will be called on
>> a logical pathname string?  I don't see anything to keep it from
>> happening.  If so, it looks like it will lose badly; split-path-string
>> assumes that the pathname separator is "/".
>>
> Split path string will be called on a what is provided as :name to
> ASDF. In these circumstances, we get to define what is the pathname
> separator convention (if any) and I think that having one is better
> than having none, and "/" is a pretty unsurprising one. Yes, that
> needs to be documented.
> 
>> If you all agree with me, this looks like a job for a launchpad ticket.
>>
> No! This looks like a job for someone willing to write the damn doc
> strings and get their patch committed. Ahem, don't you have commit
> priviledge?


Sorry, not clear!  Two tasks:

1.  Get docstrings in.  I can do that.  I've written them already, just
thought I'd get a review --- once Xophe went over one of my docstrings
for SBCL with a fine-tooth comb and the results were much better.

I will take care of the docstrings, as long as no one thinks these are bad.

2.  SPLIT-PATH-STRING --- this is the one I think might need a ticket.
I confess I'm bamboozled by this one.  It's called on (component-name
component), not on a pathname.  Can you explain why the COMPONENT-NAME
would end up being a string that looks like a pathname?

This SPLIT-PATH-STRING stuff looks like a relatively recent gwking
addition (if I understand the output of git blame correctly).  I don't
see what use case it was introduced for.  Anyone else have a clue?  I
see this docstring for component-name:

"Component name: designator for a string composed of portable pathname
characters"

but I have never seen at component-name that was anything other than a
simple name, never something with directory separators.  Is this ever
used in the wild?  Or was this something that was added in an excess of
enthusiasm and that should just be killed (like the undocumented
tripartite FEATURE form)?

thanks,
r