Network.URI changes

[Simon Marlow]

On 22 October 2004 12:20, Graham Klyne wrote:

>> Our general policy is to use the capitalised version of acronyms (ie.
>> URI rather than Uri), but there are many exceptions to this in the
>> libraries already.  But sometimes the capitalised version looks ugly,
>> especially when it occurs in the middle of an identifier.
>> 
>> I'm inclined to agree with Sven here.  Graham?
> 
> I think I agree, too.  This bothered me a little as I was developing
> the code, and (as noted) I didn't really settle on a single consistent
> position.  I think my feeling is that because Haskell gives some
> significance to case in names, it's sometimes awkward and/or ugly to
> try 
> and impose an uppercasing-of-acronyms convention.
> 
> This would be a good time to make changes for consistency, and I'm
> content 
> to update my code as needed.
> 
>> perhaps stringToURI instead of parseURI?
> 
> So the four parse*Uri* functions would become stringTo*URI* ?
> 
> That works for me.  Almost.  The problem is that the different names
> refer 
> to variations in the string content, not differences in the final
> value (otherwise a Read instance could be used, right?).  I think a
> <verb>*URI* here is more meaningful.  e.g.
>     readURIReference
>     decodeURIReference
> or suchlike.  What's most Haskell-ish here?

Ok.  I suggest:

  - use upper-case URI consistently

  - replace the old parseURI with the new version.  It has the same
type,
    and doesn't completely differ in semantics.  Besides, we're allowed
    to make changes to library interfaces in a major release.  We'll be
    sure to document this change when 6.4 is released.

>>>     * Should we deprecate parseURI, scheme, authority, path, query,
>>> and fragment?
>> 
>> Yes.
> 
> That's a plan I like.  (I assume we'd keep them for a release or two
> while software get's converted?)  Any deprecation note should make
> clear that the new components have different functionality (including
> the '//', '/', '?', '#' characters, etc.)

The policy is to leave deprecated functions in for at least one major
release.  In practice it's usually longer.

In the future we'll be able to provde versioned APIs (although whether
we actually do or not is a different matter - keeping the old version
working is extra effort).

> While considering this issue, would it be appropriate to consider
> interfaces for updating URI components that isolate calling programs
> from 
> the internal data type components?  That coupling was a (small)
> problem for me in developing this new version.
> 
> ...
> 
> Another area that I think might possibly be improved is the interface
> for suppressing authority passwords in the string form of a URI.  I
> don't know, what do you think?  The current interface is thus:
> [[
> -- |URI as instance of Show.  Note that for security reasons, the
> default 
> --  behaviour is to suppress any userinfo field (see RFC2396bis,
> section 7.5). 
> --  This can be overridden by using uriToString directly with first
> --  argument @id at .
> ]]

I don't have a strong opinion here.  We should probably follow whatever
the convention is.

Cheers,
	Simon