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