FreeBSD Manual Pages
CHA-API(7) Miscellaneous Information Manual CHA-API(7) 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 appro- priate 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 func- tion in a closure, as above. However, this has poor reusability; for more complex actions, you would have to copy and paste the entire func- tion 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. Docu- mented functions of this are: Property Description -------------------------------------------------------------------------- quit() Exit the browser. -------------------------------------------------------------------------- suspend() Temporarily suspend the browser, by delivering the client process a SIGTSTP signal. Note: this suspends the en- tire process group. -------------------------------------------------------------------------- readFile(path) Read a file at path. Returns the file's content as a string, or null if the file does not exist. -------------------------------------------------------------------------- writeFile(path, content) Write content to the file at path. Throws a TypeError if this failed for whatever reason. -------------------------------------------------------------------------- openEditor(text) Open "text" in the command config- ured as external.editor (this is typically just $EDITOR.) If the editor signals an er- ror (crash or non-zero exit code), null is returned. Otherwise, the user's input is returned as a string. -------------------------------------------------------------------------- getenv(name, fallback = null) Get an environment variable by name. Returns fallback if the variable does not exist. -------------------------------------------------------------------------- setenv(name, value) Set an environment variable by name. Throws a type error if the operation failed (e.g. be- cause the variable's size exceeded an OS-specified limit.) -------------------------------------------------------------------------- pager The pager object. Implements Pager, as described below. -------------------------------------------------------------------------- line The line editor. Implements Li- neEdit, as described below. -------------------------------------------------------------------------- config The config object. A currently incomplete in- terface for retrieving and setting configuration op- tions. In general, names are the same as in con- fig.toml, except all - (ASCII hyphen) characters are stripped and the next character is upper-cased. e.g. external.cgi-dir can be queried as config.exter- nal.cgiDir, etc. Setting individual options sometimes works, but some- times they do not get propa- gated as expected. Consider this an experimental API. Currently, siteconf, proto- col and omnirule values are not exposed to JS. The configuration directory itself can be queried as config.dir. 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 prop- erties that do not exist on the pager will dispatch those to the cur- rent buffer (pager.buffer). So if you see e.g. pager.url, that is ac- tually equivalent to pager.buffer.url, because Pager has no url getter. Following properties (functions/getters) are defined by Pager: Property Description ----------------------------------------------------------------------------------------------------------------------------------------- load(url = pager.buffer.url) 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 de- fault scheme/local files, etc. Opens a prompt with the cur- rent URL when no parameters are specified; otherwise, the string passed is dis- played in the prompt. Deprecated quirk: If this string ends with a newline (e.g. pager.load("about:chawan\n")), the URL is loaded directly. This usage isn't recom- mended; use loadSubmit in- stead. ----------------------------------------------------------------------------------------------------------------------------------------- loadSubmit(url) Act as if url had been entered to the URL bar. loadSubmit differs from gotoURL in that it also evaluates omni-rules, tries to prepend a scheme, etc. ----------------------------------------------------------------------------------------------------------------------------------------- gotoURL(url, options = {replace: Go to the specified URL immediately (with- null, contentType: null, save: out a prompt). This differs from loadSub- false}) mit in that it loads the exact URL as passed (no prepending https, etc.) When replace is set, the new buffer may replace the old one if it loads successfully. When contentType is set, the new buffer's content type is forcefully set to that string. When save is true, the user is prompted to save the resource in- stead of displaying it in a buffer. ----------------------------------------------------------------------------------------------------------------------------------------- traverse(dir) Switch to the next buffer in direction dir, interpreted as in Buffer#find. ----------------------------------------------------------------------------------------------------------------------------------------- nextBuffer(), prevBuffer(), nextSi- Same as traverse("next"), traverse("prev"), blingBuffer(), prevSiblingBuffer(), traverse("next-sibling"), tra- parentBuffer() verse("prev-sibling"), and traverse("par- ent"). ----------------------------------------------------------------------------------------------------------------------------------------- dupeBuffer() Duplicate the current buffer by loading its source in a new buffer. ----------------------------------------------------------------------------------------------------------------------------------------- discardBuffer(buffer = Discard buffer, then move back to the pager.buffer, dir = pager.navDirec- buffer opposite to dir (interpreted as in tion) Buffer#find). ----------------------------------------------------------------------------------------------------------------------------------------- discardTree() Discard all next siblings of the current buffer. This function is deprecated, and may be removed in the future. ----------------------------------------------------------------------------------------------------------------------------------------- addTab(target) Open a new tab. If target is a buffer, it is removed from its current tab and added to the newly created tab. Otherwise, target is interpreted as a URL to open with gotoURL. ----------------------------------------------------------------------------------------------------------------------------------------- prevTab(), nextTab() Switch to the previous/next tab in the tab list. ----------------------------------------------------------------------------------------------------------------------------------------- discardTab() Discard the current tab. ----------------------------------------------------------------------------------------------------------------------------------------- reload() Open a new buffer with the current buffer's URL, replacing the current buffer. ----------------------------------------------------------------------------------------------------------------------------------------- reshape() Reshape the current buffer (=render the current page anew.) ----------------------------------------------------------------------------------------------------------------------------------------- redraw() Redraw screen contents. Useful if some- thing messed up the display. ----------------------------------------------------------------------------------------------------------------------------------------- toggleSource() If viewing an HTML buffer, open a new buffer with its source. Otherwise, open the current buffer's contents as HTML. ----------------------------------------------------------------------------------------------------------------------------------------- lineInfo() Display information about the current line. ----------------------------------------------------------------------------------------------------------------------------------------- searchForward(), searchBackward() Search forward/backward for a string in the current buffer. ----------------------------------------------------------------------------------------------------------------------------------------- isearchForward(), isearchBackward() Incremental-search forward/backward for a string, highlighting the first result. ----------------------------------------------------------------------------------------------------------------------------------------- gotoLine(n?) Go to the line passed as the first argu- ment. If no arguments were specified, an input window for entering a line is shown. ----------------------------------------------------------------------------------------------------------------------------------------- searchNext(n = 1), searchPrev(n = Jump to the nth next/previous search re- 1) sult. ----------------------------------------------------------------------------------------------------------------------------------------- peek() Display an alert message of the current URL. ----------------------------------------------------------------------------------------------------------------------------------------- peekCursor() Display an alert message of the URL or ti- tle under the cursor. Multiple calls allow cycling through the two. (i.e. by default, press u once -> title, press again -> URL) ----------------------------------------------------------------------------------------------------------------------------------------- showFullAlert() Show the last alert inside the line editor. ----------------------------------------------------------------------------------------------------------------------------------------- ask(prompt) 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: q = 'pager.ask("Do you want to exit Chawan?").then(x => x ? pager.quit() : void(0))' ----------------------------------------------------------------------------------------------------------------------------------------- askChar(prompt) Ask the user for any character. Like pager.ask, but the return value is a character. ----------------------------------------------------------------------------------------------------------------------------------------- clipboardWrite(s) Write s to the clipboard (copy). By default, it tries using OSC 52; if that fails, it tries to run external.copy-cmd (defaults to xsel). Returns true if the copy succeeded, false otherwise. (There may be false positives in case OSC 52 is used and the terminal doesn't consume the text.) ----------------------------------------------------------------------------------------------------------------------------------------- extern(cmd, options = {env: { ... Run an external command cmd. }, suspend: true, wait: false}) By default, the $CHA_URL and $CHA_CHARSET variables are set; change this using the env op- tion. options.suspend suspends the pager while the command is being executed, and options.wait makes it so the user must press a key before the pager is resumed. Returns true if the command exited successfully, false otherwise. ----------------------------------------------------------------------------------------------------------------------------------------- externCapture(cmd) Like extern(), but redirect the command's stdout string into the result. null is returned if the command wasn't executed successfully, or if the command returned a non-zero exit value. ----------------------------------------------------------------------------------------------------------------------------------------- externInto(cmd, ins) Like extern(), but redirect ins into the command's standard input stream. true is returned if the command exits successfully, otherwise the return value is false. ----------------------------------------------------------------------------------------------------------------------------------------- externFilterSource(cmd, buffer = Redirects the specified (or if buffer is null, the current) buffer's source into cmd. null, contentType = null) Then, it pipes the output into a new buffer, with the content type contentType (or, if con- tentType is null, the original buffer's content type). Returns undefined. (It should return a promise; TODO.) ----------------------------------------------------------------------------------------------------------------------------------------- openMenu(x = pager.cursorx - Opens the context menu at the specified x/y positions. pager.fromx, y = pager.cursory - pager.fromy) ----------------------------------------------------------------------------------------------------------------------------------------- closeMenu() Closes the menu if it is opened. ----------------------------------------------------------------------------------------------------------------------------------------- buffer Getter for the currently displayed buffer. Returns a Buffer object; see below. ----------------------------------------------------------------------------------------------------------------------------------------- menu Getter for the currently displayed menu. Returns a Select object. ----------------------------------------------------------------------------------------------------------------------------------------- navDirection The direction the user last moved in the buffer list using traverse. Possible values are prev, next, prev-sibling, next-sibling, parent, any. ----------------------------------------------------------------------------------------------------------------------------------------- revDirection Equivalent to Pager.oppositeDir(pager.navDirection). Also, the following static function is defined on Pager itself: Property Description -------------------------------------------------------------------------- Pager.oppositeDir(dir) Return a string representing the direction opposite to dir. For "next", this is "prev"; for "parent", "next"; for "prev-sibling", "next-sib- ling"; for "any", it is the same; for the rest, vice versa. Buffer Each buffer is exposed as an object that implements the Buffer inter- face. To get a reference to the currently displayed buffer, use pager.buffer. Note the quirk mentioned above where Pager dispatches unknown proper- ties onto the current buffer. Following properties (functions/getters) are defined by Buffer: Property Description -------------------------------------------------------------------------- cursorUp(n = 1), cursorDown(n = 1) Move the cursor upwards/downwards by n lines, or if n is unspecified, by 1. -------------------------------------------------------------------------- cursorLeft(n = 1), cursorRight(n = Move the cursor to the left/right 1) by n cells, or if n is unspecified, by 1. Note: n right now represents cells, but really it should represent characters. (The difference is that right now numbered cursorLeft/cursor- Right is broken for dou- ble-width chars.) -------------------------------------------------------------------------- cursorLineBegin(), cursorLineEnd() Move the cursor to the first/last cell of the line. -------------------------------------------------------------------------- cursorLineTextStart() Move the cursor to the first non-blank character of the line. -------------------------------------------------------------------------- cursorNextWord(), cursorNextVi- Move the cursor to the beginning of Word(), cursorNextBigWord() the next word. -------------------------------------------------------------------------- cursorPrevWord(), cursorPrevVi- Move the cursor to the end of the Word(), cursorPrevBigWord() previous word. -------------------------------------------------------------------------- cursorWordEnd(), cursorViWordEnd(), Move the cursor to the end of the cursorBigWordEnd() current word, or if already there, to the end of the next word. -------------------------------------------------------------------------- cursorWordBegin(), cursorViWordBe- Move the cursor to the beginning of gin(), cursorBigWordBegin() the current word, or if already there, to the end of the previous word. -------------------------------------------------------------------------- cursorNextLink(), cursorPrevLink() Move the cursor to the beginning of the next/previous clickable ele- ment. -------------------------------------------------------------------------- cursorLinkNavDown(n = 1), cursor- Move the cursor to the beginning of LinkNavUp(n = 1) the next/previous clickable ele- ment. Buffer scrolls pagewise, wrap to beginning/end if content is less than one page length. -------------------------------------------------------------------------- cursorNextParagraph(n = 1), cursor- Move the cursor to the begin- PrevParagraph(n = 1) ning/end of the nth next/previous paragraph. -------------------------------------------------------------------------- cursorNthLink(n = 1) Move the cursor to the nth link of the document. -------------------------------------------------------------------------- cursorRevNthLink(n = 1) Move the cursor to the nth link of the document, counting backwards from the document's last line. -------------------------------------------------------------------------- pageUp(n = 1), pageDown(n = 1), Scroll up/down/left/right by n pageLeft(n = 1), pageRight(n = 1) pages. -------------------------------------------------------------------------- halfPageUp(n = 1), halfPageDown(n = Scroll up/down/left/right by n half 1), halfPageLeft(n = 1), half- pages. PageRight(n = 1) -------------------------------------------------------------------------- scrollUp(n = 1), scrollDown(n = 1), Scroll up/down/left/right by n scrollLeft(n = 1), scrollRight(n = lines. 1) -------------------------------------------------------------------------- click(n = 1) Click the HTML element currently under the cursor. n controls the number of clicks, e.g. n = 2 is a double click. (The number of clicks is only relevant in JS apps.) -------------------------------------------------------------------------- cursorFirstLine(), cursorLastLine() Move to the first/last line in the buffer. -------------------------------------------------------------------------- cursorTop(), cursorMiddle(), cur- Move to the first/middle/bottom sorBottom() line on the screen. (Equivalent to H/M/L in vi.) -------------------------------------------------------------------------- lowerPage(n = this.cursory) Move cursor to line n, then scroll up so that the cursor is on the top line on the screen. (zt in vim.) -------------------------------------------------------------------------- lowerPageBegin(n = this.cursory) 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. (z<CR> in vi.) -------------------------------------------------------------------------- centerLine(n = this.cursory) Center screen around line n. (zz in vim.) -------------------------------------------------------------------------- centerLineBegin(n = this.cursory) Center screen around line n, and move the cursor to the line's first non-blank character. (z. in vi.) -------------------------------------------------------------------------- raisePage(n = this.cursory) Move cursor to line n, then scroll down so that the cursor is on the top line on the screen. (zb in vim.) -------------------------------------------------------------------------- lowerPageBegin(n = this.cursory) 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. (z^ in vi.) -------------------------------------------------------------------------- nextPageBegin(n = this.cursory) If n was given, move to the screen before the nth line and raise the page. Otherwise, go to the previ- ous screen's last line and raise the page. (z+ in vi.) -------------------------------------------------------------------------- cursorLeftEdge(), cursorMiddleCol- Move to the first/middle/last col- umn(), cursorRightEdge() umn on the screen. -------------------------------------------------------------------------- centerColumn() Center screen around the current column. -------------------------------------------------------------------------- findNextMark(x = this.cursorx, y = Find the next/previous mark af- this.cursory), findPrevMark(x = ter/before x, y, if any; and return this.cursorx, y = this.cursory) its id (or null if none were found.) -------------------------------------------------------------------------- setMark(id, x = this.cursorx, y = Set a mark at (x, y) using the name this.cursory) id. Returns true if no other mark exists with id. If one already exists, it will be overridden and the function returns false. -------------------------------------------------------------------------- clearMark(id) Clear the mark with the name id. Returns true if the mark existed, false otherwise. -------------------------------------------------------------------------- gotoMark(id) If the mark id exists, jump to its position and return true. Other- wise, do nothing and return false. -------------------------------------------------------------------------- gotoMarkY(id) If the mark id exists, jump to the beginning of the line at its Y po- sition and return true. Otherwise, do nothing and return false. -------------------------------------------------------------------------- getMarkPos(id) If the mark id exists, return its position as an array where the first element is the X position and the second element is the Y posi- tion. If the mark does not exist, return null. -------------------------------------------------------------------------- cursorToggleSelection(n = 1, opts = Start a vim-style visual selection. {selectionType: "normal"}) The cursor is moved to the right by n cells. selectionType may be "nor- mal" (regular selection), "line" (line-based selec- tion) and "column" (col- umn-based selection). -------------------------------------------------------------------------- getSelectionText() Get the currently selected text. Returns a promise, so con- sumers must await it to get the text. -------------------------------------------------------------------------- markURL() Convert URL-like strings to anchors on the current page. -------------------------------------------------------------------------- showLinkHints() Display link hints on the page. Mainly intended for the built-in toggleLinkHints command. Returns an array of objects with x representing the x position, y the y position of a link. -------------------------------------------------------------------------- toggleImages() Toggle display of images in this buffer. -------------------------------------------------------------------------- saveLink() Save URL pointed to by the cursor. -------------------------------------------------------------------------- saveSource() Save the source of this buffer. -------------------------------------------------------------------------- setCursorX(x), setCursorY(y), Set the cursor position to x and y setCursorXY(x, y), setCursorXCen- respectively, scrolling the view if ter(x), setCursorYCenter(y), necessary. setCursorXYCenter(x, y) Variants that end with "Cen- ter" will also center the screen around the position if it is outside the screen. -------------------------------------------------------------------------- find(dir) Find the next buffer in the list in a specific direction. Possible values of dir are: prev, next, prev-sibling, next-sibling, parent, any. "next" and "prev" return the next/previous buffer respec- tively. "prev-sibling", "parent" are deprecated aliases for "prev", while "next-sibling" is a deprecated alias for "next". Finally, "any" returns ei- ther "prev", or if it's null, "next". -------------------------------------------------------------------------- url Getter for the buffer's URL. Note: this returns a URL object, not a string. -------------------------------------------------------------------------- hoverTitle, hoverLink, hoverImage Getter for the string representa- tion of the element title/link/im- age currently under the cursor. Returns the empty string if no ti- tle is found. -------------------------------------------------------------------------- cursorx, cursory The x/y position of the cursor in- side the buffer. Note that although the sta- tus line is 1-based, these values are 0-based. -------------------------------------------------------------------------- fromx, fromy The x/y position of the first line displayed on the screen. -------------------------------------------------------------------------- numLines The number of lines currently loaded in the buffer. -------------------------------------------------------------------------- width, height The width and height of the buffer's window (i.e. the visible part of the canvas). -------------------------------------------------------------------------- process The process ID of the buffer. -------------------------------------------------------------------------- title Text from the title element, or the buffer's URL if there is no title. -------------------------------------------------------------------------- next Next buffer in the buffer list. May be null. -------------------------------------------------------------------------- prev Previous buffer in the buffer list. May be null. -------------------------------------------------------------------------- select Reference to the current select el- ement's widget, or null if no se- lect element is open. This object implements the Select interface, which is somewhat compatible with the Buffer interface with some exceptions. (TODO: elabo- rate) 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: Property Description ---------------------------------------------------- submit() Submit line. ---------------------------------------------------- cancel() Cancel operation. ---------------------------------------------------- backspace() Delete character before cursor. ---------------------------------------------------- delete() Delete character after cursor. ---------------------------------------------------- clear() Clear text before cursor. ---------------------------------------------------- kill() Clear text after cursor. ---------------------------------------------------- clearWord() Delete word before cursor. ---------------------------------------------------- killWord() Delete word after cursor. ---------------------------------------------------- backward(), forward() Move cursor backward/for- ward by one character. ---------------------------------------------------- nextWord(), prevWord() Move cursor to the next/previous word by one character. ---------------------------------------------------- begin(), end() Move cursor to the begin- ning/end of the line. ---------------------------------------------------- escape() Ignore keybindings for next character. ---------------------------------------------------- nextHist(), prevHist() Jump to the previous/next history entry. ---------------------------------------------------- text The currently entered text. See also cha(1) cha-config(5) CHA-API(7)
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=cha-api&sektion=7&manpath=FreeBSD+Ports+15.0.quarterly>