Module plist 

Packing list parsing.

Packing lists, commonly referred to as plists and named PLIST in pkgsrc package directories, contain a list of files 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.

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 parsed, various functions allow examination of the parsed data.

As plists can contain data that is not UTF-8 clean (for example ISO-8859 filenames), the primary interfaces for parsing input are byte oriented.

Two parser styles are available:

• Plist::from_bytes parses the entire byte slice eagerly into an owning Plist, a Vec<PlistEntry<'static>> with named query methods. Use this when you want to interrogate the plist multiple times.

• parse returns a lazy iterator of PlistEntry<'_> borrowing directly from the source bytes. Use this when you only need to walk the plist once: it avoids per-entry allocation.

Examples

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

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

fn main() -> Result<()> {
    let input = indoc! {"
        @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().count(), 2);
     assert_eq!(pkglist.build_depends().count(), 2);
     assert_eq!(pkglist.conflicts().count(), 1);
     assert_eq!(pkglist.pkgdirs().count(), 1);
     assert_eq!(pkglist.pkgrmdirs().count(), 1);

     Ok(())
}

Plist implements IntoIterator, allowing direct iteration over entries:

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

fn main() -> Result<()> {
    let plist = Plist::from_bytes(b"@name pkg-1.0\nbin/foo\nbin/bar")?;

    for entry in &plist {
        if let PlistEntry::File(path) = entry {
            println!("File: {}", path.display());
        }
    }

    Ok(())
}

Structs

FileInfo

Information about a file in the packing list, including optional metadata.

Parser

A lazy iterator over a plist’s entries, borrowing from the source bytes.

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.

Functions

parse

Lazily parse bytes into a stream of PlistEntry values.

Type Aliases

Result

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