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

- NAME
- SYNOPSIS
- DESCRIPTION
- MAJOR ELEMENTS

- PPMCONFIG
- PACKAGE

- MINOR ELEMENTS

- PPMVER
- PLATFORM
- REPOSITORY
- OPTIONS
- PPMPRECIOUS
- LOCATION
- INSTDATE
- INSTROOT
- INSTPACKLIST
- INSTPPD

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

# NAME

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

# SYNOPSIS

     use XML::Parser;
     use PPM::XML::PPMConfig;

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

# DESCRIPTION

This module provides a set of classes for parsing PPM configuration files using the `XML::Parser` module. All of the elements unique to a PPM configuration file are derived from `PPM::XML::ValidatingElement`. There are also several classes rebuilt here which are derived from elements in `PPM::XML::PPD` as we can include a PPD file within our own INSTPPD element.

# MAJOR ELEMENTS

## PPMCONFIG

Defines a PPM configuration file. The root of a PPMConfig document is always a PPMCONFIG element.

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

NAME
  Name of the package as given in it's PPD

# MINOR ELEMENTS

## PPMVER

Child of PPMCONFIG, used to state the version of PPM for which this configuration file is valid. A single instance should be present.

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

OSVALUE
  Description of the local operating system as defined in the Config.pm file under 'osname'.

OSVERSION
  Version of the local operating system.

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

LANGUAGE
  Description of the language used on the local system as specified by the language codes in ISO 639.

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

NAME
  Name by which the repository will be known (e.g. ``ActiveState'').

LOCATION
  An URL or directory where the repository can be found.

USERNAME
  Optional username for a repository requiring authenticated connection.

PASSWORD
  Optional password for a repository requiring authenticated connection.

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

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

IGNORECASE
  Sets case-sensitive searching. Can be either '1' or '0'.

CLEAN
  Sets removal of temporarily files. Can be either '1' or '0'.

CONFIRM
  Sets confirmation of all installs/removals/upgrades. Can be either '1' or '0'.

BUILDDIR
  Directory in which packages will be unpacked before their installation.

ROOT
  Directory under which packages should be installed on the local system.

TRACE
  Level of tracing (0 is no tracing, 4 is max tracing).

TRACEFILE
  File to which trace information will be written.

VERBOSE
  Controls whether query and search results are verbose (1 == verbose, 0 == no).

## PPMPRECIOUS

Child of PPMCONFIG, used to specify the modules which PPM itself is dependant upon. A single instance should be present.

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

## INSTDATE

Child of PACKAGE, used to specify the date on which the Perl Package was installed. A single instance should be present.

## INSTROOT

Child of PACKAGE, used to specify the root directory that the Perl Package was installed into. A single instance should be present.

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

## INSTPPD

Child of PACKAGE, used to hold a copy of the PPD from which Perl Packages were installed. Multiple instances are valid.

# 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 `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)>

# SAMPLE PPMConfig FILE

The following is a sample PPMConfig file. Note that this may 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>

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

# 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 XML::Parser manpage, the PPM::XML::PPD manpage .

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