Class: Sbom::PackageUrl

Inherits:
Object
  • Object
show all
Defined in:
lib/sbom/package_url.rb,
lib/sbom/package_url/decoder.rb,
lib/sbom/package_url/encoder.rb,
lib/sbom/package_url/normalizer.rb,
lib/sbom/package_url/string_utils.rb,
lib/sbom/package_url/argument_validator.rb

Overview

A package URL, or 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.

A purl is a URL composed of seven components:

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

For example, the package URL for this Ruby package at version 0.1.0 is ‘pkg:ruby/mattt/[email protected]`.

More details on the package URL format can be found in the purl specification: github.com/package-url/purl-spec/blob/0b1559f76b79829e789c4f20e6d832c7314762c5/PURL-SPECIFICATION.rst

Defined Under Namespace

Modules: StringUtils Classes: ArgumentValidator, Decoder, Encoder, Normalizer

Constant Summary collapse

InvalidPackageUrl =

Raised when attempting to parse an invalid package URL string.

See Also:

  • #parse
Class.new(ArgumentError)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(type:, name:, namespace: nil, version: nil, qualifiers: nil, subpath: nil) ⇒ PackageUrl

Constructs a package URL from its components

Parameters:

  • type (String) —

    The package type or protocol.

  • namespace (String) (defaults to: nil) —

    A name prefix, specific to the type of package.

  • name (String) —

    The name of the package.

  • version (String) (defaults to: nil) —

    The version of the package.

  • qualifiers (Hash) (defaults to: nil) —

    Extra qualifying data for a package, specific to the type of package.

  • subpath (String) (defaults to: nil) —

    An extra subpath within a package, relative to the package root.



81
82
83
84
85
86
87
88
89
90
 
# File 'lib/sbom/package_url.rb', line 81

def initialize(type:, name:, namespace: nil, version: nil, qualifiers: nil, subpath: nil)
  @type = type&.downcase
  @namespace = namespace
  @name = name
  @version = version
  @qualifiers = qualifiers
  @subpath = subpath

  ArgumentValidator.new(self).validate!
end

Instance Attribute Details

#name ⇒ Object (readonly)

The name of the package.



62
63
64
 
# File 'lib/sbom/package_url.rb', line 62

def name
  @name
end

#namespace ⇒ Object (readonly)

A name prefix, specific to the type of package. For example, an npm scope, a Docker image owner, or a GitHub user.



59
60
61
 
# File 'lib/sbom/package_url.rb', line 59

def namespace
  @namespace
end

#qualifiers ⇒ Object (readonly)

Extra qualifying data for a package, specific to the type of package. For example, the operating system or architecture.



69
70
71
 
# File 'lib/sbom/package_url.rb', line 69

def qualifiers
  @qualifiers
end

#subpath ⇒ Object (readonly)

An extra subpath within a package, relative to the package root.



72
73
74
 
# File 'lib/sbom/package_url.rb', line 72

def subpath
  @subpath
end

#type ⇒ Object (readonly)

The package type or protocol, such as ‘“gem”`, `“npm”`, and `“github”`.



55
56
57
 
# File 'lib/sbom/package_url.rb', line 55

def type
  @type
end

#version ⇒ Object (readonly)

The version of the package.



65
66
67
 
# File 'lib/sbom/package_url.rb', line 65

def version
  @version
end

Class Method Details

.parse(string) ⇒ PackageUrl

Creates a new PackageUrl from a string.

Parameters:

  • string (String) —

    The package URL string.

Returns:

Raises:



96
97
98
 
# File 'lib/sbom/package_url.rb', line 96

def self.parse(string)
  Decoder.new(string).decode!
end

Instance Method Details

#scheme ⇒ Object

The URL scheme, which has a constant value of ‘“pkg”`.



50
51
52
 
# File 'lib/sbom/package_url.rb', line 50

def scheme
  'pkg'
end

#to_h ⇒ Object

Returns a hash containing the scheme, type, namespace, name, version, qualifiers, and subpath components of the package URL.



103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/sbom/package_url.rb', line 103

def to_h
  {
    scheme: scheme,
    type: @type,
    namespace: @namespace,
    name: @name,
    version: @version,
    qualifiers: @qualifiers,
    subpath: @subpath
  }
end

#to_s ⇒ Object

Returns a string representation of the package URL. Package URL representations are created according to the instructions from github.com/package-url/purl-spec/blob/0b1559f76b79829e789c4f20e6d832c7314762c5/PURL-SPECIFICATION.rst#how-to-build-purl-string-from-its-components.



118
119
120
 
# File 'lib/sbom/package_url.rb', line 118

def to_s
  Encoder.new(self).encode
end