Mozdev.org

Writing new commands for Conkeror is simple. This page will give you the basic information you need to know to write commands. The Conkeror source contains lots of commands that you can reference for examples.

You can think of a command as having two halves. One half is a javascript function that implements what you want the command to do. The other half is the interactive definition. The interactive definition does the following:

• Names the command, so it can be bound to a key or called with M-x.
• Documents the command concisely for Conkeror's self-documentation system.
• Provides a function that carries out user-interface interaction to collect arguments with which to call the command function.

That third bullet point is the most complex, and we will return it it shortly.

Let's write a simple command, to have something concrete to study. The first thing we need is a javascript function that does what we want the command to do. In this example, we want a command that echoes a message to the minibuffer. Our function will need to be provided with a conkeror window in which to echo a message, and a message. So we can define the command function like this:

function echo_message (window, message) {

    window.minibuffer.message (message);

}

Note that our command function is itself completely free of code to collect information from the user. The command function should contain only output side-effects, with input side-effects being located in the interactive definition. This keeps the code clean and organized, and ensures that command functions can be called non-interactively by other scripts.

Our interactive definition is here:

interactive ("echo-message", "echo a user-supplied message in the minibuffer",

    function (I) {

        echo_message (

            I.window,

            (yield I.minibuffer.read ($prompt = "message: ")));

    });

There is a lot here, but we will take it apart, and you will see that it is really not all that complex.

The first argument of interactive is a string giving the name of the command. We follow the emacs convention and use all lower case with words separated by hyphens.

After the command name is the docstring. This argument is completely optional, and can be omitted altogether.

The last argument to interactive is a function of one argument that carries out the user-interface interaction, and finally calls the command function (echo_message). The argument to this function, which by convention is the variable `I', is the interactive context. The interactive context contains some useful pieces of information, including `window', which is the current conkeror browser window. Since echo_message expects to be called with a window, we pass it `I.window'.

The second argument to echo_message is the message. We will collect the message by prompting the user. The javascript keyword `yield' is used to perform this interaction asynchronously. (Note, the parentheses around yield are required.)

The call to I.minibuffer.read contains some odd looking syntax, $prompt = "message: ". Javascript itself does not contain a mechanism for keyword arguments, but conkeror provides a keywords system. We felt this to be desirable for functions like minibuffer.read because often many parameters of the interaction can be customized, and it would have been too messy and consistency too hard to maintain, using positional arguments for all of them. Keyword arguments all start with `$'. Here we just set the $prompt keyword to a suitable prompt.

After evalling our command function and interactive definition, we can now call our new command with M-x echo-message.