# run analysis 'seqret' using a default location and a default
  # access method (which means using a Web Service at EBI)
  use Bio::Tools::Run::Analysis;
  print new Bio::Tools::Run::Analysis (-name => 'edit::seqret')
       ->wait_for ({ sequence_direct_data => 'tatatacgtatacga',
		     osformat => 'embl'
		     })
       ->result ('outseq');

  # run a longer job without waiting for its completion
  use Bio::Tools::Run::Analysis;
  my $job = Bio::Tools::Run::Analysis->new(-name => 'edit::seqret')
                 ->run ({ sequence_direct_data => 'tatatacgtatacga',
		          osformat => 'embl'
		          });
  # ...and after a while
  $job->result ('outseq');

  # get all results in the same invocation (as a hash reference
  # with result names as keys) - let the module decide which
  # results are binary (images in this examples) and save those
  # in file (or files); it also shows how to tell that the module
  # should read input data from a local file first
  use Bio::Tools::Run::Analysis;
  my $results =
    Bio::Tools::Run::Analysis->new(-name => 'alignment_multiple::prettyplot')
       ->wait_for ( { msf_direct_data => '@/home/testdata/my.seq' } )
       ->results ('?');
  use Data::Dumper;
  print Dumper ($results);

  # get names, types of all inputs and results,
  # get short and detailed (in XML) service description
  use Bio::Tools::Run::Analysis;
  my $service = Bio::Tools::Run::Analysis->new(-name => 'edit::seqret');
  my $hash1 = $service->input_spec;
  my $hash2 = $service->result_spec;
  my $hash3 = $service->analysis_spec;
  my $xml = $service->describe;

  # get current job status
  use Bio::Tools::Run::Analysis;
  print new Bio::Tools::Run::Analysis (-name => 'edit::seqret')
    ->run ( { #...input data...
            } )
    ->status;

  # run a job and print its job ID, keep the job un-destroyed
  use Bio::Tools::Run::Analysis;
  my $job =
    Bio::Tools::Run::Analysis->new(-name => 'edit::seqret',
                                   -destroy_on_exit => 0)
    ->run ( { sequence_direct_data => '@/home/testdata/mzef.seq' } );
  print $job->id . "\n";
  # ...it prints (for example):
  #    edit::seqret/c8ef56:ef535489ac:-7ff4

  # ...in another time, on another planet, you may say
  use Bio::Tools::Run::Analysis;
  my $job =
    Bio::Tools::Run::Analysis::Job->new(-name => 'edit::seqret',
			                -id => 'edit::seqret/c8ef56:ef535489ac:-7ff4');
  print join ("\n",
	    $job->status,
	    'Finished: ' . $job->ended (1),   # (1) means 'formatted'
            'Elapsed time: ' . $job->elapsed,
	    $job->last_event,
	    $job->result ('outseq')
	    );

  # ...or you may achieve the same keeping module
  # Bio::Tools::Run::Analysis::Job invisible
  use Bio::Tools::Run::Analysis;
  my $job =
    Bio::Tools::Run::Analysis->new(-name => 'edit::seqret')
        ->create_job ('edit::seqret/c8ef56:ef535489ac:-7ff4');
  print join ("\n",
	    $job->status,
            # ...
	    );

  # ...and later you may free this job resources
  $job->remove;

  #
  # --- See DESCRIPTION for using generator 'applmaker.pl':
  #

  # this will generate module Seqret.pm
  perl papplmaker.PLS -n edit.seqret -m Seqret

  # ...which can be used with data-specific methods
  use Seqret;
  my $outseq = new Seqret
    ->sequence_direct_data ('@/home/testdata/my.seq')
    ->osformat ('embl')
    ->wait_for
    ->outseq
    ;
  print $outseq;

    $Revision = q[$Id: Analysis.pm 15558 2009-02-21 22:07:57Z maj $];

    my ($caller,@args) = @_;
    my $class = ref($caller) || $caller;
  
    if ($class eq 'Bio::Tools::Run::Analysis') {

	# this is called only the first time when somebody calls: 'new
	# Bio::Tools::Run::Analysis (...)', and it actually loads a 'real-work-doing'
	# module and call this new() method again (unless the loaded
	# module has its own new() method)

	my %param = @args;
	@param { map { lc $_ } keys %param } = values %param; # lowercase keys
	my $access =
	    $param {'-access'} ||                  # use -access parameter
	    &Bio::Tools::Run::Analysis::Utils::_guess_access (\% param ) ||   # or guess from other parameters
	    'soap';                                # or use a default access method
	$access = "\L$access";	# normalize capitalization to lower case

	# remember the access method (putting it into @args means that the
	# object - when created - will remember it)
	push (@args, (-access => $access)) unless $param {'-access'};

	# load module with the real implementation - as defined in $access
	return undef unless (&Bio::Tools::Run::Analysis::Utils::_load_access_module ($access));

	# this calls this same method new() - but now its object part
	# (see the upper branche above) is called
	return "Bio::Tools::Run::Analysis::$access"->new (@args);

    } else {

	# if $caller is an object, or if it is an underlying
	# 'real-work-doing' class (e.g. Bio::Tools::Run::Analysis::soap) then
	# we want to call SUPER to create and bless a new object

	my ($self) = $class->SUPER::new (@args);

	# now the $self is an empty object - we will populate it from
	# the $caller - if $caller is an object (so we do cloning here)

	if (ref ($caller)) {
	    %{ $self } = %{ $caller };
	}

	# and finally add values from '@args' into the newly created
	# object (the values will overwrite the values copied above);
	# this is done by calling '_initialize' of the 'real-work-doing'
	# class (if there is no one there, there is always an empty one
	# in Bio::Root::Root)

	$self->_initialize (@args);
	return $self;
    }

}

#
# Create a hash with named inputs, all extracted 
# from the given data.
#

    my $self = shift;
    my %inputs = ();   # collect here input data

    foreach my $input (@_) {

	next unless defined $input;

	# an element can be an array reference
	# (with scalar elements: 'name = [[@]value]')
	if (ref $input eq 'ARRAY') {
	    foreach my $elem (@$input) {
		unless (ref $elem) {   # taking only scalars
		    my ($name, $value) = split (/\s*=\s*/, $elem, 2);
		    next unless $name;   # am I paranoid ?
		    $value = 1 unless defined $value;
		    $inputs{$name} = $value;
		    next;
		}
	    }
	}

	# ...or an element can be a hash
	# (name => [@]value)
	elsif (ref $input eq 'HASH') {
	    foreach my $name (keys %$input) {
		my $value = $$input{$name};
		$inputs{$name} = $value;
	    }
	}

	# ...or an element can be a scalar (which means that it
	# represents a name of a boolean parameter (an option)
	elsif (ref\$ input eq 'SCALAR') {
	    $input =~ s/^@/\\@/;   # this cannot be a filename
	    $inputs{$input} = 1;
	}

	# everything else is ignored
	else {
	    warn "Unrecognized input data type: $input\n";
	}
    }

    # extracted inputs may be actually filenames and we want the
    # contents of the files instead
    # TBD: to support also filehandlers here?
    foreach my $name (keys %inputs) {
	$inputs{$name} = $self->_read_value ($inputs{$name});
    }
    return\% inputs;
}

# --- if a $value is a filename, read it and return its contents
#     otherwise return the $value itself; if $value start with
#     an escaped '@', change it to a normal '@'

    my ($self, $value) = @_;
    return unless defined $value;
    if ($value =~ s/^\@//) {
	my ($buf);
	open (DATA, $value) || $self->throw ("Cannot read from '$value' ($!)");
	binmode (DATA);
	undef $value;
	while (read (DATA, $buf, 8 * 2**10)) {
	    $value .= $buf;
	}
	close DATA;
    } elsif ($value =~ s/^\\\@/@/) {
    }
    $value;
}

# --- save $value of result $name into file $filename + $seq;
#     use some default filename if $filename not given

#$part = $self->_save_result (-value    => $part,
#			      -name     => $name,
#                             -filename => $filename,
#			      -template => $template,
#			      -seq      => $seq++);

    my ($self, %params) = @_;
    my $name = $params{'-name'} || 'result';

    # invent filename (if not given) from the given or default template
    my $filename = $params{'-filename'};
    unless ($filename) {
	$filename = $params{'-template'};
	$filename = "\$ANALYSIS_*_$name" unless $filename;

	# replace $ANALYSIS and $RESULT in the filename
	if ($filename =~ /\$\{?ANALYSIS\}?/) {
	    # (better to ask if we need it because getting
	    #  the analysis name may require going to server)
	    my $analysis = $self->analysis_name;
	    $analysis =~ s/[:\/]/_/g;  # would be troubles in filename
	    $filename =~ s/\$\{?ANALYSIS\}?/$analysis/ig;
	}
	$filename =~ s/\$\{?RESULT\}?/$name/ig;
    }

    # include the sequential number before file extension (if any)
    my $seq = $params{'-seq'};
    if ($seq) {
	my $pos = rindex ($filename, '.');
	if ($pos > -1) {
	    substr ($filename, $pos, 0) = ".$seq";   # insert $seq
	} else {
            $filename .= ".$seq";   # add $seq
	}
    }

    # replace '*' in filename with a unique number
    while ($filename =~ /\*/) {
        my $unique_name;
	my $number = 1;
	while (1) {
	    ($unique_name = $filename) =~ s/\*/$number/;
	    last unless -e $unique_name;
	    $number++;
	}
	$filename = $unique_name;
    }

    # and finally write the file
    open (DATA, ">$filename") ||
	$self->throw ("Error by saving result '$name' into '$filename' ($!)");
    binmode (DATA);
    print (DATA $params{'-value'}) ||
	$self->throw ("Error by writing result '$name' into '$filename' ($!)");
    close DATA ||
	$self->throw ("Error by closing result '$name' in '$filename' ($!)");

    return $filename;

  bioperl-l@bioperl.org                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

 
Please direct usage questions or support issues to the mailing list:
  
bioperl-l@bioperl.org
  
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.

  http://bugzilla.open-bio.org/

 Usage   : print $Bio::Tools::Run::Analysis::VERSION;
           print $Bio::Tools::Run::Analysis::Revision;