From 9954d37a6804488c1b70d6cd361c2b5f22c1b57a Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Thu, 10 Jul 2008 20:31:22 +0300 Subject: [PATCH] Move most of contrib/smjs/README into the manual. Also document elinks.vs and elinks.action. Miciah: IMO most of contrib/smjs/README should be moved into the ELinks manual. Specifically the parts that do not depend on contrib/smjs/hooks.js. However manual.txt contains a notice: "Hold blameless the authors. Any lawful use is allowed." Will you allow that also for what is now in contrib/smjs/README? Absolutely. In fact, I would allow some lawless uses. It seems a little silly to say that lawful uses are allowed. --- contrib/smjs/README | 253 ++--------------------------- doc/manual.txt | 2 + doc/smjs-scripting.txt | 351 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 366 insertions(+), 240 deletions(-) create mode 100644 doc/smjs-scripting.txt diff --git a/contrib/smjs/README b/contrib/smjs/README index 897120de2..dd0121f69 100644 --- a/contrib/smjs/README +++ b/contrib/smjs/README @@ -1,163 +1,15 @@ -Methods -------- +Most of the SpiderMonkey scripting interface is documented in the +ELinks manual. This README describes only features added by +contrib/smjs/*.js. -do_file(path) - Load and evaluate the file with the given path (string). For example: +Multiple functions in the same hook +----------------------------------- - do_file("/home/me/.elinks/hooks.js"); - - will reload your hooks file. - - -elinks.alert(message) - - Display the given message (string) in a message box. For example: - - elinks.alert("Hello, world!"); - - will display a friendly greeting. - - -elinks.execute(command) - - Execute the given command (string) on the current terminal. For example: - - var quoted_uri = "'" + elinks.location.replace(/'/g, "'\\''") + "'"; - elinks.execute("firefox " + quoted_uri); - - will run Firefox with the URI of the current document. - - Note: one must be very careful with elinks.execute, because depending - on the OS, the command may be subject to interpretation by a command shell - language. When constructing the command string, be sure to quote any - dubious parts (such as the URI of the current document, as above). - - -elinks.load_uri(uri, callback) - - Load the given URI (string). When the URI completes loading, ELinks calls - the given callback (function). The callback is passed the cache object - that corresponds to the URI. For example: - - elinks.load_uri("http://www.eldar.org/cgi-bin/fortune.pl?text_format=yes", - function (cached) { elinks.alert(cached.content); }); - - displays a fortune. - - The cache object will not expire until after the callback returns. - - -Properties ----------- - -elinks.home (string) - - ELinks's 'home' directory, where it stores its configuration files. - Read-only. For example, - - do_file(elinks.home + "hooks.js"); - - will reload your hooks file. - - -elinks.location (string) - - The URI of the currently open document. This can be read to get a string - with the URI or set to load a different document. For example, - - elinks.location = elinks.location + "/.."; - - will go up a directory (if the URI doesn't end in a file). - - -elinks.bookmarks (hash) - - This is a hash, the elements of which correspond to the bookmarks. - One can delve into the bookmarks hierarchy in a reasonably nifty - fashion, just by using standard ECMAScript syntax: - - elinks.bookmarks.x.children.y.children.z.children.foo.title - - gets the title of the bookmark titled 'foo' under the folder 'z', - which is a subfolder of 'y', which is a subfolder of 'x'. - - A bookmark object has these properties: - - item.title (string) - - This is the title of the bookmark. It can be read and set. - - item.url (string) - - This is the URI of the bookmark. It can be read and set. - - item.children (hash) - - This is a hash, the elements of which are the bookmarks that - are children to the item. It is read-only. - - -elinks.globhist (hash) - - This is a hash, the elements of which correspond to entries in ELinks's - global history. The hash is indexed by URI. For example, - - elinks.globhist["file:///"] - - will get you the history item for your root directory. - - A history item has these properties: - - item.title (string) - - This is the title of the history item. It can be read and set. - - item.url (string) - - This is the URI of the history item. It can be read and set. - - item.last_visit (number) - - This is the UNIX time of the last visit time for the item. UNIX time - is the number of seconds that have passed between the UNIX epoch (which - is 1970-01-01 00:00:00 UTC) and the represented time. Note that this is - _seconds_ since the epoch, whereas ECMAScript likes to use _milliseconds_ - since the epoch. This property can be set or read. - - -elinks.keybinding (hash) - - This is a hash, the elements of which correspond to ELinks's keymaps. - Currently, there are three: elinks.keybinding.main, elinks.keybinding.edit, - and elinks.keybinding.menu. These elements are also hashes, the elements of - which correspond to bindings. For example, elinks.keymaps.main["q"] is - the binding to the 'q' key in the main map. These bindings can be red, - to get the name of the action to which the key is bound, or set, either - to a string with the name of the ELinks action or to a function, which will - thenceforth be called when the key is pressed. For example, - - elinks.keymaps.main["!"] = function () { elinks.alert("Hello!"); } - - binds the '!' key in the main map to a function that displays a friendly - alert. - - elinks.keymaps.main["/"] = "search-typeahead-text"; - - changes the '/' key to use the nice typeahead search function instead of - opening that ugly old search dialogue box. - - -Hooks ------ - -These are actually properties, but a special case: one assigns functions -to them, which functions are called at certain events. - -Note that the default hooks file assigns functions that provide a mechanism -to register multiple functions to each hook. When these default hooks are -called, they iterate over all functions that are registered to them, calling -each one in serial. +The default hooks file contrib/smjs/hooks.js assigns functions that +provide a mechanism to register multiple functions to each hook. When +these default hooks are called, they iterate over all functions that +are registered to them, calling each one in serial. If you want to register a preformat_html hook, for example, the preferred way to do so is not this: @@ -173,87 +25,8 @@ elinks.preformat_html function will iterate. If any function in that array returns false, the default hook will stop iteration, not calling any more handlers. This applies -to all of the default hooks. +to all of the default hooks: - -elinks.preformat_html(cached, vs) - - This function is called every time a document is loaded, before the document - is actually rendered, to give scripts the opportunity to modify it. The - first parameter is the cache object and the second is the view_state object - (documented below). As explained above, it is preferred to add your hook - to elinks.preformat_html_hooks rather than to assign it to - elinks.preformat_html. - - The cache object will not expire until after this function returns. - - -elinks.goto_url_hook(url) - - This function is called every time the user enters something - in the Go to URL box. The url (string) can be modified or not, - and the returned string is substituted for what the user entered. - If the value false is returned, the URL is not changed and further hooks - in ELinks are not run. As explained above, it is preferred to add your hook - to elinks.goto_url_hooks rather than to assign it to elinks.goto_url_hook. - - -elinks.follow_url_hook(url) - - This function is called every time the user tries to load a document, - whether by following a link, by entering a URI in the Go to URL box, - by setting elinks.location, or whatever. It behaves the same as - elinks.goto_url_hook above. As explained above, it is preferred to add your - hook to elinks.follow_url_hooks rather than to assign it to - elinks.follow_url_hook. - -Other Objects -------------- - -cache - - The cache object mentioned in the descriptions of elinks.load_uri and - elinks.preformat_html is a wrapper for the internal ELinks cache object. - ELinks passes the ECMAScript cache object as an argument to your - ECMAScript function, and keeps the corresponding document in the - cache until the function returns. After that, ELinks may remove the - document from the cache, even if the function has saved the cache - object to some global variable. Such an expired cache object does - not work but it does not crash ELinks either. - - The properties of the cache object are: - - cached.content (string) - - This is the content received from the server. It can be read and set. - - cached.type (string) - - This is the MIME type of the cache entry. It can be read and set. - - cached.length (number) - - This is the length of cached.content. It is read-only. - - cached.head (string) - - This is the header received from the server. It can be read and set. - - cached.uri (string) - - This is the URI of the cache entry. It is read-only. - -view_state - - The view_state object mentioned in the description of elinks.preformat_html - is a wrapper for the internal ELinks view_state object. The view state holds - information on how the current document is being displayed. - - vs.plain (boolean) - - Whether the current document is rendered as HTML or displayed - as plaintext. This can be read and set. - - vs.uri (string) - - This is the URI of the current document. It is read-only. +- elinks.preformat_html_hooks +- elinks.goto_url_hooks +- elinks.follow_url_hooks diff --git a/doc/manual.txt b/doc/manual.txt index ee3af56e8..75f87e8dc 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -59,3 +59,5 @@ include::exmode.txt[] include::bittorrent.txt[] include::lua-scripting.txt[] + +include::smjs-scripting.txt[] diff --git a/doc/smjs-scripting.txt b/doc/smjs-scripting.txt new file mode 100644 index 000000000..440f269ff --- /dev/null +++ b/doc/smjs-scripting.txt @@ -0,0 +1,351 @@ +[[smjs-scripting]] +Scripting ELinks with ECMAScript +-------------------------------- + +As a user of ELinks, you can control its behaviour by writing scripts +in ECMAScript. Unlike <>, these user scripts run with all the permissions of your user +account, the same as with <>. The object model is +very different too. + +Support for ECMAScript user scripts was first added in ELinks 0.11.0. +The `configure` script enables it by default if the required SpiderMonkey +library has been installed, but you can disable it with `configure +\--disable-sm-scripting` or by <>. + +WARNING: ECMAScript scripting is still a bit experimental: there seem to be +ways to crash ELinks with it, and the object model may change. However, if +you don't have a `hooks.js` file, the risk is minimal. + +When ELinks starts up, it evaluates the ECMAScript file `hooks.js` in +your ELinks configuration directory (thus normally `~/.elinks/hooks.js` +on Unix-like systems), or if the file does not exist there, then in +the system-wide ELinks configuration directory (the location depends +on how ELinks was built, but `/etc/elinks/hooks.js` is typical). + +In the ELinks source tree, the `contrib/smjs` directory contains some +examples about scripting ELinks with ECMAScript. Please see the +`README` file in that directory for details. + + +[[smjs-global-object]] +Global Object +~~~~~~~~~~~~~ + +The global object provided to ECMAScript user scripts contains the standard +ECMAScript classes, as well as the following: + + +[[smjs-global-methods]] +Global Object Methods +^^^^^^^^^^^^^^^^^^^^^ + +[[smjs-global.do_file]] do_file(path):: + Load and evaluate the file with the given path (string). For example: ++ +-- +---------------------------------------------------------------------- +do_file("/home/me/.elinks/hooks.js"); +---------------------------------------------------------------------- + +will reload your hooks file. +-- + + +[[smjs-global-properties]] +Global Object Properties +^^^^^^^^^^^^^^^^^^^^^^^^ + +[[smjs-global.elinks]] elinks (elinks):: + A reference to the <>. + + +[[smjs-elinks-object]] +ELinks Object +~~~~~~~~~~~~~ + +The global <> property refers to this object. + + +[[smjs-elinks-methods]] +ELinks Object Methods +^^^^^^^^^^^^^^^^^^^^^ + +[[smjs-elinks.alert]] elinks.alert(message):: + Display the given message (string) in a message box. For example: ++ +-- +---------------------------------------------------------------------- +elinks.alert("Hello, world!"); +---------------------------------------------------------------------- + +will display a friendly greeting. +-- + +[[smjs-elinks.execute]] elinks.execute(command):: + Execute the given command (string) on the current terminal. + For example: ++ +-- +---------------------------------------------------------------------- +var quoted_uri = "'" + elinks.location.replace(/'/g, "'\\''") + "'"; +elinks.execute("firefox " + quoted_uri); +---------------------------------------------------------------------- + +will run Firefox with the URI of the current document. + +WARNING: One must be very careful with 'elinks.execute', because depending +on the OS, the command may be subject to interpretation by a command +shell language. When constructing the command string, be sure to quote +any dubious parts (such as the URI of the current document, as above). +-- + +[[smjs-elinks.load_uri]] elinks.load_uri(uri, callback):: + Load the given URI (string). When the URI completes loading, ELinks + calls the given callback (function). The callback is passed the + <> that corresponds to the URI. + For example: ++ +-- +---------------------------------------------------------------------- +elinks.load_uri("http://www.eldar.org/cgi-bin/fortune.pl?text_format=yes", + function (cached) { elinks.alert(cached.content); }); +---------------------------------------------------------------------- + +displays a fortune. + +The <> will not expire until after the +callback returns. +-- + + +[[smjs-elinks-properties]] +ELinks Object Properties +^^^^^^^^^^^^^^^^^^^^^^^^ + +[[smjs-elinks.home]] elinks.home (string):: + ELinks's ``home'' directory, where it stores its configuration files. + Read-only. For example, ++ +-- +---------------------------------------------------------------------- +do_file(elinks.home + "hooks.js"); +---------------------------------------------------------------------- + +will reload your hooks file. +-- + +[[smjs-elinks.location]] elinks.location (string):: + The URI of the currently open document. This can be read to get a + string with the URI or set to load a different document. + For example, ++ +-- +---------------------------------------------------------------------- +elinks.location = elinks.location + "/.."; +---------------------------------------------------------------------- + +will go up a directory (if the URI doesn't end in a file). +-- + +[[smjs-elinks.bookmarks]] elinks.bookmarks (hash):: + This is a hash, the elements of which correspond to the bookmarks. + One can delve into the bookmarks hierarchy in a reasonably nifty + fashion, just by using standard ECMAScript syntax: ++ +-- +---------------------------------------------------------------------- +elinks.bookmarks.x.children.y.children.z.children.foo.title +---------------------------------------------------------------------- + +gets the title of the bookmark titled ``foo'' under the folder ``z'', +which is a subfolder of ``y'', which is a subfolder of ``x''. + +[[smjs-bookmark-properties]] +A bookmark object has these properties: + +[[smjs-bookmark.title]] item.title (string):: + This is the title of the bookmark. It can be read and set. + +[[smjs-bookmark.url]] item.url (string):: + This is the URI of the bookmark. It can be read and set. + +[[smjs-bookmark.children]] item.children (hash):: + This is a hash, the elements of which are the bookmarks that + are children to the item. It is read-only. +-- + +[[smjs-elinks.globhist]] elinks.globhist (hash):: + This is a hash, the elements of which correspond to entries in ELinks's + global history. The hash is indexed by URI. For example, ++ +-- +---------------------------------------------------------------------- +elinks.globhist["file:///"] +---------------------------------------------------------------------- + +will get you the history item for your root directory. + +[[smjs-global_history_item-properties]] +A history item has these properties: + +[[smjs-global_history_item.title]] item.title (string):: + This is the title of the history item. It can be read and set. + +[[smjs-global_history_item.url]] item.url (string):: + This is the URI of the history item. It can be read and set. + +[[smjs-global_history_item.last_visit]] item.last_visit (number):: + This is the UNIX time of the last visit time for the item. UNIX time + is the number of seconds that have passed between the UNIX epoch + (which is 1970-01-01 00:00:00 UTC) and the represented time. Note that + this is 'seconds' since the epoch, whereas ECMAScript likes to use + 'milliseconds' since the epoch. This property can be set or read. +-- + +[[smjs-elinks.action]] elinks.action (hash):: + This hash lets you call the built-in actions of ELinks. For example, + you can call `elinks.action.auth_manager()` to open the authentication + manager. The names of the actions are the same as in elinks.conf or + in the keybinding manager, except they have underscores instead of + dashes in order to make them valid ECMAScript identifiers. ++ +-- +NOTE: When you read an action function from this hash, ELinks binds it to the +current tab; any later calls to the function affect that tab. This may be +changed in a future version. It is safest to call the function right away, +rather than save it in a variable and call it later. +-- + +[[smjs-elinks.keymaps]] elinks.keymaps (hash):: + This is a hash, the elements of which correspond to ELinks's keymaps. + Currently, there are three: 'elinks.keymaps.main', 'elinks.keymaps.edit', + and 'elinks.keymaps.menu'. These elements are also hashes, the elements of + which correspond to bindings. For example, `elinks.keymaps.main["q"]` is + the binding to the ``q'' key in the main map. These bindings can be red, + to get the name of the action to which the key is bound, or set, either + to a string with the name of the ELinks action or to a function, which will + thenceforth be called when the key is pressed. For example, ++ +-- +---------------------------------------------------------------------- +elinks.keymaps.main["!"] = function () { elinks.alert("Hello!"); } +---------------------------------------------------------------------- + +binds the ``!'' key in the main map to a function that displays a friendly +alert. + +---------------------------------------------------------------------- +elinks.keymaps.main["/"] = "search-typeahead-text"; +---------------------------------------------------------------------- + +changes the ``/'' key to use the nice typeahead search function instead of +opening that ugly old search dialogue box. + +NOTE: Do not read a function from <>, +e.g. `elinks.action.search_typeahead_text`, and place it in a keymap. +ELinks binds such functions to the current tab when the script reads +them from 'elinks.action', so they will not work right in other tabs. +Use the name of the action instead. +-- + +[[smjs-elinks.vs]] elinks.vs (view_state):: + This property refers to the <> for the current document, if any. + + +[[smjs-elinks-hooks]] +ELinks Object Hooks +^^^^^^^^^^^^^^^^^^^ + +These are actually properties, but a special case: one assigns functions +to them, which functions are called at certain events. + +In the ELinks source tree, `contrib/smjs/hooks.js` provides a mechanism +with which multiple scripts can add their functions to the same hooks. +Please see `contrib/smjs/README` for details. + +[[smjs-elinks.preformat_html]] elinks.preformat_html(cached, vs):: + This function is called every time a document is loaded, before the + document is actually rendered, to give scripts the opportunity to + modify it. The first parameter is the <> and the second is the <>. ++ +-- +The <> will not expire until after this +function returns. +-- + +[[smjs-elinks.goto_url_hook]] elinks.goto_url_hook(url):: + This function is called every time the user enters something in the + 'Go to URL' box. The url (string) can be modified or not, and the + returned string is substituted for what the user entered. If the + value `false` is returned, the URL is not changed and further hooks + in ELinks are not run. + +[[smjs-elinks.follow_url_hook]] elinks.follow_url_hook(url):: + This function is called every time the user tries to load a document, + whether by following a link, by entering a URI in the Go to URL box, + by setting <>, or whatever. + It behaves the same as <> + above. + + +[[smjs-cache_entry-object]] +Cache Object +~~~~~~~~~~~~ + +The cache object mentioned in the descriptions of +<> and +<> is a wrapper for the +internal ELinks cache object. ELinks passes the ECMAScript cache object as an +argument to your ECMAScript function, and keeps the corresponding document in +the cache until the function returns. After that, ELinks may remove the +document from the cache, even if the function has saved the cache object to +some global variable. Such an expired cache object does not work but it does +not crash ELinks either. + + +[[smjs-cache_entry-properties]] +Cache Object Properties +^^^^^^^^^^^^^^^^^^^^^^^ + +[[smjs-cache_entry.content]] cached.content (string):: + This is the content received from the server. It can be read and set. + +[[smjs-cache_entry.type]] cached.type (string):: + This is the MIME type of the cache entry. It can be read and set. + +[[smjs-cache_entry.length]] cached.length (number):: + This is the length of cached.content. It is read-only. + +[[smjs-cache_entry.head]] cached.head (string):: + This is the header received from the server. It can be read and set. + +[[smjs-cache_entry.uri]] cached.uri (string):: + This is the URI of the cache entry. It is read-only. + + +[[smjs-view_state-object]] +View-state Object +~~~~~~~~~~~~~~~~~ + +The view-state object mentioned in the descriptions of +<> and +<> is a wrapper for the internal ELinks view_state +object. The view state holds information on how the current document is being +displayed. + + +[[smjs-view_state-properties]] +View-state Object Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +[[smjs.view_state.plain]] vs.plain (boolean):: + Whether the current document is rendered as HTML or displayed + as plaintext. This can be read and set. + +[[smjs.view_state.uri]] vs.uri (string):: + This is the URI of the current document. It is read-only.