Browser object commands are prefix commands. If you have done your homework, you will instantly recall that the job of a prefix command is to modify the interactive context of the command that follows it. Browser object commands modify the interactive context by placing a reference to their own handler in I.browser_object. The following command can then call the handler of the browser object command. The browser object command's handler will usually carry out some interaction, such as prompting the user, and then return a piece of data to its caller.

define_browser_object_class

The function define_browser_object_class does what its name suggests. Its arguments are as follows:

name

Name of the browser object class given as a string. Multi-word names should be hyphenated. From this name will be generated a top level variable of the form browser_object_NAME, as well as an interactive command called browser-object-NAME.

doc

A documentation string.

handler

A coroutine function of two arguments, (I, prompt), to carry out the UI interaction and yield the datum. Return the datum with yield co_return(ob).

$hint

Optional keyword argument. It is a terse string, usually noun and verb, instructing the user in what they will do with this browser object class. For example, "select link". Any browser object class which uses the minibuffer prompt for interaction should provide this keyword.

interactive

When defining a new command with interactive, you can specify the default browser object for that command. This browser object will be used when no other browser object is given by a prefix command by the user.

interactive(command_name, docstring, handler,
            $browser_object = browser_object_foo);

A browser object given in a command definition can be one of three types of objects: a constant, a function, or an object of type browser_object_class. Constants are used for things like an url which is always the same. Function browser-objects will be called when read_browser_object is called, and its value will be the thing that gets passed to the command. Function browser-objects are used for computable values that do not involve UI interaction. The browser_object_class type is the most dynamic. A browser_object_class holds a procedure for carrying out a UI interaction to obtain a datum. Examples are the hints class (selecting an element by number or text) and the url-reader class (that prompts for an url or webjump in the minibuffer).