Module pkgsrc::summary

pkg_summary(5) parsing and generation.

A pkg_summary file contains a selection of useful package metadata, and is primarily used by binary package managers to configure package repositories.

A package entry in pkg_summary contains a list of VARIABLE=VALUE pairs, and a complete pkg_summary file consists of multiple package entries separated by a single blank line.

This module supports parsing a pkg_summary file, for example if configuring a remote repository, as well as generating pkg_summary output from a binary package or local repository.

A Summary is a complete entry for a package. It implements the FromStr trait which is the primary method of parsing an existing pkg_summary entry. A new Summary can also be created from package metadata, using various functions that are provided.

A collection of Summary entries can be stored in a SummaryStream, thus containing a complete pkg_summary file for a package repository. SummaryStream implements both FromStr and Write, so can be populated by streaming in a pkg_summary file.

Examples

Read pkg_summary

Read the generated pkg_summary output from pkg_info -Xa and parse into a new SummaryStream containing a Summary for each entry.

use pkgsrc::summary;
use std::io::BufReader;
use std::process::{Command, Stdio};

fn main() -> summary::Result<()> {
    let mut pkgsum = summary::SummaryStream::new();

    /*
     * Read "pkg_info -Xa" output into a buffer.
     */
    let pkg_info = Command::new("/opt/pkg/sbin/pkg_info")
        .args(&["-X", "-a"])
        .stdout(Stdio::piped())
        .spawn()
        .expect("could not spawn pkg_info");
    let mut pkg_info = BufReader::new(pkg_info.stdout.expect("failed"));

    /*
     * SummaryStream implements the Write trait, so copying the data in will
     * parse it into separate Summary entries and return a Result.
     */
    std::io::copy(&mut pkg_info, &mut pkgsum)?;

    /*
     * We have a complete pkg_summary, let's emulate "pkg_info".  Note that
     * each Summary entry will have been validated to ensure all required
     * entries exist, so it's safe to unwrap those.
     */
    for pkg in pkgsum.entries() {
        println!("{:20} {}", pkg.pkgname().unwrap(), pkg.comment().unwrap());
    }

    Ok(())
}

Generate a pkg_summary entry

Create a Summary entry from package metadata. Here we only set the minimum required fields, using is_completed() to check for validity.

use pkgsrc::summary::Summary;

let mut sum = Summary::new();

assert_eq!(sum.is_completed(), false);

sum.set_build_date("2019-08-12 15:58:02 +0100");
sum.set_categories("devel pkgtools");
sum.set_comment("This is a test");
sum.set_description(&["A test description".to_string(),
                      "".to_string(),
                      "This is a multi-line variable".to_string()]);
sum.set_machine_arch("x86_64");
sum.set_opsys("Darwin");
sum.set_os_version("18.7.0");
sum.set_pkgname("testpkg-1.0");
sum.set_pkgpath("pkgtools/testpkg");
sum.set_pkgtools_version("20091115");
sum.set_size_pkg(4321);

assert_eq!(sum.is_completed(), true);

/*
 * With the Display trait implemented we can simply print the Summary and
 * it will be output in the correct format, i.e.
 *
 * BUILD_DATE=2019-08-12 15:58:02 +0100
 * CATEGORIES=devel pkgtools
 * COMMENT=This is a test
 * DESCRIPTION=A test description
 * DESCRIPTION=
 * DESCRIPTION=This is a multi-line variable
 * ...
 */
println!("{}", sum);

Structs

Summary	A complete pkg_summary(5) entry.
SummaryStream	A collection of pkg_summary(5) entries.

Enums

MissingVariable	Missing variables that are required for a valid pkg_summary(5) entity.
SummaryError	Enum containing possible reasons that parsing pkg_summary(5) failed.
SummaryVariable	Supported pkg_summary(5) variables.

Type Definitions

Result

A type alias for the result from the creation of either a Summary or a SummaryStream, with SummaryError returned in Err variants.