purl

package module
v0.1.18 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 27, 2026 License: MIT Imports: 10 Imported by: 15

README

purl

Go library for working with Package URLs (PURLs). Wraps packageurl-go with additional helpers for registry URL generation, type configuration, and version cleaning.

Installation

go get github.com/git-pkgs/purl

Usage

import "github.com/git-pkgs/purl"

// Parse a PURL
p, _ := purl.Parse("pkg:npm/%40babel/core@7.24.0")
fmt.Println(p.FullName())  // @babel/core
fmt.Println(p.Type)        // npm
fmt.Println(p.Version)     // 7.24.0

// Create a PURL
p := purl.New("npm", "@babel", "core", "7.24.0", nil)
fmt.Println(p.String())  // pkg:npm/%40babel/core@7.24.0

// Generate registry URL
url, _ := p.RegistryURL()
fmt.Println(url)  // https://www.npmjs.com/package/@babel/core

// Parse registry URL back to PURL
p, _ := purl.ParseRegistryURL("https://crates.io/crates/serde")
fmt.Println(p.String())  // pkg:cargo/serde

// Check if using private registry
p, _ := purl.Parse("pkg:npm/lodash?repository_url=https://npm.example.com")
fmt.Println(p.IsPrivateRegistry())  // true

// Get type configuration
cfg := purl.TypeInfo("npm")
fmt.Println(*cfg.DefaultRegistry)  // https://registry.npmjs.org

// Clean version constraints
version := purl.CleanVersion("^1.2.3", "npm")
fmt.Println(version)  // 1.2.3

Type Configuration

Type information comes from an embedded copy of purl-types.json which includes default registries, namespace requirements, and URI templates for registry URL generation.

purl.KnownTypes()           // []string of all known PURL types
purl.IsKnownType("npm")     // true
purl.DefaultRegistry("npm") // https://registry.npmjs.org

License

MIT

Documentation

Overview

Package purl provides utilities for working with Package URLs (PURLs).

It wraps github.com/package-url/packageurl-go with additional helpers for registry URL generation, type configuration, and version cleaning.

Parsing and Creating PURLs 

// Parse a PURL string
p, err := purl.Parse("pkg:npm/%40babel/core@7.24.0")
fmt.Println(p.Type)      // npm
fmt.Println(p.Namespace) // @babel
fmt.Println(p.Name)      // core
fmt.Println(p.Version)   // 7.24.0
fmt.Println(p.FullName()) // @babel/core

// Create a PURL from components
p := purl.New("npm", "@babel", "core", "7.24.0", nil)
fmt.Println(p.String()) // pkg:npm/%40babel/core@7.24.0

Registry URLs 

// Generate a registry URL from a PURL
p, _ := purl.Parse("pkg:npm/lodash@4.17.21")
url, _ := p.RegistryURLWithVersion()
fmt.Println(url) // https://www.npmjs.com/package/lodash/v/4.17.21

// Parse a registry URL back to a PURL
p, _ := purl.ParseRegistryURL("https://crates.io/crates/serde")
fmt.Println(p.String()) // pkg:cargo/serde

Type Configuration

Type information comes from an embedded purl-types.json file. 

purl.KnownTypes()           // []string of all known PURL types
purl.IsKnownType("npm")     // true
purl.DefaultRegistry("npm") // https://registry.npmjs.org

cfg := purl.TypeInfo("maven")
fmt.Println(cfg.NamespaceRequired()) // true

Private Registries 

p, _ := purl.Parse("pkg:npm/lodash?repository_url=https://npm.example.com")
fmt.Println(p.IsPrivateRegistry()) // true
fmt.Println(p.RepositoryURL())     // https://npm.example.com

Package purl provides utilities for working with Package URLs (PURLs).

It wraps github.com/package-url/packageurl-go with additional helpers for ecosystem-specific name formatting, registry URL generation, and PURL construction from ecosystem-native package identifiers.

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoMatch = errors.New("URL does not match any known registry pattern")

ErrNoMatch is returned when a URL doesn't match the reverse regex.

View Source 
var ErrNoRegistryConfig = errors.New("no registry configuration for this type")

ErrNoRegistryConfig is returned when a PURL type has no registry configuration.

Functions

func BuildPURLString added in v0.1.8 

func BuildPURLString(ecosystem, name, version, registryURL string) string

BuildPURLString builds a PURL string directly from ecosystem-native identifiers without creating intermediate PURL structs. This is the fast path for manifest parsing where we just need the string output. It returns an empty string when the package identifier cannot be represented as a PURL.

func CleanVersion 

func CleanVersion(version, scheme string) string

CleanVersion returns plain versions unchanged. For version constraints, it uses the vers library to extract the minimum bound. If parsing fails, it returns the original string.

func DefaultRegistry 

func DefaultRegistry(purlType string) string

DefaultRegistry returns the default registry URL for a PURL type. Returns empty string if the type has no default registry.

func EcosystemToOSV 

func EcosystemToOSV(ecosystem string) string

EcosystemToOSV converts an ecosystem name to the OSV ecosystem name. OSV uses specific capitalization and naming conventions.

func EcosystemToPURLType 

func EcosystemToPURLType(ecosystem string) string

EcosystemToPURLType converts an ecosystem name to the corresponding PURL type. Returns the input unchanged if no mapping exists.

func IsDefaultRegistry 

func IsDefaultRegistry(purlType, registryURL string) bool

IsDefaultRegistry returns true if the registryURL matches the default registry for the type.

func IsKnownType 

func IsKnownType(purlType string) bool

IsKnownType returns true if the PURL type is defined in types.json.

func IsNonDefaultRegistry 

func IsNonDefaultRegistry(purlType, registryURL string) bool

IsNonDefaultRegistry returns true if the registryURL is not the default registry for the type.

func IsValidEcosystem 

func IsValidEcosystem(ecosystem string) bool

IsValidEcosystem returns true if the ecosystem is recognized.

func KnownTypes 

func KnownTypes() []string

KnownTypes returns a sorted list of all known PURL types.

func MakePURLString 

func MakePURLString(ecosystem, name, version string) string

MakePURLString is like MakePURL but returns the PURL as a string. It returns an empty string when the package identifier cannot be represented as a PURL.

func NormalizeEcosystem 

func NormalizeEcosystem(ecosystem string) string

NormalizeEcosystem returns the canonical ecosystem name. Handles aliases like "go" -> "golang", "gem" -> "rubygems".

func PURLTypeToDepsdev added in v0.1.5 

func PURLTypeToDepsdev(purlType string) string

PURLTypeToDepsdev converts a PURL type to the deps.dev system name. Returns empty string if the type is not supported by deps.dev.

func PURLTypeToEcosystem 

func PURLTypeToEcosystem(purlType string) string

PURLTypeToEcosystem converts a PURL type back to an ecosystem name. This is the inverse of EcosystemToPURLType.

func PURLTypeToOSV added in v0.1.14 

func PURLTypeToOSV(purlType string) (string, bool)

PURLTypeToOSV converts a PURL type to the OSV ecosystem name and reports whether the type is one OSV recognises. Unlike EcosystemToOSV, it takes the PURL type directly (skipping the ecosystem-name normalisation when the caller already has a parsed PURL) and returns ok=false on a miss rather than passing the input through, so callers that emit OSV records can fall back to a GIT range instead of writing an ecosystem the OSV schema will reject.

func SupportedEcosystems 

func SupportedEcosystems() []string

SupportedEcosystems returns a list of all supported ecosystem names. This includes both PURL types and common aliases.

func TypesVersion 

func TypesVersion() string

TypesVersion returns the version of the types.json data.

Types

type PURL 

type PURL struct {
	packageurl.PackageURL
}

PURL wraps packageurl.PackageURL with additional helpers.

func MakePURL 

func MakePURL(ecosystem, name, version string) *PURL

MakePURL constructs a PURL from ecosystem-native package identifiers.

It handles namespace extraction for ecosystems:

  • npm: @scope/pkg -> namespace="@scope", name="pkg"
  • maven: group:artifact -> namespace="group", name="artifact"
  • golang: github.com/foo/bar -> namespace="github.com/foo", name="bar"
  • composer: vendor/package -> namespace="vendor", name="package"
  • alpine: pkg -> namespace="alpine", name="pkg"
  • arch: pkg -> namespace="arch", name="pkg"
  • swift: host/owner/package -> namespace="host/owner", name="package"

Swift registry identities do not contain source repository coordinates and return nil because the Swift PURL type cannot represent them.

func New 

func New(purlType, namespace, name, version string, qualifiers map[string]string) *PURL

New creates a new PURL from components.

The result is normalized with the same per-type rules Parse applies (packageurl-go's Normalize), so New and Parse produce the same string for equivalent inputs. Normalization errors are ignored; any adjustments Normalize applied before erroring are kept.

func Parse 

func Parse(s string) (*PURL, error)

Parse parses a Package URL string into a PURL.

func ParseRegistryURL 

func ParseRegistryURL(url string) (*PURL, error)

ParseRegistryURL attempts to parse a registry URL into a PURL. It tries all known types to find a match.

func ParseRegistryURLWithType 

func ParseRegistryURLWithType(url, purlType string) (*PURL, error)

ParseRegistryURLWithType parses a registry URL using a specific PURL type.

func (*PURL) FullName 

func (p *PURL) FullName() string

FullName returns the package name combining namespace and name. If there's no namespace, returns just the name. Maven uses ":" as separator (groupId:artifactId), all others use "/".

func (*PURL) IsPrivateRegistry 

func (p *PURL) IsPrivateRegistry() bool

IsPrivateRegistry returns true if the PURL has a non-default repository_url.

func (*PURL) Qualifier 

func (p *PURL) Qualifier(key string) string

Qualifier returns the value of a qualifier, or empty string if not present.

func (*PURL) RegistryURL 

func (p *PURL) RegistryURL() (string, error)

RegistryURL returns the human-readable registry URL for the package. For example, pkg:npm/lodash returns "https://www.npmjs.com/package/lodash".

func (*PURL) RegistryURLWithVersion 

func (p *PURL) RegistryURLWithVersion() (string, error)

RegistryURLWithVersion returns the registry URL including version. Falls back to RegistryURL if version URLs aren't supported.

func (*PURL) RepositoryURL 

func (p *PURL) RepositoryURL() string

RepositoryURL returns the repository_url qualifier value, if present.

func (*PURL) String 

func (p *PURL) String() string

String returns the PURL as a string.

func (*PURL) WithQualifier 

func (p *PURL) WithQualifier(key, value string) *PURL

WithQualifier returns a copy of the PURL with the qualifier set. If the qualifier already exists, it is replaced.

func (*PURL) WithVersion 

func (p *PURL) WithVersion(version string) *PURL

WithVersion returns a copy of the PURL with a different version.

func (*PURL) WithoutVersion 

func (p *PURL) WithoutVersion() *PURL

WithoutVersion returns a copy of the PURL without a version.

type RegistryComponents 

type RegistryComponents struct {
	Namespace         bool   `json:"namespace"`
	NamespaceRequired bool   `json:"namespace_required"`
	NamespacePrefix   string `json:"namespace_prefix"`
	VersionInURL      bool   `json:"version_in_url"`
	VersionPath       string `json:"version_path"`
	VersionPrefix     string `json:"version_prefix"`
	VersionSeparator  string `json:"version_separator"`
	DefaultVersion    string `json:"default_version"`
	TrailingSlash     bool   `json:"trailing_slash"`
	SpecialHandling   string `json:"special_handling"`
}

RegistryComponents describes which PURL components are used in registry URLs.

type RegistryConfig 

type RegistryConfig struct {
	BaseURL                    string             `json:"base_url"`
	ReverseRegex               string             `json:"reverse_regex"`
	URITemplate                string             `json:"uri_template"`
	URITemplateNoNamespace     string             `json:"uri_template_no_namespace"`
	URITemplateWithVersion     string             `json:"uri_template_with_version"`
	URITemplateWithVersionNoNS string             `json:"uri_template_with_version_no_namespace"`
	Components                 RegistryComponents `json:"components"`
}

RegistryConfig contains URL templates and patterns for registry URLs.

type TypeConfig 

type TypeConfig struct {
	Description          string          `json:"description"`
	DefaultRegistry      *string         `json:"default_registry"`
	NamespaceRequirement string          `json:"namespace_requirement"`
	Examples             []string        `json:"examples"`
	RegistryConfig       *RegistryConfig `json:"registry_config"`
}

TypeConfig contains configuration for a PURL type.

func TypeInfo 

func TypeInfo(purlType string) *TypeConfig

TypeInfo returns configuration for a PURL type, or nil if unknown.

func (*TypeConfig) NamespaceProhibited 

func (t *TypeConfig) NamespaceProhibited() bool

NamespaceProhibited returns true if the type prohibits namespaces.

func (*TypeConfig) NamespaceRequired 

func (t *TypeConfig) NamespaceRequired() bool

NamespaceRequired returns true if the type requires a namespace.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.