doc/perl.pod

   1 =head1 NAME
   2
   3 ELinks Perl Interface
   4
   5 =head1 INTRODUCTION
   6
   7 This document aims to describe the ELinks (powerful text WWW browser) interface
   8 for Perl (powerful and enchanting programming language). This interface falls
   9 to the "internal scripting" domain of ELinks, therefore it concerns scripts
  10 which affect ELinks general behaviour, I<not> scripts embedded in the WWW
  11 documents.
  12
  13 The interface consists of two largely separate and independent parts. The first
  14 one is where ELinks is the active party, calling Perl I<hooks> upon certain
  15 events (going to a URL, about to render an HTML document, exiting) and
  16 conniving the hook results. This part of the interface is not subject of this
  17 document, however. There is no document dedicated to this so far, however the
  18 example Perl hooks file (I<contrib/perl/hooks.pl> in the source distribution)
  19 has some plentiful POD documentation embedded, which lists the currently
  20 implemented hooks exhaustively, along with I<Developer's usage> sections which
  21 describe the Perl side of the hooks interface. If you are also at least mildly
  22 capable C programmer, you might consider contributing Perl interface for some
  23 other hooks which are supported by the rest of ELinks; see I<doc/events.txt>
  24 for detailed listing of these.
  25
  26 The other part of the interface, which is also the main subject of this
  27 document, are functions and data structures provided by ELinks for the Perl
  28 scripts. Here, the Perl script is the active party, accessing ELinks data
  29 structures and functions.
  30
  31 While the event hooks are already pretty standardized and settled down, each
  32 internal scripting language has a very different Perl->ELinks interface; well,
  33 each of the two who actually provide any interface of this kind.  The other
  34 language having this is Lua, but the author of this document chose to
  35 completely ignore its interface since he believes it needs a radical redesign
  36 anyway.  It is currently result of some historical features gluing, is pretty
  37 clumsy, ugly and ad hoc built together. So the author took this opporunity
  38 to think out something he believes is nice, consistent, and elegant. ;-)
  39
  40
  41
  42 =head1 ABOUT THIS DOCUMENT
  43
  44 Please note that this is currently mostly only a design document. Nothing or
  45 only very little of it is already actually implemented. The unimplemented parts
  46 are marked by the B<TODO> marker. The whole thing is also still subject of
  47 discussion and can be changed anytime without any notice or compatibility
  48 measures.
  49
  50
  51
  52 =head1 GENERAL USAGE
  53
  54 The data structures are generally exported to the global namespace (B<TODO>:
  55 a way to prevent this) for greater convenience, while the functions provided
  56 are kept in the C<ELinks> (or subsequent) namespace. Please note well that
  57 B<you do not need to load the ELinks package explicitly>! No
  58
  59         use ELinks;
  60
  61 is needed. Don't do it.
  62
  63 ELinks exports some of its internals as Perl data structures.  Especially the
  64 vectors are usually generated dynamically and behave as tied vectors; therefore
  65 changes to them propagate as changes to their internal counterparts; e.g.
  66 adding an item to the array of bookmarks will reflect immediately in the ELinks
  67 internal bookmarks list.
  68
  69
  70
  71 =head1 CONFIGURATION SUBSYSTEM
  72
  73 =over 4
  74
  75 =item %options
  76
  77 This hash is keyed by option names and contains the respective value - either
  78 a stringnumber or a reference to a subsequent hash. Values are automatically
  79 converted to the option type - e.g. if you set a boolean option to 12938
  80 or 'pasky' and read it back, you get just 1; if the value is bounded integer,
  81 you get the value modulo max.
  82
  83 The first level of the hash is keyed by the option trees; two trees are
  84 present now, I<config> and I<cmdline>.
  85
  86 You may not add options (set previously unset keys) through this hash
  87 except for the I<autocreate> keys (those with a I<_template_> option,
  88 e.g. B<mime.extension>). Options with the I<deleted> flag appear as
  89 unset in this hash. Deleting options from this hash merely sets the
  90 I<deleted> flag on them.
  91
  92 B<Example:>
  93
  94         $options{'config'}->{'document'}->{'download'}->{'notify_bell'}++;
  95
  96 B<TODO>
  97
  98
  99 =item %extoptions
 100
 101 This hash is keyed the same way as I<%options>, however it contains all the
 102 information about the option.
 103
 104 You may add options (set previously unset keys) through this hash only by
 105 setting the I<type> member first. You can delete options from this hash,
 106 which wipes them altogether, but B<never do that>!
 107
 108 =over 4
 109
 110 =item type
 111
 112 String containing I<bool> (B<not> considered an integer type), I<int> (basic
 113 integer type), I<long> (big integer), I<string>, I<codepage>, I<language>,
 114 I<color>, I<command> (the I<value> is undefined in this case), I<alias>, or
 115 I<tree> (the I<value> member is a hash reference).
 116
 117 =item value
 118
 119 =item flags
 120
 121 Reference of array of strings, which can be: I<hidden> (never touch those
 122 options), I<autocreate> (the tree is magical), I<watermark> (this is for
 123 internal options marking; you must know what are you doing if you are ever
 124 going to use it, and you B<must> clear it after you are done; B<never touch
 125 this flag>), I<touched> (whether this option should be saved/updated in the
 126 configuration file), I<sort> (the tree shall be kept sorted by ELinks; no
 127 impact on subtrees), or I<deleted> (the option is already gone; this option is
 128 merely a shadow neccesary for appropriate edit of the configuration file).
 129
 130 Note that ELinks internally uses some other flags too, those are of no value
 131 whatsoever for the Perl scripts though, so you cannot see them.
 132
 133 =item min
 134
 135 Meaningful only for integer types.
 136
 137 =item max
 138
 139 Meaningful only for integer types.
 140
 141 =item description
 142
 143 =item caption
 144
 145 =item changehook
 146
 147 B<TODO>: A way to bind Perl coderef as a changehook.
 148
 149 =back
 150
 151 B<Example:>
 152
 153         my $btree = $extoptions{'config'}->{'bookmarks'}->{'value'};
 154         $btree->{'cute'} = { type => 'bool', value => 1 };
 155
 156         $btree->{'lovely'}->{'type'} = 'tree';
 157         $btree->{'lovely'}->{'value'}->{'shiny'}->{'type'} = 'int';
 158
 159         $btree->{'cool'}->{'type'} = 'string';
 160
 161         # Equivalent:
 162         $btree->{'cool'}->{'flags'} = [ 'deleted' ];
 163         delete $options{'config'}->{'bookmarks'}->{'cool'};
 164
 165 B<TODO>
 166
 167
 168 =item %keybindings
 169
 170 This hash is keyed by the keymap name (I<main>, I<menu>, and I<edit>) on the
 171 first level and by the key string on the second level (with the same rules
 172 as in the configuration file). The value is an action name string I<or>
 173 it can be also a Perl code reference, if you want to bind your own
 174 subroutine.
 175
 176 Currently the custom Perl subroutine will get only the key string as its
 177 first parameter. More parameters (different for each keymap) will be added
 178 in future as the required infrastructure for them will be added.
 179
 180 B<Example:>
 181
 182         my $q = $keybindings{'main'}->{'q'};
 183         ELinks::alert(ref $q ? 'perl hook' : $q);
 184         $keybindings{'main'}->{'q'} = \&quit_wrapper;
 185
 186 B<TODO>
 187
 188
 189 =item %actbindings
 190
 191 This hash is keyed by the keymap name (I<main>, I<menu>, and I<edit>) on the
 192 first level and by the action string on the second level (see the configuration
 193 documentation for the list of actions), I<or> the key can also be a Perl code
 194 reference (that may sound sick but it is actually cool! ;-). The value is a
 195 reference to an array of key strings. Therefore, it simply provides reverse
 196 mapping to the I<%keybindings> map; you could emulate that by some Perl code
 197 but in this case these two mappings are both so frequently needed that it is
 198 practical to have both builtin.
 199
 200 The values are unique, so adding the value at one place will make it disappear
 201 from another possible occurence.
 202
 203 B<Example:>
 204
 205         ELinks::alert(join(' ', @{$keybindings{'main'}->{'quit'}});
 206         push(@{$keybindings{'main'}->{\&quit_wrapper}}, 'q');
 207
 208 B<TODO>
 209
 210
 211 =item ELinks::conf_eval($string)
 212
 213 This function takes the supplied I<$string> and evaluates it as a [set of]
 214 configuration command[s] (like the B<-eval> commandline option). It
 215 returns an array of errors encountered during the evaluation; empty
 216 array signifies successful evaluation.
 217
 218 B<Example:>
 219
 220         ELinks::conf_eval('set connection.async_dns = 0');
 221         ELinks::conf_eval('bind "main" "q" = "quit"');
 222
 223 B<TODO>
 224
 225
 226 =back
 227
 228
 229
 230 =head1 SIMPLE DIALOGS
 231
 232 This chapter is concerned of using simple prefabricated dialogs.  Explicitly
 233 construing complex custom dialogs from widgets is described in the CUSTOM
 234 DIALOGS section.
 235
 236 =over 4
 237
 238 =item ELinks::alert(...)
 239
 240 This function shows a trivial window containing only the supplied text and an
 241 C<[ OK ]> button.
 242
 243 The function takes either a single parameter with the text, or a hash with the
 244 I<message> and optional I<title> key. The window title defaults to "Perl
 245 Alert").
 246
 247 The function returns nothing (or rather, anything).
 248
 249 B<Example:>
 250
 251         ELinks::alert('They are after you!');
 252         ELinks::alert(title => 'The Litany Against Fear',
 253                       message => 'I must not fear. Fear is the mind-killer...');
 254
 255 B<TODO>
 256
 257 =item ELinks::confirm(...)
 258
 259 This function shows a simple window containing only the supplied text and two
 260 C<[ Yes ]> and C<[ No ]> buttons.
 261
 262 The function takes either a single parameter with the text, or a hash with the
 263 I<message> and optional I<title> (window title) key, which defaults to "Perl
 264 Confirmation". You can also pass optional I<yes> and I<no> keys, changing the
 265 default button labels.
 266
 267 The function returns true if the yes button was pressed, false otherwise.
 268
 269 B<Example:>
 270
 271         ELinks::emit_action('quit') if Elinks::confirm('Quit ELinks?');
 272
 273         # Abuse example: ;-)
 274         if (ELinks::confirm(title => 'Candy shop',
 275                             message => 'What will you choose?'
 276                             yes => 'Sweet', no => 'Lollipop')
 277                 { ELinks::alert('Yummy!'); }
 278         else
 279                 { ELinks::alert('*Smack*'); }
 280
 281 B<TODO>
 282
 283 =item ELinks::inputbox(...)
 284
 285 This functionn shows a simple window containing the supplied label, an input
 286 box, and the C<[ OK ]> and C<[ Cancel ]> buttons. So it will look like e.g.
 287 the Goto URL dialog.
 288
 289 The function takes either a single parameter with the label, or a hash with the
 290 I<label> and and optional I<title> (window title) key, which defaults to "Perl
 291 Input".
 292
 293 The function returns the input value if the OK button was pressed, undef
 294 otherwise.
 295
 296 B<Example:>
 297
 298         ELinks::alert('I have ' . ELinks::inputbox('Amount') . ' of '
 299                       . ELinks::inputbox(title => 'Curious',
 300                                          label => 'Fruit sort'));
 301
 302 B<TODO>
 303
 304 =back
 305
 306
 307
 308 =head1 AUTHORS
 309
 310 This document was scribbled by Petr Baudis.