CHA-URIMETHODMAP(5)

URI method map support in Chawan
Chawan can be used to map unrecognized protocols to known protocols using the urimethodmap format.

The main use case for this is implementing handlers to protocols unknown to Chawan through a protocol that the browser does understand.

  Search path
The search path for urimethodmap files can be overridden using the configuration variable external.urimethodmap.

The default search path for urimethodmap files is:

        $CHA_DIR/urimethodmap:$HOME/.urimethodmap:/etc/urimethodmap

  Format
The urimethodmap format is taken 1:1 from w3m, with some modifications to the interpretation of templates.

A rough attempt at the formal description of this:

        URIMethodMap-File = *URIMethodMap-line
        URIMethodMap-Line = Comment / URIMethodMap-Entry
        URIMethodMap-Entry = Protocol *WHITESPACE Template *WHITESPACE CR
        Protocol = 1*CHAR COLON
        Template = [see below]
        Comment = *WHITESPACE CR / "#" *CHAR CR

Note that an ASCII colon sign (:) must be present after the protocol name. However, the whitespace may be omitted.

Examples:

        # This is ok:
        protocol:	/cgi-bin/interpret-protocol?%s
        # This is ok too:
        protocol:/cgi-bin/interpret-protocol?%s
        # Spaces and tabs are both allowed, so this is also ok:
        protocol:	/cgi-bin/interpret-protocol?%s
        # However, this is incorrect, because the colon sign is missing:
        protocol	/cgi-bin/interpret-protocol?%s

The redirection template is the target URL. If the string %s is contained in the template, it will be replaced by the target URL.

For compatibility with w3m, templates starting with /cgi-bin/ and file:/cgi-bin/ are special-cased and the starting string is replaced with cgi-bin:. So for example, the template /cgi-bin/w3mdict.cgi is the same as cgi-bin:w3mdict.cgi (and so is file:/cgi-bin/w3mdict.cgi).

Example:

        # The following are the same in Chawan
        protocol:	/cgi-bin/interpret-protocol?%s
        protocol:	file:/cgi-bin/interpret-protocol?%s
        # Note: this last entry does not work in w3m.
        protocol:	cgi-bin:interpret-protocol?%s

Note however that absolute paths to cgi scripts are NOT special cased, so e.g. file:///usr/local/libexec/w3m/cgi-bin/w3mdict.cgi will simply open w3mdict.cgi in the file viewer. (Unlike in w3m, where it could run w3mdict.cgi depending on the user’s configuration.)

  Examples
Following lines should be specified in $CHA_DIR/urimethodmap (where $CHA_DIR is either ~/.chawan or ~/.config/chawan depending on where your config.toml is).

  magnet.cgi

        # Use the `magnet.cgi` CGI shell script to pass magnet links to Transmission.
        magnet:		/cgi-bin/magnet.cgi?%s

magnet.cgi can be found in the bonus/ directory. You can also write a local CGI wrapper to pass the links to your BitTorrent client of choice.

  dict
In w3m, urimethodmap is commonly (ab)used to define shorthands for CGI scripts.

This works in Chawan too; for an example, you could define a tl: shorthand like this:

        # (trans.cgi is a script you can find and study in the bonus/ directory.)
        tl:		/cgi-bin/trans.cgi?%s

Then, you could open the translation of any word using tl:word.

Note however that Chawan has a more powerful facility for substitution shorthands like this in the form of omni-rules. So if you want to redirect to an online dictionary site with tl:word instead of providing a local CGI interface, it is easier to just use omni-rules instead of urimethodmap + local CGI redirection.

  See also
cha(1) cha-cgi(5)