Documentation of lisp functions that need to be imported from somewhere else

[esakilpi]

Just spent a couple of hours trying to find "first" function. Finally found out that it has to be separately imported.

(import toolz.itertoolz [first])

The manual has no mention of this. I think it is fine that functions that already exist in other python libraries are not reimplemented in hy, but at least for "standard" lisp functions like "first" the manual should have an entry that tells where to import them from.

[Kodiologist]

There is no standard for Lisp as a whole, despite the best efforts of X3J13, so that would just raise the question of which functions or macros should exist and what they would be named. Some of the things you might expect in some kind of standard Lisp, like call/cc, aren't even possible to implement for Hy.

Maybe you're trying to update a Hy program written for an older Hy, since first used to a builtin. For such cases, look at NEWS, which will tell you which features were removed or changed in which release and how to update your code. For first, you can see that it was removed in 1.0a2 and the recommendation is indeed to import it from Toolz (or CyToolz).

[esakilpi]

Yes, that is exactly what I'm doing and what I did. Now that I know that it is essential to scan NEWS.rst for anything missing or puzzling, I should have much less problems. But it took some time to figure that out. Sometimes I thought the whole project is broken and considered giving up. I am thinking about other newcomers that are trying to learn hy using some example code. Because almost all code that is older than about half a year is very likely partially outdated now. The manual should have at least some instructions and a link to NEWS.rst.

[Kodiologist]

The manual should have at least some instructions

What sort of instructions?

and a link to NEWS.rst

Sure, we can do that.