# Luakit Documentation / Modules / luakit

# 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