hooks.pl -- Perl hooks for the ELinks text WWW browser
This file contains the Perl hooks for the ELinks text WWW browser.
These hooks can alter the browser's behavior in various ways; probably the most popular is processing the user input in the Goto URL dialog box and rewriting it in various ways (like the builtin URL prefix capability, but much more powerful and flexible).
Another popular capability of the hooks is to rewrite the HTML source of a page before it is rendered, usually to get rid of ads and/or make the web page more ELinks-friendly. The hooks also allow you to fine-tune the proxying rules, can show a fortune when ELinks exits, and more!
The hooks file reads its configuration from ~/.elinks/config.pl. Note that the following is only an example, and does not contain the default values:
bork: yep # BORKify Google? collapse: okay # Collapse all XBEL bookmark folders on exit? email: # Set to show one's own bugs with the "bug" prefix. fortune: elinks # *fortune*, *elinks* tip, or *none* on quit? googlebeta: hell no # I miss DejaNews... gotosearch: not yet # Don't use this yet. It's broken. Don't use it at all, actually. ipv6: sure # IPV4 or 6 address blocks with "ip" prefix? language: english # "bf nl en" still works, but now "bf nl" does too news: msnbc # Agency to use for "news" and "n" prefixes search: elgoog # Engine for (search|find|www|web|s|f|go) prefixes usenet: google # *google* or *standard* view for news:// URLs weather: cnn # Server for "weather" and "w" prefixes
# news: bbc, msnbc, cnn, fox, google, yahoo, reuters, eff, wired, # slashdot, newsforge, usnews, newsci, discover, sciam # search: elgoog, google, yahoo, ask jeeves, a9, altavista, msn, dmoz, # dogpile, mamma, webcrawler, netscape, lycos, hotbot, excite # weather: weather underground, google, yahoo, cnn, accuweather, # ask jeeves
Developer's usage: The function loadrc() takes a preference name as its
single argument and returns either an empty string if it is not specified,
yes for a true value (even if specified like sure or why not), no
for a false value (even if like nah, off or 0), or the lowercased
preference value (like cnn for weather: CNN
).
This is a summary of all the available rewrites of what you type into the Goto URL box. They are similar in spirit to the builtin URL rewrites, but more flexible and immensely more powerful.
Developer's usage: The function goto_url_hook is called when the hook is triggered, taking the target URL and current URL as its two arguments. It returns the final target URL.
In this section, name mapping routines are described. They are probably of no interest to regular hooks users, only for hooks developers.
These routines do a name->URL mapping - e.g. the goto_url_hook() described
above maps a certain prefix to google
and then asks the search() mapping
routine described below to map the google
string to an appropriate URL.
The mappings themselves should be obvious and are not described here. Interested readers can look them up themselves in the hooks.pl file.
There are generally two URLs for each name, one for a direct shortcut jump and another for a search on the given site (if any string is specified after the prefix, usually).
default engine: search, find, www, web, s, f, go
The %search_engines hash maps each engine name to two URLs, home and search. In case of search, the query is appended to the mapped URL.
!bork! string in the URL is substitued for an optional xx-bork
localization specifier, but only in the google
mapping.
The search engines mapping is done by the search() function, taking the search engine name as its first parameter and optional search string as its second parameter. It returns the mapped target URL.
Google is used as the default search engine if the given engine is not found.
default agency: n, news
The %news_servers hash maps each engine name to two URLs, home and search. In case of search, the query is appended to the mapped URL.
The news servers mapping is done by the news() function, taking the search engine name as its first parameter and optional search string as its second parameter. It returns the mapped target URL.
BBC is used as the default search engine if the given engine is not found.
The %locators hash maps each engine name to two URLs, home and search.
!bork! string in the URL is substitued for an optional xx-bork
localization specifier (for any mappings in this case, not just google
).
!current! string in the URL is substitued for the URL of the current document.
!query! string in the search URL is substitued for the search string. If no !query! string is found in the URL, the query is appended to the mapped URL.
The locators mapping is done by the location() function, taking the search engine name as its first parameter, optional search string as its second parameter and the current document's URL as its third parameter. It returns the mapped target URL.
An error is produced if the given locator is not found.
There's no place like home...
Dialects: redneck, jive, cockney, fudd, bork, moron, piglatin, or hacker
These rewrites happen everytime ELinks is about to follow an URL and load it, so this is an order of magnitude more powerful than the Goto URL rewrites.
Developer's usage: The function follow_url_hook is called when the hook is triggered, taking the target URL as its only argument. It returns the final target URL.
When an HTML document is downloaded and is about to undergo the final rendering, the rewrites described here are done first. This is frequently used to get rid of ads, but also various ELinks-unfriendly HTML code and HTML snippets which are irrelevant to ELinks but can obfuscate the rendered document.
Note well that these rules are applied only before the final rendering, not before the gradual re-renderings which happen when only part of the document is available.
Developer's usage: The function pre_format_html_hook is called when the hook is triggered, taking the document's URL and the HTML source as its two arguments. It returns the rewritten HTML code.
This rewrite rule is DISABLED due to weird behavior with fragments.
The Perl hooks are asked whether to use a proxy for a given URL (or what proxy to actually use). You can use it if you don't want to use a proxy for certain Intranet servers but you need to use it in order to get to the Internet, or if you want to use some anonymizer for access to certain naughty sites.
Developer's usage: The function proxy_for_hook is called when the hook is triggered, taking the target URL as its only argument. It returns the proxy URL, empty string to use no proxy or undef to use the default proxy URL.
http://localhost
.
The Perl hooks can also perform various actions when ELinks quits. These can be things like retouching the just saved ``information files'', or doing some fun stuff.
Developer's usage: The function quit_hook is called when the hook is triggered, taking no arguments nor returning anything. ('cause, you know, what would be the point?)
elinks(1), perl(1)
Russ Rowan, Petr Baudis