cha-api -

Chawan’s command API Interfaces Client Pager Buffer LineEdit See also

Chawan’s command API

As described in cha−config(5), keypress combinations can be bound to actions.

An action can be either a JavaScript expression, or a command defined in the [cmd] section of config.toml. For example, the following works:

gpn = 'n => pager.alert(n)' # e.g. 2gpn prints `2' to the status line

Note however, that JavaScript functions must be called with an appropriate this value. So e.g. the following does not work:

gpn = 'pager.alert' # broken!!!

To work around this limitation, actions have to wrap the target function in a closure, as above. However, this has poor reusability; for more complex actions, you would have to copy and paste the entire function every time you re−bind it or call it from a different function.

To fix this, it is possible to define a command in the [cmd] section:

[cmd.my.namespace]
showNumber = 'n => pager.alert(n)'

my.namespace can be anything you want; it is to avoid collisions when including multiple configs. The only restriction is that the first component (in this case, “my”) must not contain an upper−case letter.

Now you can call cmd.my.namespace.showNumber() from any other function, or include it in a keybinding (in that case, cmd. is optional):

'gpn' = 'my.namespace.showNumber'
# same as
'gpn' = 'cmd.my.namespace.showNumber'

Interfaces

Client

The global object (globalThis) implements the Client interface. Documented functions of this are:

Client also implements various web standards normally available on the Window object on websites, e.g. fetch(). Note however that it does not give access to JS objects in buffers, so e.g. globalThis.document is not available.

Pager

Pager is a separate interface from Client that gives access to the pager (i.e. browser chrome). It is accessible as globalThis.pager, or simply pager.

Note that there is a quirk of questionable value, where accessing properties that do not exist on the pager will dispatch those to the current buffer (pager.buffer). So if you see e.g. pager.url, that is actually equivalent to pager.buffer.url, because Pager has no url getter.

Following properties (functions/getters) are defined by Pager:

Also, the following static function is defined on Pager itself:

Buffer

Each buffer is exposed as an object that implements the Buffer interface. To get a reference to the currently displayed buffer, use pager.buffer.

Note the quirk mentioned above where Pager dispatches unknown properties onto the current buffer.

Following properties (functions/getters) are defined by Buffer:

LineEdit

The line editor at the bottom of the screen is exposed to the JavaScript context as globalThis.line, or simply line, and implements the LineEdit interface.

Note that there is no single LineEdit object; a new one is created every time the line editor is opened, and when the line editor is closed, globalThis.line simply returns null.

Following properties (functions/getters) are defined by LineEdit: