Document requirements for minimum implementation/kernel

[lucaswerkmeister]

It sounds like it’s supposed to be possible to write different implementations, or kernels, for eneyj. (The specification talks about implementations, the README calls the contents of src/ the kernel; I assume the two are roughly equivalent.) It would be nice to have some sort of guide, or list of needed things, to get started with a rudimentary kernel.

From my current understanding, this would have to include:

• A parser for the normal JSON serialization. (Depending on your internal representation, this can be just a JSON parser.)
• A parser for the canonical JSON serialization: not a strict requirement by the spec, but without it, you won’t be able to use the objects in eneyj/data/, which seem to be using this serialization. (Again, depending on your internal representation, this can be just a JSON parser.)
• An emitter for the normal and/or canonical JSON serialization. (This too could be fairly simple depending on your internal representation.) One or the other is probably more useful in that it will allow you to reuse eneyj’s tests to some degree, I haven’t checked yet.
• Implementations for the required builtins. As a first approximation, the JS-implemented builtins that only have that builtin implementation in the data file:

  $ for builtin_js in eneyj/src/builtin/*.js; do builtin_basename=${builtin_js#eneyj/src/builtin/}; builtin_z=${builtin_basename%.js}; if [[ $(jq '(.Z8K4 | length) == 1 and .Z8K4[0].Z14K1.Z1K1 == "Z19"' "eneyj/data/$builtin_z.json") == true ]]; then printf '% 4s\n' "$builtin_z"; fi; done
  Z100
   Z26
   Z33
   Z36
   Z37
   Z38
   Z62
  

  That said, while this list excludes the JS builtins Z64 (head) and Z65 (tail), because they also have non-builtin implementations based on Z190 (by_key), Denny already mentioned that Z190 might in turn depend on builtin Z64 and Z65, so maybe the above list is too short and all (or at least more) of the JS-implemented builtins are required after all.
• Some sort of entry point… the simplest version probably accepts/reads a single Z object, evaluates it until reaching the fix point, and then returns/prints the result?
• …
• Profit? No, there’ll certainly be more things.

[lucaswerkmeister]

(I’m toying with the idea of writing an implementation in GraalVM, because the polyglot capabilities of that platform could be really useful for this.)

[vrandezo]

Yes, I think that is right.

One consideration was that one could internalize more than is currently internalized, and make the kernel simpler. For example, the kernel has currently a lot of validation code (and pulls in a whole JSON Schema validator in). Obviously, validation can be skipped in a first implementation, so that's not so dramatic.

One more thing in the kernel that needs to be implemented is probably a way to evaluate the JS implementations, or else the system will be too slow. That's a bit of ugly code that would benefit a lot from being internalized.

But yes, in the end it's about reading a single Z object and then evaluated it until a fix point is reached. Complementary is a parser to take a string and turn it into a Z Object (should be internalized anyway), and the linearizers have already been internalized, so that should come for free.

I keep this issue open for now to collect these conditions, and they should eventually move to the SPECIFICATION file.

Thank you so much for exploring this!

[lucaswerkmeister]

I think a bit more would need to be said about evaluation – technically, it’s part of the list in the task description, as Z100 is the “evaluate” builtin, but the actual Z100 builtin implementation does almost nothing besides delegate to a whole family of other functions. The list should probably mention the built-in evaluation functions for various types.

[vrandezo]

D'oh! I just realised that many of the builtins could be moved to be implementations, because, well, they could simply be JavaScript implementations. That's not true for all (I know Z100 and Z24 wouldn't), but most of the others should be internalizable.

I didn't do that from the beginning because there was no JavaScript implementation in the beginning, and I never cleaned it up.