for those curious here are the design decisions that I find confusing or just bad:

the (frequencies) form (which is meant to count the number of occurrences of each element in a list) completely ignores all nil values, and this isn’t documented anywhere

#Janet has a really cool concept where there are separate types for mutable or immutable data structures. for example "asdf" is an immutable string, but @"asdf" is a mutable string. but the problem is that for some reason, @"asdf" != "asdf" and also @"asdf" != @"asdf" - even if you do a deep/recursive equality check? and this is true for all data structure types

since the above means that the difference between mutable and immutable is very important if you want to compare things, you would think that all of Janet’s forms would be very clear about whether they return a mutable or immutable data structure, right? nope! there is no documentation of this whatsoever, which means that every time you want to compare two data structures you have to manually convert both of them - recursively - to immutable structures, just in case

the (complement) macro is meant to take a function and return its complement (a function that returns true when the original function would return false and vice-versa) but I think it’s just straight-up broken if you run it on a function with an arity of more than 1, and this is not documented anywhere

Janet’s random number generation is deterministic by default because the random seed defaults to the same number every time. you have to manually set the random seed yourself if you want to fix this. this isn’t documented either btw

Janet has a built-in error system using fibers (this is really cool!) but almost none of its forms actually throw errors when they should. instead they return values like nil or false and expect you to check this every time (even when this isn’t a documented behavior)

Janet’s docstrings use terms like “strictly equal”, “strictly less than”, etc. but the documentation calls this “primitive comparison” instead and never uses the word “strict”

in general there’s a pretty big disconnect between the language that Janet’s docstrings use, and the language used in the documentation. it feels like they were written by separate people who didn’t communicate very much

a lot of Janet’s docstrings say that they only take an indexable type but this seems to never be true - they can take any data structure type just fine, including strings

also, Janet either has no documentation for, or extremely limited documentation for:

• any basic file operations
• the existence of Lua-style metamethods which apparently this language has?
• how to get a list of an object’s methods (you need to use (keys «object») in the REPL, even though a lot of objects are a bespoke type imported from C so there’s no indication that they might have methods or keys at all)
• which features are supported by its regex implementation and how to use them (for example: if I regex/replace, is there any way that I can access the text of the capture group in my replacement?)

@iacore @jayalane @screwlisp

Thanks

I'm not trying to learn an easy to learn language. I'm trying to learn lisp. (Which doesn't seem all that hard.)

I'm a retired computer consultant with 40 years of database programming experience who now codes for a hobby, mostly plain text programming.

@screwlisp has got me interested in lisp again which I explored in the eighties while in school.

And I'm still in school but now I'm taking jazz improv not computer science.

#lisp #janet #programming