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 (opts)	Close view
web.view.create (url)	Create a new view with a url
web.view.current ()	Get current view id
web.view.current_url ()	Get current url
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, opts)	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)	Reload a given view
web.view.expose (name, action, opts)	Expose a lua function inside a view (Only works with decorations)
web.view.open_devtools (opts)	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, opts)	Go back in history for given view
web.history.forward (count, opts)	Go forward in history for given view
web.search.set_text (text, opts)	Search text inside a view
web.search.reset (opts)	Reset searched text in a view (Same as web.search.set_text(''))
web.search.get_text ()	Get the last searched text
web.search.next (opts)	Highlight next search term for the last searched text
web.search.previous (opts)	Highlight previous search term for the last searched text
web.view.scroll (deltax, deltay, opts)	TODO: Document
web.view.scroll_to_top (opts)	TODO: Document
web.view.scroll_to_bottom (opts)	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
print (value)	Print a lua object to inspect
web.json.encode (obj, opts)	Encodes lua object as json into a string
web.json.decode (json_str, opts)	Decodes a string into a lua object
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
WebEvents	Events that can be listened to with web.events.add_listener
WinCreatedEventOpts
ViewCreatedEventOpts
ViewSelectedEventOpts
ViewClosedEventOpts
UrlChangedEventOpts
PermissionRequestedEventOpts
ModeChangedEventOpts
KeyPressedEventOpts
NotificationReceivedEventOpts

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 (opts)

Close view

Parameters:

• opts Options
  • view number? View id (default = 0)

Usage:

web.view.close()  -- Close current view in active window
web.view.close({ view = 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.current_url ()

Get current url

Returns:

string Current view url

Usage:

local url = web.view.current_url()

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, opts)

Set url of a given view

Parameters:

• url string Url to open
• opts Options
  • view number? View id (default = 0)

Usage:

web.view.set_url('https://foobar.com')
web.view.set_url('https://foobar.com', { view = 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 (default = 0)

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 JS string
• opts Options
  • view number? View id (default = 0)
  • on_result ? fun(v: any): nil Callback with serialized result of evaluation

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.run_js('2 * 3', {
  on_result = function(result)
    print(result * 7)
  end,
})

web.view.reload (opts)

Reload a given view

Parameters:

• opts Options
  • view number? View id (default = 0)

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 Options
  • view number? View id (default = 0)

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 (opts)

Open devtools window for the view

Parameters:

• opts Options
  • view number? View id (default = 0)

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

See also:

WebEvents

Usage:

web.event.add_listener('UrlChanged', {
  callback = function(opts)
    print(opts.url, opts.view, 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, opts)

Go back in history for given view

Parameters:

• count number? Number of history items to go back in (default = 1)
• opts Options
  • view number? View id (default = 0)

Usage:

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

web.history.forward (count, opts)

Go forward in history for given view

Parameters:

• count number? Number of history items to go forward in (default = 1)
• opts Options
  • view number? View id (default = 0)

Usage:

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

web.search.set_text (text, opts)

Search text inside a view

Parameters:

• text string? Text to search
• opts Options
  • view number? View id (default = 0)

Usage:

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

web.search.reset (opts)

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

Parameters:

• opts Options
  • view number? View id (default = 0)

Usage:

web.search.reset() -- Reset search state for current view
web.search.reset({ view = 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 (opts)

Highlight next search term for the last searched text

Parameters:

• opts Options
  • view number? View id (default = 0)

Usage:

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

web.search.previous (opts)

Highlight previous search term for the last searched text

Parameters:

• opts Options
  • view number? View id (default = 0)

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, opts)

TODO: Document

Parameters:

• deltax number
• deltay number
• opts Options
  • view number? View id (default = 0)

web.view.scroll_to_top (opts)

TODO: Document

Parameters:

• opts Options
  • view number? View id (default = 0)

web.view.scroll_to_bottom (opts)

TODO: Document

Parameters:

• opts Options
  • view number? View id (default = 0)

web.help.get_items ()

Get a list of items for help

Returns:

table help_items List of help item names

web.help.show (item, opts)

Open help docs for a given item

Parameters:

• item string Help item name
• opts Options
  • view number? View id (default = 0)

print (value)

Print a lua object to inspect

Parameters:

• value any

web.json.encode (obj, opts)

Encodes lua object as json into a string

Parameters:

• obj any Value to encode into json string
• opts Options
  • indent boolean? Whether to enable indentation (default: false)

Returns:

string

web.json.decode (json_str, opts)

Decodes a string into a lua object

Parameters:

• json_str string Json string to decode
• opts Options
  • null any? What to use as null value (default: nil)

Returns:

any

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')
• null_assets_dir string (readonly) Directory where null assets are installed
• null_docs_dir string (readonly) Directory where null docs are installed
• permissions_persistance 'always'|'session'|'never' How to persist choices for permissions (default: 'always')
• user_agent string User agent sent by the browser

WebEvents

Events that can be listened to with web.events.add_listener

See also:

• KeyPressedEventOpts
• ModeChangedEventOpts
• NotificationReceivedEventOpts
• PermissionRequestedEventOpts
• UrlChangedEventOpts
• ViewClosedEventOpts
• ViewCreatedEventOpts
• ViewSelectedEventOpts
• WinCreatedEventOpts
• web.event.add_listener

Usage:

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

WinCreatedEventOpts

Fields:

• type 'WinCreated'
• view integer
• win integer

ViewCreatedEventOpts

Fields:

• type 'ViewCreated'
• view integer
• win integer

ViewSelectedEventOpts

Fields:

• type 'ViewSelected'
• view integer
• win integer

ViewClosedEventOpts

Fields:

• type 'ViewClosed'
• view integer
• win integer

UrlChangedEventOpts

Fields:

• type 'UrlChanged'
• view_id integer
• win_id integer
• url string

PermissionRequestedEventOpts

Fields:

• type 'PermissionRequested'
• premission_type 'MediaAudioCapture' | 'MediaVideoCapture' | 'MediaAudioVideoCapture' | 'DesktopVideoCapture' | 'DesktopAudioVideoCapture' | 'MouseLock' | 'Notifications' | 'Geolocation' | 'ClipboardReadWrite' | 'LocalFontsAccess' | 'Unsupported'
• webview_id integer
• win_id integer
• accept fun():nil
• reject fun():nil

ModeChangedEventOpts

Fields:

• type 'ModeChanged'
• mode string

KeyPressedEventOpts

Fields:

• type 'KeyPressed'
• key string

NotificationReceivedEventOpts

Fields:

• type 'NotificationReceived'
• title string
• message string
• tag string
• origin string
• click fun():nil
• show fun():nil
• close fun():nil

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