NAME
    "IPC::PerlSSH" - execute remote perl code over an SSH link

SYNOPSIS
     use IPC::PerlSSH;

     my $ips = IPC::PerlSSH->new( Host => "over.there" );

     $ips->eval( "use POSIX qw( uname )" );
     my @remote_uname = $ips->eval( "uname()" );

     # We can pass arguments
     $ips->eval( 'open FILE, ">", $_[0]; print FILE $_[1]; close FILE;',
                 "foo.txt", "Hello, world!" );

     # We can pre-compile stored procedures
     $ips->store( "get_file", 'local $/; 
                               open FILE, "<", $_[0];
                               $_ = <FILE>;
                               close FILE;
                               return $_;' );
     foreach my $file ( @files ) {
        my $content = $ips->call( "get_file", $file );
        ...
     }

     # We can use existing libraries for remote stored procedures
     $ips->use_library( "FS", qw( readfile ) );
     foreach my $file ( @files ) {
        my $content = $ips->call( "readfile", $file );
        ...
     }

DESCRIPTION
    This module provides an object class that provides a mechanism to
    execute perl code in a remote instance of perl running on another host,
    communicated via an SSH link or similar connection. Where it differs
    from most other IPC modules is that no special software is required on
    the remote end, other than the ability to run perl. In particular, it is
    not required that the "IPC::PerlSSH" module is installed there. Nor are
    any special administrative rights required; any account that has shell
    access and can execute the perl binary on the remote host can use this
    module.

  Argument Passing
    The arguments to, and return values from, remote code are always
    transferred as lists of strings. This has the following effects on
    various types of values:

    *       String values are passed as they stand.

    *       Booleans and integers will become stringified, but will work as
            expected once they reach the other side of the connection.

    *       Floating-point numbers will get converted to a decimal notation,
            which may lose precision.

    *       A single array of strings, or a single hash of string values,
            can be passed by-value as a list, possibly after positional
            arguments:

             $ips->store( 'foo', 'my ( $arg, @list ) = @_; ...' );

             $ips->store( 'bar', 'my %opts = @_; ...' );

    *       No reference value, including IO handles, can be passed; instead
            it will be stringified.

    To pass or return a more complex structure, consider using a module such
    as Storable, which can serialise the structure into a plain string, to
    be deserialised on the remote end. Be aware however, that "Storable" was
    only added to core in perl 5.7.3, so if the remote perl is older, it may
    not be available.

    To work with remote IO handles, see the IPC::PerlSSH::Library::IO
    module.

FUNCTIONS
  $ips = IPC::PerlSSH->new( @args )
    This function returns a new instance of a "IPC::PerlSSH" object. The
    connection can be specified in one of three ways, given in the @args
    list:

    *   Connecting to a named host.

         Host => $hostname

        Optionally passing in the path to the perl binary in the remote host

         Perl => $perl

        Optionally passing in an alternative username

         User => $user

        Optionally specifying a different path to the ssh binary

         SshPath => $path

    *   Running a specified command, connecting to its standard input and
        output.

         Command => $command

        Or

         Command => [ $command, @args ]

    *   Using a given pair of functions as read and write operators.

         Readfunc => \&read, Writefunc => \&write

        Usually this form won't be used in practice; it largely exists to
        assist the test scripts. But since it works, it is included in the
        interface in case the earlier alternatives are not suitable.

        The functions are called as

         read( my $buffer, $len );

         write( $buffer );

        In each case, the returned value should be the number of bytes read
        or written.

    The "Command" key can be used to create an "IPC::PerlSSH" running perl
    directly on the local machine, for example; so that the "remote" perl is
    in fact running locally, but still in its own process.

     my $ips = IPC::PerlSSH->new( Command => $^X );

  @result = $ips->eval( $code, @args )
    This method evaluates code in the remote host, passing arguments and
    returning the result.

    The code should be passed in a string, and is evaluated using a string
    "eval" in the remote host, in list context. If this method is called in
    scalar context, then only the first element of the returned list is
    returned.

    If the remote code threw an exception, then this function propagates it
    as a plain string.

  $ips->store( $name, $code )
  $ips->store( %funcs )
    This method sends code to the remote host to store in named procedure(s)
    which can be executed later. The code should be passed in strings.

    While the code is not executed, it will still be compiled into CODE
    references in the remote host. Any compile errors that occur will be
    throw as exceptions by this method.

    Multiple functions may be passed in a hash, to reduce the number of
    network roundtrips, which may help latency.

  $ips->bind( $name, $code )
    This method is identical to the "store" method, except that the remote
    function will be available as a plain function within the local perl
    program, as a function of the given name in the caller's package.

  @result = $ips->call( $name, @args )
    This method invokes a remote method that has earlier been defined using
    the "store" or "bind" methods. The arguments are passed and the result
    is returned in the same way as with the "eval" method.

    If an exception occurs during execution, it is propagated and thrown by
    this method.

  $ips->use_library( $library, @funcs )
    This method loads a library of code from a module, and stores them to
    the remote perl by calling "store" on each one. The $library name may be
    a full class name, or a name within the "IPC::PerlSSH::Library::" space.

    If the @funcs list is non-empty, then only those named functions are
    stored (analogous to the "use" perl statement). This may be useful in
    large libraries that define many functions, only a few of which are
    actually used.

    For more information, see IPC::PerlSSH::Library.

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

