Class: GemHadar::VersionSpec

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/gem_hadar/version_spec.rb

Overview

A class that represents a version specification for a gem.

This class provides functionality to parse and manipulate version strings, including handling of semantic versioning formats and optional ‘v’ prefixes. It supports creating version specifications from various input formats and provides methods to access the underlying version information and string representation.

Examples:

Creating a version specification

version = GemHadar::VersionSpec['1.2.3']

Checking if a version is a HEAD reference

version = GemHadar::VersionSpec['HEAD']
version.head? # => true

Getting the version tag with appropriate prefixing

version = GemHadar::VersionSpec['1.2.3']
version.tag # => 'v1.2.3'

Comparing versions

version1 = GemHadar::VersionSpec['1.2.3']
version2 = GemHadar::VersionSpec['1.2.4']
version1.version < version2.version # => true

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(string, version) ⇒ VersionSpec

Initializes a new VersionSpec instance.

Parameters:

  • string (String) —

    the original string representation of the version

  • version (Tins::StringVersion::Version, nil) —

    the parsed version object or nil if parsing failed



74
75
76
 
# File 'lib/gem_hadar/version_spec.rb', line 74

def initialize(string, version)
  @string, @version = string, version
end

Instance Attribute Details

#version ⇒ Tins::StringVersion::Version? (readonly)

Retrieves the parsed version object.

Returns:

  • (Tins::StringVersion::Version, nil) —

    the parsed version object or nil if parsing failed



81
82
83
 
# File 'lib/gem_hadar/version_spec.rb', line 81

def version
  @version
end

Class Method Details

.[](spec, with_prefix: nil, without_prefix: nil) ⇒ GemHadar::VersionSpec

The [] method creates a new VersionSpec instance from a specification.

This factory method attempts to extract version information from the provided specification, handling both gem specifications and version strings. It supports optional prefix handling for the resulting version string.

Parameters:

  • spec (Object) —

    the specification to parse, typically a String or Gem::Specification

  • with_prefix (Boolean) (defaults to: nil) —

    if true, ensures the version string has a ‘v’ prefix

  • without_prefix (Boolean) (defaults to: nil) —

    if true, ensures the version string does not have a ‘v’ prefix

Returns:

Raises:

  • (ArgumentError) —

    if both with_prefix and without_prefix are specified simultaneously



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/gem_hadar/version_spec.rb', line 42

def [](spec, with_prefix: nil, without_prefix: nil)
  !(with_prefix && without_prefix) or
    raise ArgumentError, 'with_prefix and without_prefix is invalid'
  spec.is_a?(self) and return spec
  obj, version = nil, (spec.version rescue nil)
  if version
    ;
  elsif /\Av?(\d+\.\d+\.\d+)\z/ =~ spec
    begin
      version = Tins::StringVersion::Version.new($1)
    rescue ArgumentError
    end
  end
  spec = spec.to_s
  if version
    if with_prefix
      spec = spec.sub(/\A(?!v)/, 'v')
    elsif without_prefix
      spec = spec.sub(/\Av?/, '')
    end
  end
  obj = new(spec, version)
  obj.freeze
end

Instance Method Details

#<=>(other) ⇒ Integer

The <=> method compares this version specification with another object.

This method implements the comparison operator for VersionSpec objects, allowing them to be sorted and compared using standard Ruby comparison operators.

Parameters:

  • other (Object) —

    the object to compare against

Returns:

  • (Integer) —

    -1 if this version is less than the other, 0 if they are equal, 1 if this version is greater than the other

Raises:

  • (TypeError) —

    if the other object is not a VersionSpec instance

  • (TypeError) —

    if the other object has no valid version to compare against



158
159
160
161
162
 
# File 'lib/gem_hadar/version_spec.rb', line 158

def <=>(other)
  other.is_a?(self.class) or raise TypeError, "other needs to be a #{self.class}"
  other.version or raise TypeError, "cannot compare to #{other.inspect}"
  version <=> other.version
end

#eql?(other) ⇒ TrueClass, FalseClass

The eql? method checks for equality between this version specification and another object.

This method determines if the current VersionSpec instance is equal to another object by first checking if the other object is of the same class. If so, it compares either both objects represent HEAD references or their underlying version objects for equality.

Parameters:

  • other (Object) —

    the object to compare against

Returns:

  • (TrueClass, FalseClass) —

    true if the objects are equal, false otherwise



176
177
178
 
# File 'lib/gem_hadar/version_spec.rb', line 176

def eql?(other)
  other.is_a?(self.class) && (head? && other.head? || version == other.version)
end

#hash ⇒ Integer

The hash method computes a hash value for the version specification.

This method returns a hash code that represents the version specification. If the version specification has a valid version object, it returns the hash of that version object. Otherwise, it returns the hash of the string representation of the version specification.

Returns:

  • (Integer) —

    the hash value of the version specification



188
189
190
191
192
193
194
 
# File 'lib/gem_hadar/version_spec.rb', line 188

def hash
  if version?
    version.hash
  else
    to_s.hash
  end
end

#head? ⇒ Boolean

The head? method checks if the version string represents a HEAD reference.

This method returns true if the internal string representation of the version spec is exactly ‘HEAD’, indicating that it refers to the latest commit rather than a specific tagged version.

Returns:

  • (Boolean) —

    true if the version string is ‘HEAD’, false otherwise



97
98
99
 
# File 'lib/gem_hadar/version_spec.rb', line 97

def head?
  @string == 'HEAD'
end

#tag ⇒ String

The tag method returns the version tag string with appropriate prefixing.

This method checks if the version represents a HEAD reference and returns the raw string representation if so. Otherwise, it returns the version string with a ‘v’ prefix added to it.

Returns:

  • (String) —

    the version tag string, either as-is for HEAD or with ‘v’ prefix added



108
109
110
 
# File 'lib/gem_hadar/version_spec.rb', line 108

def tag
  head? ? to_s : with_prefix
end

#to_s ⇒ String

Returns the original string representation.

Returns:

  • (String) —

    the original version string



127
128
129
 
# File 'lib/gem_hadar/version_spec.rb', line 127

def to_s
  @string.to_s
end

#untag ⇒ String

The untag method returns the version string without a ‘v’ prefix.

This method checks if the version represents a HEAD reference and returns the raw string representation if so. Otherwise, it returns the version string with the ‘v’ prefix removed.

Returns:

  • (String) —

    the version string without ‘v’ prefix or the raw string if it represents a HEAD reference



120
121
122
 
# File 'lib/gem_hadar/version_spec.rb', line 120

def untag
  head? ? to_s : without_prefix
end

#version? ⇒ Boolean

Checks if a version object was successfully parsed.

Returns:

  • (Boolean) —

    true if version was parsed successfully, false otherwise



86
87
88
 
# File 'lib/gem_hadar/version_spec.rb', line 86

def version?
  !!@version
end

#with_prefix ⇒ String

Adds a ‘v’ prefix to the version string if not already present.

Returns:

  • (String) —

    the version string with ‘v’ prefix



141
142
143
 
# File 'lib/gem_hadar/version_spec.rb', line 141

def with_prefix
  to_s.sub(/\A(?!v)/, 'v')
end

#without_prefix ⇒ String

Removes the ‘v’ prefix from the version string if present.

Returns:

  • (String) —

    the version string without ‘v’ prefix



134
135
136
 
# File 'lib/gem_hadar/version_spec.rb', line 134

def without_prefix
  to_s.sub(/\Av/, '')
end