MIME Functions (zsh)

### 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.