doc/python.txt

   1 Python programmers can customize the behavior of ELinks by creating a Python
   2 hooks module. The embedded Python interpreter provides an internal module
   3 called elinks that can be used by the hooks module to create keystroke
   4 bindings for Python code, obtain information about the document being
   5 viewed, display simple dialog boxes and menus, load documents into the
   6 ELinks cache, or display documents to the user. These two modules are
   7 described below.
   8
   9 ------------------------------------------------------------------------------
  10
  11 MODULE
  12     hooks - Python hooks for ELinks.
  13
  14 DESCRIPTION
  15     If ELinks is compiled with an embedded Python interpreter, it will try
  16     to import a Python module called hooks when the browser starts up. To
  17     use Python code from within ELinks, create a file called hooks.py in
  18     the ~/.elinks directory, or in the system-wide configuration directory
  19     (defined when ELinks was compiled), or in the standard Python search path.
  20     An example hooks.py file can be found in the contrib/python directory of
  21     the ELinks source distribution.
  22
  23     The hooks module may implement any of several functions that will be
  24     called automatically by ELinks in appropriate circumstances; it may also
  25     bind ELinks keystrokes to callable Python objects so that arbitrary Python
  26     code can be invoked at the whim of the user.
  27
  28     Functions that will be automatically called by ELinks (if they're defined):
  29
  30     follow_url_hook() -- Rewrite a URL for a link that's about to be followed.
  31     goto_url_hook() -- Rewrite a URL received from a "Go to URL" dialog box.
  32     pre_format_html_hook() -- Rewrite a document's body before it's formatted.
  33     proxy_for_hook() -- Determine what proxy server to use for a given URL.
  34     quit_hook() -- Clean up before ELinks exits.
  35
  36 FUNCTIONS
  37     follow_url_hook(url)
  38         Rewrite a URL for a link that's about to be followed.
  39
  40         This function should return a URL for ELinks to follow, or None if
  41         ELinks should follow the original URL.
  42
  43         Arguments:
  44
  45         url -- The URL of the link.
  46
  47     goto_url_hook(url)
  48         Rewrite a URL that was entered in a "Go to URL" dialog box.
  49
  50         This function should return a URL for ELinks to follow, or None if
  51         ELinks should follow the original URL.
  52
  53         Arguments:
  54
  55         url -- The URL provided by the user.
  56
  57     pre_format_html_hook(url, html)
  58         Rewrite the body of a document before it's formatted.
  59
  60         This function should return a string for ELinks to format, or None
  61         if ELinks should format the original document body. It can be used
  62         to repair bad HTML, alter the layout or colors of a document, etc.
  63
  64         Arguments:
  65
  66         url -- The URL of the document.
  67         html -- The body of the document.
  68
  69     proxy_for_hook(url)
  70         Determine what proxy server to use for a given URL.
  71
  72         This function should return a string of the form "hostname:portnumber"
  73         identifying a proxy server to use, or an empty string if the request
  74         shouldn't use any proxy server, or None if ELinks should use its
  75         default proxy server.
  76
  77         Arguments:
  78
  79         url -- The URL that is about to be followed.
  80
  81     quit_hook()
  82         Clean up before ELinks exits.
  83
  84         This function should handle any clean-up tasks that need to be
  85         performed before ELinks exits. Its return value is ignored.
  86
  87 ------------------------------------------------------------------------------
  88
  89 MODULE
  90     elinks - Interface to the ELinks web browser.
  91
  92 DESCRIPTION
  93     Functions:
  94
  95     bind_key() -- Bind a keystroke to a callable object.
  96     current_document() -- Return the body of the document being viewed.
  97     current_header() -- Return the header of the document being viewed.
  98     current_link_url() -- Return the URL of the currently selected link.
  99     current_title() -- Return the title of the document being viewed.
 100     current_url() -- Return the URL of the document being viewed.
 101     info_box() -- Display information to the user.
 102     input_box() -- Prompt for user input.
 103     load() -- Load a document into the ELinks cache.
 104     menu() -- Display a menu.
 105     open() -- View a document.
 106
 107     Exception classes:
 108
 109     error -- Errors internal to ELinks.
 110
 111     Other public objects:
 112
 113     home -- A string containing the pathname of the ~/.elinks directory, or
 114             None if ELinks has no configuration directory.
 115
 116 FUNCTIONS
 117     bind_key(...)
 118         bind_key(keystroke, callback[, keymap]) -> None
 119
 120         Bind a keystroke to a callable object.
 121
 122         Arguments:
 123
 124         keystroke -- A string containing a keystroke. The syntax for
 125                 keystrokes is described in the elinkskeys(5) man page.
 126         callback -- A callable object to be called when the keystroke is
 127                 typed. It will be called without any arguments.
 128
 129         Optional arguments:
 130
 131         keymap -- A string containing the name of a keymap. Valid keymap
 132                   names can be found in the elinkskeys(5) man page. By
 133                   default the "main" keymap is used.
 134
 135     current_document(...)
 136         current_document() -> string or None
 137
 138         If a document is being viewed, return its body; otherwise return None.
 139
 140     current_header(...)
 141         current_header() -> string or None
 142
 143         If a document is being viewed and it has a header, return the header;
 144         otherwise return None.
 145
 146     current_link_url(...)
 147         current_link_url() -> string or None
 148
 149         If a link is selected, return its URL; otherwise return None.
 150
 151     current_title(...)
 152         current_title() -> string or None
 153
 154         If a document is being viewed, return its title; otherwise return None.
 155
 156     current_url(...)
 157         current_url() -> string or None
 158
 159         If a document is being viewed, return its URL; otherwise return None.
 160
 161     info_box(...)
 162         info_box(text[, title]) -> None
 163
 164         Display information to the user in a dialog box.
 165
 166         Arguments:
 167
 168         text -- The text to be displayed in the dialog box. This argument can
 169                 be a string or any object that has a string representation as
 170                 returned by str(object).
 171
 172         Optional arguments:
 173
 174         title -- A string containing a title for the dialog box. By default
 175                 the string "Info" is used.
 176
 177     input_box(...)
 178         input_box(prompt, callback, title="User dialog", initial="") -> None
 179
 180         Display a dialog box to prompt for user input.
 181
 182         Arguments:
 183
 184         prompt -- A string containing a prompt for the dialog box.
 185         callback -- A callable object to be called after the dialog is
 186                 finished. It will be called with a single argument, which
 187                 will be either a string provided by the user or else None
 188                 if the user canceled the dialog.
 189
 190         Optional keyword arguments:
 191
 192         title -- A string containing a title for the dialog box. By default
 193                 the string "User dialog" is used.
 194         initial -- A string containing an initial value for the text entry
 195                 field. By default the entry field is initially empty.
 196
 197     load(...)
 198         load(url, callback) -> None
 199
 200         Load a document into the ELinks cache and pass its contents to a
 201         callable object.
 202
 203         Arguments:
 204
 205         url -- A string containing the URL to load.
 206         callback -- A callable object to be called after the document has
 207                 been loaded. It will be called with two arguments: the first
 208                 will be a string representing the document's header, or None
 209                 if it has no header; the second will be a string representing
 210                 the document's body, or None if it has no body.
 211
 212     menu(...)
 213         menu(items[, type]) -> None
 214
 215         Display a menu.
 216
 217         Arguments:
 218
 219         items -- A sequence of tuples. Each tuple must have two elements: a
 220                 string containing the name of a menu item, and a callable
 221                 object that will be called without any arguments if the user
 222                 selects that menu item.
 223
 224         Optional arguments:
 225
 226         type -- A constant specifying the type of menu to display. By default
 227                 the menu is displayed at the top of the screen, but if this
 228                 argument's value is the constant elinks.MENU_TAB then the menu
 229                 is displayed in the same location as the ELinks tab menu. If
 230                 its value is the constant elinks.MENU_LINK then the menu is
 231                 displayed in the same location as the ELinks link menu and is
 232                 not displayed unless a link is currently selected.
 233
 234     open(...)
 235         open(url, new_tab=False, background=False) -> None
 236
 237         View a document in either the current tab or a new tab.
 238
 239         Arguments:
 240
 241         url -- A string containing the URL to view.
 242
 243         Optional keyword arguments:
 244
 245         new_tab -- By default the URL is opened in the current tab. If this
 246                 argument's value is the boolean True then the URL is instead
 247                 opened in a new tab.
 248         background -- By default a new tab is opened in the foreground. If
 249                 this argument's value is the boolean True then a new tab is
 250                 instead opened in the background. This argument is ignored
 251                 unless new_tab's value is True.
 252