Skip to main content ↑ ↓
Topic: Sphere v2 API discussion (Read 891110 times) previous topic - next topic
0 Members and 9 Guests are viewing this topic.

Re: Sphere v2 API discussion

Reply #105 –
I'm renaming some APIs to make them more newbie-friendly and self-documenting:

FS.exists() --> FS.fileExists()
FS.resolve() --> FS.fullPath()
FileStream::size --> FileStream::fileSize

Any other functions/properties that anyone thinks could be renamed to make them more approachable?

Re: Sphere v2 API discussion

Reply #107 –
FS.exists() wasn't clear whether it worked with directories or not (spoiler: it doesn't).  As for fileSize, I changed the name to make it very clear that it gets the size of the underlying file and not the stream itself.  "Size of a stream" is an ambiguous concept and could refer to, for example, the size of an internal buffer.  I want the API to be self-documenting so ambiguity = bad :)

Re: Sphere v2 API discussion

Reply #109 –
Sure, but it might be better to have a separate function for directories.  If your code is asking "does this file exist?" to avoid an error and the engine says "yes, it does" then you probably expect it to actually be a file and not a folder.

File systems conflating files with directories at the API level was always something that annoyed me.  In practice you almost never want to treat them interchangeably so the low-level file system functions tend to work against you in that regard. :'(

Re: Sphere v2 API discussion

Reply #110 –
I'm adding support for relative paths in FS.fullPath().  This is different than just prepending a base directory, as it will honor prefixes.  To illustrate, suppose you had a function to load map files and it did:
Code: (javascript) [Select]
path = "maps/" + mapName;

If the caller passed a mapName as, e.g. "@/otherMaps/map.xml", this would fail because it would end up with something like "maps/@/otherMaps/map.xml" and won't be able to find the file.  So instead, now you'll be able to do:
Code: (javascript) [Select]
path = FS.fullPath(mapName, "maps");
and that will work correctly with prefixed paths.

Re: Sphere v2 API discussion

Reply #111 –
I think I did something right with the Sphere v2 API: I'm teaching my cousin with minimal programming background how to use JS and miniSphere and he's picking up a lot of Sphere v2 things very quickly.  So it looks like I got the newbie-friendliness down, at least. :D

Re: Sphere v2 API discussion

Reply #112 –
That's very encouraging! Also, does this mean that eventually we're going to have another member on here? :P

Re: Sphere v2 API discussion

Reply #113 –
I added a new SphereFS prefix, $/, which is shorthand for the directory containing the main script.  This makes it easier to do absolute imports/requires even when your main script is in a subdirectory, e.g.

Code: (JavaScript) [Select]
import { DayNightEngine } from '$/inGameClock`;

In Cell, $/ is the root of the source tree, i.e. the directory containing Cellscript.mjs.

Re: Sphere v2 API discussion

Reply #114 –
I refactored a bunch more stuff, in particular the file system stuff which still had clear signs of how things were handled before SphereFS was introduced.

I also went into various old source files from early in the engine's development and modernized them, updating the naming conventions, code policy, etc.

Overall, the code is much, much cleaner now.

Re: Sphere v2 API discussion

Reply #115 –
Oops, meant to post that in the miniSphere thread.

Anyway, besides the $/ prefix, I also added a FS.directoryExists() function.  It's not as useful as fileExists since FS.createDirectory() will automatically create parent directories as needed, but it might be useful in some cases to know if some directory exists without actually needing to create it on the spot.

Re: Sphere v2 API discussion

Reply #116 –
New API coming in miniSphere 4.8: the DirectoryStream class!  It allows you to read filenames from a directory one at a time.  It even works with from(), e.g. this query to load tests in the Specs test harness:

Code: (JavaScript) [Select]
let fileNames = from(new DirectoryStream('$/testCases'))
	.where(it => !it.isDirectory)
	.where(it => it.fileName.endsWith('.js'))
	.select(it => it.fullPath);

Much nicer than what we had before, GetFileList().

Re: Sphere v2 API discussion

Reply #117 –
Much nicer, I would say. There was so much lacking/overly convoluted in the Sphere 1 functions it was a real hassle to work with.

Re: Sphere v2 API discussion

Reply #118 –
This came about because I happened to notice in Specs a call to GetFileList() and I realized there wasn't a Sphere v2 equivalent.  I considered just adding FS.listDirectory() or something, but then realized it would be much more extensible (and easier to optimize) as an object similar to FileStream.

Re: Sphere v2 API discussion

Reply #119 –
Decided to take advantage of the revamped FS.fullPath() function to bring back some of the good things about Sphere v1.  SphereFS is improved in miniSphere 4.8 to support relative paths:

Code: (JS) [Select]
var path1 = FS.fullPath('pig.png', '@/images');  // relative
var path2 = FS.fullPath('@/otherDir/pig.png', '@/images');  // absolute
// path1 = '@/images/whatever.png'
// path2 = '@/otherDir/pig.png'

The system modules can take advantage of that to allow conveniences like:
Code: (JS) [Select]
var pigImage = new Image('pig');  // relative to @/images
var superFatPig = new Image('@/otherDir/pig.png');  // absolute

The low-level Core API of course will still use full paths.