Class: Gem::Requirement

Inherits:
Object
  • Object
show all
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 Gem::Version for a description on how versions and requirements work together in RubyGems.

Defined Under Namespace

Classes: BadRequirementError

Constant Summary collapse

OPS =

:nodoc:

{ #: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
SOURCE_SET_REQUIREMENT =

:nodoc:

Struct.new(:for_lockfile).new "!"
PATTERN_RAW =

:nodoc:

"\\s*(#{quoted})?\\s*(#{Gem::Version::VERSION_PATTERN})\\s*".freeze
PATTERN =

A regular expression that matches a requirement

/\A#{PATTERN_RAW}\z/.freeze
DefaultRequirement =

The default requirement matches any version

[">=", Gem::Version.new(0)].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*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".



127
128
129
130
131
132
133
134
135
136
137
138
 
# 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

Instance Attribute Details

#requirements ⇒ Object (readonly)

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



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

def requirements
  @requirements
end

Class Method Details

.create(*inputs) ⇒ Object

Factory method to create a Gem::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.



54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# 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 ⇒ Object

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



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

def self.default
  new '>= 0'
end

.parse(obj) ⇒ Object

Parse obj, returning an [op, version] pair. obj can be a String or a Gem::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")]



101
102
103
104
105
106
107
108
109
110
111
112
113
 
# 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 ⇒ Object

A source set requirement, used for Gemfiles and lockfiles



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

def self.source_set # :nodoc:
  SOURCE_SET_REQUIREMENT
end

Instance Method Details

#==(other) ⇒ Object

:nodoc:



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

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

#as_list ⇒ Object

:nodoc:



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

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

#concat(new) ⇒ Object

Concatenates the new requirements onto this requirement.



143
144
145
146
147
148
149
150
151
 
# 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) ⇒ Object

:nodoc:



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

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

#exact? ⇒ Boolean

true if the requirement is for only an exact version

Returns:

  • (Boolean) 


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

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

#for_lockfile ⇒ Object

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



156
157
158
159
160
161
162
163
164
165
166
 
# 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 ⇒ Object

:nodoc:



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

def hash # :nodoc:
  requirements.hash
end

#init_with(coder) ⇒ Object

:nodoc:



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

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

#marshal_dump ⇒ Object

:nodoc:



195
196
197
198
199
 
# File 'lib/rubygems/requirement.rb', line 195

def marshal_dump # :nodoc:
  fix_syck_default_key_in_requirements

  [@requirements]
end

#marshal_load(array) ⇒ Object

:nodoc:



201
202
203
204
205
 
# File 'lib/rubygems/requirement.rb', line 201

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

  fix_syck_default_key_in_requirements
end

#none? ⇒ Boolean

true if this gem has no requirements.

Returns:

  • (Boolean) 


171
172
173
174
175
176
177
 
# File 'lib/rubygems/requirement.rb', line 171

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

#prerelease? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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

#pretty_print(q) ⇒ Object

:nodoc:



236
237
238
239
240
 
# 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.

Returns:

  • (Boolean)

Raises:

  • (ArgumentError) 


245
246
247
248
249
250
 
# 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

#specific? ⇒ Boolean

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

Returns:

  • (Boolean) 


258
259
260
261
262
 
# 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

#to_s ⇒ Object

:nodoc:



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

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

#to_yaml_properties ⇒ Object

:nodoc:



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

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

#yaml_initialize(tag, vals) ⇒ Object

:nodoc:



207
208
209
210
211
212
213
214
 
# 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