Craig Dillabaugh:

> However, I can't seem to remember in C++ or any other language (not that I know all that many other languages) coming across a function in the standard library that conflicted with another function in the standard library in this way.

Generally Phobos should be designed to avoid name clashes as much as possible. Because Phobos functions are used often, and because specifying fully the path of function doesn't play well with UFCS chains (unless you use Alias!(), but it's long to write).

Recently one name clash, with "chunks", was removed from Phobos. Another clash, with "splitter", is currently worked on.

Bye,
bearophile

On Thursday, October 03, 2013 20:57:20 Craig Dillabaugh wrote:
> On Thursday, 3 October 2013 at 18:12:01 UTC, Jonathan M Davis
> 
> wrote:
> > On Thursday, October 03, 2013 15:22:28 Craig Dillabaugh wrote:
> >> It seems that std.file should include a writeText() function
> >> for
> >> the sake of consistency that is the above alias. When you come
> >> across readText() in the documentation you sort of expect that
> >> such a function would exist, and then you spot write() below
> >> it,
> >> and think hey that does what I need. Then you hit upon the
> >> syntax error if you are also using std.stdio (which is a very
> >> commonly used module).
> >> 
> >> Adding writeText() doesn't really add much to the library, but
> >> having to jump through hoops (as minor as they may be) to
> >> perform
> >> such a simple op is a bit of a pain for people new to the
> >> language.
> > 
> > writeText would be redundant. write will already write
> > arbitrary data to a file
> > - including strings. writeText would add no functionality.
> > Functions should
> > add actual value, or they just clutter up the library.
> > 
> > Conflicting functions is just part of life. The module system
> > is designed to
> > let you disambiguate them. We're not going to try and make all
> > of the function
> > names unique just because you might import a module with a
> > conflicting
> > function. If write is the best name for the function, then
> > that's what we'll
> > use, even if it conflicts with a function in another module. To
> > do otherwise
> > would be to ignore the features of the module system and force
> > us to come up
> > with worse names just to avoid conflicts.
> > 
> > - Jonathan M Davis
> 
> Fair enough. As you point out the fix is pretty simple.
> 
> However, I can't seem to remember in C++ or any other language (not that I know all that many other languages) coming across a function in the standard library that conflicted with another function in the standard library in this way. I am likely to get corrected on that claim though :o)

I'm sure that it could be found somewhere, but C++ avoids it for two reasons:

1. As good as the STL is, it's pathetically small.
2. It only uses one namespace, so it _has_ to avoid conflicts, even if that
means using uglier names.

Java or C# might have some conflicts (I'm not sure - they certainly have much richer standard libraries than C++ does), but they almost always avoid it, because they're don't even allow free functions, so you only end up having to worry about class names conflicting. Their module systems are also different from D's (particularly C#'s), which changes things a bit.

Other languages like python tend to force you to give the full path anyway, which avoids conflicts.

The reason that D runs into them is because the default is to pull everything into the current module when you import it. If we'd taken the approach of making you give the full import path by default or forcing you to explicitly import each symbol, then it wouldn't be a problem (though that would obviously cause other problems).

And we'll definitely pick different names where appropriate, but if the best names for two different functions in two different modules happen to be the same name, then we're going to use it. And in same cases, we very purposely picked the same name, because the functions did the same type of thing (e.g. the functions in std.ascii and std.uni which do the same thing but for ASCII and Unicode respectively).

- Jonathan M Davis

On Thursday, 3 October 2013 at 19:49:07 UTC, Jonathan M Davis wrote:
> On Thursday, October 03, 2013 20:57:20 Craig Dillabaugh wrote:
>> On Thursday, 3 October 2013 at 18:12:01 UTC, Jonathan M Davis

clip

>> > 
>> > - Jonathan M Davis
>> 
>> Fair enough. As you point out the fix is pretty simple.
>> 
>> However, I can't seem to remember in C++ or any other language
>> (not that I know all that many other languages) coming across a
>> function in the standard library that conflicted with another
>> function in the standard library in this way. I am likely to get
>> corrected on that claim though :o)
>
> I'm sure that it could be found somewhere, but C++ avoids it for two reasons:
>
> 1. As good as the STL is, it's pathetically small.
> 2. It only uses one namespace, so it _has_ to avoid conflicts, even if that
> means using uglier names.
>
> Java or C# might have some conflicts (I'm not sure - they certainly have much
> richer standard libraries than C++ does), but they almost always avoid it,
> because they're don't even allow free functions, so you only end up having to
> worry about class names conflicting. Their module systems are also different
> from D's (particularly C#'s), which changes things a bit.
>
> Other languages like python tend to force you to give the full path anyway,
> which avoids conflicts.
>
> The reason that D runs into them is because the default is to pull everything
> into the current module when you import it. If we'd taken the approach of
> making you give the full import path by default or forcing you to explicitly
> import each symbol, then it wouldn't be a problem (though that would obviously
> cause other problems).
>
> And we'll definitely pick different names where appropriate, but if the best
> names for two different functions in two different modules happen to be the same
> name, then we're going to use it. And in same cases, we very purposely picked
> the same name, because the functions did the same type of thing (e.g. the
> functions in std.ascii and std.uni which do the same thing but for ASCII and
> Unicode respectively).
>
> - Jonathan M Davis

That is an excellent explanation.  Thank you.

Do you think it would be worth noting the conflict in the documentation for readText()/write()?

I should have mentioned in my original post that I likely could have figured out the workaround for this, and I posted here more because I was surprised that std.stdio and std.file would have a conflict!  It seems like something folks new to D might run into with some frequency, and be thinking "whats up with that!".

If others think it is a good idea, maybe I will head over to gitHub and try to add something.

Craig

On Thursday, October 03, 2013 22:57:22 Craig Dillabaugh wrote:
> On Thursday, 3 October 2013 at 19:49:07 UTC, Jonathan M Davis
> 
> wrote:
> > On Thursday, October 03, 2013 20:57:20 Craig Dillabaugh wrote:
> >> On Thursday, 3 October 2013 at 18:12:01 UTC, Jonathan M Davis
> 
> clip
> 
> >> > - Jonathan M Davis
> >> 
> >> Fair enough. As you point out the fix is pretty simple.
> >> 
> >> However, I can't seem to remember in C++ or any other language
> >> (not that I know all that many other languages) coming across a
> >> function in the standard library that conflicted with another
> >> function in the standard library in this way. I am likely to
> >> get
> >> corrected on that claim though :o)
> > 
> > I'm sure that it could be found somewhere, but C++ avoids it for two reasons:
> > 
> > 1. As good as the STL is, it's pathetically small.
> > 2. It only uses one namespace, so it _has_ to avoid conflicts,
> > even if that
> > means using uglier names.
> > 
> > Java or C# might have some conflicts (I'm not sure - they
> > certainly have much
> > richer standard libraries than C++ does), but they almost
> > always avoid it,
> > because they're don't even allow free functions, so you only
> > end up having to
> > worry about class names conflicting. Their module systems are
> > also different
> > from D's (particularly C#'s), which changes things a bit.
> > 
> > Other languages like python tend to force you to give the full
> > path anyway,
> > which avoids conflicts.
> > 
> > The reason that D runs into them is because the default is to
> > pull everything
> > into the current module when you import it. If we'd taken the
> > approach of
> > making you give the full import path by default or forcing you
> > to explicitly
> > import each symbol, then it wouldn't be a problem (though that
> > would obviously
> > cause other problems).
> > 
> > And we'll definitely pick different names where appropriate,
> > but if the best
> > names for two different functions in two different modules
> > happen to be the same
> > name, then we're going to use it. And in same cases, we very
> > purposely picked
> > the same name, because the functions did the same type of thing
> > (e.g. the
> > functions in std.ascii and std.uni which do the same thing but
> > for ASCII and
> > Unicode respectively).
> > 
> > - Jonathan M Davis
> 
> That is an excellent explanation. Thank you.
> 
> Do you think it would be worth noting the conflict in the
> documentation for readText()/write()?
> 
> I should have mentioned in my original post that I likely could have figured out the workaround for this, and I posted here more because I was surprised that std.stdio and std.file would have a conflict! It seems like something folks new to D might run into with some frequency, and be thinking "whats up with that!".
> 
> If others think it is a good idea, maybe I will head over to gitHub and try to add something.

I'm inclined to think that there's no need, since people learning D should know how the module system works, and I'd prefer not to clutter the documentation, but I also haven't been a newbie for a very long time.

- Jonathan M Davis

On Thursday, 3 October 2013 at 21:58:18 UTC, Jonathan M Davis wrote:
> On Thursday, October 03, 2013 22:57:22 Craig Dillabaugh wrote:
>> On Thursday, 3 October 2013 at 19:49:07 UTC, Jonathan M Davis
>> 
>> wrote:
>> > On Thursday, October 03, 2013 20:57:20 Craig Dillabaugh wrote:
>> >> On Thursday, 3 October 2013 at 18:12:01 UTC, Jonathan M Davis
>> 
>> clip
>> 
>> >> > - Jonathan M Davis
>> >> 
>> >> Fair enough. As you point out the fix is pretty simple.
>> >> 
>> >> However, I can't seem to remember in C++ or any other language
>> >> (not that I know all that many other languages) coming across a
>> >> function in the standard library that conflicted with another
>> >> function in the standard library in this way. I am likely to
>> >> get
>> >> corrected on that claim though :o)
>> > 
>> > I'm sure that it could be found somewhere, but C++ avoids it
>> > for two reasons:
>> > 
>> > 1. As good as the STL is, it's pathetically small.
>> > 2. It only uses one namespace, so it _has_ to avoid conflicts,
>> > even if that
>> > means using uglier names.
>> > 
>> > Java or C# might have some conflicts (I'm not sure - they
>> > certainly have much
>> > richer standard libraries than C++ does), but they almost
>> > always avoid it,
>> > because they're don't even allow free functions, so you only
>> > end up having to
>> > worry about class names conflicting. Their module systems are
>> > also different
>> > from D's (particularly C#'s), which changes things a bit.
>> > 
>> > Other languages like python tend to force you to give the full
>> > path anyway,
>> > which avoids conflicts.
>> > 
>> > The reason that D runs into them is because the default is to
>> > pull everything
>> > into the current module when you import it. If we'd taken the
>> > approach of
>> > making you give the full import path by default or forcing you
>> > to explicitly
>> > import each symbol, then it wouldn't be a problem (though that
>> > would obviously
>> > cause other problems).
>> > 
>> > And we'll definitely pick different names where appropriate,
>> > but if the best
>> > names for two different functions in two different modules
>> > happen to be the same
>> > name, then we're going to use it. And in same cases, we very
>> > purposely picked
>> > the same name, because the functions did the same type of thing
>> > (e.g. the
>> > functions in std.ascii and std.uni which do the same thing but
>> > for ASCII and
>> > Unicode respectively).
>> > 
>> > - Jonathan M Davis
>> 
>> That is an excellent explanation. Thank you.
>> 
>> Do you think it would be worth noting the conflict in the
>> documentation for readText()/write()?
>> 
>> I should have mentioned in my original post that I likely could
>> have figured out the workaround for this, and I posted here more
>> because I was surprised that std.stdio and std.file would have a
>> conflict! It seems like something folks new to D might run into
>> with some frequency, and be thinking "whats up with that!".
>> 
>> If others think it is a good idea, maybe I will head over to
>> gitHub and try to add something.
>
> I'm inclined to think that there's no need, since people learning D should
> know how the module system works, and I'd prefer not to clutter the
> documentation, but I also haven't been a newbie for a very long time.
>
> - Jonathan M Davis

There are two problems with this for newbies:

1. They may not understand the module system well.
2. The may not know that a string = char array, and that as such it may not even occur to them that write() will accept a string. Now a careful reading of the docs for readText() should clue them in that string = char array, but when you are new to a language and trying to absorb the new syntax it is something that can easily be overlooked.

I have just enough D experience now that for the most part I don't struggle to follow the documentation, but I remember when I was new to D I found it very frustrating. That is even after reading Anderi's book (maybe I am a slow learner, but I am likely fairly representative of the average coder!) Now part of that is the known shortage of documentation, but often example code can be hard to follow, for example, from write:

   int[] a = [ 0, 1, 1, 2, 3, 5, 8 ];
   write("filename", a);
   assert(cast(int[]) read("filename") == a);

Consider the final 'assert' line.  On the one hand, it shows how to concisely use language features and good D coding practices, however, on the other hand  there is an awful lot going on in a single line of code. To someone who knows the language it looks trivial, but it can be a bit overwhelming to a newbie who wants to see if they can use this new language to write some text to a file!

I guess the more fundamental question is, what is the purpose of the documentation?  Is it a quick reference for D users, or is it a resource for people trying to learn the language?  I learned C++ using Qt, largely from their online docs. The Qt documentation is a reference, but it also tends to provide lots of explanation.

I've seen both, documentation strictly as a reference for those who already know how to use it, and docs with more focus on explaining how things work to the uninitiated.  I tend to like the later approach, but it is certainly debatable.

On Friday, October 04, 2013 16:12:14 Craig Dillabaugh wrote:
> I guess the more fundamental question is, what is the purpose of the documentation? Is it a quick reference for D users, or is it a resource for people trying to learn the language? I learned C++ using Qt, largely from their online docs. The Qt documentation is a reference, but it also tends to provide lots of explanation.

It would never have occurred to me that API documentation would be use for teaching the language - even documentation for the standard library. I would expect people to learn the language first. Yes, the standard library documentation needs to be reasonably accessible to newbies, but I would not expect it to be used as a teaching tool for the language. The documentation on a type or function is there to teach you about how to use that particular type or function, not how to use the language.

Of course, I'm also the sort of person who thinks that people are nuts to just jump into a game without reading the entire manual first.

- Jonathan M Davis

On Saturday, 5 October 2013 at 02:42:54 UTC, Jonathan M Davis
wrote:
> On Friday, October 04, 2013 16:12:14 Craig Dillabaugh wrote:
>> I guess the more fundamental question is, what is the purpose of
>> the documentation? Is it a quick reference for D users, or is it
>> a resource for people trying to learn the language? I learned
>> C++ using Qt, largely from their online docs. The Qt
>> documentation is a reference, but it also tends to provide lots
>> of explanation.
>
> It would never have occurred to me that API documentation would be use for
> teaching the language - even documentation for the standard library. I would
> expect people to learn the language first. Yes, the standard library
> documentation needs to be reasonably accessible to newbies, but I would not
> expect it to be used as a teaching tool for the language. The documentation on
> a type or function is there to teach you about how to use that particular type
> or function, not how to use the language.
>
> Of course, I'm also the sort of person who thinks that people are nuts to just
> jump into a game without reading the entire manual first.
>
> - Jonathan M Davis

Yes, but the manual (Andrei's book?) barely touches on the
standard library (ranges are not even covered).  Things are
getting better now that Ali's book is getting closer to having a
complete English translation.  For whatever reason, when I first
started trying to use Phobos, I found that the knowledge I had
gathered from Andrei's book still left me dazed and confused at
times.

Cheers,
Craig