URI::PackageURL(3pm)

📦
version 2.25 · 2 versions
, in ubuntu resolute, ubuntu stonking

💅 NAME 💅

URI::PackageURL — the Perl extension for PURL (Package URL). That's the whole vibe bestie, and yes, this is the page you get when you ask man for URI::PackageURL(3pm) 🫶

✨ SYNOPSIS ✨

Okay so here's the entire flex, in code, untouched, exactly as it ships:

use URI::PackageURL;

# OO-interface

# Encode components in PURL string
$purl = URI::PackageURL->new(
  type      => 'cpan',
  namespace => 'GDT',
  name      => 'URI-PackageURL',
  version   => '2.25'
);

say $purl; # pkg:cpan/GDT/URI-PackageURL@2.25

# Parse a PURL string
$purl = URI::PackageURL->from_string('pkg:cpan/GDT/URI-PackageURL@2.25');

# use setter methods

my $purl = URI::PackageURL->new(type => 'cpan', namespace => 'GDT', name => 'URI-PackageURL');

say $purl; # pkg:cpan/GDT/URI-PackageURL
say $purl->version; # undef

$purl->version('2.25');
say $purl; # pkg:cpan/GDT/URI-PackageURL@2.25
say $purl->version; # 2.25

# exported functions

$purl = decode_purl('pkg:cpan/GDT/URI-PackageURL@2.25');
say $purl->type;  # cpan

$purl_string = encode_purl(type => cpan, namespace => 'GDT', name => 'URI-PackageURL', version => '2.25');
say $purl_string; # pkg:cpan/GDT/URI-PackageURL@2.25

# uses the legacy CPAN PURL type, to be used only for compatibility (will be removed in the future)

$ENV{PURL_LEGACY_CPAN_TYPE} = 1;
URI::PackageURL->new(type => 'cpan', name => 'URI::PackageURL');

# alias

$purl = PURL->new(
  type      => 'cpan',
  namespace => 'GDT',
  name      => 'URI-PackageURL',
  version   => '2.25'
);

$purl = PURL->from_string('pkg:cpan/GDT/URI-PackageURL');

# clone

$cloned = $purl->clone;

$cloned->version('1.00');

say $cloned; # pkg:cpan/GDT/URI-PackageURL@1.00
say $purl;   # pkg:cpan/GDT/URI-PackageURL@2.25

💖 DESCRIPTION 💖

So. This module takes PURL components and turns them into a PURL string, and it takes a PURL string and turns it back into components. Both directions, no cap. 🔁

A PURL (Package URL) is a URL string used to identify and locate a software package in a mostly universal and uniform way across programing languages, package managers, packaging conventions, tools, APIs and databases. It's giving world peace but for package identifiers ✨

A purl is a URL composed of seven components:

scheme:type/namespace/name@version?qualifiers#subpath

Components are separated by a specific character, because unambiguous parsing is the moment and we're not ruining it with guesswork 💅

The definition for each components is:

  • scheme — this is the URL scheme with the constant value of pkg. One of the primary reason for this single scheme is to facilitate the future official registration of the pkg scheme for package URLs. Required. 👑
  • type — the package type or package protocol such as cpan, maven, npm, nuget, gem, pypi, etc. Required.
  • namespace — some name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization. Optional and type-specific.
  • name — the name of the package. Required.
  • version — the version of the package. Optional.
  • qualifiers — extra qualifying data for a package such as an OS, architecture, a distro, etc. Optional and type-specific.
  • subpath — extra subpath within a package, relative to the package root. Optional.

🎀 CPAN PURL TYPE 🎀

cpan is an official PURL type ( https://github.com/package-url/purl-spec/blob/main/types-doc/cpan-definition.md ) 🍓

  • The default repository is https://www.cpan.org/.
  • The namespace is the CPAN id of the author/publisher. It MUST be written uppercase and is required.
  • The name is the distribution name and is case sensitive. A distribution name MUST NOT contain the string ::.
  • The version is the distribution version.
  • Optional qualifiers may include:
    • repository_url: CPAN/MetaCPAN/BackPAN/DarkPAN repository base URL (default is https://www.cpan.org)
    • download_url: URL of package or distribution
    • vcs_url: extra URL for a package version control system
    • ext: file extension (default is tar.gz)

Examples

pkg:cpan/DROLSKY/DateTime@1.55
pkg:cpan/GDT/URI-PackageURL
pkg:cpan/OALDERS/libwww-perl@6.76

Legacy CPAN PURL type

Add PURL_LEGACY_CPAN_TYPE environment variable for use the legacy CPAN PURL type.

⚠️ NOTE: This is only to be used for compatibility purposes (it will be removed in the future). Like, it's on its way out bestie, don't build your whole personality on it 😭

🧚 FUNCTIONAL INTERFACE 🧚

They are exported by default:

encode_purl

$purl_string = encode_purl(%purl_components)

Converts the given PURL components to PURL string. Croaks on error. 💀

This function call is functionally identical to:

$purl_string = URI::PackageURL->new(%purl_components)->to_string;

decode_purl

$purl_components = decode_purl($purl_string)

Converts the given PURL string to PURL components. Croaks on error.

This function call is functionally identical to:

$purl = URI::PackageURL->from_string($purl_string);

👑 OBJECT-ORIENTED INTERFACE 👑

new

$purl = URI::PackageURL->new(%components)
$purl = PURL->new(%components)

Create new URI::PackageURL instance using provided PURL components (type, name, version, etc).

Disable PURL-type validation:

$purl = URI::PackageURL->new(validate => 0, ...);

Allowed parameters:

  • validate, Enable/Disable PURL-type validation (default: 1).
  • type, PURL type component.
  • namespace, PURL namespace component.
  • name, PURL name component.
  • version, PURL version component.
  • qualifiers, PURL qualifiers component (default: {}).
  • subpath, PURL subpath component.

scheme

The scheme is a constant with the value pkg. Never changes, never will. Iconic behaviour honestly ⭐

type

The package type or package protocol such as cpan, maven, npm, nuget, gem, pypi, etc.

namespace

Some name prefix such as a Maven groupid, a Docker image owner, a GitHub user or organization. Optional and type-specific.

name

The name of the package.

version

The version of the package.

qualifiers

Extra qualifying data for a package such as an OS, architecture, a distro, etc.

subpath

Extra subpath within a package, relative to the package root.

to_string

Stringify Package URL components. ✨

to_urls

Return download and/or repository URLs.

download_url

Return download URL.

See purl_to_urls in URI::PackageURL::Util.

repository_url

Return repository URL.

See purl_to_urls in URI::PackageURL::Util.

to_hash

Turn PURL components into a hash reference.

definition

Return URI::PackageURL::Type instance.

clone

Clone PURL object. Two separate little guys, living two separate lives 🦋

$cloned = $purl->clone;

$cloned->version('1.00');

say $cloned; # pkg:cpan/GDT/URI-PackageURL@1.00
say $purl;   # pkg:cpan/GDT/URI-PackageURL@2.25

TO_JSON

Helper method for JSON modules (JSON, JSON::PP, JSON::XS, Cpanel::JSON::XS, Mojo::JSON, etc).

use Mojo::JSON qw(encode_json);

say encode_json($purl);

# {
#    "name" : "URI-PackageURL",
#    "namespace" : "GDT",
#    "qualifiers" : {},
#    "scheme" : "pkg",
#    "subpath" : null,
#    "type" : "cpan",
#    "version" : "2.25"
# }

from_string

$purl = URI::PackageURL->from_string($purl_string);
$purl = PURL->from_string($purl_string);

Converts the given PURL string to PURL components and return URI::PackageURL instance. Croaks on error. 😤

🫶 SUPPORT 🫶

💀 Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/giterlizzi/perl-URI-PackageURL/issues. You will be notified automatically of any progress on your issue. So you'll literally know the second someone fixes your thing, no refreshing, no anxiety, slay 🙈

🦋 Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/giterlizzi/perl-URI-PackageURL

git clone https://github.com/giterlizzi/perl-URI-PackageURL.git

⭐ AUTHOR ⭐

  • Giuseppe Di Terlizzi <gdt@cpan.org>

This software is copyright (c) 2022-2026 by Giuseppe Di Terlizzi.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🎀

okay bestie that's the whole page 💖 shoutout to perl v5.40.1, dated 2026-01-31, and to this very manual page URI::PackageURL(3pm) for existing so I could tell you about it. go build something cute with it, periodt 👑🌸

📦 where this page comes from