NAME

Ifeffit::Demeter::Dispose - OO interface to handling Ifeffit command strings

VERSION

This documentation refers to Ifeffit::Demeter version 0.0.1

SYNOPSIS

  Ifeffit::Demeter->set_mode({ifeffit=>1, buffer=>\@buffer, screen=>1});
  my $data_object = Ifeffit::Demeter::Data -> new();
  $data_object -> dispose($ifeffit_command);

DESCRIPTION

This module contains contains the dispose method, which is used to dispatch Ifeffit command strings to various places. This is part of the base of all other objects in the Demeter system, thus any object can dispose text.

METHODS

`dispose` method

This method dispatches command strings to various places. Most methods in the Demeter system generate text. The intent is that you accumulate text through successive method calls and the dispose of the text using this method. The method takes one argument, a scalar containing all the text that you have accumulates.

Use the set_mode class method to establish the disposal channels.

   Ifeffit::Demeter->set_mode({ifeffit=>1, screen=>1, file=>0, buffer=>0});
   $dataobject -> dispose($commands);

There are four disposal channels:

ifeffit

This channel sends command strings to ifeffit for processing. The value of ifeffit in the hash is interpretted as a boolean.

screen

This channel sends command strings to standard output. The value of screen in the hash is interpretted as a boolean.

file

This channel send command strings to a file. If the value of file evaluates false, then this channel is not used. If it is true, the value is taken to be the name of the output file. At this time, IO control is extremely simple. If you want to append command strings to an existing file, simply append > to the beginning of the file name:

   # clobber foo and start a new file by that name
   Ifeffit::Demeter->set_mode({file=>"foo"});
   $dataobject -> dispose($commands);

   # append to foo
   Ifeffit::Demeter->set_mode({file=>">foo"});
   $dataobject -> dispose($commands);

buffer

This channel pushes each command line onto an in-memory buffer. The buffer can be either a string or an array. The buffer attribute is a reference to the scalar or array.

If a scalar reference is used, the scalar is treated as a string and each command line is concatinated to the end of the string.

   $buffer = q{};
   Ifeffit::Demeter->set_mode({buffer=>\$buffer});
   $dataobject -> dispose($commands);
   print $buffer;

If an array reference is used, each command line is pushed onto the end of the array.

   @buffer = ();
   Ifeffit::Demeter->set_mode({buffer=>\@buffer});
   $dataobject -> dispose($commands);
   map {print $_} @buffer;

other methods

Reset

This method sends the reset command to ifeffit. The method name is capitalized to avoid confusion with the perl built-in function.

cursor

This method sends the cursor command to ifeffit with the show and cross-hair arguments. It returns the x and y coordinates of the cursor click.

   my ($xclick, $yclick) = $dobject->cursor;

Note that this is a blocking operation. Your program will pause until a click event happens in the plot window.

screen_echo

This method sets the value of the Ifeffit program variable &screen_echo. When set to 1, Ifeffit writes its feedback to STDOUT

BUGS AND LIMITATIONS

Currently, nothing is done to capture feedback from Ifeffit. This is a serious shortcoming.

The file disposal channel is handled in the most primitive manner that remains functional. It may be useful to consider using IO::File or something similar. Further, it is only possible to specify a single file for this channel. Something clever with ``tee'' can be done to dispatch to multiple files.

The buffer disposal channel currently only works with normal scalars and normal arrays. It would be reasonable for a user to want the buffer to be, say, a tied array or some special object. I'll deal with that should it ever come up.

The screen disposal channel currently writes to STDOUT. The user can direct STDOUT elsewhere. It may be useful to have the option of specifying a filehandle for this channel.

Please report problems to Bruce Ravel (bravel AT anl DOT gov)

Patches are welcome.

AUTHOR

Bruce Ravel (bravel AT anl DOT gov)

http://cars9.uchicago.edu/~ravel/software/

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See 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.