Initial Commit

database/perl/vendor/lib/PPM/RelocPerl.pm

@@ -0,0 +1,83 @@
+#
+# Search for our Unix signature in text and binary files
+# and replace it with the real prefix ($Config{prefix} by default).
+#
+package PPM::RelocPerl;
+require Exporter;
+
+@ISA = qw(Exporter);
+@EXPORT = qw(RelocPerl);
+
+use File::Find;
+use Config;
+use strict;
+
+# We have to build up this variable, otherwise
+# PPM will mash it when it upgrades itself.
+my $frompath_default
+  = '/tmp' . '/.ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZpErLZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZperl'
+;
+my ($topath, $frompath);
+
+sub wanted {
+    if (-l) {
+        return;         # do nothing for symlinks
+    }
+    elsif (-B) {
+        check_for_frompath($_, 1);   # binary file edit
+    }
+    elsif (-e && -s && -f) {
+        check_for_frompath($_, 0);   # text file edit
+    }
+}
+
+sub check_for_frompath {
+    my ($file, $binmode) = @_;
+    local(*F, $_);
+    open(F, "<$file") or die "Can't open `$file': $!";
+    binmode F if $binmode;
+    while (<F>) {
+        if (/\Q$frompath\E/o) {
+	    close F;
+            edit_it($file, $binmode);
+            last;
+        }
+    }
+    # implicit close of F;
+}
+
+sub edit_it
+{
+    my ($file, $binmode) = @_;
+    my $nullpad = length($frompath) - length($topath);
+    $nullpad = "\0" x $nullpad;
+
+    local $/;
+    # Force the file to be writable
+    my $mode = (stat($file))[2] & 07777;
+    chmod $mode | 0222, $file;
+    open(F, "+<$file") or die "Couldn't open $file: $!";
+    binmode(F) if $binmode;
+    my $dat = <F>;
+    if ($binmode) {
+        $dat =~ s|\Q$frompath\E(.*?)\0|$topath$1$nullpad\0|gs;
+    } else {
+        $dat =~ s|\Q$frompath\E|$topath|gs;
+    }
+    seek(F, 0, 0) or die "Couldn't seek on $file: $!";
+    print F $dat;
+    close(F);
+    # Restore the permissions
+    chmod $mode, $file;
+}
+
+sub RelocPerl
+{
+    my ($dir, $opt_topath, $opt_frompath) = @_;
+    $topath = defined $opt_topath ? $opt_topath : $Config{'prefix'};
+    $frompath = defined $opt_frompath ? $opt_frompath : $frompath_default;
+
+    find(\&wanted, $dir);
+}
+
+1;

database/perl/vendor/lib/PPM/XML/Element.pm

@@ -0,0 +1,238 @@
+package PPM::XML::Element;
+
+#
+# PPM::XML::Element
+#
+# Base class for XML Elements.  Provides the ability to output the XML document
+# once it's been parsed using the XML::Parser module.
+#
+###############################################################################
+
+###############################################################################
+# Required inclusions.
+###############################################################################
+use HTML::Entities;                     # Needed for escaping char entities
+
+###############################################################################
+# Allow for creation via 'new'.
+###############################################################################
+sub new
+{
+    my ($class, %args) = @_;
+    bless \%args, $class;
+}
+
+###############################################################################
+# Subroutine:   output
+###############################################################################
+# Outputs the entire XML document on the currently selected filehandle.
+###############################################################################
+sub output
+{
+    my $self = shift;
+    print $self->as_text();
+}
+
+###############################################################################
+# Subroutine:   content
+###############################################################################
+# Returns a string containing all of the content of this element.
+###############################################################################
+sub content
+{
+    my $self = shift;
+    my $kids = $self->{'Kids'};
+    return unless (defined $kids and ref($kids) eq 'ARRAY');
+    my @kids = @{ $kids };
+    my $text;
+
+    if (@kids > 0)
+    {
+        foreach (@kids)
+        {
+            # Allow for outputting of char data
+            if ((ref $_) =~ /::Characters$/o)
+                { $text .= encode_entities( $_->{'Text'} ); }
+            else
+                { $text .= $_->as_text(); }
+        }
+    }
+
+    return $text;
+}
+
+###############################################################################
+# Subroutine:   add_child ($elemref)
+###############################################################################
+# Adds a new child element to ourselves.
+###############################################################################
+sub add_child (\$)
+{
+    my $self    = shift;
+    my $elemref = shift;
+    push( @{$self->{'Kids'}}, $elemref );
+}
+
+###############################################################################
+# Subroutine:   remove_child ($elemref)
+###############################################################################
+# Removes a child element from ourselves.  Returns non-zero if it was able to
+# remove the child element, and zero if it was unable to do so.
+###############################################################################
+sub remove_child
+{
+    my $self    = shift;
+    my $elemref = shift;
+
+    foreach my $idx (0 .. @{$self->{'Kids'}})
+    {
+        if ($self->{'Kids'}[$idx] == $elemref)
+        {
+            splice( @{$self->{'Kids'}}, $idx, 1 );
+            return 1;
+        }
+    }
+
+    return 0;
+}
+
+###############################################################################
+# Subroutine:   add_text ($text)
+###############################################################################
+# Adds character data to the given element.  Returns undef if unable to add the
+# text to this element, and returns a reference to the character data element
+# if successful.
+###############################################################################
+sub add_text
+{
+    my $self = shift;
+    my $text = shift;
+
+    return if (!defined $text);
+
+    my $type = ref $self;                   # Do package name magic
+    $type =~ s/::[^:]+?$/::Characters/o;
+
+    my $elem = new $type;
+    $elem->{'Text'} = $text;
+    $self->add_child( $elem );
+    return $elem;
+}
+
+###############################################################################
+# Subroutine:   as_text
+###############################################################################
+# Returns a string containing the entire XML document.
+###############################################################################
+sub as_text
+{
+    my $self = shift;
+    my $text;
+
+    my $type = ref $self;
+    $type =~ s/.*:://;
+
+    $text = "\n<" . $type;
+    foreach (sort keys %{$self})
+    {
+        if ($_ !~ /Text|Kids/) { 
+	  if (defined $self->{$_} ) {
+	      $text .= " $_=\"" . $self->{$_} . '"'; }
+	  }
+    }
+
+    my $cont = $self->content();
+    if (defined $cont)
+        { $text .= '>' . $cont . '</' . $type . '>'; }
+    else
+        { $text .= ' />'; }
+
+    $text =~ s/\n\n/\n/g;
+    return $text;
+}
+
+1;
+
+__END__
+
+###############################################################################
+# PPD Documentation
+###############################################################################
+
+=head1 NAME
+
+PPM::XML::Element - Base element class for XML elements
+
+=head1 SYNOPSIS
+
+ use PPM::XML::Element;
+ @ISA = qw( PPM::XML::Element );
+
+=head1 DESCRIPTION
+
+Base element class for XML elements.  To be derived from to create your own
+elements for use with the XML::Parser module.  Supports output of empty
+elements using <.... />.
+
+It is recommended that you use a version of the XML::Parser module which 
+includes support for Styles; by deriving your own elements from 
+PPM::XML::Element and using the 'Objects' style it becomes B<much> easier 
+to create your own parser.
+
+=head1 METHODS
+
+=over 4
+
+=item add_text ($text)
+
+Adds character data to the end of the element.  The element created is placed
+within the same package space as the element it was created under (e.g. adding
+text to a XML::Foobar::Stuff element would put the character data into an
+XML::Foobar::Characters element).  If successful, this method returns a
+reference to the newly created element.
+
+=item as_text
+
+Returns a string value containing the entire XML document from this element on
+down.
+
+=item content
+
+Returns a string value containing the entire content of this XML element.  Note
+that this is quite similar to the C<as_text()> method except that it does not
+include any information about this element in particular.
+
+=item output
+
+Recursively outputs the structure of the XML document from this element on
+down.
+
+=item add_child ($elemref)
+
+Adds the child element to the list of children for this element.  Note that
+the element given must be a reference to an object derived from 
+C<PPM::XML::Element>.
+
+=item remove_child ($elemref)
+
+Removes the given child element from the list of children for this element.
+This method returns non-zero if it is able to locate and remove the child
+element, returning zero if it is unable to do so.
+
+=back
+
+=head1 LIMITATIONS
+
+The C<PPM::XML::Element> module has no provisions for outputting processor
+directives or external entities.  It only outputs child elements and any
+character data which the elements may contain.
+
+=head1 AUTHORS
+
+Graham TerMarsch <gtermars@activestate.com>
+
+=head1 SEE ALSO
+
+L<XML::Parser>
+
+=cut

database/perl/vendor/lib/PPM/XML/PPD.pm

@@ -0,0 +1,620 @@
+#
+# PPM::XML::PPD
+#
+# Definition of the PPD file format.
+#
+###############################################################################
+
+use PPM::XML::ValidatingElement;
+use Exporter;
+
+###############################################################################
+# Set up PPM::XML::PPD to export its sub-packages so that we can use them in 
+# other XML documents without too much effort.
+###############################################################################
+package PPM::XML::PPD;
+@ISA = qw( Exporter );
+%EXPORT_TAGS = ( 'elements' =>
+                 [ '%SOFTPKG::', '%IMPLEMENTATION::', '%DEPENDENCY::',
+                   '%TITLE::', '%ABSTRACT::', '%AUTHOR::',
+                   '%LANGUAGE::', '%LICENSE::', '%OS::',
+                   '%OSVERSION::', '%PERLCORE::', '%PROCESSOR::',
+                   '%CODEBASE::', '%INSTALL::', '%UNINSTALL::',
+                   '%ARCHITECTURE::', '%PROVIDE::', '%REQUIRE::',
+                 ] );
+Exporter::export_ok_tags( 'elements' );
+
+###############################################################################
+# PPD Element: SOFTPKG
+###############################################################################
+package PPM::XML::PPD::SOFTPKG;
+@ISA = qw( PPM::XML::ValidatingElement );
+@oattrs = qw( VERSION );
+@rattrs = qw( NAME );
+@okids  = qw( ABSTRACT AUTHOR IMPLEMENTATION LICENSE 
+              TITLE INSTALL UNINSTALL PROVIDE REQUIRE);
+
+###############################################################################
+# PPD Element: TITLE
+###############################################################################
+package PPM::XML::PPD::TITLE;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPD Element: ABSTRACT
+###############################################################################
+package PPM::XML::PPD::ABSTRACT;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPD Element: AUTHOR
+###############################################################################
+package PPM::XML::PPD::AUTHOR;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPD Element: PROVIDE
+###############################################################################
+package PPM::XML::PPD::PROVIDE;
+@ISA = qw( PPM::XML::ValidatingElement );
+@oattrs = qw( VERSION );
+@rattrs = qw( NAME );
+
+###############################################################################
+# PPD Element: REQUIRE
+###############################################################################
+package PPM::XML::PPD::REQUIRE;
+@ISA = qw( PPM::XML::ValidatingElement );
+@oattrs = qw( VERSION );
+@rattrs = qw( NAME );
+
+###############################################################################
+# PPD Element: LICENSE
+###############################################################################
+package PPM::XML::PPD::LICENSE;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( HREF );
+
+###############################################################################
+# PPD Element: IMPLEMENTATION
+###############################################################################
+package PPM::XML::PPD::IMPLEMENTATION;
+@ISA = qw( PPM::XML::ValidatingElement );
+@okids = qw( DEPENDENCY INSTALL LANGUAGE OS OSVERSION PERLCORE PROCESSOR
+             UNINSTALL ARCHITECTURE PROVIDE REQUIRE);
+@rkids = qw( CODEBASE );
+
+###############################################################################
+# PPD Element: OS
+###############################################################################
+package PPM::XML::PPD::OS;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( VALUE );
+sub validate_possible_attrs
+{
+    my $self = shift;
+    $self->compatibility_check();
+    $self->SUPER::validate_possible_attrs( @_ );
+}
+
+sub validate_required_attrs
+{
+    my $self = shift;
+    $self->compatibility_check();
+    $self->SUPER::validate_required_attrs( @_ );
+}
+
+sub compatibility_check
+{
+    my $self = shift;
+    if (exists $self->{NAME})
+    {
+        $self->{VALUE} = $self->{NAME};
+        delete $self->{NAME};
+    }
+}
+
+###############################################################################
+# PPD Element: OSVERSION
+###############################################################################
+package PPM::XML::PPD::OSVERSION;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( VALUE );
+sub validate_possible_attrs
+{
+    my $self = shift;
+    $self->compatibility_check();
+    $self->SUPER::validate_possible_attrs( @_ );
+}
+
+sub validate_required_attrs
+{
+    my $self = shift;
+    $self->compatibility_check();
+    $self->SUPER::validate_required_attrs( @_ );
+}
+
+sub compatibility_check
+{
+    my $self = shift;
+    if (exists $self->{NAME})
+    {
+        $self->{VALUE} = $self->{NAME};
+        delete $self->{NAME};
+    }
+}
+
+###############################################################################
+# PPD Element: PROCESSOR
+###############################################################################
+package PPM::XML::PPD::PROCESSOR;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( VALUE );
+sub validate_possible_attrs
+{
+    my $self = shift;
+    $self->compatibility_check();
+    $self->SUPER::validate_possible_attrs( @_ );
+}
+
+sub validate_required_attrs
+{
+    my $self = shift;
+    $self->compatibility_check();
+    $self->SUPER::validate_required_attrs( @_ );
+}
+
+sub compatibility_check
+{
+    my $self = shift;
+    if (exists $self->{NAME})
+    {
+        $self->{VALUE} = $self->{NAME};
+        delete $self->{NAME};
+    }
+}
+
+###############################################################################
+# PPD Element: ARCHITECTURE
+###############################################################################
+package PPM::XML::PPD::ARCHITECTURE;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( VALUE );
+sub validate_possible_attrs
+{
+    my $self = shift;
+    $self->compatibility_check();
+    $self->SUPER::validate_possible_attrs( @_ );
+}
+
+sub validate_required_attrs
+{
+    my $self = shift;
+    $self->compatibility_check();
+    $self->SUPER::validate_required_attrs( @_ );
+}
+
+sub compatibility_check
+{
+    my $self = shift;
+    if (exists $self->{NAME})
+    {
+        $self->{VALUE} = $self->{NAME};
+        delete $self->{NAME};
+    }
+}
+
+###############################################################################
+# PPD Element: CODEBASE
+###############################################################################
+package PPM::XML::PPD::CODEBASE;
+@ISA = qw( PPM::XML::ValidatingElement );
+@oattrs = qw( FILENAME );
+@rattrs = qw( HREF );
+
+###############################################################################
+# PPD Element: DEPENDENCY
+###############################################################################
+package PPM::XML::PPD::DEPENDENCY;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( NAME );
+@oattrs = qw( VERSION );
+
+###############################################################################
+# PPD Element: LANGUAGE
+###############################################################################
+package PPM::XML::PPD::LANGUAGE;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( VALUE );
+
+###############################################################################
+# PPD Element: PERLCORE
+###############################################################################
+package PPM::XML::PPD::PERLCORE;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( VERSION );
+
+###############################################################################
+# PPD Element: INSTALL
+###############################################################################
+package PPM::XML::PPD::INSTALL;
+@ISA = qw( PPM::XML::ValidatingElement );
+@oattrs = qw( HREF EXEC );
+
+###############################################################################
+# PPD Element: UNINSTALL
+###############################################################################
+package PPM::XML::PPD::UNINSTALL;
+@ISA = qw( PPM::XML::ValidatingElement );
+@oattrs = qw( HREF EXEC );
+
+__END__
+
+###############################################################################
+# POD
+###############################################################################
+
+=head1 NAME
+
+PPM::XML::PPD - PPD file format and XML parsing elements
+
+=head1 SYNOPSIS
+
+ use XML::Parser;
+ use PPM::XML::PPD;
+
+ $p = new PPM::XML::Parser( Style => 'Objects', Pkg => 'PPM::XML::PPD' );
+ ...
+
+=head1 DESCRIPTION
+
+This module provides a set of classes for parsing PPD files using the
+C<XML::Parser> module.  Each of the classes is derived from
+C<PPM::XML::ValidatingElement>, with optional/required attributes/children
+enforced.
+
+=head1 MAJOR ELEMENTS
+
+=head2 SOFTPKG
+
+Defines a Perl Package.  The root of a PPD document is B<always> a SOFTPKG
+element.  The SOFTPKG element allows for the following attributes:
+
+=over 4
+
+=item NAME
+
+Required attribute.  Name of the package (e.g. "Foobar").
+
+=item VERSION
+
+Version number of the package, in comma-delimited format (e.g. "1,0,0,0").
+
+=back
+
+=head2 IMPLEMENTATION
+
+Child of SOFTPKG, used to describe a particular implementation of the Perl
+Package.  Multiple instances are valid, and should be used to describe
+different implementations/ports for different operating systems or
+architectures.
+
+=head2 DEPENDENCY
+
+Child of SOFTPKG or IMPLEMENTATION, used to indicate a dependency this Perl
+Package has on another Perl Package.  Multiple instances are valid.  The
+DEPENDENCY element allows for the following attributes:
+
+=over 4
+
+=item NAME
+
+Name of the package that this implementation is dependant upon.
+
+=item VERSION
+
+Version number of the dependency, in comma-delimited format (e.g. "1,0,0,0").
+
+=back
+
+=head1 MINOR ELEMENTS
+
+=head2 TITLE
+
+Child of SOFTPKG, used to state the title of the Perl Package.  Only one
+instance should be present.
+
+=head2 ABSTRACT
+
+Child of SOFTPKG, used to provide a short description outlining the nature and
+purpose of the Perl Package.  Only one instance should be present.
+
+=head2 AUTHOR
+
+Child of SOFTPKG, used to provide information about the author(s) of the Perl
+Package.  Multiple instances are valid.
+
+=head2 LANGUAGE
+
+Child of IMPLEMENTATION, used to specify the language used within the given
+implementation of the Perl Package.  Only one instance should be present.
+
+=head2 LICENSE
+
+Child of SOFTPKG, indicating the location of the appropriate license agreement
+or copyright notice for the Perl Package.  Only one instance should be
+present.  The LICENSE element allows for the following attributes:
+
+=over 4
+
+=item HREF
+
+Required attribute.  A reference to the location of the license agreement or
+copyright notice for this package.
+
+=back
+
+=head2 OS
+
+Child of IMPLEMENTATION, used to outline the operating system required for this
+implementation of the Perl Package.  Multiple instances are valid.  Valid
+values can be taken from the OSD Specification and it's OS element.  The OS
+element allows for the following attributes:
+
+=over 4
+
+=item VALUE
+
+The name of the operating system required for this implementation of the Perl
+Package.  This value should be obtained from Config.pm as 'osname'.
+
+=back
+
+Note that previous versions of the PPD format used a 'NAME' attribute.  It's
+use has been deprecated in preference of the 'VALUE' attribute.  Also note that
+during validation, this element will automatically convert any existing 'NAME'
+attribute to be a 'VALUE' attribute.
+
+=head2 OSVERSION
+
+Child of IMPLEMENTATION, used to outline the required version of the operating
+system required for this implementation of the Perl Package.  Only one instance
+should be present.  The OSVERSION element allows for the following attributes:
+
+=over 4
+
+=item VALUE
+
+The version of the operating system required for installation of this
+implementation of the package, in a comma-delimited format (e.g. "3,1,0,0").
+
+=back
+
+Note that previous versions of the PPD format used a 'NAME' attribute.  It's
+use has been deprecated in preference of the 'VALUE' attribute.  Also note that
+during validation, this element will automatically convert any existing 'NAME'
+attribute to be a 'VALUE' attribute.
+
+=head2 PERLCORE
+
+Child of IMPLEMENTATION, used to specify the minimum version of the Perl core
+distribution that this Perl Package is to be used with.  Only one instance
+should be present.  The PERLCORE element allows for the following attributes:
+
+=over 4
+
+=item VERSION
+
+Version of the Perl core that is required for this implementation of the Perl
+Package.
+
+=back
+
+=head2 PROCESSOR
+
+Child of IMPLEMENTATION, outlining the cpu required for this implementation
+of the Perl Package.  Only one instance should be present.  The PROCESSOR
+element allows for the following attributes:
+
+=over 4
+
+=item VALUE
+
+CPU required for the installation of this implementation of the Perl Package.
+The following values are all valid according to the OSD Specification:
+
+ x86 alpha mips sparc 680x0
+
+=back
+
+Note that previous versions of the PPD format used a 'NAME' attribute.  It's
+use has been deprecated in preference of the 'VALUE' attribute.  Also note that
+during validation, this element will automatically convert any existing 'NAME'
+attribute to be a 'VALUE' attribute.
+
+=head2 CODEBASE
+
+Child of IMPLEMENTATION, indicating a location where an archive of the Perl
+Package can be retrieved.  Multiple instances are valid, and can be used to
+indicate multiple possible locations where the same version of the Perl Package
+can be retrieved.  The CODEBASE element allows for the following attributes:
+
+=over 4
+
+=item FILENAME
+
+???
+
+=item HREF
+
+Required attribute.  A reference to the location of the Perl Package
+distribution.
+
+=back
+
+=head2 INSTALL
+
+Child of IMPLEMENTATION, used to provide either a reference to an
+installation script or a series of commands which can be used to install
+the Perl Package once it has been retrieved.  If the EXEC attribute is not
+specified, the value is assumed to be one or more commands, separated by
+`;;'.  Each such command will be executed by the Perl `system()' function.
+Only one instance should be present.  The INSTALL element allows for
+the following attributes:
+
+=over 4
+
+=item HREF
+
+Reference to an external script which should be retrieved and run as part
+of the installation process.  Both filenames and URLs should be considered
+valid.
+
+=item EXEC
+
+Name of interpreter/shell used to execute the installation script.
+If the value of EXEC is `PPM_PERL', the copy of Perl that is executing
+PPM itself ($^X) is used to execute the install script.
+
+=back
+
+=head2 UNINSTALL
+
+Child of IMPLEMENTATION, used to provide either a reference to an
+uninstallation script or a raw Perl script which can be used to uninstall the
+Perl Package at a later point.  Only one instance should be present.  The
+UNINSTALL element allows for the following attributs:
+
+=over 4
+
+=item HREF
+
+Reference to an external script which should be retrieved and run as part of
+the removal process.  Both filenames and URLs should be considered valid.
+
+=item EXEC
+
+Name of interpreter/shell used to execute the uninstallation script.
+If the value of EXEC is `PPM_PERL', the copy of Perl that is executing
+PPM itself ($^X) is used to execute the install script.
+
+=back
+
+=head1 DOCUMENT TYPE DEFINITION
+
+The DTD for PPD documents is available from the ActiveState website and the
+latest version can be found at http://www.ActiveState.com/PPM/DTD/ppd.dtd
+
+This revision of the C<PPM::XML::PPD> module implements the following DTD:
+
+ <!ELEMENT SOFTPKG   (ABSTRACT | AUTHOR | IMPLEMENTATION | LICENSE | TITLE)*>
+ <!ATTLIST SOFTPKG   NAME    CDATA #REQUIRED
+                     VERSION CDATA #IMPLIED>
+
+ <!ELEMENT TITLE     (#PCDATA)>
+
+ <!ELEMENT ABSTRACT  (#PCDATA)>
+
+ <!ELEMENT AUTHOR    (#PCDATA)>
+
+ <!ELEMENT LICENSE   EMPTY>
+ <!ATTLIST LICENSE   HREF     CDATA #REQUIRED>
+
+ <!ELEMENT IMPLEMENTATION    (CODEBASE | DEPENDENCY | LANGUAGE | OS |
+                              OSVERSION | PERLCORE | PROCESSOR | INSTALL |
+                              UNINSTALL) *>
+
+ <!ELEMENT CODEBASE  EMPTY>
+ <!ATTLIST CODEBASE  FILENAME CDATA #IMPLIED
+                     HREF     CDATA #REQUIRED>
+
+ <!ELEMENT DEPENDENCY EMPTY>
+ <!ATTLIST DEPENDENCY VERSION CDATA #IMPLIED
+                      NAME CDATA #REQUIRED>
+
+ <!ELEMENT LANGUAGE  EMPTY>
+ <!ATTLIST LANGUAGE  VALUE CDATA #REQUIRED>
+
+ <!ELEMENT OS        EMPTY>
+ <!ATTLIST OS        VALUE CDATA #REQUIRED>
+
+ <!ELEMENT OSVERSION EMPTY>
+ <!ATTLIST OSVERSION VALUE CDATA #REQUIRED>
+
+ <!ELEMENT PERLCORE  EMPTY>
+ <!ATTLIST PERLCORE  VERSION CDATA #REQUIRED>
+
+ <!ELEMENT PROCESSOR EMPTY>
+ <!ATTLIST PROCESSOR VALUE CDATA #REQUIRED>
+
+ <!ELEMENT INSTALL   (#PCDATA)>
+ <!ATTLIST INSTALL   HREF  CDATA #IMPLIED
+                     EXEC  CDATA #IMPLIED>
+
+ <!ELEMENT UNINSTALL (#PCDATA)>
+ <!ATTLIST UNINSTALL HREF  CDATA #IMPLIED
+                     EXEC  CDATA #IMPLIED>
+
+=head1 SAMPLE PPD FILE
+
+The following is a sample PPD file describing the C<Math-MatrixBool> module.
+Note that this may B<not> be a current/proper description of this module and is
+for sample purposes only.
+
+ <SOFTPKG NAME="Math-MatrixBool" VERSION="4,2,0,0">
+     <TITLE>Math-MatrixBool</TITLE>
+     <ABSTRACT>Easy manipulation of matrices of booleans (Boolean Algebra)</ABSTRACT>
+     <AUTHOR>Steffen Beyer (sb@sdm.de)</AUTHOR>
+     <LICENSE HREF="http://www.ActiveState.com/packages/Math-MatrixBool/license.html" />
+     <IMPLEMENTATION>
+         <OS VALUE="WinNT" />
+         <OS VALUE="Win95" />
+         <PROCESSOR VALUE="x86" />
+         <CODEBASE HREF="http://www.ActiveState.com/packages/Math-MatrixBool/Math-MatrixBool-4.2-bin-1-Win32.tar.gz" />
+         <DEPENDENCY NAME="Bit-Vector" />
+         <INSTALL>
+         </INSTALL>
+         <UNINSTALL>
+         </UNINSTALL>
+     </IMPLEMENTATION>
+
+     <IMPLEMENTATION>
+         <DEPENDENCY NAME="Bit-Vector" />
+         <CODEBASE HREF="&CPAN;/CPAN/modules/by-module/Math/Math-MatrixBool-4.2.tar.gz" />
+         <INSTALL>
+             system("make"); ;;
+             system("make test"); ;;
+             system("make install"); ;;
+         </INSTALL>
+     </IMPLEMENTATION>
+ </SOFTPKG>
+
+=head1 KNOWN BUGS/ISSUES
+
+Elements which are required to be empty (e.g. LICENSE) are not enforced as
+such.
+
+Notations above about elements for which "only one instance" or "multiple
+instances" are valid are not enforced; this primarily a guideline for
+generating your own PPD files.
+
+=head1 AUTHORS
+
+Graham TerMarsch <grahamt@ActiveState.com>
+
+Murray Nesbitt <murrayn@ActiveState.com>
+
+Dick Hardt <dick_hardt@ActiveState.com>
+
+=head1 HISTORY
+
+v0.1 - Initial release
+
+=head1 SEE ALSO
+
+L<PPM::XML::ValidatingElement>,
+L<PPM::XML::Element>,
+L<XML::Parser>,
+OSD Specification (http://www.microsoft.com/standards/osd/)
+
+=cut

database/perl/vendor/lib/PPM/XML/PPMConfig.pm

@@ -0,0 +1,423 @@
+#
+# PPM::XML::PPMConfig
+#
+# Definition of the PPMConfig file format; configuration options for the Perl
+# Package Manager.
+#
+###############################################################################
+
+###############################################################################
+# Import everything from PPM::XML::PPD into our own namespace.
+###############################################################################
+package PPM::XML::PPMConfig;
+
+use PPM::XML::PPD ':elements';
+
+###############################################################################
+# PPMConfig Element: Characters
+###############################################################################
+package PPM::XML::PPMConfig::Characters;
+@ISA = qw( PPM::XML::Element );
+
+###############################################################################
+# PPMConfig Element: PPMCONFIG
+###############################################################################
+package PPM::XML::PPMConfig::PPMCONFIG;
+@ISA = qw( PPM::XML::ValidatingElement );
+@okids  = qw( PPMVER PLATFORM REPOSITORY OPTIONS PPMPRECIOUS PACKAGE );
+
+###############################################################################
+# PPMConfig Element: PPMVER
+###############################################################################
+package PPM::XML::PPMConfig::PPMVER;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPMConfig Element: PLATFORM
+###############################################################################
+package PPM::XML::PPMConfig::PLATFORM;
+@ISA = qw( PPM::XML::ValidatingElement );
+@oattrs = qw( LANGUAGE );
+@rattrs = qw( OSVALUE OSVERSION CPU );
+
+###############################################################################
+# PPMConfig Element: REPOSITORY
+###############################################################################
+package PPM::XML::PPMConfig::REPOSITORY;
+@ISA = qw( PPM::XML::ValidatingElement );
+@oattrs = qw( USERNAME PASSWORD SUMMARYFILE);
+@rattrs = qw( NAME LOCATION );
+
+###############################################################################
+# PPMConfig Element: OPTIONS
+###############################################################################
+package PPM::XML::PPMConfig::OPTIONS;
+@ISA = qw( PPM::XML::ValidatingElement );
+@rattrs = qw( IGNORECASE CLEAN CONFIRM FORCEINSTALL ROOT BUILDDIR MORE );
+@oattrs = qw( TRACE TRACEFILE VERBOSE DOWNLOADSTATUS );
+
+###############################################################################
+# PPMConfig Element: PPMPRECIOUS
+###############################################################################
+package PPM::XML::PPMConfig::PPMPRECIOUS;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPMConfig Element: PACKAGE
+###############################################################################
+package PPM::XML::PPMConfig::PACKAGE;
+@ISA = qw( PPM::XML::ValidatingElement );
+@okids  = qw( LOCATION INSTDATE INSTROOT INSTPACKLIST INSTPPD );
+@rattrs = qw( NAME );
+
+###############################################################################
+# PPMConfig Element: LOCATION
+###############################################################################
+package PPM::XML::PPMConfig::LOCATION;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPMConfig Element: INSTDATE
+###############################################################################
+package PPM::XML::PPMConfig::INSTDATE;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPMConfig Element: INSTROOT
+###############################################################################
+package PPM::XML::PPMConfig::INSTROOT;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPMConfig Element: INSTPACKLIST
+###############################################################################
+package PPM::XML::PPMConfig::INSTPACKLIST;
+@ISA = qw( PPM::XML::ValidatingElement );
+
+###############################################################################
+# PPMConfig Element: INSTPPD
+###############################################################################
+package PPM::XML::PPMConfig::INSTPPD;
+@ISA = qw( PPM::XML::ValidatingElement );
+@okids = qw( SOFTPKG );                 # Allow for an PPM::XML::PPD::SOFTPKG
+
+__END__
+
+###############################################################################
+# POD
+###############################################################################
+
+=head1 NAME
+
+PPM::XML::PPMConfig - PPMConfig file format and XML parsing elements
+
+=head1 SYNOPSIS
+
+ use XML::Parser;
+ use PPM::XML::PPMConfig;
+
+ $p = new PPM::XML::Parser( Style => 'Objects', Pkg => 'PPM::XML::PPMConfig' );
+ ...
+
+=head1 DESCRIPTION
+
+This module provides a set of classes for parsing PPM configuration files 
+using the C<XML::Parser> module.  All of the elements unique to a PPM
+configuration file are derived from C<PPM::XML::ValidatingElement>. 
+There are also several classes rebuilt here which are derived from 
+elements in C<PPM::XML::PPD> as we can include a PPD file within our own 
+INSTPPD element.
+
+=head1 MAJOR ELEMENTS
+
+=head2 PPMCONFIG
+
+Defines a PPM configuration file.  The root of a PPMConfig document is
+B<always> a PPMCONFIG element.
+
+=head2 PACKAGE
+
+Child of PPMCONFIG, used to describe a Perl Package which has already been
+installed.  Multiple instances are valid.  The PACKAGE element allows for the
+following attributes:
+
+=over 4
+
+=item NAME
+
+Name of the package as given in it's PPD
+
+=back
+
+=head1 MINOR ELEMENTS
+
+
+=head2 PPMVER
+
+Child of PPMCONFIG, used to state the version of PPM for which this
+configuration file is valid.  A single instance should be present.
+
+=head2 PLATFORM
+
+Child of PPMCONFIG, used to specify the platform of the target machine.  A
+single instance should be present.  The PLATFORM element allows for the
+following attributes:
+
+=over 4
+
+=item OSVALUE
+
+Description of the local operating system as defined in the Config.pm file
+under 'osname'.
+
+=item OSVERSION
+
+Version of the local operating system.
+
+=item CPU
+
+Description of the CPU in the local system.  The following list of possible
+values was taken from the OSD Specification:
+
+ x86 mips alpha ppc sparc 680x0
+
+=item LANGUAGE
+
+Description of the language used on the local system as specified by the
+language codes in ISO 639.
+
+=back
+
+=head2 REPOSITORY
+
+Child of PPMCONFIG, used to specify a repository where Perl Packages can be
+found.  Multiple instances are valid.  The REPOSITORY element allows for the
+following attributes:
+
+=over 4
+
+=item NAME
+
+Name by which the repository will be known (e.g.  "ActiveState").
+
+=item LOCATION
+
+An URL or directory where the repository can be found.
+
+=item USERNAME
+
+Optional username for a repository requiring authenticated connection.
+
+=item PASSWORD
+
+Optional password for a repository requiring authenticated connection.
+
+=item SUMMARYFILE
+
+Optional package summary filename.
+
+If this file exists on the repository, its contents can be retrieved
+using PPM::RepositorySummary().  The contents are not strictly enforced
+by PPM.pm, however ppm.pl expects this to be a file with the following
+format (for display with the 'summary' command):
+
+Agent [2.91]:   supplies agentspace methods for perl5.
+Apache-OutputChain [0.06]:      chain stacked Perl handlers
+[etc.]
+
+=back
+
+=head2 OPTIONS
+
+Child of PPMCONFIG, used to specify the current configuration options for PPM.
+A single instance should be present.  The OPTIONS element allows for the
+following attributes:
+
+=over 4
+
+=item IGNORECASE
+
+Sets case-sensitive searching.  Can be either '1' or '0'.
+
+=item CLEAN
+
+Sets removal of temporarily files.  Can be either '1' or '0'.
+
+=item CONFIRM
+
+Sets confirmation of all installs/removals/upgrades.  Can be either '1' or
+'0'.
+
+=item BUILDDIR
+
+Directory in which packages will be unpacked before their installation.
+
+=item ROOT
+
+Directory under which packages should be installed on the local system.
+
+=item TRACE
+
+Level of tracing (0 is no tracing, 4 is max tracing).
+
+=item TRACEFILE
+
+File to which trace information will be written.
+
+=item VERBOSE
+
+Controls whether query and search results are verbose (1 == verbose, 0 == no).
+
+=back
+
+=head2 PPMPRECIOUS
+
+Child of PPMCONFIG, used to specify the modules which PPM itself is dependant
+upon.  A single instance should be present.
+
+=head2 LOCATION
+
+Child of PACKAGE, used to specify locations at which to search for updated
+versions of the PPD file for this package.  Its value can be either a
+directory or an Internet address.  A single instance should be present.
+
+=head2 INSTDATE
+
+Child of PACKAGE, used to specify the date on which the Perl Package was
+installed.  A single instance should be present.
+
+=head2 INSTROOT
+
+Child of PACKAGE, used to specify the root directory that the Perl Package was
+installed into.  A single instance should be present.
+
+=head2 INSTPACKLIST
+
+Child of PACKAGE, used to specify a reference to the packlist for this Perl
+Package; a file containing a list of all of the files which were installed.  A
+single instance should be present.
+
+=head2 INSTPPD
+
+Child of PACKAGE, used to hold a copy of the PPD from which Perl Packages
+were installed.  Multiple instances are valid.
+
+=head1 DOCUMENT TYPE DEFINITION
+
+The DTD for PPMConfig documents is available from the ActiveState website and
+the latest version can be found at:
+    http://www.ActiveState.com/PPM/DTD/ppmconfig.dtd
+
+This revision of the C<PPM::XML::PPMConfig> module implements the following DTD:
+
+ <!ELEMENT PPMCONFIG (PPMVER | PLATFORM | REPOSITORY | OPTIONS |
+                      PPMPRECIOUS | PACKAGE)*>
+
+ <!ELEMENT PPMVER   (#PCDATA)>
+
+ <!ELEMENT PLATFORM  EMPTY>
+ <!ATTLIST PLATFORM  OSVALUE     CDATA   #REQUIRED
+                     OSVERSION   CDATA   #REQUIRED
+                     CPU         CDATA   #REQUIRED
+                     LANGUAGE    CDATA   #IMPLIED>
+
+ <!ELEMENT REPOSITORY    EMPTY>
+ <!ATTLIST REPOSITORY    NAME     CDATA  #REQUIRED
+                         LOCATION CDATA  #REQUIRED
+                         USERNAME CDATA  #IMPLIED
+                         PASSWORD CDATA  #IMPLIED
+                         SUMMARYFILE CDATA #IMPLIED>
+
+ <!ELEMENT OPTIONS   EMPTY>
+ <!ATTLIST OPTIONS   IGNORECASE      CDATA   #REQUIRED
+                     CLEAN           CDATA   #REQUIRED
+                     CONFIRM         CDATA   #REQUIRED
+                     FORCEINSTALL    CDATA   #REQUIRED
+                     ROOT            CDATA   #REQUIRED
+                     BUILDDIR        CDATA   #REQUIRED
+                     MORE            CDATA   #REQUIRED
+                     DOWNLOADSTATUS  CDATA   #IMPLIED
+                     TRACE           CDATA   #IMPLIED
+                     TRACEFILE       CDATA   #IMPLIED>
+
+ <!ELEMENT PPMPRECIOUS (#PCDATA)>
+
+ <!ELEMENT PACKAGE   (LOCATION | INSTDATE | INSTROOT | INSTPACKLIST |
+                      INSTPPD)*>
+ <!ATTLIST PACKAGE   NAME    CDATA   #REQUIRED>
+
+ <!ELEMENT LOCATION  (#PCDATA)>
+
+ <!ELEMENT INSTDATE  (#PCDATA)>
+
+ <!ELEMENT INSTROOT  (#PCDATA)>
+
+ <!ELEMENT INSTPACKLIST (#PCDATA)>
+
+ <!ELEMENT INSTPPD   (#PCDATA)>
+
+=head1 SAMPLE PPMConfig FILE
+
+The following is a sample PPMConfig file.  Note that this may B<not> be a
+current description of this module and is for sample purposes only.
+
+ <PPMCONFIG>
+     <PPMVER>1,0,0,0</PPMVER>
+     <PLATFORM CPU="x86" OSVALUE="MSWin32" OSVERSION="4,0,0,0" />
+     <OPTIONS BUILDDIR="/tmp" CLEAN="1" CONFIRM="1" FORCEINSTALL="1"
+              IGNORECASE="0" MORE="0" ROOT="/usr/local" TRACE="0" TRACEFILE="" DOWNLOADSTATUS="16384" />
+     <REPOSITORY LOCATION="http://www.ActiveState.com/packages"
+                 NAME="ActiveState Package Repository" SUMMARYFILE="package.lst" />
+     <PPMPRECIOUS>PPM;libnet;Archive-Tar;Compress-Zlib;libwww-perl</PPMPRECIOUS>
+     <PACKAGE NAME="AtExit">
+         <LOCATION>g:/packages</LOCATION>
+         <INSTPACKLIST>c:/perllib/lib/site/MSWin32-x86/auto/AtExit/.packlist</INSTPACKLIST>
+         <INSTROOT>c:/perllib</INSTROOT>
+         <INSTDATE>Sun Mar  8 02:56:31 1998</INSTDATE>
+         <INSTPPD>
+             <SOFTPKG NAME="AtExit" VERSION="1,02,0,0">
+                 <TITLE>AtExit</TITLE>
+                 <ABSTRACT>Register a subroutine to be invoked at program -exit time.</ABSTRACT>
+                 <AUTHOR>Brad Appleton (Brad_Appleton-GBDA001@email.mot.com)</AUTHOR>
+                 <IMPLEMENTATION>
+                     <CODEBASE HREF="x86/AtExit.tar.gz" />
+                 </IMPLEMENTATION>
+             </SOFTPKG>
+         </INSTPPD>
+     </PACKAGE>
+ </PPMCONFIG>
+
+=head1 KNOWN BUGS/ISSUES
+
+Elements which are required to be empty (e.g. REPOSITORY) are not enforced as
+such.
+
+Notations above about elements for which "only one instance" or "multiple
+instances" are valid are not enforced; this primarily a guideline for
+generating your own PPD files.
+
+Currently, this module creates new classes within it's own namespace for all of
+the PPD elements which can be contained within the INSTPPD element.  A suitable
+method for importing the entire PPM::XML::PPD:: namespace should be found 
+in order to make this cleaner.
+
+=head1 AUTHORS
+
+Graham TerMarsch <grahamt@ActiveState.com>
+
+Murray Nesbitt <murrayn@ActiveState.com>
+
+Dick Hardt <dick_hardt@ActiveState.com>
+
+=head1 HISTORY
+
+v0.1 - Initial release
+
+=head1 SEE ALSO
+
+L<PPM::XML::ValidatingElement>,
+L<XML::Parser>,
+L<PPM::XML::PPD>
+.
+
+=cut

database/perl/vendor/lib/PPM/XML/RepositorySummary.pm

@@ -0,0 +1,29 @@
+#
+# PPM::XML::PPMConfig
+#
+# Definition of the PPMConfig file format; configuration options for the Perl
+# Package Manager.
+#
+###############################################################################
+
+###############################################################################
+# Import everything from PPM::XML::PPD into our own namespace.
+###############################################################################
+package PPM::XML::RepositorySummary;
+
+use PPM::XML::PPD ':elements';
+
+###############################################################################
+# RepositorySummary Element: Characters
+###############################################################################
+package PPM::XML::RepositorySummary::Characters;
+@ISA = qw( PPM::XML::Element );
+
+###############################################################################
+# RepositorySummary Element: REPOSITORYSUMMARY
+###############################################################################
+package PPM::XML::RepositorySummary::REPOSITORYSUMMARY;
+@ISA = qw( PPM::XML::ValidatingElement );
+@okids  = qw( SOFTPKG );
+
+__END__

database/perl/vendor/lib/PPM/XML/ValidatingElement.pm

@@ -0,0 +1,329 @@
+package PPM::XML::ValidatingElement;
+use PPM::XML::Element;
+use vars qw( @ISA );
+
+###############################################################################
+#
+# PPM::XML::ValidatingElement
+#
+# Base class for validating elements.  Allows for applying DTD type
+# restrictions to elements parsed using the XML::Parser module.
+#
+###############################################################################
+
+###############################################################################
+# Define the validating element class.
+###############################################################################
+@ISA = qw( PPM::XML::Element );
+
+###############################################################################
+# Recursively validate myself and all child elements with all four types of
+# validation.  Returns non-zero on success and zero on any errors.
+###############################################################################
+sub rvalidate
+{
+    my $self = shift;
+    my $func = shift;
+    my $success = 1;
+
+    $success &= $self->validate_possible_attrs( $func );
+    $success &= $self->validate_required_attrs( $func );
+    $success &= $self->validate_possible_kids( $func );
+    $success &= $self->validate_required_kids( $func );
+
+    foreach (@{$self->{Kids}})
+    {
+        if ((ref $_) !~ /::Characters$/o)
+            { $success &= $_->rvalidate( $func ); }
+    }
+
+    return $success;
+}
+
+###############################################################################
+# Validate the element with all four types of validation.  Returns non-zero on
+# success any zero if any errors occurred.
+###############################################################################
+sub validate
+{
+    my $self = shift;
+    my $func = shift;
+    my $success = 1;
+
+    $success &= $self->validate_possible_attrs( $func );
+    $success &= $self->validate_required_attrs( $func );
+    $success &= $self->validate_possible_kids( $func );
+    $success &= $self->validate_required_kids( $func );
+
+    return $success;
+}
+
+###############################################################################
+# Validate possible attributes.  Returns non-zero on sucess, and zero if any
+# errors occurred.
+###############################################################################
+sub validate_possible_attrs
+{
+    my $self = shift;
+    my $func = shift;
+    my $attr;
+    my $type = ref $self;
+    my $success = 1;
+
+    my $elem = $type;
+    $elem =~ s/.*:://;
+
+    my @allattrs;
+    push( @allattrs, @{"$type\::oattrs"}, @{"$type\::rattrs"} );
+
+    # Check our list of attributes against the list of possible attributes we
+    # can have.
+    foreach $attr (keys %{$self})
+    {
+        if ( ($attr ne 'Kids') and ($attr ne 'Text') )
+        {
+            if (!grep( /^$attr$/, @allattrs ))
+            {
+                &$func( "Element '$elem' doesn't allow the '$attr' attribute." );
+                $success = 0;
+            }
+        }
+    }
+
+    return $success;
+}
+
+###############################################################################
+# Validate required attributes.  Returns non-zero on success and zero if any
+# errors occurred.
+###############################################################################
+sub validate_required_attrs
+{
+    my $self = shift;
+    my $func = shift;
+    my $attr;
+    my $type = ref $self;
+    my $success = 1;
+
+    my $elem = $type;
+    $elem =~ s/.*:://;
+
+    # Check the list of required attributes against the list of attributes
+    # which were parsed.
+    foreach $attr (@{"$type\::rattrs"})
+    {
+        if (!grep( /^$attr$/, (keys %{$self}) ))
+        {
+            &$func( "Element '$elem' must have a '$attr' attribute." );
+            $success = 0;
+        }
+    }
+
+    return $success;
+}
+
+###############################################################################
+# Validate possible child elements.  Returns non-zero on success and zero if
+# any errors occurred.
+###############################################################################
+sub validate_possible_kids
+{
+    my $self = shift;
+    my $func = shift;
+    my $kid;
+    my $type = ref $self;
+    my $success = 1;
+    
+    my $elem = $type;
+    $elem =~ s/.*:://;
+
+    my $base = $type;
+    $base =~ s/::[^:]*?$//;
+
+    my @allkids;
+    push( @allkids, @{"$type\::okids"}, @{"$type\::rkids"} );
+
+    foreach $kid (@{ $self->{Kids} })
+    {
+        my $kid_type = ref $kid;
+        $kid_type =~ s/.*:://;
+        next if ($kid_type eq 'Characters');    # Don't validate character data
+
+        if (!grep( /^$kid_type$/, @allkids ))
+        {
+            &$func( "Element '$elem' cannot contain a child element '$kid_type'" );
+            $success = 0;
+        }
+    }
+
+    return $success;
+}
+
+###############################################################################
+# Validate required child elements.  Returns non-zero on success and zero if
+# any errors occurred.
+###############################################################################
+sub validate_required_kids
+{
+    my $self = shift;
+    my $func = shift;
+    my $kid;
+    my $type = ref $self;
+    my $success = 1;
+
+    my $elem = $type;
+    $elem =~ s/.*:://;
+
+    my $base = $type;
+    $base =~ s/::[^:]*?$//;
+
+    foreach $kid (@{"$type\::rkids"})
+    {
+        my @kidlist = map( ref, @{$self->{Kids}} );
+
+        if (!grep( /^$base\::$kid$/, @kidlist ))
+        {
+            &$func( "Element '$elem' must contain a '$kid' element." );
+            $success = 0;
+        }
+    }
+
+    return $success;
+}
+
+__END__
+
+###############################################################################
+# POD
+###############################################################################
+
+=head1 NAME
+
+PPM::XML::ValidatingElement - XML Element with DTD-like validation rules
+
+=head1 SYNOPSIS
+
+ use PPM::XML::ValidatingElement;
+
+ package PPM::XML::MyElement;
+ @ISA = qw( PPM::XML::ValidatingElement );
+ @oattrs = qw( BAR );       # Allow for both FOO and BAR attributes
+ @rattrs = qw( FOO );
+ @okids  = qw( BLEARGH );   # Allow for both BLEARGH and FOOBAR children
+ @rkids  = qw( FOOBAR );
+
+=head1 DESCRIPTION
+
+PPM::XML::ValidatingElement inherits from PPM::XML::Element.  It extends 
+this class to support methods for validation to allow for DTD-like 
+restrictions to be places on documents read in with the XML::Parser module.
+
+=head1 VALIDATION RULES
+
+In order to set up rules for validation of elements, each element should
+define four list values in it's own package namespace.  When validating, this
+module will check to ensure that any parsed attributes or child elements are
+actually ones that are possible for this element, as well as checking to see
+that any required attributes/child elements are present.
+
+Note that an attribute/child element only has to be present in either the
+optional or required list; when checking for possible attributes/children,
+these lists will be combined.
+
+Validation lists:
+
+=over 4
+
+=item @oattrs
+
+List of optional attributes.
+
+=item @rattrs
+
+List of required attributes.
+
+=item @opkids
+
+List of optional child elements.
+
+=item @rkids
+
+List of required child elements.
+
+=back
+
+=head1 METHODS
+
+=over 4
+
+=item validate( err_handler )
+
+Validates the current element.  This method calls four other methods to
+validate all of requirements for the element.  Returns non-zero on success and
+zero if any errors occurred.
+
+=item rvalidate( err_handler )
+
+Validates the current element, and recursively validates all child elements.
+This method calls four other methods to validate all of the requirements for
+the element.  Returns non-zero on success and zero if any errors occurred.
+
+=item validate_possible_attrs( err_handler )
+
+Checks against the list of attributes possible for this element (taken from
+@oattr and @rattr) to ensure that all of the parsed attributes are valid.  If
+any parsed attributes are not in the list of possible attributes for this
+element, err_handler will be called with a message stating the error.  Returns
+non-zero on success and zero if any errors occurred.
+
+=item validate_required_attrs( err_handler )
+
+Checks against the list of required attributes (taken from @rattr) to ensure
+that all of the required attributes are present and have been parsed.  If any
+required attributes are missing, err_handler will be called with a message
+stating the error.  Returns non-zero on success and zero if any errors
+occurred.
+
+=item validate_possible_kids( err_handler )
+
+Checks against the list of child elements this element can contain (taken from
+@okids and @rkids) to ensure that any child elements that have been read in are
+valid.  If any child elements have been parsed which are not in the list of
+possible children, err_handler will be called with a message stating the
+error.  Returns non-zero on success and zero if any errors occurred.
+
+=item validate_required_kids( err_handler )
+
+Checks against the lsit of required child elements (taken from @rkids) to
+ensure that all of the required child elements are present and have been
+parsed.  If any of the required child elements are missing, err_handler will be
+called with a message stating the error.  Returns non-zero on success and zero
+if any errors occurred.
+
+=back
+
+=head1 LIMITATIONS
+
+The PPM::XML::ValidatingElement module only provides checks for determining
+whether or not the possible/required attributes/children are present.  This 
+module currently has no support for determining whether or not the values 
+provided are actually valid (although I imagine it wouldn't be too hard to
+add this in somewhere).  This also includes elements which have been declared
+in a DTD as being 'EMPTY' elements.
+
+=head1 AUTHORS
+
+Graham TerMarsch <grahamt@activestate.com>
+
+=head1 HISTORY
+
+v0.2 - Added failure return values to each of the methods.
+
+v0.1 - Initial version
+
+=head1 SEE ALSO
+
+L<PPM::XML::Element>,
+L<XML::Parser>
+
+=cut