Lua scripting capabilities permit users to customize the ELinks behaviour to unusual degree - they allow automatic rewriting of HTML code of the received documents, rewriting of the URLs entered by user etc. You can even write your own bookmarks system with Lua. See also contrib/lua/ for some examples of the possibilities of ELinks Lua support.

Please do not confuse Lua scripting with JavaScript, EcmaScript, VBScript and similar. Those are embedded in page, allowing per-document scripting related to its presentation and providing some degree of interactivity etc. On the contrary, the current Lua support permits scripts to be embedded to the browser directly, changing the behaviour of the browser, not the document.

The original Lua support (in the form of Links-Lua fork of original Links) was written by Peter Wang and Cliff Cunnington. There are some rough edges remaining, but is suitable for everyday use (I have been using it every day for a year).

The Lua scripting support comes with the stock ELinks distribution, no additional patches and tweaks should be needed.

The web site of the original Links-Lua is at http://links.sourceforge.net/links-lua/. Some older patches against regular Links are available at http://www.sourceforge.net/projects/links/, but they are not being maintained.

Lua can be found at http://www.lua.org/.

The Lua support has only been tested under Linux, although it should work under other platforms that ELinks and Lua support (perhaps with some changes to source code?).

Also, note that many of the scripts given here assume a Unix system. Your mileage will definitely vary on other platforms.

Before you can compile ELinks with Lua support, you must compile and install Lua. The following instructions are for a Linux system. People on other systems should try to enable popen support, but this is not necessary (you will lose a bit of functionality though).

On systems without shared object support, simply run make; make install instead.

Since ELinks 0.11.0, only version 5.0 of Lua is supported. Future versions of ELinks will probably support Lua 5.1 too; see bug 742.

Follow the instructions for building ELinks (it is the standard ./configure; make; make install procedure). During the configure step make sure that Lua has been detected on your system.

Simply start ELinks as you normally would. To check you have Lua support compiled in, open up the "Help | About" dialog box. It should list "Scripting (Lua)" under "Features". If not, make sure you do not have other copies of ELinks running, or start ELinks again with the "-no-connect" option on the command-line.

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 ~/.config/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.

As well as providing hooks, ELinks provides some functions in addition to the standard Lua functions.

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.

There are some web sites that I visit often. Bookmarks are okay, but they are separate from the "Go to URL" dialog box, so I keep forgetting to use them. Also, when I visit a search engine home page, all I really want to do is enter a search term.

The following script allows me to type certain strings into the "Go to URL" dialog box, and it will convert them to the URL I actually want to visit. As a bonus, it allows me perform some searches on sites like Google without loading up the front page first.

function match (prefix, url)
    return string.sub (url, 1, string.len (prefix)) == prefix
end

function strip (str)
    return string.gsub (str, "^%s*(.-)%s*$", "%1")
end

function plusify (str)
    return string.gsub (str, "%s", "+")
end

function goto_url_hook (url, current_url)
    -- Google search (e.g. ,gg unix browsers).
    if match (",gg", url) then
        url = plusify (strip (string.sub (url, 4)))
        return "http://www.google.com/search?q="..url.."&btnG=Google+Search"

    -- Freshmeat search.
    elseif match (",fm", url) then
        url = plusify (strip (string.sub (url, 4)))
        return "http://www.freshmeat.net/search/?q="..url

    -- Dictionary.com search (e.g. ,dict congenial).
    elseif match (",dict", url) then
        url = plusify (strip (string.sub (url, 6)))
        return "http://www.dictionary.com/cgi-bin/dict.pl?db=%2A&term="..url

    -- RPM search (e.g. ,rpm links).
    elseif match (",rpm", url) then
        url = plusify (strip (string.sub (url, 5)))
        return "http://www.rpmfind.net/linux/rpm2html/search.php?query="
                ..url.."&submit=Search+..."

    -- Netcraft.com search (e.g. ,whatis www.google.com).
    elseif match (",whatis", url) then
        url = plusify (strip (string.sub (url, 8)))
        return "http://uptime.netcraft.com/up/graph/?host="..url

    -- LinuxToday home page.
    elseif match (",lt", url) then
        return "http://linuxtoday.com/"

    -- Weather forecast for Melbourne, Australia.
    elseif match (",forecast", url) then
        return "http://www.bom.gov.au/cgi-bin/wrap_fwo.pl?IDV10450.txt"

    -- Unmatched
    else
        return url
    end
end

By adding an extra snippet of code to the previous example, we can make ELinks expand pathnames such as ~/foo/bar and ~user/zappo, like in the shell and other Unix programs.

function goto_url_hook (url, current_url)
                .
                .

    -- Expand ~ to home directories.
    elseif match ("~", url) then
        if string.sub(url, 2, 2) == "/" then    -- ~/foo
            return os.getenv ("HOME")..string.sub(url, 2)
        else                                    -- ~foo/bar
            return "/home/"..string.sub(url, 2)
        end

                .
                .

Many web pages nowadays have columns to the left and right of the text, which are utterly useless. If you happen to be viewing the page in a 80x25 screen, the text you want to read ends up crammed into a tiny space in the centre. We use ELinks Lua support to manipulate the HTML before it reaches the parser.

-- Plain string.find (no metacharacters)
function sstrfind (s, pattern)
    return string.find (s, pattern, 1, true)
end

function pre_format_html_hook (url, html)
    -- Strip the left and right columns from Linux Today pages
    -- and change the font colour to white.
    if sstrfind (url, "linuxtoday.com") then
        if sstrfind (url, "news_story") then
            html = string.gsub (html, '<TABLE CELLSPACING="0".-</TABLE>', '', 1)
            html = string.gsub (html, '<TR BGCOLOR="#FFF.-</TR></TABLE>', '', 1)
        else
            html = string.gsub (html, 'WIDTH="120">\n<TR.+</TABLE></TD>', '>', 1)
        end
        html = string.gsub (html, '<A HREF="http://www.internet.com.-</A>', '')
        html = string.gsub (html, "<IFRAME.-</IFRAME>", "")
        -- emphasis in text is lost
        return string.gsub (html, 'text="#002244"', 'text="#001133"', 1)
    end

    return nil
end

function pre_format_html_hook (url, html)
                .
                .

    elseif string.find (url, "linuxgames.com", 1, true) then
        return string.gsub (html, "<CENTER>.-</center>", "", 1)

                .
                .

Sometimes documents come gzipped in order to save space, but then you need to uncompress them to read them with ELinks. Here is a recipe to handle gzipped files on a Unix system.

function pre_format_html_hook (url, html)
                .
                .

    -- Handle gzip'd files within reasonable size.
    if string.find (url, "%.gz$") and string.len (html) < 65536 then
        local name = tmpname ()
        local file = io.open (name, "wb")
        file:write (html)
        file:close ()
        html = pipe_read ("(gzip -dc "..name.." || cat "..name..") 2>/dev/null")
        os.remove (name)
        return html
    end

                .
                .

Printing a web page with ELinks usually involves quite a few steps: Save the current document onto disk. Run it through ELinks on the command-line (so it fits into 80 columns) to generate a plain text version. Remove the 80th column from the text version, as it will make printers wrap down to the next line. Finally, run the processed file through `lpr', then delete it.

The following functions allow you to print web pages directly from ELinks, using lpr' or `enscript'. Type `lpr() or enscript() in the Lua Console to run them. (In the hooks.lua, I have also made it so you can just type lpr or enscript.)

function pipe_formatted_to (program)
    local lp, errmsg = io.popen (program, "w")
    if lp == nil then
        error (errmsg)
    else
        lp:write (current_document_formatted (79))
        lp:close ()
    end
end

-- Send the current document to `lpr'.
function lpr ()
    pipe_formatted_to ("lpr")
end

-- Send the current document to `enscript'.
function enscript ()
    pipe_formatted_to ("enscript -fCourier8")
end

If you come across a brain-dead web page that is totally unreadable with ELinks, you'd probably want to open it with a graphical browser. The following function opens the current document in Netscape.

-- When starting Netscape: Set to `nil' if you do not want
-- to open a new window for each document.
netscape_new_window = 1

-- Open current document in Netscape.
function netscape ()
    local new = netscape_new_window and ",new_window" or ""
    execute ("( netscape -remote 'openURL("..current_url ()..new..")'"
             .." || netscape '"..current_url ().."' ) 2>/dev/null &")
end

Many people would like to have a bookmark system with categories (note that ELinks already supports that, marketing name Hierarchical bookmarks), and also to be able to view them and search for them in an HTML page. I have written an alternative bookmark system (for ELinks), which some people may like better than the standard bookmark system.