Module luakit

Luakit core API
Some functions and fields are not available from web processes.

This library provides a set of infrastructure and utility functions for controlling luakit, accessing and modifying current settings, running background programs, and more.

Functions

luakit.quit ()

Quit luakit immediately, without asking modules for confirmation.

luakit.spawn (cmd, callback)

Spawn a process asynchronously.

Parameters

  • cmd
    Type: string
    The command to execute. It is parsed with a simple shell-like parser (g_shell_parse_argv).
  • callback
    Type: function
    Optional
    A callback function to execute when the spawned process is terminated, of type process_exit_cb.

luakit.spawn_sync (cmd)

Spawn a process synchronously.

This will block the luakit UI until the process exits.

Parameters

  • cmd
    Type: string
    The command to execute. It is parsed with a simple shell-like parser (g_shell_parse_argv).

Return Values

  • number
    The exit status of the command.
  • string
    A string containig data printed on stdout.
  • string
    A string containig data printed on stderr.

luakit.time ()

Get the time since Luakit startup.

Return Values

  • number
    The number of seconds Luakit has been running.

luakit.uri_encode (str)

Escape a string for use in a URI.

Parameters

  • str
    Type: string
    The string to encode.

Return Values

  • string
    The escaped/encoded string.

luakit.uri_decode (str)

Unescape an escaped string used in a URI.

Returns the unescaped string, or nil if the string contains illegal characters.

Parameters

  • str
    Type: string
    The string to decode.

Return Values

  • string
    The unescaped/decoded string, or nil on error.
  • string
    Error message.

luakit.idle_add (cb)

Add a function to be called regularly when Luakit is idle. If the function returns false, or if an error is encountered during execution, the function is automatically removed from the set of registered idle functions, and will not be called again.

The provided callback function is not called with any arguments; to pass context to the callback function, use a closure.

Parameters

  • cb
    Type: function
    The function to call when Luakit is idle, of type idle_cb.

luakit.idle_remove (cb)

Remove a function previously registered with idle_add.

Parameters

  • cb
    Type: function
    The function to removed from the set of idle callbacks.

Return Values

  • boolean
    true if the callback was present (and removed); false if the callback was not found.

luakit.register_scheme (scheme)

Register a custom URI scheme.

Registering a scheme causes network requests to that scheme to be redirected to Lua code via the signal handling interface. A signal based on the scheme name will be emitted on a webview widget when it attempts to load a URI on the registered scheme. To return content to display, as well as an optional mime-type, connect to the signal and return a string with the content to display.

This interface is used to register the luakit:// scheme, but is not limited to this prefix alone.

Example

Registering a scheme foo will cause URIs beginning with foo:// to be redirected to Lua code. A signal scheme-request::foo will be emitted on a webview in response to a foo:// load attempt, and should be handled to provide contentt.

Parameters

  • scheme
    Type: string
    The network scheme to register.

luakit.wch_upper (key)

Convert a key or key name to uppercase.

Parameters

  • key
    Type: string
    The key or key name to convert.

Return Values

  • string
    The converted key. This will be the same as key if the key is already uppercase or if case conversion does not apply to the key.

luakit.wch_lower (key)

Convert a key or key name to lowercase.

Parameters

  • key
    Type: string
    The key or key name to convert.

Return Values

  • string
    The converted key. This will be the same as key if the key is already lowercase or if case conversion does not apply to the key.

luakit.clear_favicon_database ()

Clear the favicon cache database.

Properties

luakit.config_dir

Type: string
Read-only
The path to the luakit configuration directory.

luakit.data_dir

Type: string
Read-only
The path to the luakit data directory.

luakit.cache_dir

Type: string
Read-only
The path to the luakit cache directory.

luakit.verbose

Type: boolean
Read-only
Whether luakit is using verbose logging. true if logging in verbose or debug mode.

luakit.install_path

Deprecated: use install_paths.install_dir instead
Type: string
Read-only
The luakit installation path.

luakit.install_paths

Type: table
Read-only
The paths to where luakit's files are installed.

luakit.version

Type: string
Read-only
The luakit version.

luakit.webkit_version

Type: string
Read-only
The WebKitGTK version that luakit was built with.

luakit.windows

Type: {widget}
Read-only
An array of all active window widgets.

luakit.enable_spell_checking

Type: boolean
Default: false
Read-write
Whether spell checking is enabled.

luakit.spell_checking_languages

Type: {string}
Read-write
The set of languages to use for spell checking, if spell checking is enabled.

Each item in the table is a code of the form lang_COUNTRY, where lang is an ISO-639 language code, in lowercase, and COUNTRY is an ISO-3166 country code, in uppercase.

When setting a new value for this property, any unrecognized codes are discarded and a warning is logged, but no error is generated.

This property has a default value based on the user's locale. Setting this value to {} will reset it to the default value.

luakit.selection

Type: {[string]=string}
Read-write
The current contents of the different X selections. The key used to access this table must be the name of the X clipboard to use (one of "primary", "secondary" or "clipboard").

Primary

When the user selects some text with the mouse, the primary selection is filled automatically with the contents of that text selection.

Secondary

The secondary selection is not used as much as the primary and clipboard selections, but is included here for completeness.

Clipboard

The clipboard selection is filled with the contents of the primary selection when the user explicitly requests a copy operation.

luakit.resource_path

Type: string
Read-write
The set of paths used by luakit to search for resource files. This property is similar to package.path; it is a semicolon-separated list of paths, and paths appearing earlier in the list will be searched first when looking for resource files.

By default, it includes the current directory and the luakit installation directory.

Signals

"page-created"

This signal is only emitted on the web process of the newly-created page.

Emitted after the creation of a page object; i.e. after a new webview widget has been created in the UI process.

Usage
luakit.add_signal("page-created", function (page)
    -- Add more signals to page
end)

Parameters

  • page
    Type: page
    The new page object.

Callback Types

process_exit_cb (reason, status)

Callback type for spawn.

Parameters

  • reason
    Type: string
    The reason for process termination. Can be one of "exit", indicating normal termination; "signal", indicating the process was killed with a signal; and "unknown".
  • status
    Type: integer
    The exit status code of the process. Its meaning is system-dependent.

idle_cb ()

Idle callback function type. Return true to keep the callback running on idle. Returning false or nil will cause the callback to be automatically removed from the set of registered idle functions.

Return Values

  • boolean
    Whether the callback should be kept running on idle.

Attribution

Copyright

  • 2016 Aidan Holm
  • 2010 Mason Larobina
  • Paweł Zuzelski