Create a spec

[wasamasa]

Note: This has been brought up by @Benaiah on IRC.

It's wonderful that MAL has a guide, loads of tests and some example code, however some parts of the guide are less than clear. One example of this is the number type (there is no mention whether you need to support signed numbers, what range they must have, whether they may be floats, etc.), another one would be the specific semantics of hash maps (how is key equality defined, would it be possible to compare the values only instead of having to keep track of the key type?). There is no need to specify everything, simply describing the minimum requirements in great detail and marking the unspecified parts would be enough.

[kanaka]

Sorry for the late reply. My github notifications started going to spam a week ago.

I mentioned this in IRC already, but yes, this would be great. I won't be able to do so any time soon but would be happy to review and give feedback.

I would suggest three different levels: basic, self-host (vectors, hash-maps, function metadata), extras (conj, seq, collection metadata).

[asarhaddon]

Hi.

Why is function metadata required for self-hosting?

For some low-level implementations, adding metadata for functions, especially built-in functions, brings no benefit for understanding LISP or self-hosting. It increases the complexity of types late in the process, potentially requiring modifications and debugging in some core functions and all previous steps. I am dubious about the educational interest of metadata in general, and I suggest to remove it at least for functions.

Similarly, I wonder about the intent of the vector type. As far as I know, self-hosting only requires vectors to support vectors…

• EVAL applies lists, not vectors. The fact that *ARGV* or (seq "ab") return lists of strings instead of vectors demonstrates that lists are preferred even when no one intends to ever apply them.
• Some implementations use a single chunk of memory containing a fixed-length array for vectors, and a linked list for lists. The guide suggests to implement lists as arrays or vectors as tagged lists if convenient, so this difference is not important either.
• There is no efficiency requirement or suggestion for count or nth on vectors, which would give a hint.
  In some real-world LISPs with vectors, the documentation is often allusive about the difference, and the difference does not seem to be the same across LISP variants, so the educational purpose is dubious at best.
  Removing the vector type altogether would widely simplify new implementations without breaking any existing implementation.