NAME
    Perl::Exe - Find the perl executable that is currently running

SYNOPSIS
      # Locate the current perl
      my $perl = Perl::Exe::find;
  
      # Execute something in a child perl
      Perl::Exe::run3( [ '-e', 'print "Hello World!\n";' ] );

DESCRIPTION
    Although Perl provides the $^X variable, which describes the currently
    running application, it is not a reliable cross-platform method to use
    if you wish to execute some delegate the execution of code to a child
    instance of the same Perl interpreter currently running.

    That requires a bit more work, and in a few case some quite esoteric
    tricks.

    The new Perl module build system Module::Build has some quite
    sophisticated code for locating the current Perl.

    Unfortunately, it is not accesible directly (outside of installing a
    module) and it requires you to install an entire build system (with all
    the requisite time, load overhead and risk of failed tests) to answer a
    relatively simple question.

    Perl::Exe is a port of the Module::Build "find_perl_interpreter" method
    into a standalone form. It has also been refactored to simplify the code
    slightly, remove the special cases needed when building inside the Perl
    core, and uses IPC::Run3 instead of the magic platform-sensing
    backtick/forking logic in Module::Build.

    The result is a light-weight module with a very simple API that makes it
    easy to locate, or run something with, the current interpreter.

FUNCTIONS
    For simply future maintenance and improve readability, Perl::Exe
    functions are not exportable into your own namespace.

    However, to make up for this, the functions have been named in an
    exremely readable and straight-forward way (and the module name is
    short) so using the full function names should not be a burdon.

  find
      my $perl = Perl::Exe::find;

    The "Perl::Exe::find" function is the main way to locate the path of the
    current Perl interpreter.

    It takes no parameters, and locates the Perl interpreter, caching the
    result and returning it as a simple string.

    If the current Perl interpreter cannot be located, an exception is
    thrown.

  discover
      my $perl = Perl::Exe::find;

    The "Perl::Exe::discover" function is the direct method for location the
    current Perl interpreter, and contains the bulk of the logic.

    You should only call "Perl::Exe::discover" directly if you intentionally
    want to avoid the cache and make a completely fresh attempt to determine
    the location of the Perl interpreter.

    It takes no parameters, and locates the Perl interpreter, returning the
    path as a simple string and throwing an exception if the interpreter
    cannot be located.

    The "Perl::Exe::discover" function is a direct port of the private
    method Module::Build::Base::_discover_perl_interpreter.

  is
      if ( Perl::Exe::is($path) ) {
         print "The Perl interpreter is $path";
      }

    The "Perl::Exe::is" function can be used to take a suspected path and
    determine if it is the path to the current Perl interpreter.

    Returns true if the path is to the current Perl.

    Returns false (but not undef) if there is no file at that path, of if
    the interpreter's confifiguration does not match that of the current
    Perl.

    Because of the file test, any path to perl must contain the extention
    (such as .exe) if required on the current platform.

  run3
      # Launch a CPAN shell for the current Perl
      Perl::Exe::run3( '-MCPAN -e shell' );
  
      # Capture some generated content
      my $stdout = '';
      Perl::Exe::run3(
          [ '-e', 'print "Hello World!\n";' ],
          undef,    # Inherit STDIN
          \$stdout, # Capture STDOUT
          \undef,   # Discard STDERR
      );

    Because Perl::Exe uses IPC::Run3 internally for some functionality, a
    "Perl::Exe::run3" pass-through function is provided as a convenience.

    Except for the prepending of the path, this function is otherwise
    identical to "IPC::Run3::run3".

    It takes the same paremeters as "IPC::Run3::run3" function, prepending
    the path to the current Perl (to either the string or ARRAY reference
    form of the command) and then hands off to the "IPC::Run3::run3",
    returning the result.

SUPPORT
    Bugs should be reported via the CPAN bug tracker at

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Adapter>

    For other issues, or commercial support, contact the author.

AUTHOR
    Adam Kennedy <adamk@cpan.org>

SEE ALSO
    Module::Build, IPC::Run3

COPYRIGHT
    Copyright 2008 Adam Kennedy.

    Some parts copyright Ken Williams 2001 - 2006.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.