NAME

Pegasus::DAX::Base - base class for all ADAG/DAX related classes.

SYNOPSIS

    use Pegasus::DAX::Base qw(:xml);
    use Exporter;
    our @ISA = qw(Pegasus::DAX::Base Exporter); 

    ...

    sub toXML {
        my $self = shift;
        my $handle = shift;
        my $indent = shift || '';
        my $xmlns = shift; 
        my $tag = defined $xmlns && $xmlns ? "$xmlns:element" : 'element';

        # open tag
        $handle->print( "$indent<$tag",
                      , attribute('key1',$self->{key1})
                      , attribute('key2',boolean($self->{key2}))
                      , ">\n" );

        # child element
        $self->{aggregate}->toXML( $handle, "  $indent", $xmlns );

        # collection of child elements
        foreach my $i ( @{$self->{collection}} ) {
            $i->toXML( $handle, "  $indent", $xmlns );
        }

        # closing tag
        $handle->print( "$indent</$tag>\n" ); 
    }

DESCRIPTION

This module implements the base class for all classes related to generating DAX files. It provides helper functions to generate XML, and mandates that non-abstract child classes implement the toXML method.

In addition, this class provides an AUTOLOAD method, which in effect implements the setter and getter for all scalar values in any child class.

FUNCTIONS

The following section defines true functions, not static methods. If you don't know the difference, you don't need to worry.

quote($string)

This function replaces all characters in the given input $string that require to be entity-escaped. The result is a string that is either the original string, if it did not contain any characters from %escape, or the string with entity replaced characters. This method will return undef, if the input string was undef.

attribute($key,$value)
attribute($key,$value,$xmlns)

This function is a helper for sub-classes that instantiate the abstract toXML method when printing an element tag. Given the $key for an element's attribute, and the $value to put with the element, this method returns the string to be put into the tag assembly.

The result starts with a space, the key as is, the equal sign, a quote character, the value as result of the quote method, and the closing quote character.

If the key is not defined or empty, or the value is not defined, the empty string will be returned.

In the 3-argument form, if the $xmlns argument is defined and true, the attribute will be qualified with the string in $xmlns.

boolean($v)

This function translates a Perl boolean value into an XML boolean value. The output is the string false, if the expression evaluates to a Perl false value or if the input value matches the expression /false/i. Every other value returns the string true.

As a quirk to accomodate the omission of attributes, an undef input will generate undef output.

METHODS

toXML( $handle, $indent, $xmlns )

This abstract function will terminate with an error, unless the child class overrides it.

The purpose of the toXML function is to recursively generate XML from the internal data structures. The first argument is a file handle open for writing. This is where the XML will be generated. The second argument is a string with the amount of white-space that should be used to indent elements for pretty printing. The third argument may not be defined. If defined, all element tags will be prefixed with this name space.

VARIABLES

%escape

This variable contains all characters that require an entity escape in an XML context, and map to the escaped XML entity that the character should be replaced with.

The variable is used internally by the quote static method.

$escape

This string is a regular expression that can be used to identify characters that will require an entity escape in XML context.

The variable is used internally by the quote static method.

AUTOLOAD

The AUTOLOAD method implement the getter and setter for all scalar values in any sibling class. While there is some effort to support non-scalar setters and getters, please do not use that feature (yet).

COPYRIGHT AND LICENSE

Copyright 2007-2011 University Of Southern California

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.