zsh: MIME Functions
26.8 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 ARGUMENTS ...
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
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 man page mailcap(4).
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.
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.
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.
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
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 :A
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.
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.
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.
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.
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.
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.
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.
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.
The order of files (entries in the mailcap style) read.
Earlier files are preferred. (Note this does not
resolve entries in the same file.)
The priority flag from the mailcap entry. The priority
is an integer from 0 to 9 with the default value being 5.
The test given by the mailcap-prio-flags option is used
to resolve entries.
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.
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.
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
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).
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.
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. )
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:
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
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
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
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.
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
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.
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.