26.9 MIME Functions

Three functions are available to provide handling of files recognised by extension, for example to dispatch a file text.ps when executed as a command to an appropriate viewer.

zsh-mime-setup [ -fv ] [ -l [ suffix ... ] ]
zsh-mime-handler [ -l ] command argument ...

These two functions use the files ~/.mime.types and /etc/mime.types, which associate types and extensions, as well as ~/.mailcap and /etc/mailcap files, which associate types and the programs that handle them. These are provided on many systems with the Multimedia Internet Mail Extensions.

To enable the system, the function zsh-mime-setup should be autoloaded and run. This allows files with extensions to be treated as executable; such files be completed by the function completion system. The function zsh-mime-handler should not need to be called by the user.

The system works by setting up suffix aliases with ‘alias -s’. Suffix aliases already installed by the user will not be overwritten.

For suffixes defined in lower case, upper case variants will also automatically be handled (e.g. PDF is automatically handled if handling for the suffix pdf is defined), but not vice versa.

Repeated calls to zsh-mime-setup do not override the existing mapping between suffixes and executable files unless the option -f is given. Note, however, that this does not override existing suffix aliases assigned to handlers other than zsh-mime-handler.

Calling zsh-mime-setup with the option -l lists the existing mappings without altering them. Suffixes to list (which may contain pattern characters that should be quoted from immediate interpretation on the command line) may be given as additional arguments, otherwise all suffixes are listed.

Calling zsh-mime-setup with the option -v causes verbose output to be shown during the setup operation.

The system respects the mailcap flags needsterminal and copiousoutput; see mailcap(4) or mailcap(5) (the man page’s name varies across platforms).

The functions use the following styles, which are defined with the zstyle builtin command (The zsh/zutil Module). They should be defined before zsh-mime-setup is run. The contexts used all start with :mime:, with additional components in some cases. It is recommended that a trailing * (suitably quoted) be appended to style patterns in case the system is extended in future. Some examples are given below.

For files that have multiple suffixes, e.g. .pdf.gz, where the context includes the suffix it will be looked up starting with the longest possible suffix until a match for the style is found. For example, if .pdf.gz produces a match for the handler, that will be used; otherwise the handler for .gz will be used. Note that, owing to the way suffix aliases work, it is always required that there be a handler for the shortest possible suffix, so in this example .pdf.gz can only be handled if .gz is also handled (though not necessarily in the same way). Alternatively, if no handling for .gz on its own is needed, simply adding the command

alias -s gz=zsh-mime-handler

to the initialisation code is sufficient; .gz will not be handled on its own, but may be in combination with other suffixes.

current-shell

If this boolean style is true, the mailcap handler for the context in question is run using the eval builtin instead of by starting a new sh process. This is more efficient, but may not work in the occasional cases where the mailcap handler uses strict POSIX syntax.

disown

If this boolean style is true, mailcap handlers started in the background will be disowned, i.e. not subject to job control within the parent shell. Such handlers nearly always produce their own windows, so the only likely harmful side effect of setting the style is that it becomes harder to kill jobs from within the shell.

execute-as-is

This style gives a list of patterns to be matched against files passed for execution with a handler program. If the file matches the pattern, the entire command line is executed in its current form, with no handler. This is useful for files which might have suffixes but nonetheless be executable in their own right. If the style is not set, the pattern *(*) *(/) is used; hence executable files are executed directly and not passed to a handler, and the option AUTO_CD may be used to change to directories that happen to have MIME suffixes.

execute-never

This style is useful in combination with execute-as-is. It is set to an array of patterns corresponding to full paths to files that should never be treated as executable, even if the file passed to the MIME handler matches execute-as-is. This is useful for file systems that don’t handle execute permission or that contain executables from another operating system. For example, if /mnt/windows is a Windows mount, then

zstyle ':mime:*' execute-never '/mnt/windows/*'

will ensure that any files found in that area will be executed as MIME types even if they are executable. As this example shows, the complete file name is matched against the pattern, regardless of how the file was passed to the handler. The file is resolved to a full path using the :P modifier described in Modifiers; this means that symbolic links are resolved where possible, so that links into other file systems behave in the correct fashion.

file-path

Used if the style find-file-in-path is true for the same context. Set to an array of directories that are used for searching for the file to be handled; the default is the command path given by the special parameter path. The shell option PATH_DIRS is respected; if that is set, the appropriate path will be searched even if the name of the file to be handled as it appears on the command line contains a ‘/’. The full context is :mime:.suffix:, as described for the style handler.

find-file-in-path

If set, allows files whose names do not contain absolute paths to be searched for in the command path or the path specified by the file-path style. If the file is not found in the path, it is looked for locally (whether or not the current directory is in the path); if it is not found locally, the handler will abort unless the handle-nonexistent style is set. Files found in the path are tested as described for the style execute-as-is. The full context is :mime:.suffix:, as described for the style handler.

flags

Defines flags to go with a handler; the context is as for the handler style, and the format is as for the flags in mailcap.

handle-nonexistent

By default, arguments that don’t correspond to files are not passed to the MIME handler in order to prevent it from intercepting commands found in the path that happen to have suffixes. This style may be set to an array of extended glob patterns for arguments that will be passed to the handler even if they don’t exist. If it is not explicitly set it defaults to [[:alpha:]]#:/* which allows URLs to be passed to the MIME handler even though they don’t exist in that format in the file system. The full context is :mime:.suffix:, as described for the style handler.

handler

Specifies a handler for a suffix; the suffix is given by the context as :mime:.suffix:, and the format of the handler is exactly that in mailcap. Note in particular the ‘.’ and trailing colon to distinguish this use of the context. This overrides any handler specified by the mailcap files. If the handler requires a terminal, the flags style should be set to include the word needsterminal, or if the output is to be displayed through a pager (but not if the handler is itself a pager), it should include copiousoutput.

mailcap

A list of files in the format of ~/.mailcap and /etc/mailcap to be read during setup, replacing the default list which consists of those two files. The context is :mime:. A + in the list will be replaced by the default files.

mailcap-priorities

This style is used to resolve multiple mailcap entries for the same MIME type. It consists of an array of the following elements, in descending order of priority; later entries will be used if earlier entries are unable to resolve the entries being compared. If none of the tests resolve the entries, the first entry encountered is retained.

files

The order of files (entries in the mailcap style) read. Earlier files are preferred. (Note this does not resolve entries in the same file.)

priority

The priority flag from the mailcap entry. The priority is an integer from 0 to 9 with the default value being 5.

flags

The test given by the mailcap-prio-flags option is used to resolve entries.

place

Later entries are preferred; as the entries are strictly ordered, this test always succeeds.

Note that as this style is handled during initialisation, the context is always :mime:, with no discrimination by suffix.

mailcap-prio-flags

This style is used when the keyword flags is encountered in the list of tests specified by the mailcap-priorities style. It should be set to a list of patterns, each of which is tested against the flags specified in the mailcap entry (in other words, the sets of assignments found with some entries in the mailcap file). Earlier patterns in the list are preferred to later ones, and matched patterns are preferred to unmatched ones.

mime-types

A list of files in the format of ~/.mime.types and /etc/mime.types to be read during setup, replacing the default list which consists of those two files. The context is :mime:. A + in the list will be replaced by the default files.

never-background

If this boolean style is set, the handler for the given context is always run in the foreground, even if the flags provided in the mailcap entry suggest it need not be (for example, it doesn’t require a terminal).

pager

If set, will be used instead of $PAGER or more to handle suffixes where the copiousoutput flag is set. The context is as for handler, i.e. :mime:.suffix: for handling a file with the given suffix.

Examples:

zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap
zstyle ':mime:.txt:' handler less %s
zstyle ':mime:.txt:' flags needsterminal

When zsh-mime-setup is subsequently run, it will look for mailcap entries in the two files given. Files of suffix .txt will be handled by running ‘less file.txt’. The flag needsterminal is set to show that this program must run attached to a terminal.

As there are several steps to dispatching a command, the following should be checked if attempting to execute a file by extension .ext does not have the expected effect.

The command ‘alias -s ext’ should show ‘ps=zsh-mime-handler’. If it shows something else, another suffix alias was already installed and was not overwritten. If it shows nothing, no handler was installed: this is most likely because no handler was found in the .mime.types and mailcap combination for .ext files. In that case, appropriate handling should be added to ~/.mime.types and mailcap.

If the extension is handled by zsh-mime-handler but the file is not opened correctly, either the handler defined for the type is incorrect, or the flags associated with it are in appropriate. Running zsh-mime-setup -l will show the handler and, if there are any, the flags. A %s in the handler is replaced by the file (suitably quoted if necessary). Check that the handler program listed lists and can be run in the way shown. Also check that the flags needsterminal or copiousoutput are set if the handler needs to be run under a terminal; the second flag is used if the output should be sent to a pager. An example of a suitable mailcap entry for such a program is:

text/html; /usr/bin/lynx '%s'; needsterminal

Running ‘zsh-mime-handler -l command line’ prints the command line that would be executed, simplified to remove the effect of any flags, and quoted so that the output can be run as a complete zsh command line. This is used by the completion system to decide how to complete after a file handled by zsh-mime-setup.

pick-web-browser

This function is separate from the two MIME functions described above and can be assigned directly to a suffix:

autoload -U pick-web-browser
alias -s html=pick-web-browser

It is provided as an intelligent front end to dispatch a web browser. It may be run as either a function or a shell script. The status 255 is returned if no browser could be started.

Various styles are available to customize the choice of browsers:

browser-style

The value of the style is an array giving preferences in decreasing order for the type of browser to use. The values of elements may be

running

Use a GUI browser that is already running when an X Window display is available. The browsers listed in the x-browsers style are tried in order until one is found; if it is, the file will be displayed in that browser, so the user may need to check whether it has appeared. If no running browser is found, one is not started. Browsers other than Firefox, Opera and Konqueror are assumed to understand the Mozilla syntax for opening a URL remotely.

x

Start a new GUI browser when an X Window display is available. Search for the availability of one of the browsers listed in the x-browsers style and start the first one that is found. No check is made for an already running browser.

tty

Start a terminal-based browser. Search for the availability of one of the browsers listed in the tty-browsers style and start the first one that is found.

If the style is not set the default running x tty is used.

x-browsers

An array in decreasing order of preference of browsers to use when running under the X Window System. The array consists of the command name under which to start the browser. They are looked up in the context :mime: (which may be extended in future, so appending ‘*’ is recommended). For example,

zstyle ':mime:*' x-browsers opera konqueror firefox

specifies that pick-web-browser should first look for a running instance of Opera, Konqueror or Firefox, in that order, and if it fails to find any should attempt to start Opera. The default is firefox mozilla netscape opera konqueror.

tty-browsers

An array similar to x-browsers, except that it gives browsers to use when no X Window display is available. The default is elinks links lynx.

command

If it is set this style is used to pick the command used to open a page for a browser. The context is :mime:browser:new:$browser: to start a new browser or :mime:browser:running:$browser: to open a URL in a browser already running on the current X display, where $browser is the value matched in the x-browsers or tty-browsers style. The escape sequence %b in the style’s value will be replaced by the browser, while %u will be replaced by the URL. If the style is not set, the default for all new instances is equivalent to %b %u and the defaults for using running browsers are equivalent to the values kfmclient openURL %u for Konqueror, firefox -new-tab %u for Firefox, opera -newpage %u for Opera, and %b -remote "openUrl(%u)" for all others.