Official language spec?

[ghost]

Several features of Janet remain underspecified: notably, the representation of values and the operation of the garbage collector. We could say the implementation is the spec, but that presents two problems:

• Applications may not know which functionality to depend on, and may break in future releases
• Third-party implementations (for instance, a hypothetical JanIT) will have to replicate everything bug-for-bug to be safe

I say we fix these problems with an official specification. We don't have to define the precise operation of everything; we may choose the appropriate level of detail, and document only those behaviours which are necessary or convenient. So, if an implementation wants to implement a more efficient scheduling algorithm or garbage collector, it is free to do so, and conformant applications will not experience problems as a result.

I think this will also help Janet become much more widespread, if we care about that.

[bakpakin]

Agreed, an "official spec" is desirable (and a lot of work). The Janet website (https://janet-lang.org) is the official Janet specification, but it is lacking in certain domains, and lacks some rigor and exhaustiveness.

Various domains that a full, perfect spec would document:

• The syntax of the parser. This should more or less be done on the website.
• The language proper - basically how the compile function works. This would not include specifications for all built in functions. A more rigorous spec
• Runtime specification - related to above, especially with respect to fibers, the event loop, and data structures.
• The C interface and API - this is currently I think the most important documentation that is needed and missing. Ideally, we would have MSDN-style detail for every function and macro in Janet's C API.
• The bytecode format - a mostly compliant implementation of Janet could possibly omit this and use a custom bytecode. However, the format of the bytecode is exposed directly with the asm function as well as marshaling closures. This is specified on the websote
• Full spec of PEGs. This is somewhat independent of a Janet specification, and is somewhat specified on the website.
• Specs for the core library. This is mostly needed for certain complicated macros like match, loop, etc. For other core functions and macros, like dofile, import, and require, we may not want to be too prescriptive. Currently we only have published source code and doc strings as specifications for these functions.

At some point, I plan on writing more exhaustive documentation for Janet's C API (including the interface to the garbage collector and memory management, multi-threading, the event loop, etc.) on Janet's website. As you might expect, this is a lot of work.

I don't really have much else to add here, but I will leave this open for task tracking purposes and further comments and suggestions.

[Yam76]

This discussion reminded me of the following comment chain: https://news.ycombinator.com/item?id=16363586

In general, it is desirable to have multiple implementations of a standard. One reason is that it is then less likely that you are standardizing the bugs or idiosyncrasies of a single implementation.

[amano-kenji]

Official language spec didn't save scheme and common lisp....

Scheme implementations aren't compatible with each other.

Common lisp stopped evolving because of rigid specification....