diff options
| -rw-r--r-- | Makefile | 7 | ||||
| -rw-r--r-- | TODO.org | 7 | ||||
| -rw-r--r-- | doc/index.html | 1228 | ||||
| -rw-r--r-- | doc/ldoc.css | 304 | ||||
| -rw-r--r-- | flake.nix | 1 | ||||
| -rw-r--r-- | init.lua | 6 | ||||
| -rw-r--r-- | lua/null-browser/api.lua | 221 | ||||
| -rw-r--r-- | lua/null-browser/extras/tabline.lua | 3 | ||||
| -rw-r--r-- | lua/null-browser/utils.lua | 37 |
9 files changed, 1670 insertions, 144 deletions
@@ -1,4 +1,4 @@ -.PHONY: clean build build-release dev-setup build-dev install build-source test run check fmt +.PHONY: clean build build-release dev-setup build-dev install build-source test run check fmt docs all: build-dev @@ -45,6 +45,11 @@ fmt: check: fmt clang-tidy --config-file=.clang-tidy ./src/**/*.{hpp,cpp} +docs: + ldoc -p null-browser -t "Null browser api" \ + --merge --ignore --lls \ + ./lua/null-browser/ + # appimage: # nix bundle --bundler github:ralismark/nix-appimage @@ -12,11 +12,14 @@ - [X] Show number of tabs in statusline - [X] On finder stop, exit find mode - [X] Callback for result of run_js -- [ ] Generate docs for api +- [X] Generate docs for api +- [ ] Any hint action/generic (currently only url open) +- [ ] Document events and event opts - [ ] Embed docs in app (`null:/docs`) - [ ] Update all api to use opts table pattern - [ ] web.decorations.*.set_size() - [ ] web.keymap.configure_mode(modename, { passthrough = false }) +- [ ] Vertical tabline ui - [ ] Fullscreen - [ ] Zoom in/out/reset - [ ] Remove unwanted "async"-ness in lua calls @@ -31,6 +34,8 @@ - [ ] Managing focus in decorations? ** Next +- [ ] View focus event (between decorations/views) +- [ ] Element focus (input focus) - [ ] User scripts (greasemonkey?) - [ ] User stylesheets (per site and global?) - [ ] Log stdout, errors and results from lua somewhere diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..f357409 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,1228 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> +<head> + <title>Null browser api</title> + <link rel="stylesheet" href="ldoc.css" type="text/css" /> +</head> +<body> + +<div id="container"> + +<div id="product"> + <div id="product_logo"></div> + <div id="product_name"><big><b></b></big></div> + <div id="product_description"></div> +</div> <!-- id="product" --> + + +<div id="main"> + + +<!-- Menu --> + +<div id="navigation"> +<br/> +<h1>null-browser</h1> + + + +<h2>Contents</h2> +<ul> +<li><a href="#Functions">Functions</a></li> +<li><a href="#Tables">Tables</a></li> +<li><a href="#Fields">Fields</a></li> +</ul> + + +<h2>Modules</h2> +<ul class="nowrap"> + <li><strong>web</strong></li> +</ul> + +</div> + +<div id="content"> + +<h1>Module <code>web</code></h1> +<p></p> +<p></p> + + +<h2><a href="#Functions">Functions</a></h2> +<table class="function_list"> + <tr> + <td class="name" nowrap><a href="#schedule">schedule (fn)</a></td> + <td class="summary">Schedule a function to be called on next tick (qt+libuv event loop)</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.keymap.set">web.keymap.set (mode, key, action)</a></td> + <td class="summary">Add a keymap</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.keymap.set_mode">web.keymap.set_mode (mode)</a></td> + <td class="summary">Set the current keymap mode</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.keymap.get_mode">web.keymap.get_mode ()</a></td> + <td class="summary">Get the current keymap mode</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.close">web.view.close (view_id)</a></td> + <td class="summary">Close view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.create">web.view.create (url)</a></td> + <td class="summary">Create a new view with a url</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.current">web.view.current ()</a></td> + <td class="summary">Get current view id</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.list">web.view.list ()</a></td> + <td class="summary">Get a list of views in the current window</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.select">web.view.select (view_id)</a></td> + <td class="summary">Select a view in current window</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.set_url">web.view.set_url (url, view_id)</a></td> + <td class="summary">Set url of a given view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.set_html">web.view.set_html (html, opts)</a></td> + <td class="summary">Set html inside the page for a given view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.run_js">web.view.run_js (js, opts)</a></td> + <td class="summary">Run js in a view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.reload">web.view.reload (opts)</a></td> + <td class="summary">Relaod a given view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.expose">web.view.expose (name, action, opts)</a></td> + <td class="summary">Expose a lua function inside a view (Only works with decorations)</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.open_devtools">web.view.open_devtools (view_id)</a></td> + <td class="summary">Open devtools window for the view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.current_index">web.view.current_index ()</a></td> + <td class="summary">Get current view index</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.event.add_listener">web.event.add_listener (events, opts)</a></td> + <td class="summary">Listen to events from the browser</td> + </tr> + <tr> + <td class="name" nowrap><a href="#set">set (key, value)</a></td> + <td class="summary">Set configuration options</td> + </tr> + <tr> + <td class="name" nowrap><a href="#get">get (key)</a></td> + <td class="summary">Get configuration value</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.history.back">web.history.back (count, view_id)</a></td> + <td class="summary">Go back in history for given view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.history.forward">web.history.forward (count, view_id)</a></td> + <td class="summary">Go forward in history for given view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.search.set_text">web.search.set_text (text, view_id)</a></td> + <td class="summary">Search text inside a view</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.search.reset">web.search.reset (view_id)</a></td> + <td class="summary">Reset searched text in a view (Same as web.search.set_text(''))</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.search.get_text">web.search.get_text ()</a></td> + <td class="summary">Get the last searched text</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.search.next">web.search.next (view_id)</a></td> + <td class="summary">Highlight next search term for the last searched text</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.search.previous">web.search.previous (view_id)</a></td> + <td class="summary">Highlight previous search term for the last searched text</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.scroll">web.view.scroll (deltax, deltay, view_id)</a></td> + <td class="summary">TODO: Document</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.scroll_to_top">web.view.scroll_to_top (view_id)</a></td> + <td class="summary">TODO: Document</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.view.scroll_to_bottom">web.view.scroll_to_bottom (view_id)</a></td> + <td class="summary">TODO: Document</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.utils.string_trim">web.utils.string_trim (str)</a></td> + <td class="summary">Trim whitespace from start and end of a string</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.utils.table_merge">web.utils.table_merge (tbl)</a></td> + <td class="summary">Merge multiple tables</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.utils.table_keys">web.utils.table_keys (tbl)</a></td> + <td class="summary">Get keys of a table</td> + </tr> + <tr> + <td class="name" nowrap><a href="#web.utils.equals">web.utils.equals (a, b)</a></td> + <td class="summary">Check if 2 values are deeply equal</td> + </tr> +</table> +<h2><a href="#Tables">Tables</a></h2> +<table class="function_list"> + <tr> + <td class="name" nowrap><a href="#WebOpts">WebOpts</a></td> + <td class="summary">Maps to values defined in ./src/Configuration.hpp</td> + </tr> +</table> +<h2><a href="#Fields">Fields</a></h2> +<table class="function_list"> + <tr> + <td class="name" nowrap><a href="#_G.__internals">_G.__internals</a></td> + <td class="summary">Internal api (unstable)</td> + </tr> + <tr> + <td class="name" nowrap><a href="#opts">opts</a></td> + <td class="summary">API for configuring browser options</td> + </tr> + <tr> + <td class="name" nowrap><a href="#uv">uv</a></td> + <td class="summary">luv api (https://github.com/luvit/luv/blob/master/docs.md)</td> + </tr> + <tr> + <td class="name" nowrap><a href="#inspect">inspect</a></td> + <td class="summary">Returns human-readable string representation of Lua tables (https://github.com/kikito/inspect.lua)</td> + </tr> +</table> + +<br/> +<br/> + + + <h2 class="section-header "><a name="Functions"></a>Functions</h2> + + <dl class="function"> + <dt> + <a name = "schedule"></a> + <strong>schedule (fn)</strong> + </dt> + <dd> + Schedule a function to be called on next tick (qt+libuv event loop) + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">fn</span> + <span class="types"><span class="type">fun</span></span> + ():nil Function to call + </li> + </ul> + + + + + +</dd> + <dt> + <a name = "web.keymap.set"></a> + <strong>web.keymap.set (mode, key, action)</strong> + </dt> + <dd> + Add a keymap + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">mode</span> + string Keymap mode ("i", "n", ...) + </li> + <li><span class="parameter">key</span> + string Key sequence (Eg: `<c-t>j`) + </li> + <li><span class="parameter">action</span> + <span class="types"><span class="type">function</span></span> + Function to run when keymap is triggered + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.keymap.<span class="function-name">set</span>(<span class="string">'n'</span>, <span class="string">'o'</span>, <span class="keyword">function</span>() + web.view.<span class="function-name">create</span>(<span class="string">'https://google.com'</span>) +<span class="keyword">end</span>)</pre> + </ul> + +</dd> + <dt> + <a name = "web.keymap.set_mode"></a> + <strong>web.keymap.set_mode (mode)</strong> + </dt> + <dd> + Set the current keymap mode + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">mode</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> + The keymap mode to set + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.keymap.<span class="function-name">set_mode</span>(<span class="string">'n'</span>) <span class="comment">-- Set to normal mode +</span>web.keymap.<span class="function-name">set_mode</span>(<span class="string">'i'</span>) <span class="comment">-- Set to insert mode</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.keymap.get_mode"></a> + <strong>web.keymap.get_mode ()</strong> + </dt> + <dd> + Get the current keymap mode + + + + + + + <h3>Usage:</h3> + <ul> + <pre class="example"><span class="keyword">local</span> current_mode = web.keymap.<span class="function-name">get_mode</span>()</pre> + </ul> + +</dd> + <dt> + <a name = "web.view.close"></a> + <strong>web.view.close (view_id)</strong> + </dt> + <dd> + Close view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">view_id</span> + ? number View id to close + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.view.<span class="function-name">close</span>() <span class="comment">-- Close current view in active window +</span>web.view.<span class="function-name">close</span>(<span class="number">3</span>) <span class="comment">-- Close view with id 3</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.create"></a> + <strong>web.view.create (url)</strong> + </dt> + <dd> + Create a new view with a url + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">url</span> + string Url to open in the new view + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.view.<span class="function-name">create</span>(<span class="string">'https://duckduckgo.com'</span>) <span class="comment">-- Opens url in new view +</span>web.view.<span class="function-name">create</span>() <span class="comment">-- Opens new_view_url by default</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.current"></a> + <strong>web.view.current ()</strong> + </dt> + <dd> + Get current view id + + + + <h3>Returns:</h3> + <ol> + + <span class="types"><span class="type">number</span></span> + _id Current view id + </ol> + + + + <h3>Usage:</h3> + <ul> + <pre class="example"><span class="keyword">local</span> view_id = web.view.<span class="function-name">current</span>()</pre> + </ul> + +</dd> + <dt> + <a name = "web.view.list"></a> + <strong>web.view.list ()</strong> + </dt> + <dd> + Get a list of views in the current window + + + + <h3>Returns:</h3> + <ol> + + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span> + List of views + </ol> + + + + <h3>Usage:</h3> + <ul> + <pre class="example"><span class="keyword">local</span> views = web.view.<span class="function-name">list</span>() +<span class="global">print</span>(views[<span class="number">1</span>].url, views[<span class="number">1</span>].title, views[<span class="number">1</span>].id)</pre> + </ul> + +</dd> + <dt> + <a name = "web.view.select"></a> + <strong>web.view.select (view_id)</strong> + </dt> + <dd> + Select a view in current window + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + View id to select + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.view.<span class="global">select</span>(<span class="number">3</span>) <span class="comment">-- Select view with id 3</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.set_url"></a> + <strong>web.view.set_url (url, view_id)</strong> + </dt> + <dd> + Set url of a given view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">url</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> + Url to open + </li> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + View id to select + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.view.<span class="function-name">set_url</span>(<span class="string">'https://foobar.com'</span>) +web.view.<span class="function-name">set_url</span>(<span class="string">'https://foobar.com'</span>, <span class="number">3</span>) <span class="comment">-- Set url for view with id 3</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.set_html"></a> + <strong>web.view.set_html (html, opts)</strong> + </dt> + <dd> + Set html inside the page for a given view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">html</span> + string HTML string + </li> + <li><span class="parameter">opts</span> table Options + <ul> + <li><span class="parameter">view</span> + number View id + </li> + </li></ul> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.view.<span class="function-name">set_html</span>(<span class="string">'<h2>HJello</h2>'</span>) +web.view.<span class="function-name">set_html</span>(<span class="string">'<h2>HJello</h2>'</span>, { view = <span class="number">3</span> }) <span class="comment">-- Set html for view with id 3</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.run_js"></a> + <strong>web.view.run_js (js, opts)</strong> + </dt> + <dd> + Run js in a view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">js</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> + HTML string + </li> + <li><span class="parameter">opts</span> + ? RunJSOpts Options + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.view.<span class="function-name">run_js</span>(<span class="string">'console.log(42)'</span>) +web.view.<span class="function-name">run_js</span>(<span class="string">'console.log(42)'</span>, { view = <span class="number">3</span> }) <span class="comment">-- Set html for view with id 3</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.reload"></a> + <strong>web.view.reload (opts)</strong> + </dt> + <dd> + Relaod a given view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">opts</span> + ? ReloadOpts Options + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.view.<span class="function-name">reload</span>() +web.view.<span class="function-name">reload</span>({ view = <span class="number">3</span> }) <span class="comment">-- Reload view with id 3</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.expose"></a> + <strong>web.view.expose (name, action, opts)</strong> + </dt> + <dd> + Expose a lua function inside a view (Only works with decorations) + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">name</span> + string Func name + </li> + <li><span class="parameter">action</span> + fun(table):nil Action to call when function is invoked in view + </li> + <li><span class="parameter">opts</span> + ExposeOpts? Options + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <li><pre class="example">web.view.<span class="function-name">expose</span>(<span class="string">'tabSelect'</span>, <span class="keyword">function</span>(args) + web.view.<span class="global">select</span>(<span class="global">tonumber</span>(args.view)) +<span class="keyword">end</span>)</pre></li> + <li><pre class="example"><span class="comment">-- In javascript +</span>_nullbrowser.rpc.<span class="function-name">tabSelect</span>({ view: <span class="number">5</span> })</pre></li> + </ul> + +</dd> + <dt> + <a name = "web.view.open_devtools"></a> + <strong>web.view.open_devtools (view_id)</strong> + </dt> + <dd> + Open devtools window for the view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + Id of the view + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.view.<span class="function-name">open_devtools</span>() <span class="comment">-- Open devtools window for current view +</span>web.view.<span class="function-name">open_devtools</span>(<span class="number">5</span>) <span class="comment">-- Open devtools window for view id 5</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.current_index"></a> + <strong>web.view.current_index ()</strong> + </dt> + <dd> + Get current view index + + + + <h3>Returns:</h3> + <ol> + + <span class="types"><span class="type">number</span></span> + |nil index Current view index + </ol> + + + + <h3>Usage:</h3> + <ul> + <pre class="example"><span class="keyword">local</span> index = web.view.<span class="function-name">current_index</span>()</pre> + </ul> + +</dd> + <dt> + <a name = "web.event.add_listener"></a> + <strong>web.event.add_listener (events, opts)</strong> + </dt> + <dd> + Listen to events from the browser + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">events</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> + |table Event or events to listen to + </li> + <li><span class="parameter">opts</span> Options + <ul> + <li><span class="parameter">callback</span> + fun(opts:any):nil Callback called when that event occurs + </li> + </li></ul> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.event.<span class="function-name">add_listener</span>(<span class="string">'UrlChanged'</span>, { + callback = <span class="keyword">function</span>(opts) + <span class="global">print</span>(opts.url, opts.tab, opts.win) + <span class="keyword">end</span>, +})</pre> + </ul> + +</dd> + <dt> + <a name = "set"></a> + <strong>set (key, value)</strong> + </dt> + <dd> + Set configuration options + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">key</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> + The name of the configuration + </li> + <li><span class="parameter">value</span> + <span class="types"><span class="type">nil</span></span> + |string|boolean|number Configuration value + </li> + </ul> + + + + <h3>See also:</h3> + <ul> + <a href="index.html#WebOpts">WebOpts</a> + </ul> + + <h3>Usage:</h3> + <ul> + <pre class="example">web.<span class="function-name">set</span>(<span class="string">'new_view_url'</span>, <span class="string">'https://duckduckgo.com'</span>) +<span class="comment">-- Can also be written as +</span>web.opts.new_view_url = <span class="string">'https://duckduckgo.com'</span></pre> + </ul> + +</dd> + <dt> + <a name = "get"></a> + <strong>get (key)</strong> + </dt> + <dd> + Get configuration value + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">key</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> + The name of the configuration + </li> + </ul> + + + + <h3>See also:</h3> + <ul> + <a href="index.html#WebOpts">WebOpts</a> + </ul> + + <h3>Usage:</h3> + <ul> + <pre class="example"><span class="keyword">local</span> url = web.<span class="function-name">get</span>(<span class="string">'new_view_url'</span>)</pre> + </ul> + +</dd> + <dt> + <a name = "web.history.back"></a> + <strong>web.history.back (count, view_id)</strong> + </dt> + <dd> + Go back in history for given view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">count</span> + number? Number of history items to go back in (default = 1) + </li> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + Id of the view + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.history.<span class="function-name">back</span>(<span class="number">2</span>, <span class="number">3</span>) <span class="comment">-- Go back 2 history items for view id 3</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.history.forward"></a> + <strong>web.history.forward (count, view_id)</strong> + </dt> + <dd> + Go forward in history for given view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">count</span> + number? Number of history items to go forward in (default = 1) + </li> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + Id of the view + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.history.<span class="function-name">forward</span>(<span class="number">2</span>, <span class="number">3</span>) <span class="comment">-- Go forward 2 history items for view id 3</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.search.set_text"></a> + <strong>web.search.set_text (text, view_id)</strong> + </dt> + <dd> + Search text inside a view + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">text</span> + string? Text to search + </li> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + Id of the view + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.search.<span class="function-name">set_text</span>(<span class="string">'whatever'</span>) <span class="comment">-- Search in current view +</span>web.search.<span class="function-name">set_text</span>(<span class="string">'whatever'</span>, <span class="number">5</span>) <span class="comment">-- Search in view id 5</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.search.reset"></a> + <strong>web.search.reset (view_id)</strong> + </dt> + <dd> + Reset searched text in a view (Same as web.search.set_text('')) + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + Id of the view + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.search.<span class="function-name">reset</span>() <span class="comment">-- Reset search state for current view +</span>web.search.<span class="function-name">reset</span>(<span class="number">5</span>) <span class="comment">-- Reset search state for view id 5</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.search.get_text"></a> + <strong>web.search.get_text ()</strong> + </dt> + <dd> + Get the last searched text + + + + + + + <h3>Usage:</h3> + <ul> + <pre class="example"><span class="keyword">local</span> text = web.search.<span class="function-name">get_text</span>()</pre> + </ul> + +</dd> + <dt> + <a name = "web.search.next"></a> + <strong>web.search.next (view_id)</strong> + </dt> + <dd> + Highlight next search term for the last searched text + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + Id of the view + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.search.<span class="global">next</span>() <span class="comment">-- Next search result in current view +</span>web.search.<span class="global">next</span>(<span class="number">5</span>) <span class="comment">-- Next search result in view id 5</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.search.previous"></a> + <strong>web.search.previous (view_id)</strong> + </dt> + <dd> + Highlight previous search term for the last searched text + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">view_id</span> + <span class="types"><span class="type">number</span></span> + Id of the view + </li> + </ul> + + + + + <h3>Usage:</h3> + <ul> + <pre class="example">web.search.<span class="function-name">previous</span>() <span class="comment">-- Previous search result in current view +</span>web.search.<span class="function-name">previous</span>(<span class="number">5</span>) <span class="comment">-- Previous search result in view id 5</span></pre> + </ul> + +</dd> + <dt> + <a name = "web.view.scroll"></a> + <strong>web.view.scroll (deltax, deltay, view_id)</strong> + </dt> + <dd> + TODO: Document + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">deltax</span> + + </li> + <li><span class="parameter">deltay</span> + + </li> + <li><span class="parameter">view_id</span> + + </li> + </ul> + + + + + +</dd> + <dt> + <a name = "web.view.scroll_to_top"></a> + <strong>web.view.scroll_to_top (view_id)</strong> + </dt> + <dd> + TODO: Document + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">view_id</span> + + </li> + </ul> + + + + + +</dd> + <dt> + <a name = "web.view.scroll_to_bottom"></a> + <strong>web.view.scroll_to_bottom (view_id)</strong> + </dt> + <dd> + TODO: Document + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">view_id</span> + + </li> + </ul> + + + + + +</dd> + <dt> + <a name = "web.utils.string_trim"></a> + <strong>web.utils.string_trim (str)</strong> + </dt> + <dd> + Trim whitespace from start and end of a string + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">str</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> + + </li> + </ul> + + <h3>Returns:</h3> + <ol> + + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> + + </ol> + + + + +</dd> + <dt> + <a name = "web.utils.table_merge"></a> + <strong>web.utils.table_merge (tbl)</strong> + </dt> + <dd> + Merge multiple tables + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">tbl</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span> + + </li> + </ul> + + <h3>Returns:</h3> + <ol> + + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span> + + </ol> + + + + +</dd> + <dt> + <a name = "web.utils.table_keys"></a> + <strong>web.utils.table_keys (tbl)</strong> + </dt> + <dd> + Get keys of a table + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">tbl</span> + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span> + + </li> + </ul> + + <h3>Returns:</h3> + <ol> + + <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span> + + </ol> + + + + +</dd> + <dt> + <a name = "web.utils.equals"></a> + <strong>web.utils.equals (a, b)</strong> + </dt> + <dd> + Check if 2 values are deeply equal + + + <h3>Parameters:</h3> + <ul> + <li><span class="parameter">a</span> + <span class="types"><span class="type">any</span></span> + + </li> + <li><span class="parameter">b</span> + <span class="types"><span class="type">any</span></span> + + </li> + </ul> + + <h3>Returns:</h3> + <ol> + + <span class="types"><span class="type">boolean</span></span> + + </ol> + + + + +</dd> +</dl> + <h2 class="section-header "><a name="Tables"></a>Tables</h2> + + <dl class="function"> + <dt> + <a name = "WebOpts"></a> + <strong>WebOpts</strong> + </dt> + <dd> + Maps to values defined in ./src/Configuration.hpp + + + <h3>Fields:</h3> + <ul> + <li><span class="parameter">app_data_dir</span> + string (readonly) Directory where app data is stored + </li> + <li><span class="parameter">close_window_when_no_views</span> + boolean If true, when the last tab in a window is closed, the window closes (default: true) + </li> + <li><span class="parameter">config_dir</span> + string (readonly) Directory where app config is stored + </li> + <li><span class="parameter">downloads_dir</span> + string Directory where downloaded files go + </li> + <li><span class="parameter">new_view_url</span> + string URL used when view url is not specified (default: 'https://duckduckgo.com') + </li> + <li><span class="parameter">permissions_persistance</span> + 'always'|'session'|'never' How to persist choices for permissions (default: 'always') + </li> + <li><span class="parameter">user_agent</span> + string User agent sent by the browser + </li> + </ul> + + + + + +</dd> +</dl> + <h2 class="section-header "><a name="Fields"></a>Fields</h2> + + <dl class="function"> + <dt> + <a name = "_G.__internals"></a> + <strong>_G.__internals</strong> + </dt> + <dd> + Internal api (unstable) + + + + + + + +</dd> + <dt> + <a name = "opts"></a> + <strong>opts</strong> + </dt> + <dd> + API for configuring browser options + + + + + + <h3>See also:</h3> + <ul> + <a href="index.html#WebOpts">WebOpts</a> + </ul> + + <h3>Usage:</h3> + <ul> + <pre class="example">web.opts.new_view_url = <span class="string">'https://duckduckgo.com'</span></pre> + </ul> + +</dd> + <dt> + <a name = "uv"></a> + <strong>uv</strong> + </dt> + <dd> + luv api (https://github.com/luvit/luv/blob/master/docs.md) + + + + + + + +</dd> + <dt> + <a name = "inspect"></a> + <strong>inspect</strong> + </dt> + <dd> + Returns human-readable string representation of Lua tables (https://github.com/kikito/inspect.lua) + + + <ul> + <li><span class="parameter">value</span> + <span class="types"><span class="type">any</span></span> + + </li> + </ul> + + + + + +</dd> +</dl> + + +</div> <!-- id="content" --> +</div> <!-- id="main" --> +<div id="about"> +<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> +<i style="float:right;">Last updated 1980-01-01 00:00:00 </i> +</div> <!-- id="about" --> +</div> <!-- id="container" --> +</body> +</html> diff --git a/doc/ldoc.css b/doc/ldoc.css new file mode 100644 index 0000000..f945ae7 --- /dev/null +++ b/doc/ldoc.css @@ -0,0 +1,304 @@ +/* BEGIN RESET + +Copyright (c) 2010, Yahoo! Inc. All rights reserved. +Code licensed under the BSD License: +http://developer.yahoo.com/yui/license.html +version: 2.8.2r1 +*/ +html { + color: #000; + background: #FFF; +} +body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td { + margin: 0; + padding: 0; +} +table { + border-collapse: collapse; + border-spacing: 0; +} +fieldset,img { + border: 0; +} +address,caption,cite,code,dfn,em,strong,th,var,optgroup { + font-style: inherit; + font-weight: inherit; +} +del,ins { + text-decoration: none; +} +li { + margin-left: 20px; +} +caption,th { + text-align: left; +} +h1,h2,h3,h4,h5,h6 { + font-size: 100%; + font-weight: bold; +} +q:before,q:after { + content: ''; +} +abbr,acronym { + border: 0; + font-variant: normal; +} +sup { + vertical-align: baseline; +} +sub { + vertical-align: baseline; +} +legend { + color: #000; +} +input,button,textarea,select,optgroup,option { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; +} +input,button,textarea,select {*font-size:100%; +} +/* END RESET */ + +body { + margin-left: 1em; + margin-right: 1em; + font-family: arial, helvetica, geneva, sans-serif; + background-color: #ffffff; margin: 0px; +} + +code, tt { font-family: monospace; font-size: 1.1em; } +span.parameter { font-family:monospace; } +span.parameter:after { content:":"; } +span.types:before { content:"("; } +span.types:after { content:")"; } +.type { font-weight: bold; font-style:italic } + +body, p, td, th { font-size: .95em; line-height: 1.2em;} + +p, ul { margin: 10px 0 0 0px;} + +strong { font-weight: bold;} + +em { font-style: italic;} + +h1 { + font-size: 1.5em; + margin: 20px 0 20px 0; +} +h2, h3, h4 { margin: 15px 0 10px 0; } +h2 { font-size: 1.25em; } +h3 { font-size: 1.15em; } +h4 { font-size: 1.06em; } + +a:link { font-weight: bold; color: #004080; text-decoration: none; } +a:visited { font-weight: bold; color: #006699; text-decoration: none; } +a:link:hover { text-decoration: underline; } + +hr { + color:#cccccc; + background: #00007f; + height: 1px; +} + +blockquote { margin-left: 3em; } + +ul { list-style-type: disc; } + +p.name { + font-family: "Andale Mono", monospace; + padding-top: 1em; +} + +pre { + background-color: rgb(245, 245, 245); + border: 1px solid #C0C0C0; /* silver */ + padding: 10px; + margin: 10px 0 10px 0; + overflow: auto; + font-family: "Andale Mono", monospace; +} + +pre.example { + font-size: .85em; +} + +table.index { border: 1px #00007f; } +table.index td { text-align: left; vertical-align: top; } + +#container { + margin-left: 1em; + margin-right: 1em; + background-color: #f0f0f0; +} + +#product { + text-align: center; + border-bottom: 1px solid #cccccc; + background-color: #ffffff; +} + +#product big { + font-size: 2em; +} + +#main { + background-color: #f0f0f0; + border-left: 2px solid #cccccc; +} + +#navigation { + float: left; + width: 14em; + vertical-align: top; + background-color: #f0f0f0; + overflow: visible; +} + +#navigation h2 { + background-color:#e7e7e7; + font-size:1.1em; + color:#000000; + text-align: left; + padding:0.2em; + border-top:1px solid #dddddd; + border-bottom:1px solid #dddddd; +} + +#navigation ul +{ + font-size:1em; + list-style-type: none; + margin: 1px 1px 10px 1px; +} + +#navigation li { + text-indent: -1em; + display: block; + margin: 3px 0px 0px 22px; +} + +#navigation li li a { + margin: 0px 3px 0px -1em; +} + +#content { + margin-left: 14em; + padding: 1em; + width: 700px; + border-left: 2px solid #cccccc; + border-right: 2px solid #cccccc; + background-color: #ffffff; +} + +#about { + clear: both; + padding: 5px; + border-top: 2px solid #cccccc; + background-color: #ffffff; +} + +@media print { + body { + font: 12pt "Times New Roman", "TimeNR", Times, serif; + } + a { font-weight: bold; color: #004080; text-decoration: underline; } + + #main { + background-color: #ffffff; + border-left: 0px; + } + + #container { + margin-left: 2%; + margin-right: 2%; + background-color: #ffffff; + } + + #content { + padding: 1em; + background-color: #ffffff; + } + + #navigation { + display: none; + } + pre.example { + font-family: "Andale Mono", monospace; + font-size: 10pt; + page-break-inside: avoid; + } +} + +table.module_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.module_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.module_list td.name { background-color: #f0f0f0; min-width: 200px; } +table.module_list td.summary { width: 100%; } + + +table.function_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.function_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.function_list td.name { background-color: #f0f0f0; min-width: 200px; } +table.function_list td.summary { width: 100%; } + +ul.nowrap { + overflow:auto; + white-space:nowrap; +} + +dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;} +dl.table h3, dl.function h3 {font-size: .95em;} + +/* stop sublists from having initial vertical space */ +ul ul { margin-top: 0px; } +ol ul { margin-top: 0px; } +ol ol { margin-top: 0px; } +ul ol { margin-top: 0px; } + +/* make the target distinct; helps when we're navigating to a function */ +a:target + * { + background-color: #FF9; +} + + +/* styles for prettification of source */ +pre .comment { color: #558817; } +pre .constant { color: #a8660d; } +pre .escape { color: #844631; } +pre .keyword { color: #aa5050; font-weight: bold; } +pre .library { color: #0e7c6b; } +pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; } +pre .string { color: #8080ff; } +pre .number { color: #f8660d; } +pre .function-name { color: #60447f; } +pre .operator { color: #2239a8; font-weight: bold; } +pre .preprocessor, pre .prepro { color: #a33243; } +pre .global { color: #800080; } +pre .user-keyword { color: #800080; } +pre .prompt { color: #558817; } +pre .url { color: #272fc2; text-decoration: underline; } + @@ -43,6 +43,7 @@ gdb valgrind go-grip + luajitPackages.ldoc ] ++ dependencies; LD_LIBRARY_PATH = "${pkgs.lib.makeLibraryPath buildInputs}"; @@ -14,7 +14,7 @@ local search_engines = require 'null-browser.extras.search-engines' search_engines.urls['ld'] = 'https://lite.duckduckgo.com/?q={}' search_engines.urls['g'] = 'https://github.com/{}' search_engines.urls['y'] = 'https://youtube.com/results?search_query={}' -search_engines.urls['r'] = 'https://reddit.com/{}' +search_engines.urls['r'] = 'https://reddit.com/r/{}' local Dmenu = require 'null-browser.extras.dmenu' local menu = Dmenu:new { @@ -55,7 +55,9 @@ web.event.add_listener('NotificationReceived', { }) -- Tabline -require 'null-browser.extras.tabline'.init() +require 'null-browser.extras.tabline'.init { + decoration = web.decorations.top, +} -- Statusline require 'null-browser.extras.statusline'.init { diff --git a/lua/null-browser/api.lua b/lua/null-browser/api.lua index e1f2acc..6d6f974 100644 --- a/lua/null-browser/api.lua +++ b/lua/null-browser/api.lua @@ -1,8 +1,10 @@ ---- Internal api (unstable) ---- @type table -__internals = __internals +---@diagnostic disable: doc-field-no-class, undefined-doc-param +--- Lua api for configuring null browser. +--- @module web + ---- @type table +--- Internal api (unstable) +_G.__internals = _G.__internals _G.web = _G.web or {} web.search = web.search or {} web.keymap = web.keymap or {} @@ -13,7 +15,9 @@ web.decorations = web.decorations or {} require 'null-browser.utils' ---- @param fn fun(): nil Schedule a function to be called on next tick (qt+libuv event loop) +--- Schedule a function to be called on next tick (qt+libuv event loop) +--- +--- @param fn fun():nil Function to call function web.schedule(fn) __internals.schedule(fn) end --- Add a keymap @@ -22,111 +26,89 @@ function web.schedule(fn) __internals.schedule(fn) end --- @param key string Key sequence (Eg: `<c-t>j`) --- @param action function Function to run when keymap is triggered --- ---- @example ---- ```lua +--- @usage --- web.keymap.set('n', 'o', function() --- web.view.create('https://google.com') --- end) ---- ``` function web.keymap.set(mode, key, action) return __internals.keymap_set(mode, key, action) end --- Set the current keymap mode --- --- @param mode string The keymap mode to set --- ---- @example ---- ```lua +--- @usage --- web.keymap.set_mode('n') -- Set to normal mode --- web.keymap.set_mode('i') -- Set to insert mode ---- ``` function web.keymap.set_mode(mode) return __internals.keymap_set_mode(mode) end --- Get the current keymap mode --- ---- @example ---- ```lua +--- @usage --- local current_mode = web.keymap.get_mode() ---- ``` function web.keymap.get_mode() return __internals.keymap_get_mode() end --- Close view --- --- @param view_id? number View id to close --- ---- @example ---- ```lua +--- @usage --- web.view.close() -- Close current view in active window --- web.view.close(3) -- Close view with id 3 ---- ``` function web.view.close(view_id) return __internals.view_close(view_id) end --- Create a new view with a url --- --- @param url string Url to open in the new view --- ---- @example ---- ```lua +--- @usage --- web.view.create('https://duckduckgo.com') -- Opens url in new view --- web.view.create() -- Opens new_view_url by default ---- ``` function web.view.create(url) return __internals.view_create(url) end --- Get current view id --- --- @return number view_id Current view id --- ---- @example ---- ```lua +--- @usage --- local view_id = web.view.current() ---- ``` function web.view.current() return __internals.view_current() end --- Get a list of views in the current window --- --- @return table views List of views --- ---- @example ---- ```lua +--- @usage --- local views = web.view.list() --- print(views[1].url, views[1].title, views[1].id) ---- ``` function web.view.list() return __internals.view_list() end --- Select a view in current window --- --- @param view_id number View id to select --- ---- @example ---- ```lua +--- @usage --- web.view.select(3) -- Select view with id 3 ---- ``` function web.view.select(view_id) return __internals.view_select(view_id) end --- Set url of a given view --- --- @param url string Url to open ---- @param view_id? number View id to select +--- @param view_id number? View id to select --- ---- @example ---- ```lua +--- @usage --- web.view.set_url('https://foobar.com') --- web.view.set_url('https://foobar.com', 3) -- Set url for view with id 3 ---- ``` function web.view.set_url(url, view_id) return __internals.view_set_url(url, view_id) end ---- @class SetHTMLOpts ---- @field view? number View id - ---- Set html in a given view +--- Set html inside the page for a given view --- ---- @param html string HTML string ---- @param opts? SetHTMLOpts Options +--- @param html string HTML string +--- @param opts table Options +--- @param opts.view number View id --- ---- @example ---- ```lua +--- @usage --- web.view.set_html('<h2>HJello</h2>') --- web.view.set_html('<h2>HJello</h2>', { view = 3 }) -- Set html for view with id 3 ---- ``` function web.view.set_html(html, opts) return __internals.view_set_html(html, (opts or {}).view) end --- @class RunJSOpts @@ -138,11 +120,9 @@ function web.view.set_html(html, opts) return __internals.view_set_html(html, (o --- @param js string HTML string --- @param opts? RunJSOpts Options --- ---- @example ---- ```lua +--- @usage --- web.view.run_js('console.log(42)') --- web.view.run_js('console.log(42)', { view = 3 }) -- Set html for view with id 3 ---- ``` function web.view.run_js(js, opts) return __internals.view_run_js(js, opts or {}) end --- @class ReloadOpts @@ -150,13 +130,11 @@ function web.view.run_js(js, opts) return __internals.view_run_js(js, opts or {} --- Relaod a given view --- ---- @param opts? RunJSOpts Options +--- @param opts? ReloadOpts Options --- ---- @example ---- ```lua +--- @usage --- web.view.reload() --- web.view.reload({ view = 3 }) -- Reload view with id 3 ---- ``` function web.view.reload(opts) return __internals.view_reload((opts or {}).view) end --- @class ExposeOpts @@ -164,41 +142,35 @@ function web.view.reload(opts) return __internals.view_reload((opts or {}).view) --- Expose a lua function inside a view (Only works with decorations) --- ---- @param name string Func name ---- @param action fun(table):nil Action to call when function is invoked in view ---- @param opts? ExposeOpts Options +--- @param name string Func name +--- @param action fun(table):nil Action to call when function is invoked in view +--- @param opts ExposeOpts? Options --- ---- @example ---- ```lua ---- web.view.expose('tab_select', function(args) +--- @usage +--- web.view.expose('tabSelect', function(args) --- web.view.select(tonumber(args.view)) --- end) ---- ``` ---- then in js ---- ```js ---- _nullbrowser.rpc.tab_select({ view: 5 }) ---- ``` +--- +--- @usage +--- -- In javascript +--- _nullbrowser.rpc.tabSelect({ view: 5 }) function web.view.expose(name, action, opts) return __internals.view_expose(name, action, (opts or {}).view) end --- Open devtools window for the view --- ---- @param view_id? number Id of the view +--- @param view_id number? Id of the view --- ---- @example ---- ```lua +--- @usage --- web.view.open_devtools() -- Open devtools window for current view --- web.view.open_devtools(5) -- Open devtools window for view id 5 ---- ``` function web.view.open_devtools(view_id) return __internals.view_open_devtools(view_id) end --- Get current view index --- --- @return number|nil index Current view index --- ---- @example ---- ```lua +--- @usage --- local index = web.view.current_index() ---- ``` function web.view.current_index() local current_view = web.view.current(); for index, view in ipairs(web.view.list()) do @@ -210,21 +182,16 @@ function web.view.current_index() end --- Listen to events from the browser +--- @param events string|table Event or events to listen to +--- @param opts table Options +--- @param opts.callback fun(opts:any):nil Callback called when that event occurs --- ---- @class nullb.EventListenerOptions ---- @field callback any Callback called when that event occurs ---- ---- @param events string|table Event or events to listen to ---- @param opts nullb.EventListenerOptions Options ---- ---- @example ---- ```lua +--- @usage --- web.event.add_listener('UrlChanged', { --- callback = function(opts) --- print(opts.url, opts.tab, opts.win) --- end, --- }) ---- ``` function web.event.add_listener(events, opts) opts = web.utils.table_merge({}, opts or {}) if type(events) == "string" then events = { events } end @@ -234,17 +201,41 @@ function web.event.add_listener(events, opts) end --- Set configuration options +--- @see WebOpts --- --- @param key string The name of the configuration --- @param value nil|string|boolean|number Configuration value --- ---- @example ---- ```lua +--- @usage --- web.set('new_view_url', 'https://duckduckgo.com') ---- ``` +--- -- Can also be written as +--- web.opts.new_view_url = 'https://duckduckgo.com' function web.set(key, value) __internals.config_set(key, value) end ---- Web options. Calls web.set/web.get for options +--- Get configuration value +--- @see WebOpts +--- +--- @param key string The name of the configuration +--- +--- @usage +--- local url = web.get('new_view_url') +function web.get(key) return __internals.config_get(key) end + +--- Maps to values defined in ./src/Configuration.hpp +--- @table WebOpts +--- @field app_data_dir string (readonly) Directory where app data is stored +--- @field close_window_when_no_views boolean If true, when the last tab in a window is closed, the window closes (default: true) +--- @field config_dir string (readonly) Directory where app config is stored +--- @field downloads_dir string Directory where downloaded files go +--- @field new_view_url string URL used when view url is not specified (default: 'https://duckduckgo.com') +--- @field permissions_persistance 'always'|'session'|'never' How to persist choices for permissions (default: 'always') +--- @field user_agent string User agent sent by the browser + +--- API for configuring browser options +--- @see WebOpts +--- +--- @usage +--- web.opts.new_view_url = 'https://duckduckgo.com' web.opts = setmetatable({}, { __index = function(_, key) return web.get(key) @@ -254,89 +245,65 @@ web.opts = setmetatable({}, { end, }) ---- Get configuration value ---- ---- @param key string The name of the configuration ---- ---- @example ---- ```lua ---- local url = web.get('new_view_url') ---- ``` -function web.get(key) return __internals.config_get(key) end - --- Go back in history for given view --- ---- @param count? number Number of history items to go back in (default = 1) ---- @param view_id? number Id of the view +--- @param count number? Number of history items to go back in (default = 1) +--- @param view_id number? Id of the view --- ---- @example ---- ```lua +--- @usage --- web.history.back(2, 3) -- Go back 2 history items for view id 3 ---- ``` function web.history.back(count, view_id) return __internals.history_back(count, view_id) end --- Go forward in history for given view --- ---- @param count? number Number of history items to go forward in (default = 1) ---- @param view_id? number Id of the view +--- @param count number? Number of history items to go forward in (default = 1) +--- @param view_id number? Id of the view --- ---- @example ---- ```lua +--- @usage --- web.history.forward(2, 3) -- Go forward 2 history items for view id 3 ---- ``` function web.history.forward(count, view_id) return __internals.history_forward(count, view_id) end --- Search text inside a view --- ---- @param text string Text to search ---- @param view_id? number Id of the view +--- @param text string? Text to search +--- @param view_id number? Id of the view --- ---- @example ---- ```lua +--- @usage --- web.search.set_text('whatever') -- Search in current view --- web.search.set_text('whatever', 5) -- Search in view id 5 ---- ``` function web.search.set_text(text, view_id) return __internals.search_set_text(text, view_id) end --- Reset searched text in a view (Same as web.search.set_text('')) --- ---- @param view_id? number Id of the view +--- @param view_id number? Id of the view --- ---- @example ---- ```lua +--- @usage --- web.search.reset() -- Reset search state for current view --- web.search.reset(5) -- Reset search state for view id 5 ---- ``` function web.search.reset(view_id) return __internals.search_set_text('', view_id) end --- Get the last searched text --- ---- @example ---- ```lua +--- @usage --- local text = web.search.get_text() ---- ``` function web.search.get_text() return __internals.search_get_text() end --- Highlight next search term for the last searched text --- ---- @param view_id? number Id of the view +--- @param view_id number? Id of the view --- ---- @example ---- ```lua +--- @usage --- web.search.next() -- Next search result in current view --- web.search.next(5) -- Next search result in view id 5 ---- ``` function web.search.next(view_id) return __internals.search_next(view_id) end --- Highlight previous search term for the last searched text --- ---- @param view_id? number Id of the view +--- @param view_id number? Id of the view --- ---- @example ---- ```lua +--- @usage --- web.search.previous() -- Previous search result in current view --- web.search.previous(5) -- Previous search result in view id 5 ---- ``` function web.search.previous(view_id) return __internals.search_previous(view_id) end --- TODO: Document @@ -348,19 +315,19 @@ function web.view.scroll_to_top(view_id) return __internals.view_scroll_to_top(v --- TODO: Document function web.view.scroll_to_bottom(view_id) return __internals.view_scroll_to_bottom(view_id) end ---- Decoration api ---- --- @class DecorationOpts --- @field win? number ---- + --- @class Decoration --- @field enable fun(opts?: DecorationOpts): nil --- @field disable fun(opts?: DecorationOpts): nil --- @field set_enabled fun(enabled: boolean, opts?: DecorationOpts): nil --- @field is_enabled fun(opts?: DecorationOpts): boolean --- @field view fun(opts?: DecorationOpts): number|nil ---- ---- @alias DecorationType number + +--- @class DecorationType: number + +--- Decoration api --- --- @param type DecorationType --- @return Decoration @@ -381,12 +348,10 @@ local function create_decoration_api(type) } end ---- @see DecorationType in ./src/widgets/Decorations.hpp +--- Maps to values defined in ./src/widgets/Decorations.hpp local DecorationType = { top = 1, bottom = 2, left = 3, right = 4 } web.decorations.top = create_decoration_api(DecorationType.top) web.decorations.bottom = create_decoration_api(DecorationType.bottom) web.decorations.left = create_decoration_api(DecorationType.left) web.decorations.right = create_decoration_api(DecorationType.right) - -print("api loaded") diff --git a/lua/null-browser/extras/tabline.lua b/lua/null-browser/extras/tabline.lua index e265940..9c53f41 100644 --- a/lua/null-browser/extras/tabline.lua +++ b/lua/null-browser/extras/tabline.lua @@ -72,6 +72,9 @@ function tabline.css() align-items: stretch; height: 100vh; } + .tabs.vertical { + flex-direction: column; + } .tab { all: unset; flex: 1; diff --git a/lua/null-browser/utils.lua b/lua/null-browser/utils.lua index 13b9d13..77ed60f 100644 --- a/lua/null-browser/utils.lua +++ b/lua/null-browser/utils.lua @@ -1,37 +1,46 @@ ---- @type table +--- Helper lua utils for null browser +--- @module web + _G.web = _G.web or {} web.utils = web.utils or {} ---- luv api ---- @type table ---- @link https://github.com/luvit/luv/blob/master/docs.md +--- luv api (https://github.com/luvit/luv/blob/master/docs.md) +--- --- @diagnostic disable-next-line: undefined-global web.uv = web.uv or nil local inspector = require 'null-browser.inspect' ---- Returns human-readable string representation of Lua tables ---- ---- @link https://github.com/kikito/inspect.lua +--- Returns human-readable string representation of Lua tables (https://github.com/kikito/inspect.lua) +--- @diagnostic disable-next-line: undefined-doc-param +--- @param value any +--- @return string web.inspect = inspector.inspect --- TODO: Documentation +--- Trim whitespace from start and end of a string +--- @param str string +--- @return string function web.utils.string_trim(str) local res, _ = string.gsub(str, '^%s*(.-)%s*$', '%1') return res end --- TODO: Documentation -function web.utils.table_merge(t, ...) +--- Merge multiple tables +--- @param tbl table +--- @return table +function web.utils.table_merge(tbl, ...) for i = 1, select("#", ...) do for k, v in pairs(select(i, ...) or {}) do - t[k] = v + tbl[k] = v end end - return t + return tbl end +--- Get keys of a table +--- @param tbl table +--- @return table function web.utils.table_keys(tbl) local keys = {} for key, _ in pairs(tbl) do @@ -63,6 +72,10 @@ local function is_deep_equal_helper(a, b, table_pairs) return a == b end +--- Check if 2 values are deeply equal +--- @param a any +--- @param b any +--- @return boolean function web.utils.equals(a, b) return is_deep_equal_helper(a, b, {}) end |