Options
All
  • Public
  • Public/Protected
  • All
Menu

External module "excmds"

Tridactyl help page

Use :help <excmd> or scroll down to show help for a particular excmd.

The default keybinds can be found here. You can also view them with bind. Try bind j.

For more information, and FAQs, check out our readme on github.

Tridactyl is in a pretty early stage of development. Please report any issues and make requests for missing features on the GitHub project page. You can also get in touch using Matrix, Gitter, or IRC chat clients:

Matrix Chat Gitter Chat Freenode Chat

All three channels are mirrored together, so it doesn't matter which one you use.

Highlighted features:

  • Press b to bring up a list of open tabs in the current window; you can type the tab ID or part of the title or URL to choose a tab
  • Press I to enter ignore mode. Shift + Escape to return to normal mode.
  • Press f to start "hint mode", F to open in background
  • Press o to :open a different page
  • Press s if you want to search for something that looks like a domain name or URL
  • bind new commands with e.g. :bind J tabnext
  • Type :help to see a list of available excmds
  • Use yy to copy the current page URL to your clipboard
  • ]] and [[ to navigate through the pages of comics, paginated articles, etc
  • Pressing ZZ will close all tabs and windows, but it will only "save" them if your about:preferences are set to "show your tabs and windows from last time"

There are some caveats common to all webextension vimperator-alikes:

  • Do not try to navigate to any about:* pages using :open as it will fail silently
  • Firefox will not load Tridactyl on addons.mozilla.org, about:*, some file:* URIs, view-source:*, or data:*. On these pages Ctrl-L (or F6), Ctrl-Tab and Ctrl-W are your escape hatches
  • Tridactyl does not currently support changing/hiding the Firefox GUI, but you can do it yourself by changing your userChrome. There is an example file available in our repository.

If you want a more fully-featured vimperator-alike, your best option is Firefox ESR and Vimperator :)

Index

Variables

INPUTPASSWORD_selectors

INPUTPASSWORD_selectors: string = `input[type='password']`

Password field selectors

INPUTTAGS_selectors

INPUTTAGS_selectors: string = `input:not([disabled]):not([readonly]):-moz-any(:not([type]),[type='text'],[type='search'],[type='password'],[type='datetime'],[type='datetime-local'],[type='date'],[type='month'],[type='time'],[type='week'],[type='number'],[type='range'],[type='email'],[type='url'],[type='tel'],[type='color']),textarea:not([disabled]):not([readonly]),object,[role='application']`

The kinds of input elements that we want to be included in the "focusinput" command (gi)

LAST_USED_INPUT

LAST_USED_INPUT: HTMLElement = null

DOM reference to the last used Input field

logger

logger: Logger = new Logging.Logger('excmds')

Functions

autocmd

  • autocmd(event: string, url: string, ...excmd: string[]): void
  • Set autocmds to run when certain events happen.

    Parameters

    • event: string

      Curently, only 'DocStart' is supported.

    • url: string

      The URL on which the events will trigger (currently just uses "contains")

    • Rest ...excmd: string[]

      The excmd to run (use composite to run multiple commands)

    Returns void

back

  • back(n?: number): void
  • Navigate back one page in history.

    Parameters

    • Default value n: number = 1

    Returns void

bind

  • bind(key: string, ...bindarr: string[]): void
  • Bind a sequence of keys to an excmd or view bound sequence.

    This is an easier-to-implement bodge while we work on vim-style maps.

    Examples:

    • bind G fillcmdline tabopen google
    • bind D composite tabclose | buffer #
    • bind j scrollline 20
    • bind F hint -b

    You can view binds by omitting the command line:

    • bind j
    • bind k

    Use composite if you want to execute multiple excmds. Use fillcmdline to put a string in the cmdline and focus the cmdline (otherwise the string is executed immediately).

    See also:

    Parameters

    • key: string
    • Rest ...bindarr: string[]

    Returns void

bmark

  • bmark(url?: string, ...titlearr: string[]): Promise<void>
  • Add or remove a bookmark.

    Optionally, you may give the bookmark a title. If no URL is given, a bookmark is added for the current page.

    If a bookmark already exists for the URL, it is removed.

    Parameters

    • Optional url: string
    • Rest ...titlearr: string[]

    Returns Promise<void>

buffer

  • buffer(index: number | "#"): Promise<void>
  • Change active tab.

    Parameters

    • index: number | "#"

      Starts at 1. 0 refers to last tab, -1 to penultimate tab, etc.

      "#" means the tab that was last accessed in this window

    Returns Promise<void>

buffers

  • buffers(): Promise<void>
  • Equivalent to fillcmdline buffer

    Sort of Vimperator alias

    Returns Promise<void>

clipboard

  • clipboard(excmd?: "open" | "yank" | "yankshort" | "yankcanon" | "tabopen", ...toYank: string[]): Promise<void>
  • Use the system clipboard.

    If excmd == "open", call open with the contents of the clipboard. Similarly for tabopen.

    If excmd == "yank", copy the current URL, or if given, the value of toYank, into the system clipboard.

    If excmd == "yankcanon", copy the canonical URL of the current page if it exists, otherwise copy the current URL.

    If excmd == "yankshort", copy the shortlink version of the current URL, and fall back to the canonical then actual URL. Known to work on https://yankshort.neocities.org/.

    Unfortunately, javascript can only give us the clipboard clipboard, not e.g. the X selection clipboard.

    Parameters

    • Default value excmd: "open" | "yank" | "yankshort" | "yankcanon" | "tabopen" = "open"
    • Rest ...toYank: string[]

    Returns Promise<void>

comclear

  • comclear(name: string): void
  • Similar to vim's comclear command. Clears an excmd alias defined by command.

    For example: comclear helloworld will reverse any changes caused by command helloworld xxx

    See also:

    Parameters

    • name: string

    Returns void

command

  • command(name: string, ...definition: string[]): void
  • Similar to vim's :command. Maps one ex-mode command to another. If command already exists, this will override it, and any new commands added in a future release will be SILENTLY overridden. Aliases are expanded recursively.

    Examples:

    • command t tabopen
    • command tn tabnext_gt = command hello t This will expand recursively into 'hello'->'tabopen'

    Note that this is only for excmd->excmd mappings. To map a normal-mode command to an excommand, see bind.

    See also:

    Parameters

    • name: string
    • Rest ...definition: string[]

    Returns void

composite

  • composite(...cmds: string[]): void
  • Split cmds on pipes (|) and treat each as it's own command.

    Workaround: this should clearly be in the parser, but we haven't come up with a good way to deal with |s in URLs, search terms, etc. yet.

    Parameters

    • Rest ...cmds: string[]

    Returns void

current_url

  • current_url(...strarr: string[]): Promise<void>
  • Equivalent to fillcmdline_notrail <yourargs><current URL>

    See also fillcmdline_notrail

    Parameters

    • Rest ...strarr: string[]

    Returns Promise<void>

fillcmdline

  • fillcmdline(...strarr: string[]): void
  • Set the current value of the commandline to string with a trailing space

    Parameters

    • Rest ...strarr: string[]

    Returns void

fillcmdline_notrail

  • fillcmdline_notrail(...strarr: string[]): void
  • Set the current value of the commandline to string without a trailing space

    Parameters

    • Rest ...strarr: string[]

    Returns void

find

  • find(direction?: number): void
  • Parameters

    • Optional direction: number

    Returns void

findnext

  • findnext(n: number): void

focusinput

  • focusinput(nth: number | string): void
  • Focus the last used input on the page

    Parameters

    • nth: number | string

      focus the nth input on the page, or "special" inputs: "-l": last focussed input "-n": input after last focussed one "-N": input before last focussed one "-p": first password field "-b": biggest input field

    Returns void

followpage

  • followpage(rel?: "next" | "prev"): void
  • Find a likely next/previous link and follow it

    If a link or anchor element with rel=rel exists, use that, otherwise fall back to:

    1) find the last anchor on the page with innerText matching the appropriate followpagepattern. 2) call urlincrement with 1 or -1

    If you want to support e.g. French:

    set followpagepatterns.next ^(next|newer|prochain)\b|»|>>
    set followpagepatterns.prev ^(prev(ious)?|older|précédent)\b|»|>>
    

    Parameters

    • Default value rel: "next" | "prev" = "next"

      the relation of the target page to the current page: "next" or "prev"

    Returns void

forward

  • forward(n?: number): void
  • Navigate forward one page in history.

    Parameters

    • Default value n: number = 1

    Returns void

get

  • get(...keys: string[]): void
  • Puts the contents of config value with keys keys into the commandline and the background page console

    It's a bit rubbish, but we don't have a good way to provide feedback to the commandline yet.

    You can view the log entry in the browser console (Ctrl-Shift-j).

    Parameters

    • Rest ...keys: string[]

    Returns void

getnexttabs

  • getnexttabs(tabid: number, n?: number): Promise<number[]>
  • Parameters

    • tabid: number
    • Optional n: number

    Returns Promise<number[]>

gobble

  • gobble(nChars: number, endCmd: string): Promise<void>
  • Initialize gobble mode.

    It will read nChars input keys, append them to endCmd and execute that string.

    Parameters

    • nChars: number
    • endCmd: string

    Returns Promise<void>

help

  • help(excmd?: string): Promise<void>
  • Show this page.

    :help <excmd> jumps to the entry for that command.

    e.g. :help bind

    Parameters

    • Optional excmd: string

    Returns Promise<void>

hint

  • hint(option?: string, selectors?: string): void
  • Hint a page.

    Parameters

    • Optional option: string
      • -b open in background
      • -y copy (yank) link's target to clipboard
      • -p copy an element's text to the clipboard
      • -r read an element's text with text-to-speech
      • -i view an image
      • -I view an image in a new tab
      • -k delete an element from the page
      • -s save (download) the linked resource
      • -S save the linked image
      • -a save-as the linked resource
      • -A save-as the linked image
      • -; focus an element
      • -# yank an element's anchor URL to clipboard
      • -c [selector] hint links that match the css selector
      • bind ;c hint -c [class*="expand"],[class="togg"] works particularly well on reddit and HN
      • -w open in new window -wp open in new private window

      Excepting the custom selector mode and background hint mode, each of these hint modes is available by default as ;<option character>, so e.g. ;y to yank a link's target.

      To open a hint in the background, the default bind is F.

      Related settings: "hintchars": "hjklasdfgyuiopqwertnmzxcvb" "hintfiltermode": "simple" | "vimperator" | "vimperator-reflow" "relatedopenpos": "related" | "next" | "last"

    • Default value selectors: string = ""

    Returns void

home

  • home(all?: "false" | "true"): void
  • Go to your homepage(s)

    Parameters

    • Default value all: "false" | "true" = "false"
      • if "true", opens all homepages in new tabs
      • if "false" or not given, opens the last homepage in the current tab

    Returns void

loadaucmds

  • loadaucmds(): Promise<void>

loggingsetlevel

  • loggingsetlevel(logModule: string, level: string): void
  • Set the logging level for a given logging module.

    Parameters

    • logModule: string

      the logging module to set the level on

    • level: string

      the level to log at: in increasing verbosity, one of "never", "error", "warning", "info", "debug"

    Returns void

mode

open

  • open(...urlarr: string[]): void
  • Open a new page in the current tab.

    Parameters

    • Rest ...urlarr: string[]
      • if first word looks like it has a schema, treat as a URI
      • else if the first word contains a dot, treat as a domain name
      • else if the first word is a key of [[SEARCH_URLS]], treat all following terms as search parameters for that provider
      • else treat as search parameters for google

      Related settings: "searchengine": "google" or any of [[SEARCH_URLS]]

    Returns void

pin

  • pin(): Promise<void>
  • Pin the current tab

    Returns Promise<void>

q

  • q(): Promise<void>

qa

  • qa(): Promise<void>

qall

  • qall(): Promise<void>

quickmark

  • quickmark(key: string, ...addressarr: string[]): Promise<void>
  • Bind a quickmark for the current URL to a key.

    Afterwards use go[key], gn[key], or gw[key] to open, tabopen, or winopen the URL respectively.

    Parameters

    • key: string
    • Rest ...addressarr: string[]

    Returns Promise<void>

quit

  • quit(): Promise<void>

reader

  • reader(): Promise<void>

reload

  • reload(n?: number, hard?: boolean): Promise<void>
  • Reload the next n tabs, starting with activeTab, possibly bypassingCache

    Parameters

    • Default value n: number = 1
    • Default value hard: boolean = false

    Returns Promise<void>

reloadall

  • reloadall(hard?: boolean): Promise<void>
  • Reloads all tabs, bypassing the cache if hard is set to true

    Parameters

    • Default value hard: boolean = false

    Returns Promise<void>

reloadhard

  • reloadhard(n?: number): Promise<void>
  • Reload the next n tabs, starting with activeTab. bypass cache for all

    Parameters

    • Default value n: number = 1

    Returns Promise<void>

repeat

  • repeat(n?: number, ...exstr: string[]): void
  • Repeats a cmd n times. Falls back to the last executed command if cmd doesn't exist. Executes the command once if n isn't defined either.

    Parameters

    • Default value n: number = 1
    • Rest ...exstr: string[]

    Returns void

reset

  • reset(key: string): Promise<void>
  • Restores a sequence of keys to their default value.

    See also:

    Parameters

    • key: string

    Returns Promise<void>

sanitize

  • sanitize(...args: string[]): Promise<void>
  • Deletes various privacy-related items.

    The list of possible arguments can be found here: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/browsingData/DataTypeSet

    Additional, tridactyl-specific arguments are:

    • commandline: Removes the in-memory commandline history.
    • tridactyllocal: Removes all tridactyl storage local to this machine. Use it with commandline if you want to delete your commandline history.
    • tridactylsync: Removes all tridactyl storage associated with your Firefox Account (i.e, all user configuration, by default). These arguments aren't affected by the timespan parameter.

    Timespan parameter: -t [0-9]+(m|h|d|w)

    Examples: sanitize all -> Deletes everything sanitize history -> Deletes all history sanitize commandline tridactyllocal tridactylsync -> Deletes every bit of data Tridactyl holds sanitize cookies -t 3d -> Deletes cookies that were set during the last three days.

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

scrollline

  • scrollline(n?: number): void
  • Parameters

    • Default value n: number = 1

    Returns void

scrollpage

  • scrollpage(n?: number): void
  • Parameters

    • Default value n: number = 1

    Returns void

scrollpx

  • scrollpx(a: number, b: number): void
  • Parameters

    • a: number
    • b: number

    Returns void

scrollto

  • scrollto(a: number, b?: number | "x" | "y"): void
  • If two numbers are given, treat as x and y values to give to window.scrollTo If one number is given, scroll to that percentage along a chosen axis, defaulting to the y-axis

    Parameters

    • a: number
    • Default value b: number | "x" | "y" = "y"

    Returns void

searchsetkeyword

  • searchsetkeyword(keyword: string, url: string): void
  • Set a search engine keyword for use with *open or set searchengine

    deprecated

    use set searchurls.KEYWORD URL instead

    Parameters

    • keyword: string

      the keyword to use for this search (e.g. 'esa')

    • url: string

      the URL to interpolate the query into. If %s is found in the URL, the query is inserted there, else it is appended. If the insertion point is in the "query string" of the URL, the query is percent-encoded, else it is verbatim.

    Returns void

set

  • set(key: string, ...values: string[]): void

showcmdline

  • showcmdline(): void
  • Please use fillcmdline instead

    Returns void

suppress

  • suppress(preventDefault?: boolean, stopPropagation?: boolean): void
  • Deprecated

    Parameters

    • Optional preventDefault: boolean
    • Optional stopPropagation: boolean

    Returns void

tabclose

  • tabclose(...indexes: string[]): Promise<void>
  • Close a tab.

    Known bug: autocompletion will make it impossible to close more than one tab at once if the list of numbers looks enough like an open tab's title or URL.

    Parameters

    • Rest ...indexes: string[]

      The 1-based indexes of the tabs to target. indexes < 1 wrap. If omitted, this tab.

    Returns Promise<void>

tabdetach

  • tabdetach(index?: number): Promise<void>
  • Detach a tab, opening it in a new window.

    Parameters

    • Optional index: number

      The 1-based index of the tab to target. index < 1 wraps. If omitted, this tab.

    Returns Promise<void>

tabduplicate

  • tabduplicate(index?: number): Promise<void>
  • Duplicate a tab.

    Parameters

    • Optional index: number

      The 1-based index of the tab to target. index < 1 wraps. If omitted, this tab.

    Returns Promise<void>

tabfirst

  • tabfirst(): Promise<void>
  • Switch to the first tab.

    Returns Promise<void>

tablast

  • tablast(): Promise<void>
  • Switch to the last tab.

    Returns Promise<void>

tabmove

  • tabmove(index?: string): Promise<void>
  • Move the current tab to be just in front of the index specified.

    Known bug: This supports relative movement, but autocomple doesn't know that yet and will override positive and negative indexes.

    Put a space in front of tabmove if you want to disable completion and have the relative indexes at the command line.

    Binds are unaffected.

    Parameters

    • Default value index: string = "0"

      New index for the current tab.

      1 is the first index. 0 is the last index. -1 is the penultimate, etc.

    Returns Promise<void>

tabnext

  • tabnext(increment?: number): Promise<void>
  • Switch to the next tab, wrapping round.

    If increment is specified, move that many tabs forwards.

    Parameters

    • Default value increment: number = 1

    Returns Promise<void>

tabnext_gt

  • tabnext_gt(index?: number): Promise<void>
  • Switch to the next tab, wrapping round.

    If an index is specified, go to the tab with that number (this mimics the behaviour of {count}gt in vim, except that this command will accept a count that is out of bounds (and will mod it so that it is within bounds as per tabmove, etc)).

    Parameters

    • Optional index: number

    Returns Promise<void>

tabonly

  • tabonly(): Promise<void>
  • Close all other tabs in this window

    Returns Promise<void>

tabopen

  • tabopen(...addressarr: string[]): Promise<void>
  • Like open, but in a new tab. If no address is given, it will open the newtab page, which can be set with set newtab [url]

    Unlike Firefox's Ctrl-t shortcut, this opens tabs immediately after the currently active tab rather than at the end of the tab list because that is the author's preference.

    If you would rather the Firefox behaviour set tabopenpos last. This preference also affects the clipboard, quickmarks, home, help, etc.

    If you would rather the URL be opened as if you'd middle clicked it, set tabopenpos related.

    Hinting is controlled by relatedopenlast

    Parameters

    • Rest ...addressarr: string[]

    Returns Promise<void>

tabprev

  • tabprev(increment?: number): Promise<void>
  • Switch to the previous tab, wrapping round.

    If increment is specified, move that many tabs backwards.

    Parameters

    • Default value increment: number = 1

    Returns Promise<void>

tabs

  • tabs(): Promise<void>
  • Equivalent to fillcmdline buffer

    Sort of Vimperator alias

    Returns Promise<void>

tssReadFromCss

  • tssReadFromCss(selector: string): void
  • Read text content of elements matching the given selector

    Parameters

    • selector: string

      the selector to match elements

    Returns void

ttscontrol

  • ttscontrol(action: string): Promise<void>
  • Cancel current reading and clear pending queue

    Arguments:

    • stop: cancel current and pending utterances

    Parameters

    • action: string

    Returns Promise<void>

ttsread

  • ttsread(mode: "-t" | "-c", ...args: string[]): Promise<void>
  • Read the given text using the browser's text to speech functionality and the settings currently set

    Parameters

    • mode: "-t" | "-c"

      the command mode -t read the following args as text -c read the content of elements matching the selector

    • Rest ...args: string[]

    Returns Promise<void>

ttsvoices

  • ttsvoices(): Promise<void>
  • Show a list of the voices available to the TTS system. These can be set in the config using ttsvoice

    Returns Promise<void>

unbind

  • unbind(key: string): Promise<void>
  • Unbind a sequence of keys so that they do nothing at all.

    See also:

    Parameters

    • key: string

    Returns Promise<void>

undo

  • undo(): Promise<void>
  • restore most recently closed tab in this window unless the most recently closed item was a window

    Returns Promise<void>

unfocus

  • unfocus(): void
  • Blur (unfocus) the active element

    Returns void

unset

  • unset(...keys: string[]): void
  • Parameters

    • Rest ...keys: string[]

    Returns void

urlincrement

  • urlincrement(count?: number): void
  • Increment the current tab URL

    Parameters

    • Default value count: number = 1

      the increment step, can be positive or negative

    Returns void

urlmodify

  • urlmodify(mode: "-t" | "-r" | "-q" | "-Q" | "-g", ...args: string[]): void
  • Open a URL made by modifying the current URL

    There are several modes:

    • Text replace mode: urlmodify -t <old> <new>

      Replaces the first instance of the text old with new.

      • http://example.com -> (-t exa peta) -> http://petample.com
    • Regex replacment mode: urlmodify -r <regexp> <new> [flags]

      Replaces the first match of the regexp with new. You can use flags i and g to match case-insensitively and to match all instances respectively

      • http://example.com -> (-r [ea] X g) -> http://XxXmplX.com
    • Query replace mode: urlmodify -q <query> <new_val>

      Replace the value of a query with a new one:

    • Query delete mode: urlmodify -Q <query>

      Deletes the given query (and the value if any):

      • http://e.com?id=foo&page=1 -> (-Q id) -> http://e.com?page=1
    • Graft mode: urlmodify -g <graft_point> <new_path_tail>

      "Grafts" a new tail on the URL path, possibly removing some of the old tail. Graft point indicates where the old URL is truncated before adding the new path.

      • graft_point >= 0 counts path levels, starting from the left (beginning). 0 will append from the "root", and no existing path will remain, 1 will keep one path level, and so on.
      • graft_point < 0 counts from the right (i.e. the end of the current path). -1 will append to the existing path, -2 will remove the last path level, and so on.
      http://website.com/this/is/the/path/component
      Graft point:       ^    ^  ^   ^    ^        ^
      From left:         0    1  2   3    4        5
      From right:       -6   -5 -4  -3   -2       -1
      

      Examples:

      • http://e.com/issues/42 -> (-g 0 foo) -> http://e.com/foo
      • http://e.com/issues/42 -> (-g 1 foo) -> http://e.com/issues/foo
      • http://e.com/issues/42 -> (-g -1 foo) -> http://e.com/issues/42/foo
      • http://e.com/issues/42 -> (-g -2 foo) -> http://e.com/issues/foo

    Parameters

    • mode: "-t" | "-r" | "-q" | "-Q" | "-g"

      The replace mode:

      • -t text replace
      • -r regexp replace
      • -q replace the value of the given query
      • -Q delete the given query
      • -g graft a new path onto URL or parent path of it
    • Rest ...args: string[]

    Returns void

urlparent

  • urlparent(count?: number): void
  • Go to the parent URL of the current tab's URL

    Parameters

    • Default value count: number = 1

    Returns void

urlroot

  • urlroot(): void
  • Go to the root domain of the current URL

    Returns void

version

  • version(): void

winclose

  • winclose(): Promise<void>

winopen

  • winopen(...args: string[]): Promise<void>
  • Like tabopen, but in a new window

    Parameters

    • Rest ...args: string[]

    Returns Promise<void>

zoom

  • zoom(level?: number, rel?: string): Promise<void>
  • Parameters

    • Default value level: number = 0
    • Default value rel: string = "false"

    Returns Promise<void>

Generated using TypeDoc