Skip to main content

News

Topic: Sphere v2 API discussion (Read 34829 times) previous topic - next topic

0 Members and 4 Guests are viewing this topic.
  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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?
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

Re: Sphere v2 API discussion
Reply #106
I can understand fullPath, but aren't the first and third functions already self-explanatory?

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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 :)
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

Re: Sphere v2 API discussion
Reply #108
Why not have it detect if it detects a directory as well? And fileSize definitely makes sense, I didn't consider that.

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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. :'(
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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().
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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.

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub