Ubuntu Manpage: URI::PackageURL - Perl extension for Package URL (aka "purl")

Provided by: liburi-packageurl-perl_2.23-1_all

NAME

       URI::PackageURL - Perl extension for Package URL (aka "purl")

SYNOPSIS

         use URI::PackageURL;

         # OO-interface

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

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

         # Parse Package URL string
         $purl = URI::PackageURL->from_string('pkg:cpan/GDT/URI-PackageURL@2.23');

         # 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.23');
         say $purl; # pkg:cpan/GDT/URI-PackageURL@2.23
         say $purl->version; # 2.23

         # exported functions

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

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

         # 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');

DESCRIPTION

       This module converts Package URL components to "purl" string and vice versa.

       A Package URL (aka "purl") 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.

       <https://github.com/package-url/purl-spec>

       A purl is a URL composed of seven components:

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

       Components are separated by a specific character for unambiguous parsing.

       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/master/PURL-TYPES.rst>)

       •   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).

   FUNCTIONAL INTERFACE
       They are exported by default:

       $purl_string = encode_purl(%purl_components)
           Converts the given Package URL components to "purl" string. Croaks on error.

           This function call is functionally identical to:

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

       $purl_components = decode_purl($purl_string)
           Converts the given "purl" string to Package URL components. Croaks on error.

           This function call is functionally identical to:

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

   OBJECT-ORIENTED INTERFACE
       $purl = URI::PackageURL->new(%components)
           Create new URI::PackageURL instance using provided Package URL components (type, name, version ,etc).

       $purl->scheme
           The scheme is a constant with the value "pkg".

       $purl->type
           The package "type" or package "protocol" such as cpan, maven, npm, nuget, gem, pypi, etc.

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

       $purl->name
           The "name" of the package.

       $purl->version
           The "version" of the package.

       $purl->qualifiers
           Extra qualifying data for a package such as an OS, architecture, a distro, etc.

       $purl->subpath
           Extra subpath within a package, relative to the package root.

       $purl->to_string
           Stringify Package URL components.

       $purl->to_urls
           Return download and/or repository URLs.

       $purl->to_hash
           Turn PURL components into a hash reference.

       $purl->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.23"
               # }

       $purl = URI::PackageURL->from_string($purl_string);
           Converts the given "purl" string to Package URL components. 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.

   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>

LICENSE AND COPYRIGHT

       This software is copyright (c) 2022-2025 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.

perl v5.40.1                                       2025-11-03                               URI::PackageURL(3pm)