deconstructing a ymacs command

[Joe]

I have a few questions on this function:

delete_whitespace: Ymacs_Interactive("^P", function(noLine) {
if (!this.deleteTransientRegion()) {
var p = this.point();
if (this.cmd("forward_whitespace", noLine)) {
this._deleteText(p, this.point());
return true;
}
}
}),

What is the ^P for? I see: "P", "^" "^p" "p" for various commands.
What is the noLine argument ?
What is the if (!this.deleteTransientRegion()) for?

Also, what is the best way to have a command work only in a particular
mode?

thanks,
-joe

[Mihai Călin Bazon]

Hi Joe,

First sorry for the late reply (I'm mostly away), and thank you for
your interest and insistence in digging the internals. :-)

Answers embedded in your email.

Can't go through your other emails right now, but I will in a few days
hopefully.

On Tue, Feb 16, 2010 at 6:32 PM, Joe <supe...@gmail.com> wrote:
> I have a few questions on this function:
>
>  delete_whitespace: Ymacs_Interactive("^P", function(noLine) {
>                if (!this.deleteTransientRegion()) {
>                        var p = this.point();
>                        if (this.cmd("forward_whitespace", noLine)) {
>                                this._deleteText(p, this.point());
>                                return true;
>                        }
>                }
>        }),
>
> What is the ^P for? I see: "P", "^" "^p" "p" for various commands.

I tried to model this in a similar way to Emacs:
http://www.gnu.org/s/emacs/manual/html_node/elisp/Interactive-Codes.html#Interactive-Codes

See ymacs-interactive.js (at the end), there's an ARG_READERS variable
that maps a letter to an argument reader function. An argument reader
receives a prompt, and a continuation, and it should call that
continuation with the argument that has been read from the minibuffer
(or passed as a prefix argument in some cases).

The ^ means "don't clear the transient mark before running this command".

In this specific example, ^ means that the function should be able to
access the transient region, and P means that the function should
receive the raw prefix argument, if any (null if no prefix argument
was passed). When you pass a prefix argument, noLine will have a
non-null value.

> What is the noLine argument ?

If null, then all whitespace will be eaten; if non-null, deletes
whitespace until the end of line.

> What is the if (!this.deleteTransientRegion())  for?

When the region was highlighted (transient mark) then
deleteTransientRegion() will return true, so no additional whitespace
will be deleted. (I preferred this behavior).

So to conclude:

1. you can call this function with S-DELETE. It will delete the
highlighted region, if any, or all whitespace (including newlines)
following the cursor.

2. you can specify a prefix arg, i.e. C-u S-DELETE, in which case it
will delete spaces until EOL.

3. you can call this command in non-interactive programs using
this.cmd("delete_whitespace"), and when you want it to stop at EOL you
would say this.cmd("delete_whitespace", true).

To take another example:

goto_line: Ymacs_Interactive("NGoto line: ", function(row){
var pos = this._rowColToPosition(row - 1, 0);
return this.cmd("goto_char", pos);
}),

The above receives a numeric argument ("N"). When called
interactively, this argument can be passed either as a prefix argument
(C-u 5 0) or will be read from the minibuffer if no prefix arg was
passed. The prompt, when the minibuffer is used, is "Goto line: ".
You can call this function with M-g (and will have to enter the line
number), or C-u 5 0 M-g (go to line 50), or in programs you can use
this.cmd("goto_line", 50).

Hope this helps.

Cheers,
-Mihai