- NAME
- SYNOPSIS
- DESCRIPTION
- FUNCTIONS
- METHODS
- VARIABLES
- AUTOLOAD
- COPYRIGHT AND LICENSE

# 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.