Fork me on GitHub
 
The documentation is scarce for now. Hopefully the source code is easy to read and mostly explains itself. In any case, this document describes pretty well what's going on. The rest are implementation details and can be found in the source code.

Ymacs development docs

Ymacs is a DynarchLIB widget. As such, it can be included in any widget container. The demo embeds it in a DlLayout, which also displays a sample menu bar. The layout in turn is embedded in a DlDialog which shows up in maximized state. As you can see from the demo, it's quite easy to add a menu, or a toolbar; I don't think the basic Ymacs widget should provide these.

DEFINE_CLASS

Ymacs is written in what I began calling “DynarchLIB new style”. I wrote a PDF that explains what's going on with the DEFINE_CLASS statements. You should read it if you plan on hacking Ymacs, but in short here's what happens: as you might know, JavaScript doesn't provide very nice syntax for defining objects. You have to do all that weird stuff with the prototype and have to instantiate an object of the base class type in order to setup inheritance. Kind of ugly.

The DEFINE_CLASS “macro” provides a more convenient syntax and it's deeply integrated into DynarchLIB. It receives 3 arguments: the name of the new class (a string), a base class constructor (or null if there's no base class) and a function. The function (in bold next, so you know that I'm referring to it) is called immediately given 3 arguments which I'm calling D, P and DOM. These args are convenient shortcuts to frequently used objects during the definition of a class. D is a reference to the new class constructor, which already exists when the function is called. P is a reference to the new class' prototype. And DOM is an alias to DynarchDomUtils, to save some typing.

The function that you supply to DEFINE_CLASS should construct the class' methods and properties. Create a method by inserting it into P, or a “static” method by inserting it into D. There are some “magic” keywords that you can add to these, such as D.CONSTRUCT—the constructor, or D.DEFAULT_ARGS—a specification of the arguments that the new object can receive in the constructor, along with their default values. Well, for more information you should really read my article (the implementation in DynarchLIB is a bit different, but not in essential ways).

Objects

Ymacs is centered around the following essential objects:

This is the playground. The objects above lay at the heart of Ymacs. There is one more object—the Ymacs widget itself, which is just a small glue that binds these together. The Ymacs widget creates a minibuffer, which is really an Ymacs_Buffer and has a frame in its own right, and a mode line which displays some information about the currently active buffer. The mode line should be refactored—in essence, it should be removed from the Ymacs widget and added to Ymacs_Frame, since it's useful (and standard in Emacs) to have a mode line for each frame. Only the minibuffer frame, of course, should not display a mode line.

The Ymacs widget also maintains a “kill ring”, which is the basis of Ymacs' clipboard. The kill ring is shared across all buffers in an Ymacs widget, to make it easy to copy from one buffer and paste (“yank”) into another. Originally I tried to keep these objects self-contained and independent, so that we could have, for instance, a buffer and a frame without using the Ymacs widget; but I think this no longer works. Could be revived if there's enough interest for it.