I’m falling out of love with Janet. it seems to have a lot of very good ideas and design choices but:

• the documentation is missing a lot of important information and is sometimes just outright wrong
• it seems like nobody really works on the documentation except for small maintenance tasks, and I wonder if the whole project is petering out similarly
• it has some design choices that are either flat-out bad, or I just don’t understand the logic behind them

it’s been fun to work with it but I think I might try learning Typed Racket next

I’m ngl I’m starting to wonder if there are any Lisp languages that I would consider good enough for my hobby projects

it’s weird because I think that S-expressions and Lisp-style macros are incredibly good ideas, and yet exploring these languages feels a bit like exploring the fossils of an evolutionary dead end. like maybe there’s some fatal flaw in Lisps that I’m just not seeing, and that’s why all of these languages die. maybe the noisiness of the parenthesis and the potential for hard-to-diagnose syntax errors is a much worse issue than I think, and Lisps just aren’t worth it because of that alone. idk. but I still want to try Racket

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?)

what really sucks is that Janet is so close to being perfect for embedding in games as a scripting language, or etc. since it’s meant to be a small, simple Lisp with modern sensibilities, and Lisp’s whole thing is letting the users extend it into whatever they want with no limits

so you could very easily embed Janet into your game, and then generations of modders after could smooth over all of the quirks and bad API decisions and even incorporate whole new programming paradigms and DSLs. it would literally be completely future-proof

it’s just that Janet is a very unfinished language (especially when it comes to documentation) and it seems to me like nobody is spending the substantial effort it would take to fix its shortcomings

although, thankfully we still have Fennel which turns Lua into exactly what I described above. I fucking love Fennel - I have literally zero complaints about it as a Lisp or as a language in general 💙