Crate purl

PURL parsing, manipulation, and formatting.

A PURL is an identifier that refers to a software package. For example, pkg:cargo/purl refers to this package.

This library supports PURLs at two levels:

1. The shape and format of a PURL is implemented by GenericPurl. It is possible to work with package-type-agnostic PURLs by using types like GenericPurl<String>. (see also package-url/purl-spec#38)
2. The behavior of package types is implemented by PackageType and combined with GenericPurl by the type alias Purl. This implementation differs slightly from the PURL specification (see PackageType for details). It is possible to implement different package-type-specific behaviors or support for different package types by implementing the PurlShape trait.

Example

use std::str::FromStr;

use purl::GenericPurl;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let purl = GenericPurl::<String>::from_str(
        "pkg:NPM/@acme/example@1.2.3?Checksum=sha256:\
        E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
    )?;
    assert_eq!("npm", purl.package_type());
    assert_eq!(Some("@acme"), purl.namespace());
    assert_eq!("example", purl.name());
    assert_eq!(Some("1.2.3"), purl.version());
    // Normalization is performed during parsing.
    assert_eq!(
        "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        purl.qualifiers()["checksum"],
    );
    assert_eq!(
        "pkg:npm/%40acme/example@1.2.3?checksum=sha256:\
        e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        &purl.to_string(),
    );

    let purl = purl.into_builder().without_version().without_qualifier("checksum").build()?;
    assert_eq!("pkg:npm/%40acme/example", &purl.to_string(),);
    Ok(())
}

Features

• package-type: PackageType and related types
• serde: PURLs can be serialized and deserialized from strings
• smartstring: The smartstring crate is used to reduce heap allocations

Re-exports

• pub use qualifiers::Qualifiers;

Modules

• qualifiers
  Specialized key-value collection for PURL qualifiers.

Structs

• GenericPurl
  An immutable PURL.
• GenericPurlBuilder
  A mutable, potentially invalid PURL.
• PurlParts
  The parts that make up a PURL, minus the package type.
• UnsupportedPackageTypepackage-type
  An error that is returned when an unsupported package type is used.

Enums

• PackageErrorpackage-type
  An error that is returned when working with PackageType.
• PackageTypepackage-type
  The known package types.
• ParseError
  An error returned when trying to parse an invalid PURL.
• PurlField
  A specific, fixed field of a PURL.

Traits

• PurlShape
  A type that provides package-type-specific behavior.

Type Aliases

• Purlpackage-type
  A PURL that supports the known package types.
• PurlBuilderpackage-type
  A PURL builder that supports the known package types.
• SmallStringsmartstring
  A string that may be stored inline instead of on the heap.