Module summary 

Parsing and generation of pkg_summary(5) package metadata.

A pkg_summary file contains a selection of useful package metadata, and is primarily used by binary package managers to retrieve information about a package repository.

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

A Summary can be created in two ways:

• Parsing: Use Summary::from_reader to parse multiple entries from any BufRead source, returning an iterator over Result<Summary>. Single entries can be parsed using FromStr.

• Building: Use SummaryBuilder::new, add VARIABLE=VALUE lines with SummaryBuilder::vars, then call SummaryBuilder::build to validate and construct the entry.

Parsing operations return Error on failure. Each error variant includes span information for use with pretty-printing error reporting libraries such as ariadne or miette which can be helpful to show exact locations of errors.

Once validated, Summary provides many access methods to retrieve information about each variable in a summary entry.

Examples

Read pkg_summary.gz and print list of packages in pkg_info format, similar to how pkgin avail works.

use flate2::read::GzDecoder;
use pkgsrc::summary::Summary;
use std::fs::File;
use std::io::BufReader;

let path = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/summary/pkg_summary.gz");
let file = File::open(path).expect("failed to open pkg_summary.gz");
let reader = BufReader::new(GzDecoder::new(file));

for pkg in Summary::from_reader(reader) {
    let pkg = pkg?;
    println!("{:20} {}", pkg.pkgname(), pkg.comment());
}

Create a Summary entry 4 different ways from an input file containing pkg_summary data for mktool-1.4.2 extracted from the main pkg_summary.gz.

use pkgsrc::summary::{Summary, SummaryBuilder};
use std::str::FromStr;

let path = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/summary/mktool.txt");
let input = std::fs::read_to_string(path).expect("failed to read mktool.txt");

// Parse implicitly through FromStr's parse
assert_eq!(
    input.parse::<Summary>().expect("parse failed").pkgname(),
    "mktool-1.4.2"
);

// Parse explicitly via from_str
assert_eq!(
    Summary::from_str(&input).expect("from_str failed").pkgname(),
    "mktool-1.4.2"
);

// Use the builder pattern, passing all input through a single vars() call.
assert_eq!(
    SummaryBuilder::new()
        .vars(input.lines())
        .build()
        .expect("build failed")
        .pkgname(),
    "mktool-1.4.2"
);

// Use the builder pattern but build up the input with separate var() calls.
let mut builder = SummaryBuilder::new();
for line in input.lines() {
    builder = builder.var(line);
}
assert_eq!(builder.build().expect("build failed").pkgname(), "mktool-1.4.2");

Re-exports

pub use crate::kv::Span;

Structs

ErrorContext

Error context containing optional entry number and span information.

Summary

A single pkg_summary(5) entry.

SummaryBuilder

Builder for constructing a Summary from VARIABLE=VALUE lines.

SummaryIter

Iterator that parses Summary entries from a BufRead source.

Enums

Error

Error type for pkg_summary(5) parsing operations.

Type Aliases

Result

A type alias for the result from parsing a Summary, with Error returned in Err variants.