As it stands now listdir is deprecated in favor of listDir, according to
one part of Ddoc for std.file:
$(RED Scheduled for deprecation in August 2011. Please use $(D listDir)
instead.

Another part says:
$(RED Scheduled for deprecation in August 2011.
        Please use $(D dirEntries) instead.

So what is the most relevant?

-- 
Dmitry Olshansky

Both listDir and listdir should go.

Andrei

On 6/9/11 3:15 PM, Dmitry Olshansky wrote:
> As it stands now listdir is deprecated in favor of listDir, according to
> one part of Ddoc for std.file:
> $(RED Scheduled for deprecation in August 2011. Please use $(D listDir)
> instead.
>
> Another part says:
> $(RED Scheduled for deprecation in August 2011.
> Please use $(D dirEntries) instead.
>
> So what is the most relevant?
>

Next question in the row - what to do with a mission to swap std.regexp
to std.regex?
Right now, std.file listDir is the only one function in the whole Phobos
that uses std.regexp.
I managed to set it on the std.regex rails, but making soft deprecation
warning appear at the right time without breaking alias listdir
->listDir is a messy thing. Now it seems like a bad idea to update
already deprecated API ;)
So, should I make all of listdir/listDir templated so that they show
deprecation warnings when used?

> Both listDir and listdir should go.
>
> Andrei
>
> On 6/9/11 3:15 PM, Dmitry Olshansky wrote:
>> As it stands now listdir is deprecated in favor of listDir, according to
>> one part of Ddoc for std.file:
>> $(RED Scheduled for deprecation in August 2011. Please use $(D listDir)
>> instead.
>>
>> Another part says:
>> $(RED Scheduled for deprecation in August 2011.
>> Please use $(D dirEntries) instead.
>>
>> So what is the most relevant?
>>


-- 
Dmitry Olshansky

On 2011-06-09 13:19, Andrei Alexandrescu wrote:
> Both listDir and listdir should go.

Quite possibly. But there are several versions of listdir and not all of them were marked as being supposed to be deprecated. In fact, glancing at std.file, it looks like only the version which took a delegate was marked as supposed to be deprecated. So, I renamed that one to _listDir and made it private (since dirEntries need it) and marked the old one as scheduled for deprecation. The overloads which hadn't been marked as supposed to be deprecated, I renamed to listDir (and scheduled the old versions for deprecation).

So, I just went with what the documentation had previously said about deprecation. I don't know if we want to get rid of all of the public versions of listdir/listDir or not. They provide a different set of functionality than dirEntries does. Of course, the version which is fully currently scheduled for deprecation rather than being renamed is the most versatile (the one which takes a delegate) - it's also the one that needs to be around for dirEntries unless it's just completely redesigned. The overload which takes a path is only useful insomuch as it's probably a bit more efficient than call dirEntries, so it should probably go. The other two take a pattern and a RegEx respectively, and so getting rid of them would certainly reduce functionality further, but in all cases, you could simply iterate with dirEntries and check each file individually as to whether it matches what you want (more verbose, but not a huge deal).

So, if you want to get rid of all public versions of listdir and listDir, that's fine with me. I don't personally use any of them anyway, but what's currently there is based on what the documentation previously said about deprecation.

- Jonathan M Davis

Make the minimum amount of work to not break people's code now while at the same time paving the road to change.

Andrei

On 6/9/11 3:31 PM, Dmitry Olshansky wrote:
> Next question in the row - what to do with a mission to swap std.regexp
> to std.regex?
> Right now, std.file listDir is the only one function in the whole Phobos
> that uses std.regexp.
> I managed to set it on the std.regex rails, but making soft deprecation
> warning appear at the right time without breaking alias listdir
> ->listDir is a messy thing. Now it seems like a bad idea to update
> already deprecated API ;)
> So, should I make all of listdir/listDir templated so that they show
> deprecation warnings when used?
>
>> Both listDir and listdir should go.
>>
>> Andrei
>>
>> On 6/9/11 3:15 PM, Dmitry Olshansky wrote:
>>> As it stands now listdir is deprecated in favor of listDir, according to
>>> one part of Ddoc for std.file:
>>> $(RED Scheduled for deprecation in August 2011. Please use $(D listDir)
>>> instead.
>>>
>>> Another part says:
>>> $(RED Scheduled for deprecation in August 2011.
>>> Please use $(D dirEntries) instead.
>>>
>>> So what is the most relevant?
>>>
>
>

On 2011-06-09 13:31, Dmitry Olshansky wrote:
> Next question in the row - what to do with a mission to swap std.regexp
> to std.regex?
> Right now, std.file listDir is the only one function in the whole Phobos
> that uses std.regexp.
> I managed to set it on the std.regex rails, but making soft deprecation
> warning appear at the right time without breaking alias listdir
> ->listDir is a messy thing. Now it seems like a bad idea to update
> already deprecated API ;)
> So, should I make all of listdir/listDir templated so that they show
> deprecation warnings when used?

listdir/listDir is fully templatizable in that I'm not aware of any situation where having it changed to be templatized would break code. So, ideally it would have deprecation pragma inside of it, but what we really need is to have deprecated to be improved such that it can be given a message as well as whether the deprecation is soft or hard rather than just being hard. If you're going to mark those functions as scheduled for deprecation, then you can copy what was done for other functions in std.file - both in the documentation and with the pragma. The version number of Phobos in the pragma would obviously be 2.054, and the date would probably be October 2011 (normally, it would be December, but at least one overload of listdir has been listed as going to be deprecated for a while, and since regexp is on its way out, and we want it out relatively quickly, 4 months as scheduled for deprecation instead of 6 is probably plenty for this case).

If you don't want to deal with that though, I can handle it. If I had understood that all overloads of listdir were supposed to be going away rather than just the one, I would have scheduled them all for deprecation instead of renaming the ones I thought that we were keeping, and I guess that I'm the main person keeping track of the deprecation of stuff at this point. But you can take care of making the changes if you want to. The chief thing that I was looking for was for the regexp to regex to be made by someone who is familiar with regexp and regex.

- Jonathan M Davis

On 10.06.2011 4:25, Jonathan M Davis wrote:
> On 2011-06-09 13:31, Dmitry Olshansky wrote:
>> Next question in the row - what to do with a mission to swap std.regexp
>> to std.regex?
>> Right now, std.file listDir is the only one function in the whole Phobos
>> that uses std.regexp.
>> I managed to set it on the std.regex rails, but making soft deprecation
>> warning appear at the right time without breaking alias listdir
>> ->listDir is a messy thing. Now it seems like a bad idea to update
>> already deprecated API ;)
>> So, should I make all of listdir/listDir templated so that they show
>> deprecation warnings when used?
> listdir/listDir is fully templatizable in that I'm not aware of any situation where having it changed to be templatized would break code. So, ideally it would have deprecation pragma inside of it, but what we really need is to have deprecated to be improved such that it can be given a message as well as whether the deprecation is soft or hard rather than just being hard. If you're going to mark those functions as scheduled for deprecation, then you can copy what was done for other functions in std.file - both in the documentation and with the pragma. The version number of Phobos in the pragma would obviously be 2.054, and the date would probably be October 2011 (normally, it would be December, but at least one overload of listdir has been listed as going to be deprecated for a while, and since regexp is on its way out, and we want it out relatively quickly, 4 months as scheduled for deprecation instead of 6 is probably plenty for this case).
>
> If you don't want to deal with that though, I can handle it.

No problem, I'll do it.

>   If I had
> understood that all overloads of listdir were supposed to be going away rather
> than just the one, I would have scheduled them all for deprecation instead of
> renaming the ones I thought that we were keeping, and I guess that I'm the
> main person keeping track of the deprecation of stuff at this point. But you
> can take care of making the changes if you want to. The chief thing that I was
> looking for was for the regexp to regex to be made by someone who is familiar
> with regexp and regex.

So it looks like listDir(dir, new RegExp(".*d")) is supposed to be
filter!` !match(a,".*d").empty`(dirEntries(dir));
The problem is that DirIterator won't work with filter... Another is
that DirEntry is not described in docs.

So I guess for now I'll add a regex overload to dirEnitries instead of listDir.

-- 
Dmitry Olshansky

On 2011-06-10 02:19, Dmitry Olshansky wrote:
> On 10.06.2011 4:25, Jonathan M Davis wrote:
> > On 2011-06-09 13:31, Dmitry Olshansky wrote:
> >> Next question in the row - what to do with a mission to swap std.regexp
> >> to std.regex?
> >> Right now, std.file listDir is the only one function in the whole Phobos
> >> that uses std.regexp.
> >> I managed to set it on the std.regex rails, but making soft deprecation
> >> warning appear at the right time without breaking alias listdir
> >> ->listDir is a messy thing. Now it seems like a bad idea to update
> >> already deprecated API ;)
> >> So, should I make all of listdir/listDir templated so that they show
> >> deprecation warnings when used?
> > 
> > listdir/listDir is fully templatizable in that I'm not aware of any situation where having it changed to be templatized would break code. So, ideally it would have deprecation pragma inside of it, but what we really need is to have deprecated to be improved such that it can be given a message as well as whether the deprecation is soft or hard rather than just being hard. If you're going to mark those functions as scheduled for deprecation, then you can copy what was done for other functions in std.file - both in the documentation and with the pragma. The version number of Phobos in the pragma would obviously be 2.054, and the date would probably be October 2011 (normally, it would be December, but at least one overload of listdir has been listed as going to be deprecated for a while, and since regexp is on its way out, and we want it out relatively quickly, 4 months as scheduled for deprecation instead of 6 is probably plenty for this case).
> > 
> > If you don't want to deal with that though, I can handle it.
> 
> No problem, I'll do it.
> 
> >   If I had
> > 
> > understood that all overloads of listdir were supposed to be going away rather than just the one, I would have scheduled them all for deprecation instead of renaming the ones I thought that we were keeping, and I guess that I'm the main person keeping track of the deprecation of stuff at this point. But you can take care of making the changes if you want to. The chief thing that I was looking for was for the regexp to regex to be made by someone who is familiar with regexp and regex.
> 
> So it looks like listDir(dir, new RegExp(".*d")) is supposed to be
> filter!` !match(a,".*d").empty`(dirEntries(dir));
> The problem is that DirIterator won't work with filter... Another is
> that DirEntry is not described in docs.
> 
> So I guess for now I'll add a regex overload to dirEnitries instead of listDir.

DirEntry is most definitely in the docs. The problem is that we switched to using version(StdDdoc) instead of version(D_Ddoc) for Phobos, and Walter hasn't adjusted whatever he does for building the docs for www.digitalmars.com. The entirety of DirEntry is in a versionStdDdoc) block, so it doesn't show up. d-programming-language.org has it though.

The main problem with dirEntries is essentially as you point out. It doesn't work with anything but foreach. You can't even pass it to std.array.array to create an array. And it's because it's set up to work with either a string or a DirEntry for the loop variable. The advantage of listdir/listDir is that you get an actual array of strings to use when you need to pass it to something. Ideally, DirIterator wolud be made to work with more, but it hasn't been. I don't know if we want to try and turn it into a range or what, but it is a bit of a problem if you want to use dirEntries outside of a foreach loop.

- Jonathan M Davis

On 6/10/11 4:47 AM, Jonathan M Davis wrote:
> The main problem with dirEntries is essentially as you point out. It doesn't work with anything but foreach. You can't even pass it to std.array.array to create an array. And it's because it's set up to work with either a string or a DirEntry for the loop variable. The advantage of listdir/listDir is that you get an actual array of strings to use when you need to pass it to something. Ideally, DirIterator wolud be made to work with more, but it hasn't been. I don't know if we want to try and turn it into a range or what, but it is a bit of a problem if you want to use dirEntries outside of a foreach loop.

Any chance of somebody finding the time to transform dirEntries into an input range? That would solve everything.

Andrei

On 10.06.2011 16:19, Andrei Alexandrescu wrote:
> On 6/10/11 4:47 AM, Jonathan M Davis wrote:
>> The main problem with dirEntries is essentially as you point out. It
>> doesn't
>> work with anything but foreach. You can't even pass it to
>> std.array.array to
>> create an array. And it's because it's set up to work with either a
>> string or
>> a DirEntry for the loop variable. The advantage of listdir/listDir is
>> that you
>> get an actual array of strings to use when you need to pass it to
>> something.
>> Ideally, DirIterator wolud be made to work with more, but it hasn't
>> been. I
>> don't know if we want to try and turn it into a range or what, but it
>> is a bit
>> of a problem if you want to use dirEntries outside of a foreach loop.
>
> Any chance of somebody finding the time to transform dirEntries into an input range? That would solve everything.
>
I decided to try just that. It will take some time though.

-- 
Dmitry Olshansky