Scripting with Lua

Webkitten includes a Lua 5.2 scripting engine for executing scripts based on input to the command bar and other event triggers.

When a command is run in Webkitten, it is matched to a file found within a directory specified by the configuration option commands.search-paths. For example, if reading-mode on is entered in the command bar, Webkitten checks the command search paths for a file named reading-mode.lua, and if a match is found, the file contents are evaluated and the run() method is called, provided the script is not in some way malformed.

Each command runs in a new Lua runtime, so there is no interaction between different commands.

Event triggers

The available entry points for running a command within Webkitten. Implement any of the following methods to run when an event is triggered. Note that some events are only triggered if a configuration prerequisite is met and that the description() method is required.

complete_commands()

Provides completions to command arguments. The scope of the function includes a prefix variable which returns the full text the user has entered, as well as a table of each individual argument as arguments. Returns a comma-delimited list of items as a string, or an empty string if no results were found.

function complete_command()
  return "open,close,save"
end

description()

A summary of the script’s purpose, intended for GUI bindings to display in autocompletion and help text. Returns a string. (required)

function description()
  return "An example script documenting all hooks"
end

on_fail_uri()

Invoked when a URI fails to load. The current scope includes a webview_index and window_index indicating which view is active, as well as requested_uri indicating what URI was requested.

This hook is only invoked if the command name is included in the configuration option commands.on-fail-uri.

function on_fail_uri()
  log_debug("Failed to load " .. requested_uri)
end

on_load_uri()

Invoked when a URI is loaded in a webview. The current scope includes a webview_index and window_index indicating which view is active, as well as requested_uri indicating what URI was requested.

This hook is only invoked if the command name is included in the configuration option commands.on-load-uri.

function on_load_uri()
  local uri = webview_uri(window_index, webview_index)
  log_debug(string.format("Just loaded %s", uri))
end

on_request_uri()

Invoked when a URI will be loaded in a webview. The current scope includes a webview_index and window_index indicating which view is active, as well as requested_uri indicating what URI was requested.

This hook is only invoked if the command name is included in the configuration option commands.on-request-uri.

function on_request_uri()
  log_debug("Requested to load " .. requested_uri)
end

run()

The default hook, invoked when the user presses Return in the command bar. The scope of the function includes an arguments variable, which is a table of the space-delimited arguments which were passed with the function. Returns a boolean indicating whether to clear the bar text.

function run()
  log_info("Running the example script")
  return true
end

Constants

The Lua scripting engine provides a few constant values to make it easier to validate values or check configuration options.

CONFIG_FILE_PATH

The path to the configuration file being used by Webkitten. It can be used as a convenience to do configuration value lookup.

NOT_FOUND

This is a possible value returned from the focused_window_index or focused_webview_index methods respectively, if there is no window or webview to correspond to the provided values. For example, if there are no windows open, focused_window_index() returns NOT_FOUND.

Provided methods

In addition to the Lua standard libraries, the following global methods are provided for use within event triggers.

add_styles(window_index, webview_index, css)

Inject CSS into a webview

function run()
  local window_index = focused_window_index()
  local webview_index = focused_webview_index(window_index)
  add_styles(window_index, webview_index, [[
    body { background-color: red; }
  ]])
end

close_webview(window_index, webview_index)

Close a webview at a given index

close_window(window_index)

Close a window with a given index

command_field_text(window_index)

The text in the command bar of a window at a given index

command_field_visible(window_index)

Return true if in the command bar of a window at a given index is visible

copy(string)

Copy text to the native clipboard

find(int, int, string)

Find and highlight text in a webview

focus_commandbar_in_window(window_index)

Assign keyboard focus to the command field area of the window at a given index

focus_webview(window_index, webview_index)

Show a webview at a given index and assign keyboard focus to it

focus_webview_in_window(window_index)

Assign keyboard focus to the webview area of the window at a given index

focused_webview_index(int)

Returns the index of the focused webview in a window at a given index or NOT_FOUND

focused_window_index()

Returns the index of the focused window or NOT_FOUND

go_back(window_index, webview_index)

Returns to the previously loaded resource (if any) in a webview at a given index

go_forward(window_index, webview_index)

Loads the next resource (if any) in a webview at a given index

hide_find(window_index, webview_index)

Hide any GUI elements or highlighting relating to finding text onscreen

hide_window(window_index)

Hide a window at a given index

load_uri(window_index, webview_index, string)

Load a resource from a URI in a webview at a given index

log_debug(message)

Write text to the application log with a severity level of debug

log_info(message)

Write text to the application log with a severity level of info

lookup_bool(string)

Gets a bool value from the user’s configuration file using the argument as a key

lookup_string(config_path, key)

Gets a string value from the user’s configuration file using the argument as a key

lookup_strings(config_path, key)

Gets a table of strings from the user’s configuration file using the argument as a key

open_webview(window_index, uri)

Open a new webview in a window at a given index and load the URI

open_window(uri)

Open a new window and load the URI

reload_webview(int, int, bool)

Reload a webview, optionally skipping content filters

resize_window(window_index, width, height)

Resize a window to the specified width and height

run_javascript(window_index, webview_index, script)

Run JavaScript source code in the webview at a given index

set_command_field_text(window_index, text)

Change the command field text in a window at a given index

set_command_field_visible(window_index, is_visible)

Change the command field visibility in a window at a given index

set_window_title(window_index, title)

Change the title in a window at a given index

show_window(window_index)

Show a previously hidden window by index

webview_count(window_index)

Returns the number of webviews contained in a window at a given index or zero if a window does not exist for that index

webview_title(window_index, webview_index)

The title of the web content in a webview at a given index

webview_uri(window_index, webview_index)

The URI of the loaded resource in a webview at a given index

window_count()

The number of windows currently open

window_title(window_index)

The title of the window at a given index or empty string if the index does not correspond to a window