=head1 NAME 

GRID::Machine::Core - Module loaded when bootstraping the remote Perl server

=head1 DESCRIPTION

The creation of a C<GRID::Machine> object through a call to C<GRID::Machine-E<gt>new>
implies the loading of a I<Remote Module> called  C<GRID::Machine::Core> which is delivered
with the C<GRID::Machine> distribution. Another module that is being I<included> at 
construction time is C<GRID::Machine::RIOHandle>.

One of the final goals of the C<GRID::Machine::Core> remote 
module is to provide homonymous methods per each of the Perl
C<CORE::> functions. At present time only a few are supported.


The following functions defined in the Remote Module C<GRID::Machine::Core> are loaded
via the C<include> mechanism on the remote machine. Therefore, they work as methods of the
C<GRID::Machine> object on the local machine. They perform the same operations than their Perl
aliases:

=head2 Function C<getcwd>

=head2 Function C<chdir>

=head2 Function C<umask>

=head2 Function C<mkdir>

=head2 Function C<system>

=head2 Function C<glob>

=head2 Function C<tar>

Is equivalent to:

            system('tar', $options, ,'-f', $file)

Where C<$options> is a string containing the options.
Returns the error code from C<tar>.
Example:

  $m->tar($dist, '-xz')->ok or warn "$host: Can't extract files from $dist\n";

=head2 Function C<version>

Syntax:

              $machine->version('Some::Module')

Returns the VERSION of the module if the given module is installed on the remote machine
and has a VERSION number. 

See an example of use:

  $ cat version.pl
  #!/usr/bin/perl -w
  use strict;
  use GRID::Machine;
  use Data::Dumper;

  my $host = $ENV{GRID_REMOTE_MACHINE} ||shift;

  my $machine = GRID::Machine->new(host => $host,);

  print Dumper($machine->version('Data::Dumper'));
  print Dumper($machine->version('Does::Not::Exist::Yet'));

When executed the program produces an  output similar to this:

  $ version.pl
  $VAR1 = bless( {
                   'stderr' => '',
                   'errmsg' => '',
                   'type' => 'RETURNED',
                   'stdout' => '',
                   'errcode' => 0,
                   'results' => [ '2.121_08' ]
                 }, 'GRID::Machine::Result' );
  $VAR1 = bless( {
                   'stderr' => 'Can\'t locate Does/Not/Exist/Yet.pm in @INC \
                                (@INC contains: /etc/perl /usr/local/lib/perl/5.8.8 ...
                                BEGIN failed--compilation aborted.
                               ',
                   'errmsg' => '',
                   'type' => 'RETURNED',
                   'stdout' => '',
                   'errcode' => 0,
                   'results' => [ '' ]
                 }, 'GRID::Machine::Result' );


=head2 Function C<installed>

Syntax:

              $machine->installed('Some::Module')

Returns TRUE if the given module is installed on the remote machine.
Is equivalent to:

            system("$^X -M$module -e 0")

=head2 File Status Methods

Methods that are equivalent to the tests function

      -r -w -e -x -z -s -f -d  -t -T -B -M -A -C

are provided. Since hyphens aren't legal in Perl identifiers
the hyphen has been substituted by an underscore.
See an example:

  $ cat -n copyandmkdir.pl
     1  #!/usr/local/bin/perl -w
     2  use strict;
     3  use GRID::Machine;
     4
     5  my $host = 'orion.pcg.ull.es';
     6  my $dir = shift || "somedir";
     7  my $file = shift || $0; # By default copy this program
     8
     9  my $machine = GRID::Machine->new(
    10    host => $host,
    11    uses => [qw(Sys::Hostname)],
    12  );
    13
    14  my $r;
    15  $r = $machine->mkdir($dir, 0777) unless $machine->_w($dir);
    16  die "Can't make dir\n" unless $r->ok;
    17  $machine->chdir($dir)->ok or die "Can't change dir\n";
    18  $machine->put([$file]) or die "Can't copy file\n";
    19  print "HOST: ",$machine->eval(" hostname ")->result,"\n",
    20        "DIR: ",$machine->getcwd->result,"\n",
    21        "FILE: ",$machine->glob('*')->result,"\n";


When this program runs we get an output similar to this:

                    $ copyandmkdir.pl
                    HOST: orion
                    DIR: /home/casiano/somedir
                    FILE: copyandmkdir.pl





=head1 AUTHOR

Casiano Rodriguez Leon E<lt>casiano@ull.esE<gt>

=head1 ACKNOWLEDGMENTS

This work has been supported by CEE (FEDER) and the Spanish Ministry of
I<Educación y Ciencia> through I<Plan Nacional I+D+I> number TIN2005-08818-C04-04
(ULL::OPLINK project L<http://www.oplink.ull.es/>). 
Support from Gobierno de Canarias was through GC02210601
(I<Grupos Consolidados>).
The University of La Laguna has also supported my work in many ways
and for many years.

I wish to thank Paul Evans for his C<IPC::PerlSSH> module: it was the source
of inspiration for this module. To Dmitri Kargapolov for his contributions.
To the perl monks, and the Perl Community for generously sharing their knowledge.
Finally, thanks to Juana, Coro and  my students at La Laguna.

=head1 LICENCE AND COPYRIGHT
 
Copyright (c) 2007 Casiano Rodriguez-Leon (casiano@ull.es). All rights reserved.

These modules are free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.
 
This program 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. 




