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 }
}
PATTERN_RAW =

:nodoc:

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

A regular expression that matches a requirement

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

The default requirement matches any version

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

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".



111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/rubygems/requirement.rb', line 111

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

  if requirements.empty?
    @requirements = [DefaultRequirement]
  else
    @requirements = requirements.map! { |r| self.class.parse r }
  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.



103
104
105
 
# File 'lib/rubygems/requirement.rb', line 103

def requirements
  @requirements
end

Class Method Details

.create(input) ⇒ 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.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/rubygems/requirement.rb', line 51

def self.create input
  case input
  when Gem::Requirement then
    input
  when Gem::Version, Array then
    new input
  else
    if input.respond_to? :to_str then
      new [input.to_str]
    else
      default
    end
  end
end

.default ⇒ Object

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



69
70
71
 
# File 'lib/rubygems/requirement.rb', line 69

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")                 # => [">", "1.0"]
parse("1.0")                   # => ["=", "1.0"]
parse(Gem::Version.new("1.0")) # => ["=,  "1.0"]



85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/rubygems/requirement.rb', line 85

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

Instance Method Details

#==(other) ⇒ Object

:nodoc:



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

def == other # :nodoc:
  Gem::Requirement === other and to_s == other.to_s
end

#as_list ⇒ Object

:nodoc:



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

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

#concat(new) ⇒ Object

Concatenates the new requirements onto this requirement.



126
127
128
129
130
131
132
133
 
# File 'lib/rubygems/requirement.rb', line 126

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

  @requirements.concat new
end

#encode_with(coder) ⇒ Object

:nodoc:



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

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

#exact? ⇒ Boolean

true if the requirement is for only an exact version

Returns:

  • (Boolean) 


164
165
166
167
 
# File 'lib/rubygems/requirement.rb', line 164

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.



138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/rubygems/requirement.rb', line 138

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:



173
174
175
 
# File 'lib/rubygems/requirement.rb', line 173

def hash # :nodoc:
  requirements.hash
end

#init_with(coder) ⇒ Object

:nodoc:



198
199
200
 
# File 'lib/rubygems/requirement.rb', line 198

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

#marshal_dump ⇒ Object

:nodoc:



177
178
179
180
181
 
# File 'lib/rubygems/requirement.rb', line 177

def marshal_dump # :nodoc:
  fix_syck_default_key_in_requirements

  [@requirements]
end

#marshal_load(array) ⇒ Object

:nodoc:



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

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) 


153
154
155
156
157
158
159
 
# File 'lib/rubygems/requirement.rb', line 153

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) 


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

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

#pretty_print(q) ⇒ Object

:nodoc:



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

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) 


227
228
229
230
231
232
 
# File 'lib/rubygems/requirement.rb', line 227

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) 


240
241
242
243
244
 
# File 'lib/rubygems/requirement.rb', line 240

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:



246
247
248
 
# File 'lib/rubygems/requirement.rb', line 246

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

#to_yaml_properties ⇒ Object

:nodoc:



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

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

#yaml_initialize(tag, vals) ⇒ Object

:nodoc:



189
190
191
192
193
194
195
196
 
# File 'lib/rubygems/requirement.rb', line 189

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