#pragma section-numbers on
<<TableOfContents(3)>>

The read-url prompt can be configured to transform patterns of input to urls, beyond the simple capabilities of the webjump system.  This configuration is done through ''read-url handlers'', and they take effect when an input to the prompt is neither ''url-like'' nor a webjump.  Input is a webjump when the first token before any inner space is the name of a webjump.  When input is 'url-like' is a subtler question..

= URL-like =

When text is entered at the url prompt, Conkeror needs to decide whether the text should be treated as an url, a webjump, or passed to the read-url handlers.  Deciding what counts as an url is not as trivial as it might appear at first, because if Mozilla is given a string which is not a well-formed url, it will still attempt to resolve it by prepending `http://`, append `.com`, and so on.  The default behavior of read-url is to consider any string as url-like if it does not have any inner spaces before the first '/'.  This behavior can be changed by overriding the function `possibly_valid_url` in your rc.

== possibly_valid_url ==

Here is an alternative version which requires the string to contain either a dot, a slash, or a colon to be considered url-like.  This version works better when you have configured a default webjump because it means a single bare word will not be considered url-like: it allows your default webjump to be called instead.

{{{
function possibly_valid_url (str) {
    return /^\s*[^\/\s]*(\/|\s*$)/.test(str)
        && /[:\/\.]/.test(str);
}
}}}

= read_url_handler_list =

Now that we know when read-url handlers are called, how do we use them?  The variable `read_url_handler_list` is an array of semipredicates.  When the input is neither url-like nor a webjump, the handlers are tried in order until one returns non-null, and that handler's value is taken as the value for the prompt.  This mechanism can be used to extend the url prompt with handlers for special syntaxes, provide a default webjump, or more.  Some utilities are provided for common uses.

== read_url_make_default_webjump_handler ==

This function takes the name of a webjump and returns a read-url handler that transforms the input into a call to that webjump with the given input.  This is how you make a default webjump.

== read_url_make_blank_url_handler ==

This function takes an url as its argument and returns a read-url handler that returns the url if the input is blank.  This allows you to have a default url or javascript bookmarklet for empty input.

= Examples =

In each of the following examples, for sake of completeness, we give a line that assigns an array containing the handler from the particular example to `read_url_handler_list`.  If you want to use more than one read-url handler, then you would provide a different value for this variable — an array containing all of the handlers you want to use.

== Default Webjump ==

{{{
read_url_handler_list = [read_url_make_default_webjump_handler("conkerorwiki")];
}}}

== Google translate ==

This transforms input like "xx|yy foo" into a Google translate url, translating the string "foo" from language code "xx" to language code "yy".  Example: ''la|en semper ubi sub ubi''

{{{
function read_url_google_translate_handler (input) {
    var m = /^(\S+\|\S+)\s+(.*)/.exec(input);
    if (m)
        return "http://translate.google.com/#"+m[1]+"|"+m[2];
    return null;
}
read_url_handler_list = [read_url_google_translate_handler];
}}}