Rappture Perl API
Perl bindings to the Rappture Development Toolkit.
Summary:
use Rappture;
RpLibrary Class
This module provides an interface to Rappture I/O (RpLibrary) library.
Constructor
$library = Rappture::RpLibrary?->new( $path )
Methods
$library->get( $path )
$library->put( $path, $value, $append )
$library->putFile( $path, $fileName, $compress, $append )
$library->result( )
Rappture::RpUnits Class
This module provides an interface to Rappture Units (RpUnits) library.
Static Methods
Rappture::RpUnits::convert( $fromVal, $to, $showUnits )
Rappture::Utils Module
This module provides an interface to Rappture Utils Module.
Static Methods
Rappture::Utils::progress( $value, $message )
Detail:
Rappture::RpLibrary?->new ($path)
Purpose:
Create a Rappture I/O object using the xml file located at $path as the object reference.
Input Arguments:
- $path - path of xml file to be opened with Rappture.
Return Value:
Rappture I/O object referencing $path as its library.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
use Rappture;
my $lib = Rappture::RpLibrary->new("driver.xml");
if (not defined $lib) {
print "creation of library successful\n";
} else {
print "creation of library failed\n";
}
print "lib = $lib";
# $lib->delete;
# Result:
# creation of library successful
# lib = Rappture::RpLibrary=SCALAR(0x1bd9060)
instance->get( $path )
Purpose:
Retrieves the data held at location $path from the rappture object.
Input Arguments:
- $path - xml path (location) of the element to be retrieved.
Return Value:
String representation of the data at path within the rappture object.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
use Rappture;
my $lib = Rappture::RpLibrary->new("driver.xml");
my $Ef = $lib->get("input.number(Ef).current");
print "Ef = $Ef";
# Result:
# Ef = 3eV
instance->put( $path, $value, $append )
Purpose:
Place data $value into this object at the xml location $path. If the $append flag is set to 1, then $value will be appended to data that already exists at path. If the $append flag is set to 0, then $value will overwrite data that may have existed at path.
Input Arguments:
- $path - xml path (location) to store value.
- $value - data to store in this object.
- $append' - overwrite flag (1 or 0). if set to 0, data at $path will be overwritten. if set to 1, data will be appended.
Return Value:
No value is returned.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
use Rappture;
my $lib = Rappture::RpLibrary->new("driver.xml");
print "Overwrite:\n";
$lib->put("input.number(Ef).current", "6", 0);
my $Ef = $lib->get("input.number(Ef).current");
print "Ef = $Ef";
print "\n";
print "Append:\n";
$lib->put("input.number(Ef).current", "eV", 1);
$Ef = $lib->get("input.number(Ef).current");
print "Ef = $Ef";
# Result:
#
# Overwrite:
# Ef = 6
#
# Append:
# Ef = 6eV
instance->putFile( $path, $fileName, $compress, $append )
Purpose:
Place data from file $fileName into this object at the xml location $path. If the $compress flag is set to 1, the data will be gzip compressed and base64 encoded. If the $append flag is set to 1, then $value will be appended to data that already exists at path. If the $append flag is set to 0, then $value will overwrite data that may have existed at path.
Input Arguments:
- $path - xml path (location) to store value.
- $fileName - name of the file to store in this object.
- $compress - flag (1 or 0). if set to 1, file data will be gzip compressed and base64 encoded.
- $append - overwrite flag (1 or 0). if set to 0, data at $path will be overwritten. if set to 1, data will be appended.
Return Value:
No value is returned.
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
#
# temp.jpg is a JPEG image file
use Rappture;
my $lib = Rappture::RpLibrary->new("driver.xml");
$lib->putFile("input.image.current", "temp.jpg", 1, 0);
instance->result( )
Purpose:
Write the data from the Rappture Library object instance to file and signal the end of processing to the graphical user interface.
Input Arguments:
None
Return Value:
None
# Contents of driver.xml
# <run>
# <input>
# <number id="Ef">
# <units>eV</units>
# <min>-10eV</min>
# <max>10eV</max>
# <default>0eV</default>
# <current>3eV</current>
# </number>
# </input>
# </run>
use Rappture;
my $lib = Rappture::RpLibrary->new("driver.xml");
$lib->result();
Rappture::RpUnits::convert( $fromVal, $to, $showUnits )
Purpose:
Convert a string, ($fromVal) containing a numeric value and option units, to the units specified in the second argument ($to).
Input Arguments:
- $fromVal - String with numeric portion and optional units (ie. "3m" or "3").
- $to - String name of the units you want to convert to.
- $showUnits - String "1" or "0" to tell if you want units to show up in the result.
Return Value:
Return converted value as a string. Return undef on failure. $showUnits are set to on ("1") by default.
Notes:
None.
use Rappture;
$result = Rappture::RpUnits::convert( "3cm", "m" )
# result is "0.03m"
$result = Rappture::RpUnits::convert( "300K", "F", "0" )
# result is "80.329999999999998"
$result = Rappture::RpUnits::convert( "3cm", "A" )
# result is "3e+08A"
$result = Rappture::RpUnits::convert( "3", "m" )
# result is "3m"
$result = Rappture::RpUnits::convert( "3", "m", "0" )
# result is "3.0"
Rappture::Utils::progress( $value, $message )
Purpose:
Print a progress percentage and message on the screen during simulation.
Input Arguments:
- $value - Percentage to display. Value between 0 and 100.
- $message - Comment associated with $value.
Return Value:
None.
Notes:
None.
use Rappture;
Rappture::Utils::progress(45,"Iterating...");
