'\" t
.\" Automatically generated by Pandoc 3.3
.\"
.TH "cha\-api" "5" "" "" "Chawan\[cq]s command API"
.SH Chawan\[cq]s command API
As described in \f[B]cha\-config\f[R](5), keypress combinations can be
bound to actions.
.PP
An action can be either a JavaScript expression, or a command defined in
the \f[CR][cmd]\f[R] section of config.toml.
For example, the following works:
.IP
.EX
gpn = \[aq]n => pager.alert(n)\[aq] # e.g. 2gpn prints \[ga]2\[aq] to the status line
.EE
.PP
Note however, that JavaScript functions must be called with an
appropriate \f[CR]this\f[R] value.
Unfortunately, this also means that the following does not work:
.IP
.EX
gpn = \[aq]pager.alert\[aq] # broken!!!
.EE
.PP
To work around this limitation, actions have to wrap the target function
in a closure, as above.
However, this has very 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.
.PP
To fix this, it is possible to define a command in the \f[CR][cmd]\f[R]
section:
.IP
.EX
\f[B][cmd.my.namespace]\f[R]
showNumber = \[aq]n => pager.alert(n)\[aq]
.EE
.PP
\f[CR]my.namespace\f[R] can be anything you want; it is to avoid
collisions when including multiple configs.
Avoid setting it to \f[CR]pager\f[R] or \f[CR]line\f[R], because these
are used by the default config.
.PP
Now you can call \f[CR]cmd.my.namespace.showNumber()\f[R] from any other
function, or just include it in an action:
.IP
.EX
\[aq]gpn\[aq] = \[aq]cmd.my.namespace.showNumber\[aq]
.EE
.SS Interfaces
.SS Client
The global object (\f[CR]globalThis\f[R]) implements the
\f[CR]Client\f[R] interface.
Documented functions of this are:
.PP
.TS
tab(@);
lw(28.0n) lw(38.5n) lw(3.5n).
T{
Property
T}@T{
Description
T}@T{
T}
_
T{
\f[CR]quit()\f[R]
T}@T{
Exit the browser.
T}@T{
T}
T{
\f[CR]suspend()\f[R]
T}@T{
Temporarily suspend the browser, by delivering the client process a
SIGTSTP signal.
Note: this suspends the entire process group.
T}@T{
T}
.TE
.PP
\f[CR]Client\f[R] also implements various web standards normally
available on the \f[CR]Window\f[R] object on websites, e.g.\ fetch().
Note however that it does \f[I]not\f[R] give access to JS objects in
buffers, so e.g.\ \f[CR]globalThis.document\f[R] is not available.
.SS Pager
\f[CR]Pager\f[R] is a separate interface from \f[CR]Client\f[R] that
gives access to the pager (i.e.\ browser chrome).
It is accessible as \f[CR]globalThis.pager\f[R], or simply
\f[CR]pager\f[R].
.PP
Following properties (functions/getters) are defined by
\f[CR]Pager\f[R]:
.PP
.TS
tab(@);
lw(28.0n) lw(38.5n) lw(3.5n).
T{
Property
T}@T{
Description
T}@T{
T}
_
T{
\f[CR]load(url)\f[R]
T}@T{
Put the specified address into the URL bar, and optionally load it.
Note that this performs auto\-expansion of URLs, so Chawan will expand
any matching omni\-rules (e.g.\ search), try to open schemeless URLs
with the default scheme/local files, etc.
Opens a prompt with the current URL when no parameters are specified;
otherwise, the string passed is displayed in the prompt.
If this string ends with a newline
(e.g.\ \f[CR]pager.load(\[dq]about:chawann\[dq])\f[R]), the URL is
loaded directly.
T}@T{
T}
T{
\f[CR]loadSubmit(url)\f[R]
T}@T{
Act as if \f[CR]url\f[R] had been input into the address bar.
Same as \f[CR]pager.load(url + \[dq]n\[dq])\f[R].
T}@T{
T}
T{
\f[CR]gotoURL(url, options = {replace: null, contentType: null})\f[R]
T}@T{
Go to the specified URL immediately (without a prompt).
This differs from \f[CR]load\f[R] and \f[CR]loadSubmit\f[R] in that it
\f[I]does not\f[R] try to correct the URL.
When \f[CR]replace\f[R] is set, the new buffer may replace the old one
if it loads successfully.
When \f[CR]contentType\f[R] is set, the new buffer\[cq]s content type is
forcefully set to that string.
Use this for loading automatically retrieved (i.e.\ non\-user\-provided)
URLs.
T}@T{
T}
T{
\f[CR]nextBuffer()\f[R], \f[CR]prevBuffer()\f[R],
\f[CR]nextSiblingBufer()\f[R], \f[CR]prevSiblingBuffer()\f[R],
\f[CR]parentBuffer()\f[R]
T}@T{
Traverse the buffer tree.
\f[CR]nextBuffer()\f[R], \f[CR]prevBuffer()\f[R] do a depth\-first
traversal; \[ga]\f[CR]nextSiblingBufer()\f[R],
\f[CR]prevSiblingBuffer()\f[R] cycle through siblings, and
\f[CR]parentBuffer()\f[R] returns to the parent.
T}@T{
T}
T{
\f[CR]dupeBuffer()\f[R]
T}@T{
Duplicate the current buffer by loading its source to a new buffer.
T}@T{
T}
T{
\f[CR]discardBuffer(buffer = pager.buffer, dir = pager.navDirection)\f[R]
T}@T{
Discard \f[CR]buffer\f[R], then move back to the buffer opposite to
\f[CR]dir\f[R].
Possible values of \f[CR]dir\f[R] are: \[lq]prev\[rq], \[lq]next\[rq],
\[lq]prev\-sibling\[rq], \[lq]next\-sibling\[rq], \[lq]parent\[rq],
\[lq]first\-child\[rq], \[lq]any\[rq].
T}@T{
T}
T{
\f[CR]discardTree()\f[R]
T}@T{
Discard all child buffers of the current buffer.
T}@T{
T}
T{
\f[CR]reload()\f[R]
T}@T{
Open a new buffer with the current buffer\[cq]s URL, replacing the
current buffer.
T}@T{
T}
T{
\f[CR]reshape()\f[R]
T}@T{
Reshape the current buffer (=render the current page anew.)
T}@T{
T}
T{
\f[CR]redraw()\f[R]
T}@T{
Redraw screen contents.
Useful if something messed up the display.
T}@T{
T}
T{
\f[CR]toggleSource()\f[R]
T}@T{
If viewing an HTML buffer, open a new buffer with its source.
Otherwise, open the current buffer\[cq]s contents as HTML.
T}@T{
T}
T{
\f[CR]lineInfo()\f[R]
T}@T{
Display information about the current line.
T}@T{
T}
T{
\f[CR]searchForward()\f[R]
T}@T{
Search for a string in the current buffer.
T}@T{
T}
T{
\f[CR]searchBackward()\f[R]
T}@T{
Search for a string, backwards.
T}@T{
T}
T{
\f[CR]isearchForward()\f[R]
T}@T{
Incremental\-search for a string, highlighting the first result.
T}@T{
T}
T{
\f[CR]isearchBackward()\f[R]
T}@T{
Incremental\-search and highlight the first result, backwards.
T}@T{
T}
T{
\f[CR]gotoLine(n?)\f[R]
T}@T{
Go to the line passed as the first argument.
If no arguments were specified, an input window for entering a line is
shown.
T}@T{
T}
T{
\f[CR]searchNext(n = 1)\f[R]
T}@T{
Jump to the nth next search result.
T}@T{
T}
T{
\f[CR]searchPrev(n = 1)\f[R]
T}@T{
Jump to the nth previous search result.
T}@T{
T}
T{
\f[CR]peek()\f[R]
T}@T{
Display an alert message of the current URL.
T}@T{
T}
T{
\f[CR]peekCursor()\f[R]
T}@T{
Display an alert message of the URL or title under the cursor.
Multiple calls allow cycling through the two.
(i.e.\ by default, press u once \-> title, press again \-> URL)
T}@T{
T}
T{
\f[CR]ask(prompt)\f[R]
T}@T{
Ask the user for confirmation.
Returns a promise which resolves to a boolean value indicating whether
the user responded with yes.
Can be used to implement an exit prompt like this:
\f[CR]q = \[aq]pager.ask(\[dq]Do you want to exit Chawan?\[dq]).then(x => x ? pager.quit() : void(0))\[aq]\f[R]
T}@T{
T}
T{
\f[CR]askChar(prompt)\f[R]
T}@T{
Ask the user for any character.
Like \f[CR]pager.ask\f[R], but the return value is a character.
T}@T{
T}
T{
\f[CR]saveLink()\f[R]
T}@T{
Save URL pointed to by the cursor.
T}@T{
T}
T{
\f[CR]saveSource()\f[R]
T}@T{
Save the source of the current buffer.
T}@T{
T}
T{
\f[CR]extern(cmd, options = {setenv: true, suspend: true, wait: false})\f[R]
T}@T{
Run an external command \f[CR]cmd\f[R].
The \f[CR]$CHA_URL\f[R] and \f[CR]$CHA_CHARSET\f[R] variables are set
when \f[CR]options.setenv\f[R] is true.
\f[CR]options.suspend\f[R] suspends the pager while the command is being
executed, and \f[CR]options.wait\f[R] makes it so the user must press a
key before the pager is resumed.
Returns true if the command exit successfully, false otherwise.
Warning: this has a bug where the output is written to stdout even if
suspend is true.
Redirect to /dev/null in the command if this is not desired.
(This will be fixed in the future.)
T}@T{
T}
T{
\f[CR]externCapture(cmd)\f[R]
T}@T{
Like extern(), but redirect the command\[cq]s stdout string into the
result.
null is returned if the command wasn\[cq]t executed successfully, or if
the command returned a non\-zero exit value.
T}@T{
T}
T{
\f[CR]externInto(cmd, ins)\f[R]
T}@T{
Like extern(), but redirect \f[CR]ins\f[R] into the command\[cq]s
standard input stream.
\f[CR]true\f[R] is returned if the command exits successfully, otherwise
the return value is \f[CR]false\f[R].
T}@T{
T}
T{
\f[CR]externFilterSource(cmd, buffer = null, contentType = null)\f[R]
T}@T{
Redirects the specified (or if \f[CR]buffer\f[R] is null, the current)
buffer\[cq]s source into \f[CR]cmd\f[R].
Then, it pipes the output into a new buffer, with the content type
\f[CR]contentType\f[R] (or, if \f[CR]contentType\f[R] is null, the
original buffer\[cq]s content type).
Returns \f[CR]undefined\f[R].
(It should return a promise; TODO.)
T}@T{
T}
T{
\f[CR]buffer\f[R]
T}@T{
Getter for the currently displayed buffer.
Returns a \f[CR]Buffer\f[R] object; see below.
T}@T{
T}
.TE
.SS Buffer
Each buffer is exposed as an object that implements the
\f[CR]Buffer\f[R] interface.
To get a reference to the currently displayed buffer, use
\f[CR]pager.buffer\f[R].
.PP
Important: there exists a quirk of questionable value on pager, where
accessing properties that do not exist on the pager will dispatch those
to the current buffer (\f[CR]pager.buffer\f[R]).
So if you see e.g.\ \f[CR]pager.url\f[R], that is actually equivalent to
\f[CR]pager.buffer.url\f[R], because \f[CR]Pager\f[R] has no
\f[CR]url\f[R] getter.
.PP
Following properties (functions/getters) are defined by
\f[CR]Buffer\f[R]:
.PP
.TS
tab(@);
lw(28.0n) lw(38.5n) lw(3.5n).
T{
Property
T}@T{
Description
T}@T{
T}
_
T{
\f[CR]cursorUp(n = 1)\f[R], \f[CR]cursorDown(n = 1)\f[R]
T}@T{
Move the cursor upwards/downwards by n lines, or if n is unspecified, by
1.
T}@T{
T}
T{
\f[CR]cursorLeft(n = 1)\f[R], \f[CR]cursorRight(n = 1)\f[R]
T}@T{
Move the cursor to the left/right by n cells, or if n is unspecified, by
1.
Note: \f[CR]n\f[R] right now represents cells, but really it should
represent characters.
(The difference is that right now numbered cursorLeft/cursorRight is
broken for double\-width chars.)
T}@T{
T}
T{
\f[CR]cursorLineBegin()\f[R], \f[CR]cursorLineEnd()\f[R]
T}@T{
Move the cursor to the first/last cell of the line.
T}@T{
T}
T{
\f[CR]cursorLineTextStart()\f[R]
T}@T{
Move the cursor to the first non\-blank character of the line.
T}@T{
T}
T{
\f[CR]cursorNextWord()\f[R], \f[CR]cursorNextViWord()\f[R],
\f[CR]cursorNextBigWord()\f[R]
T}@T{
Move the cursor to the beginning of the next word.
T}@T{
T}
T{
\f[CR]cursorPrevWord()\f[R], \f[CR]cursorPrevViWord()\f[R],
\f[CR]cursorPrevBigWord()\f[R]
T}@T{
Move the cursor to the end of the previous word.
T}@T{
T}
T{
\f[CR]cursorWordEnd()\f[R], \f[CR]cursorViWordEnd()\f[R],
\f[CR]cursorBigWordEnd()\f[R]
T}@T{
Move the cursor to the end of the current word, or if already there, to
the end of the next word.
T}@T{
T}
T{
\f[CR]cursorWordBegin()\f[R], \f[CR]cursorViWordBegin()\f[R],
\f[CR]cursorBigWordBegin()\f[R]
T}@T{
Move the cursor to the beginning of the current word, or if already
there, to the end of the previous word.
T}@T{
T}
T{
\f[CR]cursorNextLink()\f[R], \f[CR]cursorPrevLink()\f[R]
T}@T{
Move the cursor to the beginning of the next/previous clickable element.
T}@T{
T}
T{
\f[CR]cursorNextParagraph(n = 1)\f[R],
\f[CR]cursorPrevParagraph(n = 1)\f[R]
T}@T{
Move the cursor to the beginning/end of the nth next/previous paragraph.
T}@T{
T}
T{
\f[CR]cursorNthLink(n = 1)\f[R]
T}@T{
Move the cursor to the nth link of the document.
T}@T{
T}
T{
\f[CR]cursorRevNthLink(n = 1)\f[R]
T}@T{
Move the cursor to the nth link of the document, counting backwards from
the document\[cq]s last line.
T}@T{
T}
T{
\f[CR]pageUp(n = 1)\f[R], \f[CR]pageDown(n = 1)\f[R],
\f[CR]pageLeft(n = 1)\f[R], \f[CR]pageRight(n = 1)\f[R]
T}@T{
Scroll up/down/left/right by n pages.
T}@T{
T}
T{
\f[CR]halfPageUp(n = 1)\f[R], \f[CR]halfPageDown(n = 1)\f[R],
\f[CR]halfPageLeft(n = 1)\f[R], \f[CR]halfPageRight(n = 1)\f[R]
T}@T{
Scroll up/down/left/right by n half pages.
T}@T{
T}
T{
\f[CR]scrollUp(n = 1)\f[R], \f[CR]scrollDown(n = 1)\f[R],
\f[CR]scrollLeft(n = 1)\f[R], \f[CR]scrollRight(n = 1)\f[R]
T}@T{
Scroll up/down/left/right by n lines.
T}@T{
T}
T{
\f[CR]click()\f[R]
T}@T{
Click the HTML element currently under the cursor.
T}@T{
T}
T{
\f[CR]cursorFirstLine()\f[R], \f[CR]cursorLastLine()\f[R]
T}@T{
Move to the first/last line in the buffer.
T}@T{
T}
T{
\f[CR]cursorTop()\f[R]
T}@T{
Move to the first line on the screen.
(Equivalent to H in vi.)
T}@T{
T}
T{
\f[CR]cursorMiddle()\f[R]
T}@T{
Move to the line in the middle of the screen.
(Equivalent to M in vi.)
T}@T{
T}
T{
\f[CR]cursorBottom()\f[R]
T}@T{
Move to the last line on the screen.
(Equivalent to L in vi.)
T}@T{
T}
T{
\f[CR]lowerPage(n = this.cursory)\f[R]
T}@T{
Move cursor to line n, then scroll up so that the cursor is on the top
line on the screen.
(\f[CR]zt\f[R] in vim.)
T}@T{
T}
T{
\f[CR]lowerPageBegin(n = this.cursory)\f[R]
T}@T{
Move cursor to the first non\-blank character of line n, then scroll up
so that the cursor is on the top line on the screen.
(\f[CR]z<CR>\f[R] in vi.)
T}@T{
T}
T{
\f[CR]centerLine(n = this.cursory)\f[R]
T}@T{
Center screen around line n.\ (\f[CR]zz\f[R] in vim.)
T}@T{
T}
T{
\f[CR]centerLineBegin(n = this.cursory)\f[R]
T}@T{
Center screen around line n, and move the cursor to the line\[cq]s first
non\-blank character.
(\f[CR]z.\f[R] in vi.)
T}@T{
T}
T{
\f[CR]raisePage(n = this.cursory)\f[R]
T}@T{
Move cursor to line n, then scroll down so that the cursor is on the top
line on the screen.
(zb in vim.)
T}@T{
T}
T{
\f[CR]lowerPageBegin(n = this.cursory)\f[R]
T}@T{
Move cursor to the first non\-blank character of line n, then scroll up
so that the cursor is on the last line on the screen.
(\f[CR]z\[ha]\f[R] in vi.)
T}@T{
T}
T{
\f[CR]nextPageBegin(n = this.cursory)\f[R]
T}@T{
If n was given, move to the screen before the nth line and raise the
page.
Otherwise, go to the previous screen\[cq]s last line and raise the page.
(\f[CR]z+\f[R] in vi.)
T}@T{
T}
T{
\f[CR]cursorLeftEdge()\f[R], \f[CR]cursorMiddleColumn()\f[R],
\f[CR]cursorRightEdge()\f[R]
T}@T{
Move to the first/middle/last column on the screen.
T}@T{
T}
T{
\f[CR]centerColumn()\f[R]
T}@T{
Center screen around the current column.
T}@T{
T}
T{
\f[CR]findNextMark(x = this.cursorx, y = this.cursory)\f[R]
T}@T{
Find the next mark after \f[CR]x\f[R], \f[CR]y\f[R], if any; and return
its id (or null if none were found.)
T}@T{
T}
T{
\f[CR]findPrevMark(x = this.cursorx, y = this.cursory)\f[R]
T}@T{
Find the previous mark before \f[CR]x\f[R], \f[CR]y\f[R], if any; and
return its id (or null if none were found.)
T}@T{
T}
T{
\f[CR]setMark(id, x = this.cursorx, y = this.cursory)\f[R]
T}@T{
Set a mark at (x, y) using the name \f[CR]id\f[R].
Returns true if no other mark exists with \f[CR]id\f[R].
If one already exists, it will be overridden and the function returns
false.
T}@T{
T}
T{
\f[CR]clearMark(id)\f[R]
T}@T{
Clear the mark with the name \f[CR]id\f[R].
Returns true if the mark existed, false otherwise.
T}@T{
T}
T{
\f[CR]gotoMark(id)\f[R]
T}@T{
If the mark \f[CR]id\f[R] exists, jump to its position and return true.
Otherwise, do nothing and return false.
T}@T{
T}
T{
\f[CR]gotoMarkY(id)\f[R]
T}@T{
If the mark \f[CR]id\f[R] exists, jump to the beginning of the line at
its Y position and return true.
Otherwise, do nothing and return false.
T}@T{
T}
T{
\f[CR]getMarkPos(id)\f[R]
T}@T{
If the mark \f[CR]id\f[R] exists, return its position as an array where
the first element is the X position and the second element is the Y
position.
If the mark does not exist, return null.
T}@T{
T}
T{
\f[CR]markURL()\f[R]
T}@T{
Convert URL\-like strings to anchors on the current page.
T}@T{
T}
T{
\f[CR]url\f[R]
T}@T{
Getter for the buffer\[cq]s URL.
Note: this returns a \f[CR]URL\f[R] object, not a string.
T}@T{
T}
T{
\f[CR]hoverTitle\f[R], \f[CR]hoverLink\f[R], \f[CR]hoverImage\f[R]
T}@T{
Getter for the string representation of the element title/link/image
currently under the cursor.
Returns the empty string if no title is found.
T}@T{
T}
.TE
.SS LineEdit
The line editor at the bottom of the screen is exposed to the JavaScript
context as \f[CR]globalThis.line\f[R], or simply \f[CR]line\f[R], and
implements the \f[CR]LineEdit\f[R] interface.
.PP
Note that there is no single \f[CR]LineEdit\f[R] object; a new one is
created every time the line editor is opened, and when the line editor
is closed, \f[CR]globalThis.line\f[R] simply returns \f[CR]null\f[R].
.PP
Following properties (functions/getters) are defined by
\f[CR]LineEdit\f[R]:
.PP
.TS
tab(@);
lw(28.0n) lw(38.5n) lw(3.5n).
T{
Property
T}@T{
Description
T}@T{
T}
_
T{
\f[CR]submit()\f[R]
T}@T{
Submit line.
T}@T{
T}
T{
\f[CR]cancel()\f[R]
T}@T{
Cancel operation.
T}@T{
T}
T{
\f[CR]backspace()\f[R]
T}@T{
Delete character before cursor.
T}@T{
T}
T{
\f[CR]delete()\f[R]
T}@T{
Delete character after cursor.
T}@T{
T}
T{
\f[CR]clear()\f[R]
T}@T{
Clear text before cursor.
T}@T{
T}
T{
\f[CR]kill()\f[R]
T}@T{
Clear text after cursor.
T}@T{
T}
T{
\f[CR]clearWord()\f[R]
T}@T{
Delete word before cursor.
T}@T{
T}
T{
\f[CR]killWord()\f[R]
T}@T{
Delete word after cursor.
T}@T{
T}
T{
\f[CR]backward()\f[R], \f[CR]forward()\f[R]
T}@T{
Move cursor backward/forward by one character.
T}@T{
T}
T{
\f[CR]nextWord()\f[R], \f[CR]prevWord()\f[R]
T}@T{
Move cursor to the next/previous word by one character.
T}@T{
T}
T{
\f[CR]begin()\f[R], \f[CR]end()\f[R]
T}@T{
Move cursor to the beginning/end of the line.
T}@T{
T}
T{
\f[CR]escape()\f[R]
T}@T{
Ignore keybindings for next character.
T}@T{
T}
T{
\f[CR]nextHist()\f[R], \f[CR]prevHist()\f[R]
T}@T{
Jump to the previous/next history entry.
T}@T{
T}
.TE