Out of the box, ELinks with Lua will do nothing different from regular ELinks. You need to write some scripts.
The Lua support is based on the idea of hooks. A hook is a function that gets called at a particular point during the execution of ELinks. To make ELinks do what you want, you can add and edit such hooks.
The Lua support also adds an extra dialog box, which you can open while in
ELinks with the comma (
,) key. Here you can enter Lua expressions for
evaluation, or override it to do something different.
And finally, you can bind keystrokes to Lua functions. These keystrokes won't let you do any more than is possible with the Lua Console, but they're more convenient.
Note that this document assumes you have some knowledge of programming in Lua. For that, you should refer to the Lua reference manual (http://www.lua.org/docs.html). In fact, the language is relatively trivial, though. You could already do wonders with simply refactoring the example scripts.
On startup, ELinks reads in two Lua scripts. Firstly, a system-wide
configuration file called
/etc/elinks/hooks.lua, then a file in your home
~/.elinks/hooks.lua. From these files, you can include
other Lua files with
dofile, if necessary.
To see what kind of things you should put in here, look at
The following hooks are available.
nil). It should return a string, which is the URL that ELinks should follow, or
nilto cancel the operation.
nilto stop ELinks following the URL
nilif there were no modifications.
nilto use the default proxy of the protocol.
This hook is passed the string that the user entered into the "Lua
Console" dialog box. It should return two values: the type of action
to take (
a second argument, which is the shell command to run or the Lua
expression to evaluate. Examples:
return "run", "someprogram"will attempt to run the program
return "eval", "somefunction(1+2)"will attempt to call the Lua function
somefunctionwith an argument, 3.
return "goto_url", "http://www.bogus.com"will ask ELinks to visit the URL "http://www.bogus.com".
return nilwill do nothing.
As well as providing hooks, ELinks provides some functions in addition to the standard Lua functions.
The standard Lua function
os.setlocale affects ELinks' idea of
the system locale, which ELinks uses for the "System" charset, for the
"System" language, and for formatting dates. This may however have to
be changed in a future version of ELinks, in order to properly support
terminal-specific system locales.
nilif none is selected.
width, just as some lines may be wider than the screen when viewing documents online.
commandand reads in all the data from stdout, until there is no more. This is a hack, because for some reason the standard Lua function
file:readseems to crash ELinks when used in pipe-reading mode.
stringwithout waiting for it to exit. Beware that you must not read or write to stdin and stdout. And unlike the standard Lua function
os.execute, the return value is meaningless.
Returns a unique name for a temporary file, or
nil if no
such name is available. The returned string includes the
directory name. Unlike the standard Lua function
os.tmpname, this one generates ELinks-related names
(currently with "elinks" at the beginning of the name).
tmpname function does not create the file and does not
guarantee exclusive access to it: the caller must handle the
possibility that another process creates the file and begins
using it while this function is returning. Failing to do this
may expose you to symlink attacks by other users. To avoid
the risk, use
io.tmpfile instead; unfortunately, it does not
tell you the name of the file.
keymapmust be the string
"main". Keystroke is a keystroke as you would write it in the ELinks config file
~/.elinks/elinks.conf. The function
functionshould take no arguments, and should return the same values as
nilif arguments are invalid, or nothing at all if out of memory. The first three arguments must be strings, and the user can then edit them in input fields. There are also OK and Cancel buttons in the dialog. If the user presses OK, ELinks calls
functionwith the three edited strings as arguments, and it should return similar values as in
nilif arguments are invalid, or nothing at all if out of memory. All arguments except the last one must be strings, and ELinks places them in input fields in the dialog. There can be at most 5 such strings. There are also OK and Cancel buttons in the dialog. If the user presses OK, ELinks calls
functionwith the edited strings as arguments, and it should return similar values as in
optionmust be the name of the option as a string. ELinks then tries to convert the second argument
valueto match the type of the option. If successful,
optionmust be the name of the option as a string. If the option does not exist,
There is one more little thing which Links-Lua adds, which will not be
described in detail here. It is the fake "user:" protocol, which can be used
when writing your own addons. It allows you to generate web pages containing
links to "user://blahblah", which can be intercepted by the
(among other things) to perform unusual actions. For a concrete example, see
the bookmark addon.