Talk:Lush

Hi, Matt G. here. I recently re-discovered this empty wikibook that somebody had put up, after finding it for the first time a few months ago. I figured I might as well organize my usual mailing-list rants about lush quirks into something that'd help the very newbies that aren't on the list. Here's my first stab. Feel free to edit things, but also feel free to start filling in the big missing sections!. If you're going to procrastinate, it might as well be in a manner that helps future generations of Yann students :)

-- SuperElectric (Matt)

Code samples
When writing a stand-in for a variable or function name, I've used italics, with words connected by an underscore:

This is how you declare types: ((type_name) var_name)

When actually writing runnable code, I've used dashes instead of underscores: Here's an actual example of declaring a type: ((-int-) my-int)

Variable names
Unless it's instantly obvious from context, I've made variable names of the form: type_name or thing_name For example:

The table below shows how to access different lush objects from C/C++ code: On the other hand, if it is instantly obvious that some name is a variable, I've tried to avoid using such flavorless variable names: (defparameter n-chickens (idx-dim coop))

The Chapters
While the chapters do go from basic to advanced topics, I didn't write them with the assumption that the reader would need to read all of one to move on to the next. You'll see that "Beginning Lush" contains some miscellany that people can live without, like "^A" and other caret shortcuts. The assumption is that people will move on when bored, and if the chapter titles are descriptive enough, they'll know where to move on to.

Here's what I was thinking when I broke up the book into the chapters you see on the front page: Libraries Advanced Lush: Topics that you don't strictly need to know to comfortably use Lush.
 * Features: I see this as an appetite-whetter, where we show single lines of code that show the cooler features of lush, like the tensor library, interactive use, C/C++ integration, perhaps even lispy meta-code.
 * Installation: Installation howtos on all platforms supported by Lush. We should definitely focus on getting the cvs version, then cover precompiled binaries if we want. "update cvs" seems to fix a good fraction of the bugs reported in the mailing list.
 * Beginning Lush: I've written a bunch here already; you can check it out and see if you agree with the appropriateness of what I've entered or omitted.
 * Classes and Objects: Starts with enough to get people started, then discusses the major differences betw. classes in lush and classes in other languages (single inheritance, no private members, you can call virtual functions from the constructor, etc). Discussion on compilcations that arise when compiling class hierarchies.
 * Compiling: There are many problems that can pop up when you start trying to compile lush code. I think that most discussion of compiler gotchas should go in the other chapters. For example, a common problem when you override a superclass' method is that the new version of the method must have the same number of "hidden arguments." I think treatment of this problem should go in the "Classes and Objects" chapter, since it informs how people go about designing their classes. I think this "Compiling" chapter should focus on the nuts and bolts of compilation itself, namely how to link in shared and static libraries, how to use lushmake, differences between dhc-make and dhc-make-with-c++, etc.
 * Debugging: This is what most newbies have the most trouble with, since lush doesn't do line numbers or even source file identification. And god help you if it barfs in the middle of parsing a class's methods, and won't tell you where in the file it gave up at. I'd like to start this with tips and tricks on making debugging easier, then go into advanced howtos about stepping through code (Yann showed how on the mailing list once; did anybody get it working?) and using gdb.
 * The Vector / Matrix / Tensor library: Self-explanatory. It'd be nice if we could get illustrations in here to graphically show what select, narrow, and unfold do. We could show a 3d grid, and highlight what each method returns.
 * Input / Output: I have no experience here aside from save-matrix/load-matrix, but other topics that belong here include object serialization, and interfacing peripheral devices like webcams and microphones.
 * plotter
 * linalg
 * gb-learn
 * OGRE
 * libsdl
 * Macros: Most of my macro knowledge comes from aping a few macro source files in lush, so people who actually know what they're doing at a deeper level are encouraged to come in and clean up my nonsense.
 * Lisp tricks: I know they exist, but am happy to leave it to others to tell me what they are.
 * Hooks: Hooks for debugging, line stepping, and more. Again, stuff that seems very useful, but that I know nothing about myself. Please contribute if you do.
 * Standalone lush programs: Is this problem solved? Yann posted some code, but some people were saying that they couldn't make it work.

- SuperElectric (Matt)

Todo
The sections most in need of filling out are: Once these are done, we have something that can start to be useful to a complete newbie.
 * Objects & Classes
 * The Vector/Matrix/Tensor library
 * Compiling