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
directory called ~/.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
contrib/lua/hooks.lua
.
The following hooks are available.
nil
). It should return a string, which is the URL
that ELinks should follow, or nil
to cancel the operation.
nil
to stop
ELinks following the URL
nil
if there were no
modifications.
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 (run
, eval
, goto-url
or nil
), and
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
someprogram
.
return "eval", "somefunction(1+2)"
will attempt to call the Lua
function somefunction
with an argument, 3.
return "goto-url", "http://www.bogus.com"
will ask Links to visit
the URL "http://www.bogus.com".
return nil
will do nothing.
As well as providing hooks, ELinks provides some functions in addition to the standard Lua functions.
Enable some potentially dangerous functions, as well as some other functions which were unfortunate enough to be lumped in the same group.
The functions are: openfile
, closefile
, readfrom
, writeto
, appendto
,
pipe_read
, remove
, rename
, flush
, seek
, tmpname
, read
, write
execute
, exit
, clock
, date
, getenv
, setlocale
.
Note: setlocale
is a standard Lua function and will not affect
the current ELinks locale.
nil
if none is
selected.
nil
if none.
width
, just as some lines may be wider than the screen when
viewing documents online.
command
and reads in all the data from stdout, until there
is no more. This is a hack, because for some reason the standard Lua
function read
seems to crash ELinks when used in pipe-reading mode.
string
and returns the exit code. Beware
that you must not read or write to stdin and stdout. And unlike the
standard Lua function of the same name, the return value is
meaningless.
keymap
must be the string "main"
. Keystroke is a
keystroke as you would write it in the ELinks config file
~/.elinks/elinks.conf
. The function function
should take no
arguments, and should return the same values as lua_console_hook
.
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 follow_url_hook
(among other things) to perform unusual actions. For a concrete example, see
the bookmark addon.