NAME
    App::Dispatch - Tool to have #! dispatch to the best executable for the
    job.

DESCRIPTION
    Lately it has been a trend to avoid the system install of programming
    languages, Perl, Ruby, Python, etc, in most cases it is recommended that
    you do not use the system perl. A result of this is heavy use of
    "#!/usr/bin/env" to lookup the correct binary to execute based on your
    $PATH. Sometimes though you cannot control your environment as well as
    you would like. You cannot always be sure that the binary in $PATH is
    the one you want.

    App::Dispatch solves the same problem as "/usr/bin/env", but in a way
    that gives you more control. With App::Dispatch you put a configuration
    file in /etc (and optionally your home directory) which allows you
    provide aliases to specific binaries. In your #! line you specify which
    program, and a cascade of aliases to try. If the alias(es) you do not
    want are missing, or the program is missing altogether, it will result
    in an error.

    App::Dispatch also has 2 special aliases 'SYSTEM' which should be used
    to specify which binary is used by the system, and 'DEFAULT' which
    should be used when none is specified. In this way you can have system
    tools with a #! line that is very clear on which binary should run it.

SYNOPSYS
    This #! line will run perl, it will find the 'production' perl, if no
    production perl is found it will try 'DEFAULT'. Anything after the -- is
    passed as arguments to perl.

        #!/usr/local/bin/dispatch perl production DEFAULT -- -w

    This will run the default perl.

        #!/usr/local/bin/dispatch perl

CONFIG FILES
  LOCATIONS
    Locations are loaded in this order. All locations that exist are loaded.
    Later files can override earlier ones.

    /etc/dispatch.conf
        The system wide configuration

    /etc/dispatch/*
        System wide config dir, to have app specific config files for easier
        management with system packages.

    $HOME/.dispatch.conf
        User specific overrides or additions.

  EXAMPLE
        [perl]
            SYSTEM     = /usr/bin/perl
            DEFAULT    = /opt/ACME/current/bin/perl
            production = /opt/ACME/stable/bin/perl

        [gcc]
            SYSTEM  = /usr/bin/gcc
            DEFAULT = /usr/bin/gcc
            old     = /opt/legacy/bin/gcc

NOTE FOR CPAN AUTHORS
    This tool is very useful for perl shops in their own scripts. However it
    most likely should not be used in any scripts that will be installed
    with a cpan distribution. Distributions should use a normal #! line that
    will be rewritten by the build tools to use the perl for which the dist
    was installed. This is important because of dependency chains and XS
    modules.

AUTHORS
    Chad Granum exodist7@gmail.com

COPYRIGHT
    Copyright (C) 2013 Chad Granum

    App-Dispatch is free software; Standard perl licence.

    App-Dispatch is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for
    more details.