Module: Vers

Defined in:
lib/vers.rb,
lib/vers/parser.rb,
lib/vers/version.rb,
lib/vers/interval.rb,
lib/vers/constraint.rb,
lib/vers/maven_version.rb,
lib/vers/nuget_version.rb,
lib/vers/version_range.rb,
sig/vers.rbs

Overview

Vers - A Ruby gem for parsing, comparing and sorting versions according to the VERS spec

This gem provides tools for working with version ranges across different package managers, using a mathematical interval model internally and supporting the vers specification from the Package URL (PURL) project.

Features

  • Parse version ranges from multiple package ecosystems (npm, gem, pypi, maven, etc.)
  • Convert between native version range syntax and universal vers URI format
  • Mathematical interval-based operations (union, intersection, complement)
  • Version comparison and containment checking
  • Extensible architecture for adding new package manager support

Quick Start

require 'vers'

# Parse a vers URI
range = Vers.parse("vers:npm/>=1.2.3|<2.0.0")
range.contains?("1.5.0")  # => true
range.contains?("2.1.0")  # => false

# Parse native package manager syntax
npm_range = Vers.parse_native("^1.2.3", "npm")
gem_range = Vers.parse_native("~> 1.0", "gem")

# Check version containment
Vers.satisfies?("1.5.0", ">=1.0.0,<2.0.0")  # => true

# Compare versions
Vers.compare("1.2.3", "1.2.4")  # => -1

Mathematical Model

Internally, all version ranges are represented as mathematical intervals, similar to those used in mathematics (e.g., [1.0.0, 2.0.0) represents versions from 1.0.0 inclusive to 2.0.0 exclusive).

This allows for precise set operations like union, intersection, and complement, regardless of the original package manager syntax.

See Also:

Author:

  • Andrew Nesbitt

Defined Under Namespace

Modules: MavenVersion, NuGetVersion Classes: Constraint, Error, Interval, Parser, Version, VersionRange

Constant Summary collapse

VERSION =

Returns:

  • (String) 
"1.3.1"
@@parser =

Default parser instance for convenience methods

Parser.new

Class Method Summary collapse

Class Method Details

.clean(version_string) ⇒ Object 



182
183
184
 
# File 'lib/vers.rb', line 182

def self.clean(version_string)
  Version.clean(version_string)
end

.compare(a, b) ⇒ Integer

Compares two version strings

Examples

Vers.compare("1.2.3", "1.2.4")  # => -1
Vers.compare("2.0.0", "1.9.9")  # => 1
Vers.compare("1.0.0", "1.0.0")  # => 0

Parameters:

  • a (String) —

    First version string

  • b (String) —

    Second version string

Returns:

  • (Integer) —

    -1 if a < b, 0 if a == b, 1 if a > b



146
147
148
 
# File 'lib/vers.rb', line 146

def self.compare(a, b)
  Version.compare(a, b)
end

.compare_with_scheme(a, b, scheme) ⇒ Integer

Compares two version strings using scheme-specific rules

Parameters:

  • a (String) —

    First version string

  • b (String) —

    Second version string

  • scheme (String, nil) —

    Package manager scheme (maven, nuget, or nil for generic)

Returns:

  • (Integer) —

    -1 if a < b, 0 if a == b, 1 if a > b



158
159
160
 
# File 'lib/vers.rb', line 158

def self.compare_with_scheme(a, b, scheme)
  Version.compare_with_scheme(a, b, scheme)
end

.empty ⇒ VersionRange

Creates an empty version range (matches no versions)

Returns:



232
233
234
 
# File 'lib/vers.rb', line 232

def self.empty
  VersionRange.empty
end

.exact(version) ⇒ VersionRange

Creates an exact version range

Parameters:

  • version (String) —

    The exact version

Returns:

  • (VersionRange) —

    A range containing only the specified version



192
193
194
 
# File 'lib/vers.rb', line 192

def self.exact(version)
  VersionRange.exact(version)
end

.greater_than(version, inclusive: false) ⇒ VersionRange

Creates a greater-than version range

Parameters:

  • version (String) —

    The minimum version

  • inclusive (Boolean) (defaults to: false) —

    Whether to include the minimum version

Returns:

  • (VersionRange) —

    A range for versions greater than (or equal to) the specified version



203
204
205
 
# File 'lib/vers.rb', line 203

def self.greater_than(version, inclusive: false)
  VersionRange.greater_than(version, inclusive: inclusive)
end

.less_than(version, inclusive: false) ⇒ VersionRange

Creates a less-than version range

Parameters:

  • version (String) —

    The maximum version

  • inclusive (Boolean) (defaults to: false) —

    Whether to include the maximum version

Returns:

  • (VersionRange) —

    A range for versions less than (or equal to) the specified version



214
215
216
 
# File 'lib/vers.rb', line 214

def self.less_than(version, inclusive: false)
  VersionRange.less_than(version, inclusive: inclusive)
end

.normalize(version_string) ⇒ String

Normalizes a version string to a consistent format

Parameters:

  • version_string (String) —

    The version string to normalize

Returns:

  • (String) —

    The normalized version string



168
169
170
 
# File 'lib/vers.rb', line 168

def self.normalize(version_string)
  Version.normalize(version_string)
end

.parse(vers_string) ⇒ VersionRange

Parses a vers URI string into a VersionRange

Examples

Vers.parse("vers:npm/>=1.2.3|<2.0.0")
Vers.parse("vers:gem/~>1.0")
Vers.parse("*")  # unbounded range

Parameters:

  • vers_string (String) —

    The vers URI string (e.g., "vers:npm/>=1.2.3|<2.0.0")

Returns:

Raises:

  • (ArgumentError) —

    if the vers string is invalid



76
77
78
 
# File 'lib/vers.rb', line 76

def self.parse(vers_string)
  @@parser.parse(vers_string)
end

.parse_native(range_string, scheme) ⇒ VersionRange

Parses a native package manager version range into a VersionRange

Examples

Vers.parse_native("^1.2.3", "npm")      # npm caret range
Vers.parse_native("~> 1.0", "gem")      # gem pessimistic operator
Vers.parse_native(">=1.0,<2.0", "pypi") # python constraints

Parameters:

  • range_string (String) —

    The native version range string

  • scheme (String) —

    The package manager scheme (npm, gem, pypi, etc.)

Returns:



93
94
95
 
# File 'lib/vers.rb', line 93

def self.parse_native(range_string, scheme)
  @@parser.parse_native(range_string, scheme)
end

.satisfies?(version, constraint, scheme = nil) ⇒ Boolean

Checks if a version satisfies a version range constraint

Examples

Vers.satisfies?("1.5.0", "vers:npm/>=1.0.0|<2.0.0")  # => true
Vers.satisfies?("1.5.0", "^1.2.3", "npm")            # => true

Parameters:

  • version (String) —

    The version to check

  • constraint (String) —

    The version constraint (vers URI or native format)

  • scheme (String, nil) (defaults to: nil) —

    The package manager scheme (if not using vers URI)

Returns:

  • (Boolean) —

    true if the version satisfies the constraint



121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/vers.rb', line 121

def self.satisfies?(version, constraint, scheme = nil)
  sub_ranges = constraint.split('||').map(&:strip).reject(&:empty?)
  sub_ranges.any? do |sub_range|
    range = if scheme
              parse_native(sub_range, scheme)
            else
              parse(sub_range)
            end
    range&.contains?(version) || false
  end
end

.to_vers_string(version_range, scheme) ⇒ String

Converts a VersionRange to a vers URI string

Parameters:

  • version_range (VersionRange) —

    The version range to convert

  • scheme (String) —

    The package manager scheme

Returns:

  • (String) —

    The vers URI string



104
105
106
 
# File 'lib/vers.rb', line 104

def self.to_vers_string(version_range, scheme)
  @@parser.to_vers_string(version_range, scheme)
end

.unbounded ⇒ VersionRange

Creates an unbounded version range (matches all versions)

Returns:



223
224
225
 
# File 'lib/vers.rb', line 223

def self.unbounded
  VersionRange.unbounded
end

.valid?(version_string) ⇒ Boolean

Checks if a version string is valid

Parameters:

  • version_string (String) —

    The version string to validate

Returns:

  • (Boolean) —

    true if the version is valid



178
179
180
 
# File 'lib/vers.rb', line 178

def self.valid?(version_string)
  Version.valid?(version_string)
end