LUNCH(1)                    General Commands Manual                   LUNCH(1)

NAME
     lunch – open a file or URL with a user's preferred application

SYNOPSIS
     lunch FILE... | URL...
     lunch [-l | -s]
     lunch -g PREFERENCE [ARGUMENTS...]
     lunch -o PREFERENCE [ARGUMENTS...]

DESCRIPTION
     lunch opens files and URLs according to the user's preferences for the
     what should open the given file type or URL type.

     It aims to provide a way of setting a user's preferred applications that
     works with common environment variables such as BROWSER, PAGER and so on,
     rather than as a second system on top of these common mechanisms for
     declaring preferences.

     Configuration is laid out in a simple and easily understood manner, as an
     explicit goal.  No *.desktop files declaring MIME types they support,
     just commands and user-driven selection of them.  Default handlers are
     eschewed in favor delegating all choices to the user.

     The options are as follows:

     -l      List the preferences known by lunch.

     -s      Print a sh(1) script for exporting all preferences as environment
             variables.

                   $ lunch -s
                   export BROWSER="lunch -o browser"
                   export EDITOR="lunch -o editor"
                   export PAGER="lunch -o pager"
                   export TERMINAL="lunch -o terminal"

     -g PREFERENCE [ARGUMENTS...]
             Get the command corresponding to the PREFERENCE in question,
             including any [ARGUMENTS] passed.

     -o PREFERENCE [ARGUMENTS...]
             Open the application corresponding to the PREFERENCE in question,
             with any [ARGUMENTS] passed.

     FILE...
             The file to be opened.

     URL...  The URL to be opened.

   Handlers
     In lunch, handlers are the most important part of configuration.
     Handlers determine how extensions, MIME types, protocols, etc. are are to
     be opened by programs.

     In an attempt to simplify configuration and allow for more flexibility,
     lunch is configured through a file hierarchy, rather than a single file.

     There's various types of handlers:

     •   Executable files (executable handlers).

     •   Text files containing a command to execute (or, static handlers).

     •   Symbolic links (which can be of either of the aforementioned types).

     •   The catch-all handler, of which there may only be one.

     When a FILE or URL is passed to lunch, the protocol, extension, or MIME
     type handlers are checked in this order:

     1.  Protocol handlers, located in $XDG_CONFIG_HOME/lunch/protocol/*.

         For example, given an https:// URL, the existence of
         $XDG_CONFIG_HOME/lunch/protocol/https is checked for.  If it exists,
         that handler is passed the URL.

     2.  Extension handlers, located in $XDG_CONFIG_HOME/lunch/extension/*.

         For example, given a FILE named document.pdf, the existence of
         $XDG_CONFIG_HOME/lunch/extension/pdf is checked for.  If it exists,
         that handler is passed the FILE.

     3.  MIME type handlers, located in $XDG_CONFIG_HOME/lunch/mime/*.

         For example, given a FILE named document.html, lunch checks for:

         1.  $XDG_CONFIG_HOME/lunch/mime/text,

         2.  $XDG_CONFIG_HOME/lunch/mime/text/html, and

         3.  $XDG_CONFIG_HOME/lunch/mime/text/* (literal asterisk).

         Once one of these handlers are found to exist, the search stops, and
         the handler is passed the FILE.

     4.  The catch-all handler, which if it exists, is located at
         $XDG_CONFIG_HOME/lunch/catch-all.

         The catch-all handler is special.  It is only allowed to be an
         executable handler.  Furthermore, it receives not only the file name,
         but also the last handler types checked, and the handler that was
         checked for.

         For example, with a PDF file named document.pdf, MIME type
         application/pdf, the catch-all handler is executed like so:

         $ $XDG_CONFIG_HOME/lunch/catch-all document.pdf mime application/pdf

         If it exits with a non-zero status, or the catch-all does not exist,
         that's considered a fatal error, and lunch dies without opening
         anything else.

         See EXAMPLES for some ideas on using this functionality.

EXAMPLES
   Catch-all handler usage
     The catch-all handler is meant to be generic and not prescribe anything
     about if a catch-all being activated is a failure state or not.  As such,
     this means that it can be both used as an error reporting mechanism, or
     as an opener for when there's no matching handler.

     Loudly reporting errors is useful when configuring lunch.  If you have a
     graphical program that runs lunch when opening things, desktop
     notifications are of more use than errors on standard error.

     So a catch-all like,

     #!/bin/sh

     notify-send -u critical "lunch" "No handler exists for '$1' ($2: '$3')"
     exit 96

     is not a terrible way of doing that.  You could also use the syslog, with
     a similar script, but calling logger(1) instead.

     Another usecase could be passing it to another opener, maybe xdg-open(1)
     itself; however, I would recommend against that, personally.

   Terminal programs
     terminal(1) aims to provide a useful function no other application
     preference utility seems to provide: spawning a terminal program in a new
     terminal only when necessary.

     This means that you can, for example, have EDITOR set to “terminal vi”,
     and when a file is opened from a GUI file manager using your EDITOR as a
     handler, vi(1) will appear in a new terminal window, editing that file.
     And, when ran from within a terminal, it will just run vi(1) like you
     never even ran it with terminal(1).

     Unlike xdg-open(1) and its “Terminal=true” way of setting programs that
     should be ran in a terminal, this method works really well in a mixed
     workflow that includes GUIs and console-based programs since it is aware
     of it is ran from a terminal or not.

SEE ALSO
     exo-open(1), terminal(1), xdg-open(1)

AUTHORS
     Kylie McClain <kylie@somas.is>

Linux 5.4.84-1-lts             January 21, 2021             Linux 5.4.84-1-lts