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 ¶
- Variables
- func CleanVersion(version, scheme string) string
- func DefaultRegistry(purlType string) string
- func EcosystemToOSV(ecosystem string) string
- func EcosystemToPURLType(ecosystem string) string
- func IsDefaultRegistry(purlType, registryURL string) bool
- func IsKnownType(purlType string) bool
- func IsNonDefaultRegistry(purlType, registryURL string) bool
- func IsValidEcosystem(ecosystem string) bool
- func KnownTypes() []string
- func MakePURLString(ecosystem, name, version string) string
- func NormalizeEcosystem(ecosystem string) string
- func PURLTypeToEcosystem(purlType string) string
- func SupportedEcosystems() []string
- func TypesVersion() string
- type PURL
- func (p *PURL) FullName() string
- func (p *PURL) IsPrivateRegistry() bool
- func (p *PURL) Qualifier(key string) string
- func (p *PURL) RegistryURL() (string, error)
- func (p *PURL) RegistryURLWithVersion() (string, error)
- func (p *PURL) RepositoryURL() string
- func (p *PURL) String() string
- func (p *PURL) WithQualifier(key, value string) *PURL
- func (p *PURL) WithVersion(version string) *PURL
- func (p *PURL) WithoutVersion() *PURL
- type RegistryComponents
- type RegistryConfig
- type TypeConfig
Constants ¶
This section is empty.
Variables ¶
var ErrNoMatch = errors.New("URL does not match any known registry pattern")
ErrNoMatch is returned when a URL doesn't match the reverse regex.
var ErrNoRegistryConfig = errors.New("no registry configuration for this type")
ErrNoRegistryConfig is returned when a PURL type has no registry configuration.
Functions ¶
func CleanVersion ¶
CleanVersion extracts a version from a version constraint string. Uses the vers library to parse the constraint and extract the minimum bound. If parsing fails, returns the original string.
func DefaultRegistry ¶
DefaultRegistry returns the default registry URL for a PURL type. Returns empty string if the type has no default registry.
func EcosystemToOSV ¶
EcosystemToOSV converts an ecosystem name to the OSV ecosystem name. OSV uses specific capitalization and naming conventions.
func EcosystemToPURLType ¶
EcosystemToPURLType converts an ecosystem name to the corresponding PURL type. Returns the input unchanged if no mapping exists.
func IsDefaultRegistry ¶
IsDefaultRegistry returns true if the registryURL matches the default registry for the type.
func IsKnownType ¶
IsKnownType returns true if the PURL type is defined in types.json.
func IsNonDefaultRegistry ¶
IsNonDefaultRegistry returns true if the registryURL is not the default registry for the type.
func IsValidEcosystem ¶
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 ¶
MakePURLString is like MakePURL but returns the PURL as a string.
func NormalizeEcosystem ¶
NormalizeEcosystem returns the canonical ecosystem name. Handles aliases like "go" -> "golang", "gem" -> "rubygems".
func PURLTypeToEcosystem ¶
PURLTypeToEcosystem converts a PURL type back to an ecosystem name. This is the inverse of EcosystemToPURLType.
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 ¶
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"
func ParseRegistryURL ¶
ParseRegistryURL attempts to parse a registry URL into a PURL. It tries all known types to find a match.
func ParseRegistryURLWithType ¶
ParseRegistryURLWithType parses a registry URL using a specific PURL type.
func (*PURL) FullName ¶
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 ¶
IsPrivateRegistry returns true if the PURL has a non-default repository_url.
func (*PURL) Qualifier ¶
Qualifier returns the value of a qualifier, or empty string if not present.
func (*PURL) RegistryURL ¶
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 ¶
RegistryURLWithVersion returns the registry URL including version. Falls back to RegistryURL if version URLs aren't supported.
func (*PURL) RepositoryURL ¶
RepositoryURL returns the repository_url qualifier value, if present.
func (*PURL) WithQualifier ¶
WithQualifier returns a copy of the PURL with the qualifier set. If the qualifier already exists, it is replaced.
func (*PURL) WithVersion ¶
WithVersion returns a copy of the PURL with a different version.
func (*PURL) WithoutVersion ¶
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