Filesystem API - Hobgoblin of little minds in little bike sheds with little bicycles

[Kris Kowal]

I think our users will love us if we give them an API that appears to
have been wrought from a central philosophy, one that will more often
than not enable them to make an educated guess about the name of a
function before they have to look it up in the documentation. We
presently have a medley, based on mostly individual feedback for parts
of the API. To that end, I believe we are faced with one of these
options:

A.) No philosophy. So, it was designed by a committee; at least it's honest.

B.) chose names consistent with a literate naming philosophy, similar
to Java and its progeny:
makeDirectory
remove
removeTree
list
listTree
changeDirectory
changePermissions
listPaths
listTreePaths

C.) chose names consistent with this the Unix naming philosophies
(using C or shell naming conventions where apt):
mkdir
rm
rmtree
ls
lstree
chdir
chown
chmod
lsPaths
lstreePaths

D.) mostly Unixy, except use "list" and "remove" literately.

mkdir
remove
removeTree
list
listTree
chdir
chown
listPaths
listTreePaths

E-Z+.) Your ideas here.

I've left out "mtime" since we've already arrived at consensus on that
one, but it's worth pointing out that it is in the Unixy camp, so
compatible with C and D philosophically.

I've also left out "mktree", "mkdirs", "mkpath", or "mkwhatever",
since I don't think we've arrived at a consensus on that name. I'm
favoring "mkdirs" against 1 dissenter.

I'm proposing the addition of *Paths for functions that return Arrays
of Path objects instead of Strings. I experimented with just one or
the other (always returning Paths or always returning Strings), but
both turned out to be useful.

Also, regardless of the convention, we should add "glob" and "globPaths".

Kris Kowal

[Wes Garland]

B B B B B !

(and I'm a UNIX guy by trade!)

Wes

--
Wesley W. Garland
Director, Product Development
PageMail, Inc.
+1 613 542 2787 x 102

[Mark S. Miller]

On Sun, Aug 30, 2009 at 7:34 AM, Wes Garland<w...@page.ca> wrote:
> B B B B B !

Hey Wes, how come you get five votes? ;)

B too.

--
Cheers,
--MarkM

[George Moschovitis]

B

[Zachary Carter]

I'm a fan of succinctness, and Unix, but B seems like it will be
easier to keep consistent across the board.

B

--
Zach Carter
http://zach.carter.name

[Dean Landolt]

On Sun, Aug 30, 2009 at 8:27 PM, Zachary Carter <zack....@gmail.com> wrote:

I'm a fan of succinctness, and Unix, but B seems like it will be
easier to keep consistent across the board.

B

B

That's one thing java got right.

[Daniel Friesen]

Same style as the rest of the language, don't need my vote to make this
a unanimous B.

~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://daniel.friesen.name]

[Isaac Z. Schlueter]

B

--i

[Kevin Dangoor]

On Sun, Aug 30, 2009 at 1:20 AM, Kris Kowal <cowber...@gmail.com> wrote:

B.) chose names consistent with a literate naming philosophy, similar
to Java and its progeny:

Readable good :)

--
Kevin Dangoor

work: http://labs.mozilla.com/
email: k...@blazingthings.com
blog: http://www.BlueSkyOnMars.com

[Joshaven Potter]

Maybe I am a looking too deep into your example and missing the point but I would like to see libraries that control these names...

For instance a POSIX library when included should yield unix style names... 

Without a library, I don't believe you should be able to list files or make directories.  You will need to read files to load the library you want but that is about all of the file system stuff that should be baked in.

I agree that consistency is important but I want to see a very limited scope baked in.  However, I would love to have a POSIX library and then I would expect functions like ls() & mkdir() & ln()

So if I had to vote on the purposed options I would choose B because I wouldn't want to see a command so short as 'ls' being a reserved word but I would love to do something like:

require('posix.js');
shell = new POSIX(); 
array_of_files = shell.ls(path);

Thus I propose verbose function names for stuff that is baked in but nice standard libraries that would have function names that you can predict.

On Sun, Aug 30, 2009 at 1:20 AM, Kris Kowal <cowber...@gmail.com> wrote:

--
Sincerely,
Joshaven Potter

"No man making a profession of faith ought to sin, nor one possessed of love to hate his brother. For He that said, “Thou shalt love the Lord thy God,”  said also, “and thy neighbor as thyself.”  Those that profess themselves to be Christ’s are known not only by what they say, but by what they practice. “For the tree is known by its fruit.”" -- Ignatius

[Dean Landolt]

On Mon, Aug 31, 2009 at 10:11 AM, Joshaven Potter <your...@gmail.com> wrote:

Maybe I am a looking too deep into your example and missing the point but I would like to see libraries that control these names...

For instance a POSIX library when included should yield unix style names... 

Without a library, I don't believe you should be able to list files or make directories.  You will need to read files to load the library you want but that is about all of the file system stuff that should be baked in.

I agree that consistency is important but I want to see a very limited scope baked in.  However, I would love to have a POSIX library and then I would expect functions like ls() & mkdir() & ln()

So if I had to vote on the purposed options I would choose B because I wouldn't want to see a command so short as 'ls' being a reserved word but I would love to do something like:

require('posix.js');
shell = new POSIX(); 
array_of_files = shell.ls(path);

Thus I propose verbose function names for stuff that is baked in but nice standard libraries that would have function names that you can predict.

I don't think anyone is suggesting ls would be a reserved word, or any of these names would be in the globals. You would still have to something like var fs = require('file');

Which reminds me -- what was the consensus on the actual module name? Someone had proposed changing it to fs IIRC?

[Dean Landolt]

So if I had to vote on the purposed options I would choose B because I wouldn't want to see a command so short as 'ls' being a reserved word but I would love to do something like:

require('posix.js');
shell = new POSIX(); 
array_of_files = shell.ls(path);

Also, this example perhaps reiterates the "foolish consistencies" implied by Kris in this thread's subject. I would also love to see a posix module that let you work in a fashion similar to your example -- but all of this could be implemented easily on top of the file module.

[Joshaven Potter]

So how does that invalidate my statement?

1) I don't want to see a bloated baked in API

2) I want to see everything like 'ls' or 'pwd', etc in an external library

I don't care if the POSIX is just a bunch of aliases for a 'File' library.  I was answering the question regarding which method was preferred and I had to say it wasn't specifically any of the options presented.  I like verbosity for anything baked in but I also like what I am familiar with and since I know and prefer commands like: ls, pwd, etc I would prefer to use them.   However ls & pwd have no relationship to JavaScript so they should not be part of the JavaScript API.  They should be part of a library that I can use if I want to.   

My example was saying that I liked the "foolish consistencies" which are neither foolish nor inconsistent when you are using a library that does what your asking it to do.  Which was entirely my point.  I would not like to see ls & pwd as part of the Standard API.  However, I would prefer to use them so I would like to see standard libraries that will allow me, if I choose, to access the standard File & Directory libraries through an optional "Portable Operating System Interface [for Unix"] standards library.  I believe that the core JavaScript standard API should not have anything in it that the JavaScript doesn't already contain except as necessary to live in the environment outside the browser.  Everything else should be in standard libraries that work the way you would expect that library to work.  

If the library is a POSIX library then you would expect it to respond to POSIX commands but if it is only a 'File' Library then it should not be modeled after POSIX.  

[Isaac Z. Schlueter]

Joshaven,

So, if I understand you correctly, your point is:

a) The Javascript baked-in API should contain the absolute minimum
functionality.
b) Everything above the absolute minimum functionality should be in
separate libraries that you can use if you want.
c) Beyond that, you don't care much (but if someone writes a posix.js
library, you'll use it.)

I don't disagree with any of that. It's a good point. It sounds like
the key takeaway here is that you're not voting in Kris's little
(mind,shed,bike) question.

Let's still make the (minimum) baked-in stuff use the longer names.
They're more readable.

--i

On Aug 31, 7:44 am, Joshaven Potter <yourt...@gmail.com> wrote:
> So how does that invalidate my statement?
> 1) I don't want to see a bloated baked in API
> 2) I want to see everything like 'ls' or 'pwd', etc in an external library
>
> I don't care if the POSIX is just a bunch of aliases for a 'File' library.
>  I was answering the question regarding which method was preferred and I had
> to say it wasn't specifically any of the options presented.  I like
> verbosity for anything baked in but I also like what I am familiar with and
> since I know and prefer commands like: ls, pwd, etc I would prefer to use
> them.   However ls & pwd have no relationship to JavaScript so they should
> not be part of the JavaScript API.  They should be part of a library that I
> can use if I want to.
>
> My example was saying that I liked the "foolish consistencies" which are
> neither foolish nor inconsistent when you are using a library that does what
> your asking it to do.  Which was entirely my point.  I would not like to see
> ls & pwd as part of the Standard API.  However, I would prefer to use them
> so I would like to see standard libraries that will allow me, if I choose,

> to access the standard File & Directory libraries through an optional "*P*
> ortable *O*perating *S*ystem *I*nterface [for Uni*x*"] standards library.  I

[Mike Wilson]

My favourite bikeshed is built upon classic Java- and
JavaScript:ish naming, ie (B).

A small anecdote is in place :-)
Many years ago I read an interview with Kernighan and
Ritchie, and towards the end the interviewer asked
what they would change in Unix if they could do it
all over again. The reply was "not to abbreviate the
"create" function into creat()".

Best regards
Mike

[Joshaven Potter]

yep!

[Wes Garland]

Mike:

That quote is on point. I think I first read it in "Programming in the UNIX Environment" by Kerninghan & Pike. Although I believe it's typically quoted like this

Ken Thompson was once asked by a reporter what he would have changed about

Unix if he had it all to do over again. His answer: "I would spell creat
with an `e.'"

Wes

[Mike Wilson]

Thanks for the improvement on that citation Wes. I felt I didn't get that completely right - trying to recall it from reading some computer journal in the '80s :-)

Best regards

Mike 

---

From: comm...@googlegroups.com [mailto:comm...@googlegroups.com] On Behalf Of Wes Garland
Sent: den 31 augusti 2009 20:59
To: comm...@googlegroups.com
Subject: [CommonJS] Re: Filesystem API - Hobgoblin of little minds in little bike sheds with little bicycles

[Kris Kowal]

I think we've forced the dissenting opinions into hiding.

There are a lot of votes for *individual* function names in the Unix style. [1]

Kevin showed his hand "mkdir" and "mkdirs".
Wes showed his hand for "unlink".
Mario Valente showed his hand for "stat".
Tom, Kevin, and Ondrej have hands shown for "mtime", "atime", and "ctime".

If I went ahead with B for another draft, these would be named
"makeDirectory", "makeDirectories", "remove", and "lastModified".
"stat", "atime", and "ctime" don't have platform independent analogs,
but I would probably have different names for these too.

Before proceeding with a draft based on philosophy B, I would think we
need to hear from Kevin, Tom, and Ondrej at least. We haven't heard
much from Mario lately, but I'd like to hear his opinion too. Also,
Wes, as you've already shown support for B, I'd like hear whether you
feel this consideration should override your previous preferences. I
think we also need support from at least Hannes, Kris Zyp to proceed.

Kris Kowal

[1] https://wiki.mozilla.org/ServerJS/Filesystem_API/Names

[Kevin Dangoor]

On Mon, Aug 31, 2009 at 3:39 PM, Kris Kowal <cowber...@gmail.com> wrote:

Kevin showed his hand "mkdir" and "mkdirs".

I change my vote to consistent, readable style B. (And thanks for changing the presentation of the names this way, Kris... it was too easy to stick with some of the familiar names even though the API should be considered as a whole.)

Kevin

[Mike Wilson]

While sipping evening tea in my front-side bikeshed, I
came to think of a broader picture. Should the naming
philosophy chosen here maybe apply to all CommonJS
APIs, and not just the Filesystem API?

Maybe that should f ex influence the recently
discussed JSGI a bit? (which lends a fair bit from CGI
and Rack atm - but a discussion on details should
probably be forked to another thread)

Best regards
Mike Wilson

[Ash Berlin]

On the subject of stat, I was thinking that perhaps stat should only
contain entries for the metadata that can be reliably gathered cross
platform (i.e. particualrly not deviceNumber etc.), and move those
extra fields into say, |require('posix').stat('file')| so that code
has to make a conscious choice to not be portable across platforms?
Thoughts?

Also can someone explain to me the reason why Path ctor takes a FS
object? And an actual use case of this feature, since I can sort of
see why, I think.

[Mário Valente]

[Mário Valente]

On Mon, Aug 31, 2009 at 8:39 PM, Kris Kowal <cowber...@gmail.com> wrote:

>

> There are a lot of votes for *individual* function names in the Unix style.

> [1]
>
>

> Before proceeding with a draft based on philosophy B, I would think we
> need to hear from Kevin, Tom, and Ondrej at least.  We haven't heard
> much from Mario lately, but I'd like to hear his opinion too.

>

  Thanks for calling me out of lurker mode Kris :)
  I've been busy, but I've kept up with discussions, at least on reading
 mode. Most of the time I just feel that the stuff you guys discuss is

 way over my head and I dont think that I would have anything of value to
 add, especially since most of the time there's someone else that states
 what would be my opinion but does so in a much better way than what I

 would have been able,

   On the subject at hand: I would definitely prefer all File/IO ops to be
 Unix/C/POSIX oriented. I'm just used to them and feel that they are more
 succint (ie. less typing). I do hate the verbosity of Java; but like

someone
 else said, I wont hold that grudge over the advantage of having a
structured
 architected API.

   So that means I surely support the overwhelming B choice, even in the
  case of stat :-)


    But like Joshaven I would prefer that the stuff baked in would be as
  least as possible, allowing for the later creation of libraries (namely a
  POSIX one :-)

    -- MV

[Hannes Wallnoefer]

+ 1 for the longer B names, and for rethinking the previously agreed
on Unix-style names.

Hannes