ELinks Perl Interface
This document aims to describe the ELinks (powerful text WWW browser) interface for Perl (powerful and enchanting programming language). This interface falls to the ``internal scripting'' domain of ELinks, therefore it concerns scripts which affect ELinks general behaviour, not scripts embedded in the WWW documents.
The interface consists of two largely separate and independent parts. The first one is where ELinks is the active party, calling Perl hooks upon certain events (going to a URL, about to render an HTML document, exiting) and conniving the hook results. This part of the interface is not subject of this document, however. There is no document dedicated to this so far, however the example Perl hooks file (contrib/perl/hooks.pl in the source distribution) has some plentiful POD documentation embedded, which lists the currently implemented hooks exhaustively, along with Developer's usage sections which describe the Perl side of the hooks interface. If you are also at least mildly capable C programmer, you might consider contributing Perl interface for some other hooks which are supported by the rest of ELinks; see doc/events.txt for detailed listing of these.
The other part of the interface, which is also the main subject of this document, are functions and data structures provided by ELinks for the Perl scripts. Here, the Perl script is the active party, accessing ELinks data structures and functions.
While the event hooks are already pretty standardized and settled down, each internal scripting language has a very different Perl->ELinks interface; well, each of the two who actually provide any interface of this kind. The other language having this is Lua, but the author of this document chose to completely ignore its interface since he believes it needs a radical redesign anyway. It is currently result of some historical features gluing, is pretty clumsy, ugly and ad hoc built together. So the author took this opporunity to think out something he believes is nice, consistent, and elegant. ;-)
Please note that this is currently mostly only a design document. Nothing or only very little of it is already actually implemented. The unimplemented parts are marked by the TODO marker. The whole thing is also still subject of discussion and can be changed anytime without any notice or compatibility measures.
The data structures are generally exported to the global namespace (TODO:
a way to prevent this) for greater convenience, while the functions provided
are kept in the ELinks
(or subsequent) namespace. Please note well that
you do not need to load the ELinks package explicitly! No
use ELinks;
is needed. Don't do it.
ELinks exports some of its internals as Perl data structures. Especially the vectors are usually generated dynamically and behave as tied vectors; therefore changes to them propagate as changes to their internal counterparts; e.g. adding an item to the array of bookmarks will reflect immediately in the ELinks internal bookmarks list.
The first level of the hash is keyed by the option trees; two trees are present now, config and cmdline.
You may not add options (set previously unset keys) through this hash except for the autocreate keys (those with a _template_ option, e.g. mime.extension). Options with the deleted flag appear as unset in this hash. Deleting options from this hash merely sets the deleted flag on them.
Example:
$options{'config'}->{'document'}->{'download'}->{'notify_bell'}++;
TODO
You may add options (set previously unset keys) through this hash only by setting the type member first. You can delete options from this hash, which wipes them altogether, but never do that!
Note that ELinks internally uses some other flags too, those are of no value whatsoever for the Perl scripts though, so you cannot see them.
Example:
my $btree = $extoptions{'config'}->{'bookmarks'}->{'value'}; $btree->{'cute'} = { type => 'bool', value => 1 };
$btree->{'lovely'}->{'type'} = 'tree'; $btree->{'lovely'}->{'value'}->{'shiny'}->{'type'} = 'int';
$btree->{'cool'}->{'type'} = 'string';
# Equivalent: $btree->{'cool'}->{'flags'} = [ 'deleted' ]; delete $options{'config'}->{'bookmarks'}->{'cool'};
TODO
Currently the custom Perl subroutine will get only the key string as its first parameter. More parameters (different for each keymap) will be added in future as the required infrastructure for them will be added.
Example:
my $q = $keybindings{'main'}->{'q'}; ELinks::alert(ref $q ? 'perl hook' : $q); $keybindings{'main'}->{'q'} = \&quit_wrapper;
TODO
The values are unique, so adding the value at one place will make it disappear from another possible occurence.
Example:
ELinks::alert(join(' ', @{$keybindings{'main'}->{'quit'}}); push(@{$keybindings{'main'}->{\&quit_wrapper}}, 'q');
TODO
Example:
ELinks::conf_eval('set connection.async_dns = 0'); ELinks::conf_eval('bind "main" "q" = "quit"');
TODO
This chapter is concerned of using simple prefabricated dialogs. Explicitly construing complex custom dialogs from widgets is described in the CUSTOM DIALOGS section.
[ OK ]
button.
The function takes either a single parameter with the text, or a hash with the message and optional title key. The window title defaults to ``Perl Alert'').
The function returns nothing (or rather, anything).
Example:
ELinks::alert('They are after you!'); ELinks::alert(title => 'The Litany Against Fear', message => 'I must not fear. Fear is the mind-killer...');
TODO
[ Yes ]
and [ No ]
buttons.
The function takes either a single parameter with the text, or a hash with the message and optional title (window title) key, which defaults to ``Perl Confirmation''. You can also pass optional yes and no keys, changing the default button labels.
The function returns true if the yes button was pressed, false otherwise.
Example:
ELinks::emit_action('quit') if Elinks::confirm('Quit ELinks?');
# Abuse example: ;-) if (ELinks::confirm(title => 'Candy shop', message => 'What will you choose?' yes => 'Sweet', no => 'Lollipop') { ELinks::alert('Yummy!'); } else { ELinks::alert('*Smack*'); }
TODO
[ OK ]
and [ Cancel ]
buttons. So it will look like e.g.
the Goto URL dialog.
The function takes either a single parameter with the label, or a hash with the label and and optional title (window title) key, which defaults to ``Perl Input''.
The function returns the input value if the OK button was pressed, undef otherwise.
Example:
ELinks::alert('I have ' . ELinks::inputbox('Amount') . ' of ' . ELinks::inputbox(title => 'Curious', label => 'Fruit sort'));
TODO
This document was scribbled by Petr Baudis.