elinks-perl - 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.
This hash is keyed by option names and contains the respective value - either a stringnumber or a reference to a subsequent hash. Values are automatically converted to the option type - e.g. if you set a boolean option to 12938 or 'pasky' and read it back, you get just 1; if the value is bounded integer, you get the value modulo max.
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
This hash is keyed the same way as %options, however it contains all the information about the option.
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!
String containing bool (not considered an integer type), int (basic integer type), long (big integer), string, codepage, language, color, command (the value is undefined in this case), alias, or tree (the value member is a hash reference).
Reference of array of strings, which can be: hidden (never touch those options), autocreate (the tree is magical), watermark (this is for internal options marking; you must know what are you doing if you are ever going to use it, and you must clear it after you are done; never touch this flag), touched (whether this option should be saved/updated in the configuration file), sort (the tree shall be kept sorted by ELinks; no impact on subtrees), or deleted (the option is already gone; this option is merely a shadow neccesary for appropriate edit of the configuration file).
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.
Meaningful only for integer types.
Meaningful only for integer types.
TODO: A way to bind Perl coderef as a changehook.
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
This hash is keyed by the keymap name (main, menu, and edit) on the first level and by the key string on the second level (with the same rules as in the configuration file). The value is an action name string or it can be also a Perl code reference, if you want to bind your own subroutine.
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
This hash is keyed by the keymap name (main, menu, and edit) on the first level and by the action string on the second level (see the configuration documentation for the list of actions), or the key can also be a Perl code reference (that may sound sick but it is actually cool! ;-). The value is a reference to an array of key strings. Therefore, it simply provides reverse mapping to the %keybindings map; you could emulate that by some Perl code but in this case these two mappings are both so frequently needed that it is practical to have both builtin.
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
This function takes the supplied $string and evaluates it as a [set of] configuration command[s] (like the -eval commandline option). It returns an array of errors encountered during the evaluation; empty array signifies successful evaluation.
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.
This function shows a trivial window containing only the supplied text and an [ 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
This function shows a simple window containing only the supplied text and two [ 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
This functionn shows a simple window containing the supplied label, an input box, and the [ 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.