PPM::XML::PPD - PPD file format and XML parsing elements

NAME

PPM::XML::PPD - PPD file format and XML parsing elements

SYNOPSIS

 use XML::Parser;
 use PPM::XML::PPD;
 $p = new PPM::XML::Parser( Style => 'Objects', Pkg => 'PPM::XML::PPD' );
 ...

DESCRIPTION

This module provides a set of classes for parsing PPD files using the XML::Parser module. Each of the classes is derived from PPM::XML::ValidatingElement, with optional/required attributes/children enforced.

MAJOR ELEMENTS

SOFTPKG

Defines a Perl Package. The root of a PPD document is always a SOFTPKG element. The SOFTPKG element allows for the following attributes:

NAME
Required attribute. Name of the package (e.g. ``Foobar'').

VERSION
Version number of the package, in comma-delimited format (e.g. ``1,0,0,0'').

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.

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:

NAME
Name of the package that this implementation is dependant upon.

VERSION
Version number of the dependency, in comma-delimited format (e.g. ``1,0,0,0'').

MINOR ELEMENTS

TITLE

Child of SOFTPKG, used to state the title of the Perl Package. Only one instance should be present.

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.

AUTHOR

Child of SOFTPKG, used to provide information about the author(s) of the Perl Package. Multiple instances are valid.

LANGUAGE

Child of IMPLEMENTATION, used to specify the language used within the given implementation of the Perl Package. Only one instance should be present.

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:

HREF
Required attribute. A reference to the location of the license agreement or copyright notice for this package.

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:

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

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.

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:

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'').

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.

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:

VERSION
Version of the Perl core that is required for this implementation of the Perl Package.

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:

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

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.

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:

FILENAME
???

HREF
Required attribute. A reference to the location of the Perl Package distribution.

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:

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.

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.

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:

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.

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.

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

SAMPLE PPD FILE

The following is a sample PPD file describing the Math-MatrixBool module. Note that this may 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>

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.

AUTHORS

Graham TerMarsch <grahamt@ActiveState.com>

Murray Nesbitt <murrayn@ActiveState.com>

Dick Hardt <dick_hardt@ActiveState.com>

HISTORY

v0.1 - Initial release

SEE ALSO

the PPM::XML::ValidatingElement manpage, the PPM::XML::Element manpage, the XML::Parser manpage, OSD Specification (http://www.microsoft.com/standards/osd/)

 PPM::XML::PPD - PPD file format and XML parsing elements