File API thoughts

Issue #683 closed
created an issue

Could File:isOpen be removed, since its the same (I think) as File:getMode() ~= 'c'? It makes me think of how SpriteBatches and ParticleSystems don't have isEmpty and isFull, because the same information can be gained using get*Count and getBufferSize.

And another thought, could File:open and File:close be replaced by File:setMode? I know this seems a bit crazy since it deviates from file object conventions. But, ignoring external conventions a bit, maybe it makes some sense:

  • There's one less method.
  • It's easier to reopen files in a different mode.
  • It's symmetrical with File:getMode.

Comments (12)

  1. Alex Szpakowski

    I added File:isOpen for symmetry with File:open and File:close.

    I think File:setMode makes more sense in the context of the rest of the LÖVE API, but I'm not positive it makes more sense in terms of what a lover might intuitively look for when learning the File API.

    i.e., when asking "how do I use this File object to write to the file?" I think File:open might make more intuitive sense than File:setMode.

  2. hahawoo reporter

    Something to keep in mind is that newFile can now also open a File for writing/appending/reading. So in some (most, maybe?) circumstances, File:open won't be needed at all.

    I get what you mean about it being intuitive. People who have programmed in other things before have surely seen something like "File:open".

    But of course there's more to being intuitive than just being "what you're used to". I think internal consistency makes things fast to learn and easy to think about, even if it's different from what you've seen before.

    That's why I don't really like the names seek and tell. The names don't communicate what state they're changing as obviously as setX and getX names. And since they don't start with get or set, it's not obvious they deal with state, rather than performing some action.

    Here's how the File API looks currently:

    -- State
    -- Unsettable state
    -- Actions

    And here's how it could look:

    -- State
    -- Unsettable state
    -- Actions

    With the latter API, I can instantly see that there are 3 elements of changeable state, "Buffer", "Mode" and "Location".

    I also know that isEOF returns a single boolean because it starts with "is", and that "EOF" is an acronym because it's in capital letters. And I know that "write", "read", "lines" and "flush" perform actions, because they don't start with set/get/is/has.

  3. hahawoo reporter

    You don't need to use setMode to open a file, you only need to use setMode to change the way in which the file is treated, its "mode". This mode is set when the object is created, and defaults to "c", the mode which means "it can't be read or written to".

    The File's mode is a state which is set initially in the constructor, has a default value, and can be set/get with methods. This pattern is seen elsewhere in the API. If you were new to File objects and saw this in the docs, hopefully this would be as you expected.

  4. hahawoo reporter

    By "intuitive" I meant File:setMode does not sound like it has anything to do with what you actually want to do, until you know exactly what setMode does.

    What do you want it to do?

    setMode is not what I'd be looking for when I want to open a file.

    "Open" a file? There doesn't need to be concept of making a file "open". A file can simply can have a "mode" which dictates how actions performed on it work.

    Think of the problems people already have finding functions in the docs.

    Perhaps the docs would be better if functions were sorted by the state they deal with, rather than their alphabetical order. My proposed names would suit this well! ;)

  5. Alex Szpakowski

    "Open" a file? There doesn't need to be concept of making a file "open". A file can simply can have a "mode" which dictates how actions performed on it work.

    Opening and closing a file does more than just change what you can do to it. For example, calling File:close will implicitly flush all buffered data in the file to the disk. File:setMode does not convey that at all.

    EDIT: It'd also be weird to have to explain that File:setMode is called when the file object gets garbage collected, or that calling File:setMode("r") when the File is in the "w" mode actually does something like File:setMode("c"); File:setMode("r") .

  6. Bart van Strien

    What I want setMode to do? No idea, it's non-descriptive, what mode?

    And yes, opening a file is very much a thing that happens, people know how files work (kind of, in a high-level way), you don't change a file mode in word, you open a file, save it, then close it. It's how files work.

  7. hahawoo reporter

    Thanks as always for the explanations! :) Setting the mode wouldn't quite be as simple as I thought, hehe.

    So, how about File:isEOF and File:get/setLocation then? :D

    isEOF I imagine expanding to is( at )EOF. Or, like, is( at the )EO( the )F. :P

  8. hahawoo reporter

    Or, File:get/setPosition.

    This is different from Lua's file:seek, but File:get/setBuffer is also different from file:setvbuf, and I think get/setBuffer are good names because they're lovely.

  9. Log in to comment