Class: Gem::Requirement

Relationships & Source Files
Namespace Children
Exceptions: `BadRequirementError`
Inherits:	Object
Defined in:	lib/rubygems/requirement.rb

Overview

A Requirement is a set of one or more version restrictions. It supports a few (=, !=, >, <, >=, <=, ~>) different restriction operators.

See Version for a description on how versions and requirements work together in RubyGems.

Constant Summary

DefaultRequirement =

The default requirement matches any version

# File 'lib/rubygems/requirement.rb', line 40
```
[">=", Gem::Version.new(0)].freeze
```

OPS = Internal use only
# File 'lib/rubygems/requirement.rb', line 17

{ #:nodoc:
  "="  =>  lambda { |v, r| v == r },
  "!=" =>  lambda { |v, r| v != r },
  ">"  =>  lambda { |v, r| v >  r },
  "<"  =>  lambda { |v, r| v <  r },
  ">=" =>  lambda { |v, r| v >= r },
  "<=" =>  lambda { |v, r| v <= r },
  "~>" =>  lambda { |v, r| v >= r && v.release < r.bump }
}.freeze

PATTERN =

A regular expression that matches a requirement

# File 'lib/rubygems/requirement.rb', line 35
```
/\A#{PATTERN_RAW}\z/.freeze
```
PATTERN_RAW = Internal use only
# File 'lib/rubygems/requirement.rb', line 30
```
"\\s*(#{quoted})?\\s*(#{Gem::Version::VERSION_PATTERN})\\s*".freeze
```
SOURCE_SET_REQUIREMENT = Internal use only
# File 'lib/rubygems/requirement.rb', line 27
```
Struct.new(:for_lockfile).new "!"
```

Class Method Summary

.create(*inputs)

Factory method to create a Requirement object.
.default

A default “version requirement” can surely only be ‘>= 0’.
.new(*requirements) ⇒ Requirement constructor

Constructs a requirement from #requirements.
.parse(obj)

Parse obj, returning an [op, version] pair.
.source_set Internal use only

A source set requirement, used for Gemfiles and lockfiles.

Instance Attribute Summary

#exact? ⇒ Boolean readonly

true if the requirement is for only an exact version.
#none? ⇒ Boolean readonly

true if this gem has no requirements.
#prerelease? ⇒ Boolean readonly

A requirement is a prerelease if any of the versions inside of it are prereleases.
#specific? ⇒ Boolean readonly

True if the requirement will not always match the latest version.
#requirements readonly Internal use only

An array of requirement pairs.

Instance Method Summary

#===(version)

Alias for #satisfied_by?.
#=~(version)

Alias for #satisfied_by?.
#concat(new)

Concatenates the .new requirements onto this requirement.
#satisfied_by?(version) ⇒ Boolean (also: #===, #=~)

True if version satisfies this Requirement.
#_tilde_requirements protected
#==(other) Internal use only
#as_list Internal use only
#encode_with(coder) Internal use only
#for_lockfile Internal use only

Formats this requirement for use in a RequestSet::Lockfile.
#hash Internal use only
#init_with(coder) Internal use only
#marshal_dump Internal use only
#marshal_load(array) Internal use only
#pretty_print(q) Internal use only
#to_s Internal use only
#to_yaml_properties Internal use only
#yaml_initialize(tag, vals) Internal use only
#fix_syck_default_key_in_requirements private Internal use only
#sort_requirements! private Internal use only

Constructor Details

.new(*requirements) ⇒ `Requirement`

Constructs a requirement from #requirements. Requirements can be Strings, Gem::Versions, or Arrays of those. nil and duplicate requirements are ignored. An empty set of #requirements is the same as ">= 0".

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 127


def initialize(*requirements)
  requirements = requirements.flatten
  requirements.compact!
  requirements.uniq!

  if requirements.empty?
    @requirements = [DefaultRequirement]
  else
    @requirements = requirements.map! { |r| self.class.parse r }
    sort_requirements!
  end
end

Class Method Details

.create(*inputs)

Factory method to create a Requirement object. Input may be a Version, a String, or nil. Intended to simplify client code.

If the input is “weird”, the default version requirement is returned.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 54


def self.create(*inputs)
  return new inputs if inputs.length > 1

  input = inputs.shift

  case input
  when Gem::Requirement then
    input
  when Gem::Version, Array then
    new input
  when '!' then
    source_set
  else
    if input.respond_to? :to_str
      new [input.to_str]
    else
      default
    end
  end
end

.default

A default “version requirement” can surely only be ‘>= 0’.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 78


def self.default
  new '>= 0'
end

.parse(obj)

Parse obj, returning an [op, version] pair. obj can be a String or a Version.

If obj is a String, it can be either a full requirement specification, like ">= 1.2", or a simple version number, like "1.2".

parse("> 1.0")                 # => [">", Gem::Version.new("1.0")]
parse("1.0")                   # => ["=", Gem::Version.new("1.0")]
parse(Gem::Version.new("1.0")) # => ["=,  Gem::Version.new("1.0")]

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 101


def self.parse(obj)
  return ["=", obj] if Gem::Version === obj

  unless PATTERN =~ obj.to_s
    raise BadRequirementError, "Illformed requirement [#{obj.inspect}]"
  end

  if $1 == ">=" && $2 == "0"
    DefaultRequirement
  else
    [$1 || "=", Gem::Version.new($2)]
  end
end

.source_set

This method is for internal use only.

A source set requirement, used for Gemfiles and lockfiles

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 85


def self.source_set # :nodoc:
  SOURCE_SET_REQUIREMENT
end

Instance Attribute Details

#exact? ⇒ `Boolean` (readonly)

true if the requirement is for only an exact version

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 182


def exact?
  return false unless @requirements.size == 1
  @requirements[0][0] == "="
end

#none? ⇒ `Boolean` (readonly)

true if this gem has no requirements.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 171


def none?
  if @requirements.size == 1
    @requirements[0] == DefaultRequirement
  else
    false
  end
end

#prerelease? ⇒ `Boolean` (readonly)

A requirement is a prerelease if any of the versions inside of it are prereleases

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 232


def prerelease?
  requirements.any? { |r| r.last.prerelease? }
end

#requirements (readonly)

This method is for internal use only.

An array of requirement pairs. The first element of the pair is the op, and the second is the Version.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 119


attr_reader :requirements #:nodoc:

#specific? ⇒ `Boolean` (readonly)

True if the requirement will not always match the latest version.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 258


def specific?
  return true if @requirements.length > 1 # GIGO, > 1, > 2 is silly

  not %w[> >=].include? @requirements.first.first # grab the operator
end

Instance Method Details

#==(other)

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 268


def ==(other) # :nodoc:
  return unless Gem::Requirement === other

  # An == check is always necessary
  return false unless requirements == other.requirements

  # An == check is sufficient unless any requirements use ~>
  return true unless _tilde_requirements.any?

  # If any requirements use ~> we use the stricter `#eql?` that also checks
  # that version precision is the same
  _tilde_requirements.eql?(other._tilde_requirements)
end

#===(version)

Alias for #satisfied_by?.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 252


alias :=== :satisfied_by?

#=~(version)

Alias for #satisfied_by?.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 253


alias :=~ :satisfied_by?

#_tilde_requirements (protected)

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 284


def _tilde_requirements
  requirements.select { |r| r.first == "~>" }
end

#as_list

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 187


def as_list # :nodoc:
  requirements.map { |op, version| "#{op} #{version}" }
end

#concat(new)

Concatenates the .new requirements onto this requirement.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 143


def concat(new)
  new = new.flatten
  new.compact!
  new.uniq!
  new = new.map { |r| self.class.parse r }

  @requirements.concat new
  sort_requirements!
end

#encode_with(coder)

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 224


def encode_with(coder) # :nodoc:
  coder.add 'requirements', @requirements
end

#fix_syck_default_key_in_requirements (private)

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 290


def fix_syck_default_key_in_requirements # :nodoc:
  Gem.load_yaml

  # Fixup the Syck DefaultKey bug
  @requirements.each do |r|
    if r[0].kind_of? Gem::SyckDefaultKey
      r[0] = "="
    end
  end
end

#for_lockfile

This method is for internal use only.

Formats this requirement for use in a RequestSet::Lockfile.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 156


def for_lockfile # :nodoc:
  return if [DefaultRequirement] == @requirements

  list = requirements.sort_by { |_, version|
    version
  }.map { |op, version|
    "#{op} #{version}"
  }.uniq

  " (#{list.join ', '})"
end

#hash

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 191


def hash # :nodoc:
  requirements.hash
end

#init_with(coder)

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 216


def init_with(coder) # :nodoc:
  yaml_initialize coder.tag, coder.map
end

#marshal_dump

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 195


def marshal_dump # :nodoc:
  fix_syck_default_key_in_requirements

  [@requirements]
end

#marshal_load(array)

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 201


def marshal_load(array) # :nodoc:
  @requirements = array[0]

  fix_syck_default_key_in_requirements
end

#pretty_print(q)

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 236


def pretty_print(q) # :nodoc:
  q.group 1, 'Gem::Requirement.new(', ')' do
    q.pp as_list
  end
end

#satisfied_by?(version) ⇒ `Boolean` Also known as: #===, #=~

True if version satisfies this Requirement.

Raises:

(ArgumentError)

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 245


def satisfied_by?(version)
  raise ArgumentError, "Need a Gem::Version: #{version.inspect}" unless
    Gem::Version === version
  # #28965: syck has a bug with unquoted '=' YAML.loading as YAML::DefaultKey
  requirements.all? { |op, rv| (OPS[op] || OPS["="]).call version, rv }
end

#sort_requirements! (private)

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 301


def sort_requirements! # :nodoc:
  @requirements.sort! do |l, r|
    comp = l.last <=> r.last # first, sort by the requirement's version
    next comp unless comp == 0
    l.first <=> r.first # then, sort by the operator (for stability)
  end
end

#to_s

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 264


def to_s # :nodoc:
  as_list.join ", "
end

#to_yaml_properties

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 220


def to_yaml_properties # :nodoc:
  ["@requirements"]
end

#yaml_initialize(tag, vals)

This method is for internal use only.

[ GitHub ]

# File 'lib/rubygems/requirement.rb', line 207


def yaml_initialize(tag, vals) # :nodoc:
  vals.each do |ivar, val|
    instance_variable_set "@#{ivar}", val
  end

  Gem.load_yaml
  fix_syck_default_key_in_requirements
end

Class: Gem::Requirement

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(*requirements) ⇒ Requirement

Class Method Details

.create(*inputs)

.default

.parse(obj)

.source_set

Instance Attribute Details

#exact? ⇒ Boolean (readonly)

#none? ⇒ Boolean (readonly)

#prerelease? ⇒ Boolean (readonly)

#requirements (readonly)

#specific? ⇒ Boolean (readonly)

Instance Method Details

#==(other)

#===(version)

#=~(version)

#_tilde_requirements (protected)

#as_list

#concat(new)

#encode_with(coder)

#fix_syck_default_key_in_requirements (private)

#for_lockfile

#hash

#init_with(coder)

#marshal_dump

#marshal_load(array)

#pretty_print(q)

#satisfied_by?(version) ⇒ Boolean Also known as: #===, #=~

#sort_requirements! (private)

#to_s

#to_yaml_properties

#yaml_initialize(tag, vals)

.new(*requirements) ⇒ `Requirement`

#exact? ⇒ `Boolean` (readonly)

#none? ⇒ `Boolean` (readonly)

#prerelease? ⇒ `Boolean` (readonly)

#specific? ⇒ `Boolean` (readonly)

#satisfied_by?(version) ⇒ `Boolean` Also known as: #===, #=~