documentation update

[perlpilot]

So ... I updated the docs and added a couple of tests.

However, your email said "...a test that should fail to find something because it's an executable in that fallback mode..." and that caused a bit of confusion because that's not what exe => 0 does apparently. From what I can see, exe => 1 will only return results that are executable, but exe => 0 will return results whether they are executable or not. Your email would imply that this is a bug.

But, another way to look at things is that exe => 1 could mean "test that the file is executable" and dir => 1 could mean "test that the 'file' is a directory", while the => 0 versions of those mean "don't perform this test". My reading of the existing docs jibes with this interpretation. However, this would mean that dir => 0 currently has a bug. [As an aside, under this interpretation, you actually could have both exe => 1 and dir => 1 rather than croak as you do now]

Either way I think there's a bug somewhere and that the docs need to be updated to clearly reflect whichever interpretation is correct.

If you open an RT or github issue with guidance on which way you want to go, I'll fix it :-)

[timj]

It's been so long since I've looked at this I might be forgetting something. I think I mean that for the fallback 2-arg legacy version you need a test that would find an executable correctly and a test that would fail to find a different file that is not executable but is present.