Hello People,

I have held a brief discussion off-list with Emmanuel 
<[log in to unmask]>, regarding the behaviour of the list files 
command in the Satimage.osax. Emmanuel suggested that I post to one of 
several different email lists, as a way of gauging others' opinion on 
the matter, and macscrpt drew the long/short/only straw (I'm not a 
current member of the other options).

The list files command is as follows:

list files  alias -- a folder
	[recursively boolean] -- default: true
	[invisibles boolean] -- default: false
	Result : a list of alias

What I discovered, however, is that the user's choice regarding 
recursion has implications for the type of data returned:

list files --> files only, at all levels/sub-directories (default 
behaviour)
list files without recursion --> files and _folders_, but only at top 
level directory

(NB Emmanuel, you might also consider that with/without recursion seems 
a better, more english-like syntax than with/without recursively, as it 
is at present.)

In other words, list files without recursion is akin to the list folder 
command in Standard Additions.osax, albeit still returning aliases 
rather than file names.

As I wrote to Emmanuel:

I do not think I am the only person who might find this sort of 
behaviour disconcerting or inconsistent. The parameter used in the 
second line does not address the topic of whether the user wants 
folders as well as files, or just files only. To me an analogy might be 
this:

Say I own a ratchet screw-driver. One of the fittings is a "phillips" 
head (yes, I know, there's a new name for these but I forget what it 
is), but if I use that fitting, it turns my screw-driver into a hammer, 
not a screw-driver. Surely I would prefer my tool to show more 
consistency, to still remain a screw-driver when I fit a different 
screw-head on its top? If I want to turn my screw-driver into a hammer, 
I should have to attach a fitting named "hammer head"--i.e. the name of 
the parameter should match its function.

If it were me, I would make the list files command either return only 
files, regardless of the recursion param., or return both files and 
folders, once again regardless of the recursion param., so that it 
functions consistently. Another alternative would be something like the 
following, to give the user control of the output:

list files [boolean recursion] [boolean invisibles] [boolean folders]

Or else separate commands:

list files --> files only, regardless of params.
list items --> files and folders, regardless of params.

Inter alia, Emmanuel replied:

> Oh, I think I see now. You would have liked that "list files" without 
> recursion behave like "every file in". That's indeed not the case: 
> "list files" does behave like "ls".
>
> So, we do not consider that a bug - although I understand that you 
> might want to get the files only.
>
> If I had to list the files only, I would use a Regular expression - 
> often the fastest processing tool when appliable: tid(return), then 
> (list files ... as text), then change "^.*:$" into "" with regexp 
> (will suppress the lines ending with ":", which means folder.)

> you say the command is inconsistent, and I have to admit you're right: 
> you don't get the folders with "recursively true".
>
> Beyond the aesthetic side, a consistent command is easier to learn.

> Now, our reasons. We want a command useful, even if not fully 
> consistent. A useful command, I mean a command for which I know usual 
> situations where it fits. Here: list files without recursively is 
> little useful, "list folder" is as good, you just prefer list files if 
> you want the full paths. With a very fast regular expression you sort 
> out the folders from the files - and I admit that we could have 
> considered a "folders only" or something.
>
> Now, list files was first designed in its default configuration, 
> recursive. If you want, consider it to exist only in its default 
> configuration. As such, it addresses a frequent situation where the 
> user has all his *something* in one folder, but the user is free to 
> create any nested folders in that one folder.
>
> I am not saying that a majority of users would agree with our choice - 
> but I note you are. Logically, it would be interesting that you submit 
> the issue to a list of users, such as Macscrpt, ASUsers, or SUL.

Does anyone care to comment about this syntax issue, or perhaps to 
direct comments Emmanuel's way off-list?

Cheers!

Lengthy Apologja