null-browser

Contents

• Functions
• Tables
• Fields

Modules

• web

Module web

Functions

schedule (fn)	Schedule a function to be called on next tick (qt+libuv event loop)
web.keymap.set (mode, key, action)	Add a keymap
web.keymap.set_mode (mode)	Set the current keymap mode
web.keymap.get_mode ()	Get the current keymap mode
web.view.close (view_id)	Close view
web.view.create (url)	Create a new view with a url
web.view.current ()	Get current view id
web.view.list ()	Get a list of views in the current window
web.view.select (view_id)	Select a view in current window
web.view.set_url (url, view_id)	Set url of a given view
web.view.set_html (html, opts)	Set html inside the page for a given view
web.view.run_js (js, opts)	Run js in a view
web.view.reload (opts)	Relaod a given view
web.view.expose (name, action, opts)	Expose a lua function inside a view (Only works with decorations)
web.view.open_devtools (view_id)	Open devtools window for the view
web.view.current_index ()	Get current view index
web.event.add_listener (events, opts)	Listen to events from the browser
set (key, value)	Set configuration options
get (key)	Get configuration value
web.history.back (count, view_id)	Go back in history for given view
web.history.forward (count, view_id)	Go forward in history for given view
web.search.set_text (text, view_id)	Search text inside a view
web.search.reset (view_id)	Reset searched text in a view (Same as web.search.set_text(''))
web.search.get_text ()	Get the last searched text
web.search.next (view_id)	Highlight next search term for the last searched text
web.search.previous (view_id)	Highlight previous search term for the last searched text
web.view.scroll (deltax, deltay, view_id)	TODO: Document
web.view.scroll_to_top (view_id)	TODO: Document
web.view.scroll_to_bottom (view_id)	TODO: Document
web.help.get_items ()	Get a list of items for help
web.help.show (item, opts)	Open help docs for a given item
web.utils.string_trim (str)	Trim whitespace from start and end of a string
web.utils.table_merge (tbl)	Merge multiple tables
web.utils.table_keys (tbl)	Get keys of a table
web.utils.equals (a, b)	Check if 2 values are deeply equal
web.utils.table_contains (tbl, value)	Check if table contains given value

Tables

WebOpts

Maps to values defined in ./src/Configuration.hpp

Fields

_G.__internals	Internal api (unstable)
opts	API for configuring browser options
uv	luv api (https://github.com/luvit/luv/blob/master/docs.md)
inspect	Returns human-readable string representation of Lua tables (https://github.com/kikito/inspect.lua)

Functions

schedule (fn)

Schedule a function to be called on next tick (qt+libuv event loop)

Parameters:

• fn fun ():nil Function to call

web.keymap.set (mode, key, action)

Add a keymap

Parameters:

• mode string Keymap mode ("i", "n", ...)
• key string Key sequence (Eg: `j`)
• action function Function to run when keymap is triggered

Usage:

web.keymap.set('n', 'o', function()
  web.view.create('https://google.com')
end)

web.keymap.set_mode (mode)

Set the current keymap mode

Parameters:

• mode string The keymap mode to set

Usage:

web.keymap.set_mode('n') -- Set to normal mode
web.keymap.set_mode('i') -- Set to insert mode

web.keymap.get_mode ()

Get the current keymap mode

Usage:

local current_mode = web.keymap.get_mode()

web.view.close (view_id)

Close view

Parameters:

• view_id ? number View id to close

Usage:

web.view.close()  -- Close current view in active window
web.view.close(3) -- Close view with id 3

web.view.create (url)

Create a new view with a url

Parameters:

• url string Url to open in the new view

Usage:

web.view.create('https://duckduckgo.com') -- Opens url in new view
web.view.create() -- Opens new_view_url by default

web.view.current ()

Get current view id

Returns:

number _id Current view id

Usage:

local view_id = web.view.current()

web.view.list ()

Get a list of views in the current window

Returns:

table List of views

Usage:

local views = web.view.list()
print(views[1].url, views[1].title, views[1].id)

web.view.select (view_id)

Select a view in current window

Parameters:

• view_id number View id to select

Usage:

web.view.select(3) -- Select view with id 3

web.view.set_url (url, view_id)

Set url of a given view

Parameters:

• url string Url to open
• view_id number View id to select

Usage:

web.view.set_url('https://foobar.com')
web.view.set_url('https://foobar.com', 3) -- Set url for view with id 3

web.view.set_html (html, opts)

Set html inside the page for a given view

Parameters:

• html string HTML string
• opts table Options
  • view number View id

Usage:

web.view.set_html('<h2>HJello</h2>')
web.view.set_html('<h2>HJello</h2>', { view = 3 }) -- Set html for view with id 3

web.view.run_js (js, opts)

Run js in a view

Parameters:

• js string HTML string
• opts ? RunJSOpts Options

Usage:

web.view.run_js('console.log(42)')
web.view.run_js('console.log(42)', { view = 3 }) -- Set html for view with id 3

web.view.reload (opts)

Relaod a given view

Parameters:

• opts ? ReloadOpts Options

Usage:

web.view.reload()
web.view.reload({ view = 3 }) -- Reload view with id 3

web.view.expose (name, action, opts)

Expose a lua function inside a view (Only works with decorations)

Parameters:

• name string Func name
• action fun(table):nil Action to call when function is invoked in view
• opts ExposeOpts? Options

Usage:

• web.view.expose('tabSelect', function(args)
    web.view.select(tonumber(args.view))
  end)

• -- In javascript
  _nullbrowser.rpc.tabSelect({ view: 5 })

web.view.open_devtools (view_id)

Open devtools window for the view

Parameters:

• view_id number Id of the view

Usage:

web.view.open_devtools() -- Open devtools window for current view
web.view.open_devtools(5) -- Open devtools window for view id 5

web.view.current_index ()

Get current view index

Returns:

number |nil index Current view index

Usage:

local index = web.view.current_index()

web.event.add_listener (events, opts)

Listen to events from the browser

Parameters:

• events string |table Event or events to listen to
• opts Options
  • callback fun(opts:any):nil Callback called when that event occurs

Usage:

web.event.add_listener('UrlChanged', {
  callback = function(opts)
    print(opts.url, opts.tab, opts.win)
  end,
})

set (key, value)

Set configuration options

Parameters:

• key string The name of the configuration
• value nil |string|boolean|number Configuration value

See also:

WebOpts

Usage:

web.set('new_view_url', 'https://duckduckgo.com')
-- Can also be written as
web.opts.new_view_url = 'https://duckduckgo.com'

get (key)

Get configuration value

Parameters:

• key string The name of the configuration

See also:

WebOpts

Usage:

local url = web.get('new_view_url')

web.history.back (count, view_id)

Go back in history for given view

Parameters:

• count number? Number of history items to go back in (default = 1)
• view_id number Id of the view

Usage:

web.history.back(2, 3) -- Go back 2 history items for view id 3

web.history.forward (count, view_id)

Go forward in history for given view

Parameters:

• count number? Number of history items to go forward in (default = 1)
• view_id number Id of the view

Usage:

web.history.forward(2, 3) -- Go forward 2 history items for view id 3

web.search.set_text (text, view_id)

Search text inside a view

Parameters:

• text string? Text to search
• view_id number Id of the view

Usage:

web.search.set_text('whatever') -- Search in current view
web.search.set_text('whatever', 5) -- Search in view id 5

web.search.reset (view_id)

Reset searched text in a view (Same as web.search.set_text(''))

Parameters:

• view_id number Id of the view

Usage:

web.search.reset() -- Reset search state for current view
web.search.reset(5) -- Reset search state for view id 5

web.search.get_text ()

Get the last searched text

Usage:

local text = web.search.get_text()

web.search.next (view_id)

Highlight next search term for the last searched text

Parameters:

• view_id number Id of the view

Usage:

web.search.next() -- Next search result in current view
web.search.next(5) -- Next search result in view id 5

web.search.previous (view_id)

Highlight previous search term for the last searched text

Parameters:

• view_id number Id of the view

Usage:

web.search.previous() -- Previous search result in current view
web.search.previous(5) -- Previous search result in view id 5

web.view.scroll (deltax, deltay, view_id)

TODO: Document

Parameters:

• deltax
• deltay
• view_id

web.view.scroll_to_top (view_id)

TODO: Document

Parameters:

• view_id

web.view.scroll_to_bottom (view_id)

TODO: Document

Parameters:

• view_id

web.help.get_items ()

Get a list of items for help

web.help.show (item, opts)

Open help docs for a given item

Parameters:

• item string
• opts
  • view number?

web.utils.string_trim (str)

Trim whitespace from start and end of a string

Parameters:

• str string

Returns:

string

web.utils.table_merge (tbl)

Merge multiple tables

Parameters:

• tbl table

Returns:

table

web.utils.table_keys (tbl)

Get keys of a table

Parameters:

• tbl table

Returns:

table

web.utils.equals (a, b)

Check if 2 values are deeply equal

Parameters:

• a any
• b any

Returns:

boolean

web.utils.table_contains (tbl, value)

Check if table contains given value

Parameters:

• tbl table
• value any

Returns:

boolean

Tables

WebOpts

Maps to values defined in ./src/Configuration.hpp

Fields:

• app_data_dir string (readonly) Directory where app data is stored
• close_window_when_no_views boolean If true, when the last tab in a window is closed, the window closes (default: true)
• config_dir string (readonly) Directory where app config is stored
• downloads_dir string Directory where downloaded files go
• new_view_url string URL used when view url is not specified (default: 'https://duckduckgo.com')
• permissions_persistance 'always'|'session'|'never' How to persist choices for permissions (default: 'always')
• user_agent string User agent sent by the browser

Fields

_G.__internals

Internal api (unstable)

opts

API for configuring browser options

See also:

WebOpts

Usage:

web.opts.new_view_url = 'https://duckduckgo.com'

uv

luv api (https://github.com/luvit/luv/blob/master/docs.md)

inspect

Returns human-readable string representation of Lua tables (https://github.com/kikito/inspect.lua)

• value any