| Description | Perl tools for X-ray Absorption Spectroscopy |
Demeter::Dispose - Process Ifeffit, Larch, and plotting command strings
This documentation refers to Demeter version 0.9.26.
my $data_object = Demeter::Data -> new();
$data_object -> set_mode(backend=>1, buffer=>\@buffer, screen=>1);
$data_object -> dispose($ifeffit_command);This module contains contains the dispose method, which is used to dispatch Ifeffit, Larch, and Gunplot command strings. This is part of the base of all other objects in the Demeter system, thus any object can dispose text.
The command strings which are handled by the dispose method are typically generated using the command templating system, which is described in "TEMPLATES" in Demeter.
Command strings are typically generated by Demeter in a manner which is designed to be human readable. Unfortunately, human-readable and Ifeffit-efficient tend to be at odds. In the interest of speed and efficiency, Demeter processes Ifeffit commands into a form that is harder for a human to read, but faster for Ifeffit to process.
The main change made to Ifeffit command strings is to concatinate multi-line commands into a single line and to squeeze white space into a single space. This significantly reduces the number of calls to the iff_exec function in Ifeffit, which is one of the most time-consuming parts of the Demeter/Ifeffit stack. Given that Ifeffit allows command strings to be as much as 2048 characters long, it is rare that an command generated by Demeter cannot be handled in this way.
Also, the preprocessed text does not contain any lines that are only whitespace or are entirely commented out.
disposeThis method dispatches command strings to various places. Many methods in the Demeter system are command generators. The intent is that to accumulate text through successive method calls and then dispose of the text using this method. The method takes two arguments, a scalar containing all the text that you have accumulates, and an optional argument that, when true, indicates that the commands are specifically plotting commands.
Demeter is very careful to segregate plotting commands from data processing commands and to dispose of them separately. This allows transparent use of different plotting backends. The backend disposal channel is used to indicate disposal of commands either to ifeffit or to another plotting backend. That is, if you want to dispose of plotting commands to a gnuplot process, you must have the backend disposal channel enabled. ifeffit and larch are aliases for backend.
Use the set_mode class method to establish the disposal channels.
Demeter->set_mode(backend=>1, screen=>1, file=>0, buffer=>0);
$dataobject -> dispose($commands);When disposing a plotting command, use the plotting flag:
$dataobject -> dispose($commands, "plotting");There are several disposal channels:
This channel sends reprocessed command strings to ifeffit for processing. This is a boolean. By default, this channel is on and all the rest are off.
This channel sends command strings to standard output. This is a boolean. If the UI is set to screen (see Demeter::Mode) and the Term::ANSIColor package is installed, then comments in the screen output will be colored red, pink, or yellow depending on the comment character.
The default colors are:
red data processing comments
pink plotting comments
yellow fitting comments
light blue feedback from Ifeffit/Larch
white on red error messages from Ifeffit/LarchThese colors are configurable in the screen group.
This channel writes 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
$dataobject -> set_mode(file=>"foo");
$dataobject -> dispose($commands);
#
# append to foo
$dataobject -> set_mode(file=>">foo");
$dataobject -> dispose($commands);This behaves exactly like the screen parameter, but applies only to commands disposed using the plotting flag. If the UI is set to screen (see Demeter::Mode) and the Term::ANSIColor package is installed, then comments in the screen output will be colored red, pink, or yellow depending on the comment character.
This behaves exactly like the file parameter, but applies only to commands disposed using the plotting flag. This allows you to accumulate plotting commands into plotting scripts, which is handy for the gnuplot backend.
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{};
$dataobject -> 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 = ();
$dataobject -> set_mode(buffer=>\@buffer);
$dataobject -> dispose($commands);
map {print $_} @buffer;An obvious improvement to this would be to allow the buffer attribute to be a reference to an arbitrary object which can be used in some domain-specific, user-defined manner.
This is an optional output channel for the plotting commands. If unset, plotting commands go to the same channel as specified by buffer. This channel works identically to buffer, albeit redirected to a different place.
This channel sends disposed text to a user supplied code reference. For instance, in Artemis, this is a subroutine that prints the disposed lines to the command buffer. This code ref takes a single argument, which is the text to be disposed.
This optional channel redirects plotting commands to a differnt code reference from callback. If unset, plotting commands are disposed to callback's code ref.
This channel sends feedback from Ifeffit or Larch to a user supplied code reference. Note that lines indicating a problem in Ifeffit's or Larch's output start with a star (*). Information lines start with text.
This channel sends reprocessed command strings to standard output. The value of screen in the hash is interpreted as a boolean. The main use of this channel is to debug the text actually sent to Ifeffit. No colorizing is done because comments are stripped from the reprocessed commands.
This channel send reprocessed command strings to a file. This channel is handled in the same manner as the normal file channel. The main use of this channel is to debug the text actually sent to Ifeffit.
Note that the dispose method is also used to place a copyright statement on every plot. This behavior can be suppressed by setting the plot->showcopyright configuration parameter to a false value.
dispenseThis wraps calls to template and dispose. This:
$self->dispense('process', 'deriv');is the same as
$self->dispose($self->template('process', 'deriv'));which was such a common idiom in Demeter that it merited this method.
chartThis wraps calls to template and to dispose with the plotting argument. This:
$self->chart('process', 'deriv');is the same as
$self->dispose($self->template('process', 'deriv'), 'plotting');which was such a common idiom in Demeter that it merited this method.
ResetThis method sends the reset command to ifeffit. The method name is capitalized to avoid confusion with the perl built-in function.
cursorThis 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) = $object->cursor;Note that this is a blocking operation. Your program will pause until a click event happens in the plot window.
For more information about effecting command generation and disposal, see Demeter::Mode.
See Demeter::Config for a description of the configuration system.
Demeter's dependencies are in the Build.PL file.
The file and repfile disposal channels 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 particular object. That will be dealt with should it ever come up.
The screen, plotscreen, and repscreen disposal channels currently write 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 the Ifeffit Mailing List (http://cars9.uchicago.edu/mailman/listinfo/ifeffit/)
Patches are welcome.
Bruce Ravel, http://bruceravel.github.io/home
http://bruceravel.github.io/demeter/
Copyright (c) 2006-2018 Bruce Ravel (http://bruceravel.github.io/home). All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlgpl.
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.