# Configuration of Chawan Chawan supports configuration of various options like keybindings, user stylesheets, site preferences, etc. The configuration format is very similar to toml, with the following exceptions: * Inline tables may span across multiple lines. * Table arrays can be cleared by setting a variable by the same to the empty array. This allows users to disable default table array rules. Example: ``` omnirule = [] # note: this must be placed at the beginning of the file. [[omnirule]] # this is legal. all default omni-rules are now disabled. ``` Chawan will look for a config file in the $XDG_CONFIG_HOME/chawan/ directory called `config.toml`. (Chawan defaults to ~/.config if the XDG_CONFIG_HOME environment variable is not set.) See the default configuration file in the res/ folder, and bonus configuration files in the bonus/ folder for further examples. **Table of contents** * [Start](#start) * [Search](#search) * [Encoding](#encoding) * [External](#external) * [Network](#network) * [Display](#display) * [Omnirule](#omnirule) * [Siteconf](#siteconf) * [Stylesheets](#stylesheets) * [Keybindings](#keybindings) * [Pager actions](#pager-actions) * [Line-editing actions](#line-editing-actions) * [Appendix](#appendix) * [Regex handling](#regex-handling) ## Start Start-up options are to be placed in the `[start]` section. Following is a list of start-up options:

Name	Value	Function
visual-home	url	Page opened when Chawan is called with the -V option (and no other pages are passed as arguments.)
startup-script	JavaScript code	Script Chawan runs on start-up. Pages will not be loaded until this function exits. (Note however that asynchronous functions like setTimeout do not block loading.)
headless	boolean	Whether Chawan should always start in headless mode. Automatically enabled when Chawan is called with -r.

## Search Search options are to be placed in the `[search]` section. Following is a list of search options:

Name	Value	Function
wrap	boolean	When set to true, searchNext/searchPrev wraps around the document.

## Encoding Encoding options are to be placed in the `[encoding]` section. Following is a list of encoding options:

Name	Value	Function
document-charset	string/array	List of character sets for loading documents. All listed character sets are enumerated until the document has been decoded without errors. In HTML, meta tags and the BOM may override this with a different charset, so long as the specified charset can decode the document correctly.
display-charset	string	Character set for keyboard input and displaying documents. Used in dump mode as well. (This means that e.g. `cha -I EUC-JP -O UTF-8 a > b` is equivalent to `iconv -f EUC-JP -t UTF-8.)

## External External options are to be placed in the `[external]` section. Following is a list of external options:

Name	Value	Function
tmpdir	path	Directory used to save temporary files.
editor	shell command	External editor command. %s is substituted for the file name, %d for the line number.
mailcap	array of paths	Search path for [mailcap](mailcap.md) files.
mime-types	array of paths	Search path for [mime.types](mime.types.md) files.
cgi-dir	array of paths	Search path for [local CGI](localcgi.md) scripts.
cgi-dir	array of paths	Search path for [urimethodmap](urimethodmap.md) files.

## Input Input options are to be placed in the `[input]` section.

Name	Value	Function
vi-numeric-prefix	boolean	Whether vi-style numeric prefixes to commands should be accepted. When set to true, commands that return a function will be called with the numeric prefix as their first argument. Note: this only applies for keybindings defined in [page].

Examples: ``` [input] vi-numeric-prefix = true [page] # Here, the arrow function will be called with the vi numbered prefix if # one was input, and with no argument otherwise. # The numeric prefix can never be zero, so it is safe to test for undefined # using the ternary operator. G = 'n => n ? pager.gotoLine(n) : pager.cursorLastLine()' ``` ## Network Network options are to be placed in the `[network]` section.

Name	Value	Function
max-redirect	number	Maximum number of redirections to follow.
prepend-https	boolean	Whether or not Chawan should attempt loading "raw" URLs without a scheme as https (e.g. wikipedia.org as https://wikipedia.org.)
proxy	URL	Specify a proxy for all network requests Chawan makes. All proxies supported by cURL may be used. Can be overridden by siteconf.
default-headers	Table	Specify a list of default headers for all HTTP(S) network requests.

## Display Display options are to be placed in the `[display]` section. Following is a list of display options:

Name	Value	Function
color-mode	"monochrome"/"ansi"/"8bit"/"24bit"/"auto"	Set the color mode. "auto" for automatic detection, "monochrome" for black on white, "ansi" for ansi colors, "8bit" for 256-color mode, and "24bit" for true colors.
format-mode	"auto"/["bold", "italic", "underline", "reverse", "strike", "overline", "blink"]	Specifies output formatting modes. Accepts the string "auto" or an array of specific attributes. An empty array (`[]`) disables formatting completely.
no-format-mode	["bold", "italic", "underline", "reverse", "strike", "overline", "blink"]	Disable specified formatting modes.
emulate-overline	boolean	When set to true and the overline formatting attribute is not enabled, overlines are substituted by underlines on the previous line.
alt-screen	"auto"/boolean	Enable/disable the alternative screen.
highlight-color	color	Set the highlight color. Both hex values and CSS color names are accepted.
double-width-ambiguous	boolean	Assume the terminal displays characters in the East Asian Ambiguous category as double-width characters. Useful when e.g. ○ occupies two cells.
minimum-contrast	number	Specify the minimum difference between the luminance (Y) of the background and the foreground. -1 disables this function (i.e. allows black letters on black background, etc).
force-clear	boolean	Force the screen to be completely cleared every time it is redrawn.
set-title	boolean	Set the terminal emulator's window title to that of the current page.
default-background-color	color	Sets the assumed background color of the terminal.
default-foreground-color	color	Sets the assumed foreground color of the terminal.

## Omnirule The omni-bar (by default opened with C-l) can be used to perform searches using omni-rules. These are to be placed in the table array `[[omnirule]]`. Examples: ``` # Search using DuckDuckGo Lite. (Bound to C-k by default.) [[omnirule]] match = '^ddg:' substitute-url = '(x) => "https://lite.duckduckgo.com/lite/?kp=-1&kd=-1&q=" + encodeURIComponent(x.split(":").slice(1).join(":"))' # Search using Wikipedia, Firefox-style. [[omnirule]] match = '^@wikipedia' substitute-url = '(x) => "https://en.wikipedia.org/wiki/Special:Search?search=" + encodeURIComponent(x.replace(/@wikipedia/, ""))' ``` Omnirule options:

Name	Value	Function
match	regex	Regular expression used to match the input string. Note that websites passed as arguments are matched as well. Note: regexes are handled according to the [regex handling](#regex-handling) rules.
substitute-url	JavaScript function	A JavaScript function Chawan will pass the input string to. If a new string is returned, it will be parsed instead of the old one.

## Siteconf Configuration options can be specified for individual sites. Entries are to be placed in the table array `[[siteconf]]`. Examples: ``` # Enable cookies on the orange website for log-in. [[siteconf]] url = 'https://news\.ycombinator\.com/.*' cookie = true # Redirect npr.org to text.npr.org. [[siteconf]] host = '(www\.)?npr\.org' rewrite-url = ''' (x) => { x.host = "text.npr.org"; x.pathname = x.pathname.replace(/(.*)\/.*/, "$1").replace(/.*\//, ""); /* No need to return; URL objects are passed by reference. */ } ''' # Allow cookie sharing on *sr.ht domains. [[siteconf]] host = '.*sr\.ht' cookie = true share-cookie-jar = 'sr.ht' third-party-cookie = '.*\.sr.ht' ``` Siteconf options:

Name	Value	Function
url	regex	Regular expression used to match the URL. Either this or the `host` option must be specified. Note: regexes are handled according to the [regex handling](#regex-handling) rules.
host	regex	Regular expression used to match the host part of the URL (i.e. domain name/ip address.) Either this or the `url` option must be specified. Note: regexes are handled according to the [regex handling](#regex-handling) rules.
rewrite-url	JavaScript function	A JavaScript function Chawan will pass the URL to. If a new URL is returned, it will replace the old one.
cookie	boolean	Whether loading cookies should be allowed for this URL. By default, this is false for all websites.
third-party-cookie	regex/array of regexes	Domains for which third-party cookies are allowed on this domain. Note: this only works for buffers which share the same cookie jar. Note: regexes are handled according to the [regex handling](#regex-handling) rules.
share-cookie-jar	host	Cookie jar to use for this domain. Useful for e.g. sharing cookies with subdomains.
referer-from	boolean	Whether or not we should send a Referer header when opening requests originating from this domain. Simplified example: if you click a link on a.com that refers to b.com, and referer-from is true, b.com is sent "a.com" as the Referer header. Defaults to false.
scripting	boolean	Enable/disable JavaScript execution on this site.
document-charset	boolean	Specify the default encoding for this site. Overrides document-charset in [encoding].
stylesheet	CSS stylesheet	Specify an additional user-stylesheet for this site. Note: other user-stylesheets (specified under [css] or additional matching siteconfs) are not overridden. (In other words, they will be concatenated with this stylesheet to get the final user stylesheet.)
proxy	URL	Specify a proxy for network requests fetching contents of this buffer.

## Stylesheets User stylesheets are to be placed in the `[css]` section. There are two ways to import user stylesheets: 1. Include a user stylesheet using the format `include = 'path-to-user.css'`. To include multiple stylesheets, use `include = ['first-stylesheet.css, second-stylesheet.css']`. Relative paths are interpreted relative to the config directory. 2. Place your stylesheet directly in your configuration file using `inline = """your-style"""`. ## Keybindings Keybindings are to be placed in these sections: * for pager interaction: `[page]` * for line editing: `[line]` Keybindings are configured using the syntax '' = '' Where `` is a combination of unicode characters with or without modifiers. Modifiers are the prefixes `C-` and `M-`, which add control or escape to the keybinding respectively (essentially making `M-` the same as `C-[`). Modifiers can be escaped with the `\` sign. ``` Examples: 'C-M-j' = 'pager.load()' # change URL when Control, Escape and j are pressed 'gg' = 'pager.cursorFirstLine()' # go to the first line of the page when g is pressed twice ``` An action is a JavaScript expression called by Chawan every time the keybinding is typed in. If an action returns a function, Chawan will also call the returned function automatically. So this works too: ``` U = '() => pager.load()' # works ``` Note however, that JavaScript functions must be called with an appropriate this value. Unfortunately, this also means that the following does not work: ``` q = 'pager.load' # broken!!! ``` A list of built-in pager functions can be found below. ### Browser actions

Name	Function
`quit()`	Exit the browser.
`suspend()`	Temporarily suspend the browser (by delivering the client process a SIGSTOP signal.) Note: this does not suspend buffer processes.

### Pager actions

Name	Function
`pager.cursorUp(n = 1)`	Move the cursor upwards by n lines, or if n is unspecified, by 1.
`pager.cursorDown(n = 1)`	Move the cursor downwards by n lines, or if n is unspecified, by 1.
`pager.cursorLeft(n = 1)`	Move the cursor to the left by n cells, or if n is unspecified, by 1.
`pager.cursorRight(n = 1)`	Move the cursor to the right by n cells, or if n is unspecified, by 1.
`pager.cursorLineBegin()`	Move the cursor to the first cell of the line.
`pager.cursorLineTextStart()`	Move the cursor to the first non-blank character of the line.
`pager.cursorLineEnd()`	Move the cursor to the last cell of the line.
`pager.cursorNextWord()`	Move the cursor to the beginning of the next word.
`pager.cursorPrevWord()`	Move the cursor to the end of the previous word.
`pager.cursorNextLink()`	Move the cursor to the beginning of the next clickable element.
`pager.cursorPrevLink()`	Move the cursor to the beginning of the previous clickable element.
`pager.pageDown()`	Scroll down by one page.
`pager.pageUp()`	Scroll up by one page.
`pager.pageLeft()`	Scroll to the left by one page.
`pager.pageRight()`	Scroll to the right by one page.
`pager.halfPageDown()`	Scroll forwards by half a page.
`pager.halfPageUp()`	Scroll backwards by half a page.
`pager.scrollDown(n = 1)`	Scroll forwards by n lines.
`pager.scrollUp(n = 1)`	Scroll backwards by n lines.
`pager.scrollLeft(n = 1)`	Scroll to the left by n columns.
`pager.scrollRight(n = 1)`	Scroll to the right by n columns.
`pager.click()`	Click the HTML element currently under the cursor.
`pager.load(url)`	Go to the specified URL. 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. `pager.load("about:chawan\n")`), the URL is loaded directly.
`pager.dupeBuffer()`	Duplicate the current buffer by loading its source to a new buffer.
`pager.discardBuffer()`	Discard the current buffer, and move back to its previous sibling buffer, or if that doesn't exist, to its parent. If the current buffer is a root buffer (i.e. it has no parent), move to the next sibling buffer instead.
`pager.discardTree()`	Discard all child buffers of the current buffer.
`pager.reload()`	Open a new buffer with the current buffer's URL, replacing the current buffer.
`pager.reshape()`	Reshape the current buffer (=render the current page anew.)
`pager.redraw()`	Redraw screen contents. Useful if something messed up the display.
`pager.toggleSource()`	If viewing a HTML buffer, open a new buffer with its source. Otherwise, open the current buffer's contents as HTML.
`pager.cursorFirstLine()`	Move to the beginning in the buffer.
`pager.cursorLastLine()`	Move to the last line in the buffer.
`pager.cursorTop()`	Move to the first line on the screen. (Equivalent to H in vi.)
`pager.cursorMiddle()`	Move to the line in the middle of the screen. (Equivalent to M in vi.)
`pager.cursorBottom()`	Move to the last line on the screen. (Equivalent to L in vi.)
`pager.centerLine()`	Center screen around the current line.
`pager.cursorLeftEdge()`	Move to the first column on the screen.
`pager.cursorMiddleColumn()`	Move to the column in the middle of the screen.
`pager.cursorRightEdge()`	Move to the last column on the screen.
`pager.centerColumn()`	Center screen around the current column.
`pager.lineInfo()`	Display information about the current line.
`pager.searchForward()`	Search for a string in the current buffer.
`pager.searchBackward()`	Search for a string, backwards.
`pager.isearchForward()`	Incremental-search for a string, highlighting the first result.
`pager.isearchBackward()`	Incremental-search and highlight the first result, backwards.
`pager.gotoLine(n?)`	Go to the line passed as the first argument. If no arguments were specified, an input window for entering a line is shown.
`pager.searchNext(n = 1)`	Jump to the nth next search result.
`pager.searchPrev(n = 1)`	Jump to the nth previous search result.
`pager.peek()`	Display an alert message of the current URL.
`pager.peekCursor()`	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)
`pager.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))' ```
`pager.extern(cmd, options = {setenv: true, suspend: true, wait: false})`	Run an external command `cmd`. The `$CHA_URL` and `$CHA_CHARSET` variables are set when `options.setenv` is true. `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 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.)
`pager.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.

### Line-editing actions

Name	Function
`line.submit()`	Submit line
`line.cancel()`	Cancel operation
`line.backspace()`	Delete character before cursor
`line.delete()`	Delete character after cursor
`line.clear()`	Clear text before cursor
`line.kill()`	Clear text after cursor
`line.clearWord(bounds)`	Delete word before cursor
`line.killWord(bounds)`	Delete word after cursor
`line.backward()`	Move cursor back by one character
`line.forward()`	Move cursor forward by one character
`line.prevWord(bounds)`	Move cursor to the previous word by one character
`line.nextWord(bounds)`	Move cursor to the previous word by one character
`line.begin()`	Move cursor to the previous word by one character
`line.end()`	Move cursor to the previous word by one character
`line.escape()`	Ignore keybindings for next character
`line.prevHist()`	Jump to the previous history entry
`line.nextHist()`	Jump to the next history entry

Some of these entries have an optional `bounds` parameter. If passed, this must be a JavaScript function that expects one parameter (the current unicode character), and returns true if the passed character should count as a word boundary. ```Examples: # Control+A moves the cursor to the beginning of the line. 'C-a' = 'line.begin()' # Escape+D deletes everything after the cursor until it reaches a word-breaking # character. 'M-d' = 'line.killWord()' # Control+W deletes everything before the cursor until it reaches a space. 'C-w' = 'line.clearWord(x => x == " ")' ``` ## Appendix ### Regex handling Regular expressions are assumed to be exact matches, except when they start with a caret (^) sign or end with an unescaped dollar ($) sign. In other words, the following transformations occur: ``` ^abcd -> ^abcd efgh$ -> efgh$ ^ijkl$ -> ^ijkl$ mnop -> ^mnop$ ```