packageurl

README

packageurl-go

Go implementation of the package url spec.

Install

go get -u github.com/package-url/packageurl-go

Versioning

The versions will follow the spec. So if the spec is released at 1.0. Then all versions in the 1.x.y will follow the 1.x spec.

Usage

Create from parts

package main

import (
	"fmt"

	"github.com/package-url/packageurl-go"
)

func main() {
	instance := packageurl.NewPackageURL("test", "ok", "name", "version", nil, "")
	fmt.Printf("%s", instance.ToString())
}

Parse from string

package main

import (
	"fmt"

	"github.com/package-url/packageurl-go"
)

func main() {
	instance, err := packageurl.FromString("test:ok/name@version")
	if err != nil {
		panic(err)
	}
	fmt.Printf("%#v", instance)
}

Test

Testing using the normal go test command. Using make test will pull the test fixtures shared between all package-url projects and then execute the tests.

$ make test
go test -v -cover ./...
=== RUN   TestFromStringExamples
--- PASS: TestFromStringExamples (0.00s)
=== RUN   TestToStringExamples
--- PASS: TestToStringExamples (0.00s)
PASS
coverage: 94.7% of statements
ok      github.com/package-url/packageurl-go    0.002s

Documentation

Overview

Package packageurl implements the package-url spec

Index

• Variables
• type PackageURL
  • func FromString(purl string) (PackageURL, error)
  • func NewPackageURL(purlType, namespace, name, version string, qualifiers Qualifiers, ...) *PackageURL
  • func (p PackageURL) String() string
  • func (p *PackageURL) ToString() string
• type Qualifier
  • func (q Qualifier) String() string
• type Qualifiers
  • func QualifiersFromMap(mm map[string]string) Qualifiers
  • func (qq Qualifiers) Map() map[string]string
  • func (qq Qualifiers) String() string

Variables

var (
	// TypeAlpine is a pkg:apk purl.
	TypeAlpine = "apk"
	// TypeBitbucket is a pkg:bitbucket purl.
	TypeBitbucket = "bitbucket"
	// TypeCocoapods is a pkg:cocoapods purl.
	TypeCocoapods = "cocoapods"
	// TypeCargo is a pkg:cargo purl.
	TypeCargo = "cargo"
	// TypeComposer is a pkg:composer purl.
	TypeComposer = "composer"
	// TypeConan is a pkg:conan purl.
	TypeConan = "conan"
	// TypeConda is a pkg:conda purl.
	TypeConda = "conda"
	// TypeCran is a pkg:cran purl.
	TypeCran = "cran"
	// TypeDebian is a pkg:deb purl.
	TypeDebian = "deb"
	// TypeDocker is a pkg:docker purl.
	TypeDocker = "docker"
	// TypeGem is a pkg:gem purl.
	TypeGem = "gem"
	// TypeGeneric is a pkg:generic purl.
	TypeGeneric = "generic"
	// TypeGithub is a pkg:github purl.
	TypeGithub = "github"
	// TypeGolang is a pkg:golang purl.
	TypeGolang = "golang"
	// TypeHackage is a pkg:hackage purl.
	TypeHackage = "hackage"
	// TypeHex is a pkg:hex purl.
	TypeHex = "hex"
	// TypeOTP is a pkg:otp purl.
	TypeOTP = "otp"
	// TypeMaven is a pkg:maven purl.
	TypeMaven = "maven"
	// TypeNPM is a pkg:npm purl.
	TypeNPM = "npm"
	// TypeNuget is a pkg:nuget purl.
	TypeNuget = "nuget"
	// TypeOCI is a pkg:oci purl.
	TypeOCI = "oci"
	// TypePub is a pkg:pub purl.
	TypePub = "pub"
	// TypePyPi is a pkg:pypi purl.
	TypePyPi = "pypi"
	// TypeLuaRocs is a pkg:luarocks purl.
	TypeLuaRocks = "luarocks"
	// TypeRPM is a pkg:rpm purl.
	TypeRPM = "rpm"
	// TypeSwift is pkg:swift purl.
	TypeSwift = "swift"
)

These are the known purl types as defined in the spec. Some of these require special treatment during parsing. https://github.com/package-url/purl-spec#known-purl-types

var (
	// QualifierKeyPattern describes a valid qualifier key:
	//
	// - The key must be composed only of ASCII letters and numbers, '.',
	//   '-' and '_' (period, dash and underscore).
	// - A key cannot start with a number.
	QualifierKeyPattern = regexp.MustCompile(`^[A-Za-z\.\-_][0-9A-Za-z\.\-_]*$`)
)

Types

type PackageURL

type PackageURL struct {
	Type       string
	Namespace  string
	Name       string
	Version    string
	Qualifiers Qualifiers
	Subpath    string
}

PackageURL is the struct representation of the parts that make a package url

func FromString

func FromString(purl string) (PackageURL, error)

FromString parses a valid package url string into a PackageURL structure

func NewPackageURL

func NewPackageURL(purlType, namespace, name, version string,
	qualifiers Qualifiers, subpath string) *PackageURL

NewPackageURL creates a new PackageURL struct instance based on input

func (PackageURL) String

func (p PackageURL) String() string

func (*PackageURL) ToString

func (p *PackageURL) ToString() string

ToString returns the human-readable instance of the PackageURL structure. This is the literal purl as defined by the spec.

type Qualifier

type Qualifier struct {
	Key   string
	Value string
}

Qualifier represents a single key=value qualifier in the package url

func (Qualifier) String

func (q Qualifier) String() string

type Qualifiers

type Qualifiers []Qualifier

Qualifiers is a slice of key=value pairs, with order preserved as it appears in the package URL.

func QualifiersFromMap

func QualifiersFromMap(mm map[string]string) Qualifiers

QualifiersFromMap constructs a Qualifiers slice from a string map. To get a deterministic qualifier order (despite maps not providing any iteration order guarantees) the returned Qualifiers are sorted in increasing order of key.

func (Qualifiers) Map

func (qq Qualifiers) Map() map[string]string

Map converts a Qualifiers struct to a string map.

func (Qualifiers) String

func (qq Qualifiers) String() string