wiki:rappture_tcl_api

Rappture TCL API

This page describes how to use Rappture with the Tcl language.

Summary:

    package require Rappture;

Rappture::library

This module provides an interface to Rappture I/O (RpLibrary) library.

Constructor

set lib [Rappture::library <path>]

Methods

$lib element ?-as <fval>? ?<path>?
$lib parent ?-as <fval>? ?<path>?
$lib children ?-as <fval>? ?-type <name>? ?<path>?
$lib get ?-decode yes? ?<path>?
$lib put ?-append yes? ?-type string|file? ?-compress no? ?<path>? <string>
$lib xml

Procedures

Rappture::library isvalid <object>

Rappture::Units

This module provides an interface to Rappture Units library.

Procedures

Rappture::Units::convert <value> ?-context units? ?-to units? ?-units on/off?
Rappture::Units::description <units>
Rappture::Units::System::for <units>
Rappture::Units::System::all <units>

Rappture::encoding

This module provides an interface to Rappture Encoding (zlib and base64 encoding).

Procedures

Rappture::encoding::is binary <value>
Rappture::encoding::encode ?-as z|b64|zb64? ?-no-header? <string>
Rappture::encoding::decode ?-as z|b64|zb64? <string>

Rappture::Utils

This module provides an interface to Rappture Utils Module.

Procedures

Rappture::Utils::progress <value> ?-mesg message?

Module Methods

Rappture::result <lib> ?<status>?

Rappture::library <file>
Rappture::library standard
Rappture::library isvalid <object>

Purpose:

Retrieve an object reference to file
If standard is used in place of the file name, this function returns the standard Rappture library object, which contains material definitions
The isvalid operation checks an <object> to see if it is a valid library object. Returns 1 if so, and 0 otherwise.

Input Arguments:

  1. file - string providing the path to an xml file

Return Value:

Object reference to a Rappture library object

Notes:

  1. On success the return value will be an object reference to a Rappture Library
  2. On failure, tcl error will be raised 
        package require Rappture

        # open the XML file containing the material library
        set lib [Rappture::library standard]

        # open the XML file containing the run parameters
        set opt [Rappture::library [lindex $argv 0]]

        if {[Rappture::library isvalid $lib] != 1} {
            error "$lib is not a valid Rappture Library"
        }

        if {[$opt isa ::Rappture::LibraryObj] == 1} {
            puts "creation of library successful"
        }
        else {
            puts "creation of library failed"
        }

        puts "lib = $lib"

# Result:
#       creation of library successful
#       lib = ::libraryObj0

element ?-as <fval>? ?<path>?

Purpose:

This method searches the Rappture Library Object for the
node at the location described by path and returns its
component name, a concatenation of the type, id, and index.
If path is an empty string, the root of the node is used.

Input Arguments:

  1. fval - type of data to return. By default, this method returns the component name "type(id)". This is changed by setting the -as argument to "id" (for name of the tail element), to "type" (for the type of the tail element), to "object" (for an object representing the DOM node referenced by the path).
  2. path - xml DOM object path.

Return Value:

  1. data about the element being searched. 
#  Example contents of driver.xml file
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#      </input>
#  </run>


package require Rappture
set lib [Rappture::library driver.xml]

set path "input.number(temperature)"

set componentName [$lib element -as component $path]
set idName [$lib element -as id $path]
set typeName [$lib element -as type $path]
set obj [$lib element -as object $path]

puts "componentName = $componentName"
puts "idName = $idName"
puts "typeName = $typeName"
puts "obj = $obj"

#  Result:
#  componentName = number(temperature)
#  idName = temperature
#  typeName = number
#  obj = ::libraryObj1

parent ?-as <fval>? ?<path>?

Purpose:

This method searches the Rappture Library Object for the
parent of the node at the location described by path and
returns its component name, a concatenation of the type, id, and index.
If path is an empty string, the root of the node is used.
It is the same as the element function, except it returns the
parent node.

Input Arguments:

  1. fval - type of data to return. By default, this method returns the component name "type(id)". This is changed by setting the -as argument to "id" (for name of the tail element), to "type" (for the type of the tail element), to "object" (for an object representing the DOM node referenced by the path).
  2. path - xml DOM object path.

Return Value:

  1. data about the parent element being searched. 
#  Example contents of driver.xml file
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#      </input>
#  </run>

package require Rappture
set lib [Rappture::library driver.xml]

set path "input.number(temperature).min"

set componentName [$lib parent -as component $path]
set idName [$lib parent -as id $path]
set typeName [$lib parent -as type $path]
set obj [$lib parent -as object $path]

puts "componentName = $componentName"
puts "idName = $idName"
puts "typeName = $typeName"
puts "obj = $obj"

#  Result:
#  componentName = number(temperature)
#  idName = temperature
#  typeName = number
#  obj = ::libraryObj1

children ?-as <fval>? ?-type <name>? ?<path>?

Purpose:

This method searches the Rappture Library Object for the
children of the node at the location described by path and
returns its component name, a concatenation of the type, id, and index.
If path is an empty string, the root of the node is used.
The user can specify a type of child by using the -type flag

Input Arguments:

  1. fval - type of data to return. By default, this method returns the component name "type(id)". This is changed by setting the -as argument to "id" (for name of the tail element), to "type" (for the type of the tail element), to "object" (for an object representing the DOM node referenced by the path).
  2. name - type name of a child node.
  3. path - xml DOM object path.

Return Value:

  1. list of found child nodes. 
#  Example contents of driver.xml file
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#      </input>
#  </run>

package require Rappture
set lib [Rappture::library driver.xml]

set path "input.number(temperature)"

set clist [$lib children -as component $path]
set typeChild [$lib children -as component -type units $path]

puts "clist = $clist"
puts "typeChild = $typeChild"

/*
  Result:
  clist = units default current
  typeChild = units
*/

get ?-decode yes? ?<path>?

Purpose:

This method retrieves data from path within the Rappture Library Object.
If path is an empty string, the root of the node is used.
The -decode flag is used to specify if compressed/encoded data should be
uncompressed and decoded. The default behavior is to decode all data.

Input Arguments:

  1. decode - should data be uncompressed and decoded, yes or no flag.
  2. path - xml DOM object path.

Return Value:

  1. data located at the node path. 
#  Example contents of driver.xml file
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#          <string id="compressedData">
#              <current>@@RP-ENC:zb64
#  H4sIAAAAAAAAA8vIBACsKpPYAgAAAA==</current>
#          </string>
#      </input>
#  </run>


package require Rappture
set lib [Rappture::library driver.xml]

set path "input.number(temperature).current"
set currentValue [$lib get $path]

set path "input.string(compressedData).current"
set data [$lib get -decode yes $path]
set binEncodedData [$lib get -decode no $path]

puts "currentValue = $currentValue"
puts "data = $data"
puts "binEndodedData = $binEncodedData"

#  Result:
#  currentValue = 300K
#  data = hi
#  binEndodedData = @@RP-ENC:zb64
#  H4sIAAAAAAAAA8vIBACsKpPYAgAAAA==

put ?-append no? ?-type string? ?-compress no? ?<path>? <string>

Purpose:

This method places data into the Rappture Library Object at path.
If path is an empty string, the root of the node is used.
Use the -append flag tells Rappture to add string to any value already
located at path. To easily place a while file into the xml file, set the
-type flag to file and give a filename for the string. This method
also supports gzip compression of data by setting the -compress flag to yes
parent node. The user can specify a type of child by using the -type flag

Input Arguments:

  1. append - specify if Rappture should append or overwrite string to data located at path, yes or no flag.
  2. type - is the data being placed into path a string value, or a file name?
  3. compress - should this data be gzip compressed? yes or no flag.
  4. path - xml path of where to place data inside of the Rappture Object.
  5. string - data to be placed into the Rappture Object.

Return Value:

  1. None 
#  Example contents of driver.xml file
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#      </input>
#  </run>

package require Rappture
set lib [Rappture::library driver.xml]

set path "input.string(data).current"
$lib put $path "hi"

set path "input.string(compressedData).current"
$lib put -compress yes $path "hi"

puts [$lib xml]

#  Result:
#  <?xml version="1.0"?>
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#          <string id="data">
#              <current>hi</current>
#          </string>
#          <string id="compressedData">
#              <current>@@RP-ENC:zb64
#  H4sIAAAAAAAAA8vIBACsKpPYAgAAAA==</current>
#          </string>
#      </input>
#  </run>

xml

Purpose:

This method returns the xml contents of a Rappture Library Object.

Input Arguments:

  1. None

Return Value:

  1. string containing xml contents of the Rappture Library Object 
#  Example contents of driver.xml file
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#      </input>
#  </run>

package require Rappture
set lib [Rappture::library driver.xml]

puts [$lib xml]

#  Result:
#  <?xml version="1.0"?>
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#      </input>
#  </run>

Rappture::result <libraryObj> ?<status>?

Purpose:

Signal to the Rappture Graphical User Interface that processing has completed.
This method automatically writes a run.xml using the xml contents of the
Rappture Library Object libraryObj. Next a signal is sent to the graphical
user interface so the output can be visualized. An optional status argument
can be provided to denote success or failure of the science code.

Input Arguments:

  1. libraryObj - Rappture Library Object holding the output results of the science code.
  2. status - optional integer value denoting success (0) or failure (1) of science code.

Return Value:

  1. The run.xml file is automatically created and a signal is sent to the graphical user interface. 
#  Example contents of driver.xml file
#  <run>
#      <input>
#          <number id="temperature">
#              <units>K</units>
#              <default>300K</default>
#              <current>300K</current>
#          </number>
#      </input>
#  </run>

package require Rappture
set lib [Rappture::library driver.xml]

Rappture::result $lib 0

#  Result:
#    run.xml file is created, graphical user interface is signaled.

Rappture::encoding::is binary <value>

Purpose:

Check if a string or byte sequence contains binary characters

Input Arguments:

  1. binary - check for binary data
  2. <value> - string or byte sequence

Return Value:

Boolean yes or no

Notes: 

% Rappture::encoding::is binary "hi"
no

% set h "H4sIAAAAAAAAA8vIBACsKpPYAgAAAA=="
% set b [Rappture::encoding::decode -as b64 $h]
% Rappture::encoding::is binary $b
yes

Rappture::encoding::encode ?-as z|b64|zb64? ?-no-header? <string>

Purpose:

Encode a string or byte sequence with gzip and/or base64

Input Flags:

  1. -as - optional flag used to specify the type of encoding to use. Rappture can handle the gzip encoding using zlib (z), base 64 encoding (b64) or a combination of gzip and base64 encoding (zb64). When choosing (zb64) order is important. First gzip encoding is performed, then b64 encoding is performed. Default behavior is -as zb64.
  2. -no-header - do not add a header to the returned value. Default behavior is to add a header describing the type of encoding that was performed on the data. The header looks like this: @@RP-ENC:zb64.

Input Arguments:

  1. <string> - string or byte sequence to encode.

Return Value:

Encoded string or byte sequence.

Notes: 

% Rappture::encoding::encode "hi"
@@RP-ENC:zb64
H4sIAAAAAAAAA8vIBACsKpPYAgAAAA==

% Rappture::encoding::encode -as z "hi"
@@RP-ENC:z
ËȬ*“Ø

% Rappture::encoding::encode -as b64 "hi"
@@RP-ENC:b64
aGk=

% Rappture::encoding::encode -as zb64 -no-header "hi"
H4sIAAAAAAAAA8vIBACsKpPYAgAAAA==

Rappture::encoding::decode ?-as z|b64|zb64? <string>

Purpose:

Decode a string or byte sequence that was gzip and/or base64 encoded.

Input Flags:

  1. -as - optional flag used to specify the type of decoding to use. Rappture can handle the gzip decoding using zlib (z), base 64 decoding (b64) or a combination of gzip and base64 decoding (zb64). When choosing (zb64) order is important. First base64 decoding is performed, then gzip decoding is performed. If <string> contains a Rappture::encoding header which does not match the value provided with this flag, no decoding is performed.

Input Arguments:

  1. <string> - string or byte sequence to encode.

Return Value:

Decoded string or byte sequence.

Notes:

If <string> does not have a Rappture::encoding header (ex: @@RP-ENC:zb64) and the -as flag was not provided, no decoding will be performed. 

% set h "@@RP-ENC:zb64\nH4sIAAAAAAAAA8vIBACsKpPYAgAAAA=="
% Rappture::encoding::decode $h
hi

% set h "@@RP-ENC:b64\naGk="
% Rappture::encoding::decode -as b64 $h
hi

# $h's Rappture::encoding header does not match -as flag, Rappture::encoding::decode will not decode
% set h "@@RP-ENC:zb64\nH4sIAAAAAAAAA8vIBACsKpPYAgAAAA=="
% Rappture::encoding::decode -as z $h
@@RP-ENC:zb64
H4sIAAAAAAAAA8vIBACsKpPYAgAAAA==

# $h has no Rappture::encoding header, Rappture::encoding::decode will not decode
% set h "aGk="
% Rappture::encoding::decode $h
aGk=
Last modified 10 years ago Last modified on Apr 29, 2014 6:30:12 AM