API Roadmap

[joshgoebel]

trafficstars

A thread to track the overall API roadmap for the CLI.

IO

Directory

• [ ] create
• [ ] remove
• [x] exists
• [x] list

File

• [x] static create(path)
• [x] static create(path,fn)
• [x] static delete(path)
• [x] static exists(path)
• [x] static open(path)
• [x] static open(path,fn)
• [x] static openWithFlags(path, flags)
• [x] static openWithFlags(path, flags, fn)
• [x] static read(path)
• [x] static realPath(path)
• [x] size(path)
• [x] close()
• [x] size()
• [x] stat()
• [x] readBytes(count)
• [x] readBytes(count,offset)
• [x] writeBytes(bytes)
• [x] writeBytes(bytes, offset)

FileFlags

• static readOnly { 0x01 }
• static writeOnly { 0x02 }
• static readWrite { 0x04 }
• static sync { 0x08 }
• static create { 0x10 }
• static truncate { 0x20 }
• static exclusive { 0x40 }

Stat

• [x] static path(path
• [x] blockCount
• [x] blockSize
• [x] device -> isDevice
• [x] group
• [x] inode
• [x] linkCount
• [x] mode
• [x] size
• [x] specialDevice -> isSpecialDevice
• [x] user
• [x] isFile
• [x] isDirectory

Stdin

• [x] readByte
• [x] readLine
• [ ] readCodepoint (#71)
• [ ] readAll ???

Stdout

• [x] flush

OS

Platform

• [x] isPosix
• [x] isWindows
• [x] name
• [ ] homeDir (#78)

Process

• [x] arguments
• [x] allArguments
• [x] cwd -> Directory.currentWorking ???
• [x] pid
• [x] ppid
• [x] version -> System.wrenVersion
• [ ] exit (#74)

Scheduler

• [x] static add(callable)
• [x] runNextScheduled_(fiber) - not really private cause we call it everwhere

Timer

• [x] sleep -> Scheduler.sleep ???

[joshgoebel]

Thoughts/ideas just at a glance:

• move sleep from timer into scheduler
• move version to Wren proper System.wrenVersion
• Process.cwd -> Directory.currentWorking, although this starts to get into how we organize
• Scheduler.runNextScheduled_ => runNext() (scheduled is implied, it's the scheduler)
• device and specialDevice get the is prefix

[clsource]

I think Directory.remove and File.delete should be both named Directory.delete and File.delete. to be more consistent.

[PureFox48]

I don’t think it’s a good idea to move the sleep method to the Scheduler class.

Firstly, it’s the fiber from which it’s called that sleeps, not the Scheduler which takes the opportunity to run the fibers in its list one after the other. However, you can’t put it in the Fiber class because it’s only available in the CLI. Hence the creation of the Timer class.

Secondly, it would break a ton of code. I use it all the time (no pun intended).

I have no strong feelings about the other proposed changes which have either not yet been included in a release version or will not have been used much anyway.

[joshgoebel]

Secondly, it would break a ton of code. I use it all the time (no pun intended).

There are solutions to that - deprecating, supporting both for a while, etc. :-) IMHO absolute rock solid backwards compatibility shouldn't really be a major goal at this point though.... considering we're still 0.3, not even 1.0. Individual releases should be stable and people should realize it's in active development and things may change when upgrading to a new release. I've gotten very used to semantic verionsion (only break things in major) but I think when you're pre 1.0 that each minor release can have breaking changes.

it’s the fiber from which it’s called that sleeps, not the Scheduler

This is true, but:

• Class static methods are not always noun verb, only when the class is serving as a singleton.
• The Timer isn't really sleeping either. As you said Fiber would be more accurate.

In my mind scheduler is orchestrating the sleep... but I'm not super attached to moving it. Timer is ok. Some of these were just ideas. I just would like to try to focus more on "best long-term names for the API" hopefully though rather than "we called it that in version 0.1, now we're stuck". :-)

IE: If we had found consensus that say Scheduler was better/clearer naming then I think we should break thing and change it and then mention that in the release notes, etc...

[joshgoebel]

I think Directory.remove and File.delete should be both named Directory.delete and File.delete. to be more consistent.

Just curious, why not remove for both? This may be a windows vs unix thing though lol... wasn't windows del and unix has always been rm?

[PureFox48]

Just curious, why not remove for both?

Because, for better or worse, File.delete already exists and so you’d be breaking existing code for no good reason.

If we were starting from scratch, I’d prefer remove myself though delete is fine too.

[PureFox48]

Incidentally, I’m not suggesting that you should never make breaking changes in a language which hasn’t yet reached 1.0 and is still being heavily developed. However, I think there should be a good reason for doing so and, in the case of the sleep method, I think it would be inappropriate to put it in the Scheduler class anyway.