Module pkgsrc::plist

Packing list parsing and generation.

Packing lists, commonly referred to as plists and named PLIST in pkgsrc package directories, contain a list of files contents that are installed by a package. They also support a limited number of commands that configure additional package metadata, as well as setting file permissions and performing install and deinstall commands for extracted files.

As plists can contain data that is not UTF-8 clean (for example ISO-8859 filenames), the primary interfaces for parsing input are the from_bytes() functions for both PlistEntry and Plist.

Where possible, PlistEntry types are represented by String for simpler handling (and enforced UTF-8 correctness), otherwise OsString is used.

A PlistEntry is an enum representing a single line in a plist, and a Plist is a collection of PlistEntry making up a complete plist.

Once a Plist has been configured, various functions allow examination of the parsed data.

Examples

Initialize a basic PLIST. Blank lines are ignored, and only used here for clarity.

use pkgsrc::plist::{Plist, Result};
use unindent::unindent;

fn main() -> Result<()> {
    let input = unindent(
        r#"
        @comment $NetBSD$

        @name pkgtest-1.0
        @pkgdep dep-pkg1-[0-9]*
        @pkgdep dep-pkg2>=2.0
        @blddep dep-pkg1-1.0nb2
        @blddep dep-pkg2-2.0nb4
        @pkgcfl cfl-pkg1<2.0

        @display MESSAGE

        @cwd /opt/pkg

        @comment bin/foo installed with specific permissions, preserved
        @comment on uninstall (obsolete feature?), and commands are executed
        @comment after it is installed and deleted.

        @option preserve
        @mode 0644
        @owner root
        @group wheel
        bin/foo
        @exec echo "I just installed F=%F D=%D B=%B f=%f"
        @unexec echo "I just deleted F=%F D=%D B=%B f=%f"

        @comment bin/bar just installed with default permissions

        @mode
        @owner
        @group
        bin/bar

        @pkgdir /opt/pkg/share/junk
        @dirrm /opt/pkg/share/obsolete-option

        @ignore
        +BUILD_INFO
        "#);

     let pkglist = Plist::from_bytes(&input.as_bytes())?;

     assert_eq!(pkglist.pkgname(), Some("pkgtest-1.0"));
     assert_eq!(pkglist.depends().len(), 2);
     assert_eq!(pkglist.build_depends().len(), 2);
     assert_eq!(pkglist.conflicts().len(), 1);
     assert_eq!(pkglist.pkgdirs().len(), 1);
     assert_eq!(pkglist.pkgrmdirs().len(), 1);

     Ok(())
}

Structs

Plist

A complete list of PlistEntry entries.

Enums

PlistEntry	A single plist entry.
PlistError	Error type containing possible parse failures.
PlistOption	List of valid arguments for the @option command. Currently the only supported argument is preserve.

Type Definitions

Result

A type alias for the result from the creation of either a PlistEntry or a Plist, with Error returned in Err variants.