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

- NAME
- SYNOPSIS
- DESCRIPTION
- MAJOR ELEMENTS

- SOFTPKG
- IMPLEMENTATION
- DEPENDENCY

- MINOR ELEMENTS

- TITLE
- ABSTRACT
- AUTHOR
- LANGUAGE
- LICENSE
- OS
- OSVERSION
- PERLCORE
- PROCESSOR
- CODEBASE
- INSTALL
- UNINSTALL

- DOCUMENT TYPE DEFINITION
- SAMPLE PPD FILE
- KNOWN BUGS/ISSUES
- AUTHORS
- HISTORY
- SEE ALSO

# 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