Haskell platform proposal: split package

[Simon Hengel]

Hi,
not sure if that adds anything to the discussion, but I share Roman's
concerns.

On Sat, Jul 21, 2012 at 08:43:05PM -0400, Brent Yorgey wrote:
> On Sat, Jul 21, 2012 at 11:40:19PM +0300, Roman Cheplyaka wrote:
> > * Brent Yorgey <byorgey at seas.upenn.edu> [2012-07-21 08:09:09-0400]
> > > On Sat, Jul 21, 2012 at 09:24:16AM +0300, Roman Cheplyaka wrote:
> > > > 
> > > > Regarding the API: I'm a bit concerned with presence of synonyms there
> > > > (e.g. chunk = splitEvery, sepBy = splitOn etc.) IMO it makes it harder
> > > > to learn the API (which is not small even without the synonyms), and
> > > > especially to read other people's code if their preferences in naming
> > > > differ from yours.
> > > 
> > > Would your concern be addressed by Gábor's suggestion to group
> > > synonyms together in the documentation?
> > 
> > This could be a minor improvement (I haven't checked how these
> > grouped functions look like in haddock), but I don't see the need for
> > synonyms in the first place. Could you maybe explain the motivation
> > behind them?
> 
> Certainly.  The idea is to provide synonyms whenever there are
> multiple common names in use, as well as a consistent system of names
> within the package itself.  The goal is for new users to be able to
> get started using the library as quickly as possible -- users will
> usually come looking for some particular function and they may already
> have an idea about what it might be called.

This was at least not true for me.  When I first looked at split, I was
utterly confused about all those synonyms.  This was one of two reasons
why I decided not to use it (having an other dependency was the other).

> To be concrete, the split package has three sets of synonyms:
> 
>   * splitOn / sepBy / unintercalate
> 
>     Here 'splitOn' is an internally consistent name, which matches
>     with the naming scheme used in the rest of the package.  'sepBy'
>     is a name from parsec and other parser combinator libraries;
>     'unintercalate' emphasizes that this function is right inverse to
>     'intercalate'.
> 
>   * splitOneOf / sepByOneOf
> 
>   * splitEvery / chunk
> 
>     Again, 'splitEvery' matches the internal naming scheme; 'chunk' is
>     a name commonly used for this function within the community.

> I don't see much harm in this (modulo making the documentation
> clearer, which I plan to do).

Making the documentation clearer would mitigate Roman's first concern
(learning the API).  But it would not address the second concern
(reading/understanding other peoples code), which to me is even more
important.

> And I really don't want to *remove* existing names because that would
> force a major version bump and potentially break any code depending on
> split.

I think this particular point can be addressed by either deprecating
synonyms; or by removing the Haddock comment from synonyms and use:

    {-# OPTIONS_HADDOCK prune #-}

That way the synonyms do not show up in documentation, but are still
exported.

Cheers,
Simon