summaryrefslogtreecommitdiff
path: root/jni/ruby/lib/rubygems/version.rb
diff options
context:
space:
mode:
authorJari Vetoniemi <jari.vetoniemi@indooratlas.com>2020-03-16 18:49:26 +0900
committerJari Vetoniemi <jari.vetoniemi@indooratlas.com>2020-03-30 00:39:06 +0900
commitfcbf63e62c627deae76c1b8cb8c0876c536ed811 (patch)
tree64cb17de3f41a2b6fef2368028fbd00349946994 /jni/ruby/lib/rubygems/version.rb
Fresh start
Diffstat (limited to 'jni/ruby/lib/rubygems/version.rb')
-rw-r--r--jni/ruby/lib/rubygems/version.rb356
1 files changed, 356 insertions, 0 deletions
diff --git a/jni/ruby/lib/rubygems/version.rb b/jni/ruby/lib/rubygems/version.rb
new file mode 100644
index 0000000..8335ebe
--- /dev/null
+++ b/jni/ruby/lib/rubygems/version.rb
@@ -0,0 +1,356 @@
+##
+# The Version class processes string versions into comparable
+# values. A version string should normally be a series of numbers
+# separated by periods. Each part (digits separated by periods) is
+# considered its own number, and these are used for sorting. So for
+# instance, 3.10 sorts higher than 3.2 because ten is greater than
+# two.
+#
+# If any part contains letters (currently only a-z are supported) then
+# that version is considered prerelease. Versions with a prerelease
+# part in the Nth part sort less than versions with N-1
+# parts. Prerelease parts are sorted alphabetically using the normal
+# Ruby string sorting rules. If a prerelease part contains both
+# letters and numbers, it will be broken into multiple parts to
+# provide expected sort behavior (1.0.a10 becomes 1.0.a.10, and is
+# greater than 1.0.a9).
+#
+# Prereleases sort between real releases (newest to oldest):
+#
+# 1. 1.0
+# 2. 1.0.b1
+# 3. 1.0.a.2
+# 4. 0.9
+#
+# If you want to specify a version restriction that includes both prereleases
+# and regular releases of the 1.x series this is the best way:
+#
+# s.add_dependency 'example', '>= 1.0.0.a', '< 2.0.0'
+#
+# == How Software Changes
+#
+# Users expect to be able to specify a version constraint that gives them
+# some reasonable expectation that new versions of a library will work with
+# their software if the version constraint is true, and not work with their
+# software if the version constraint is false. In other words, the perfect
+# system will accept all compatible versions of the library and reject all
+# incompatible versions.
+#
+# Libraries change in 3 ways (well, more than 3, but stay focused here!).
+#
+# 1. The change may be an implementation detail only and have no effect on
+# the client software.
+# 2. The change may add new features, but do so in a way that client software
+# written to an earlier version is still compatible.
+# 3. The change may change the public interface of the library in such a way
+# that old software is no longer compatible.
+#
+# Some examples are appropriate at this point. Suppose I have a Stack class
+# that supports a <tt>push</tt> and a <tt>pop</tt> method.
+#
+# === Examples of Category 1 changes:
+#
+# * Switch from an array based implementation to a linked-list based
+# implementation.
+# * Provide an automatic (and transparent) backing store for large stacks.
+#
+# === Examples of Category 2 changes might be:
+#
+# * Add a <tt>depth</tt> method to return the current depth of the stack.
+# * Add a <tt>top</tt> method that returns the current top of stack (without
+# changing the stack).
+# * Change <tt>push</tt> so that it returns the item pushed (previously it
+# had no usable return value).
+#
+# === Examples of Category 3 changes might be:
+#
+# * Changes <tt>pop</tt> so that it no longer returns a value (you must use
+# <tt>top</tt> to get the top of the stack).
+# * Rename the methods to <tt>push_item</tt> and <tt>pop_item</tt>.
+#
+# == RubyGems Rational Versioning
+#
+# * Versions shall be represented by three non-negative integers, separated
+# by periods (e.g. 3.1.4). The first integers is the "major" version
+# number, the second integer is the "minor" version number, and the third
+# integer is the "build" number.
+#
+# * A category 1 change (implementation detail) will increment the build
+# number.
+#
+# * A category 2 change (backwards compatible) will increment the minor
+# version number and reset the build number.
+#
+# * A category 3 change (incompatible) will increment the major build number
+# and reset the minor and build numbers.
+#
+# * Any "public" release of a gem should have a different version. Normally
+# that means incrementing the build number. This means a developer can
+# generate builds all day long, but as soon as they make a public release,
+# the version must be updated.
+#
+# === Examples
+#
+# Let's work through a project lifecycle using our Stack example from above.
+#
+# Version 0.0.1:: The initial Stack class is release.
+# Version 0.0.2:: Switched to a linked=list implementation because it is
+# cooler.
+# Version 0.1.0:: Added a <tt>depth</tt> method.
+# Version 1.0.0:: Added <tt>top</tt> and made <tt>pop</tt> return nil
+# (<tt>pop</tt> used to return the old top item).
+# Version 1.1.0:: <tt>push</tt> now returns the value pushed (it used it
+# return nil).
+# Version 1.1.1:: Fixed a bug in the linked list implementation.
+# Version 1.1.2:: Fixed a bug introduced in the last fix.
+#
+# Client A needs a stack with basic push/pop capability. They write to the
+# original interface (no <tt>top</tt>), so their version constraint looks like:
+#
+# gem 'stack', '~> 0.0'
+#
+# Essentially, any version is OK with Client A. An incompatible change to
+# the library will cause them grief, but they are willing to take the chance
+# (we call Client A optimistic).
+#
+# Client B is just like Client A except for two things: (1) They use the
+# <tt>depth</tt> method and (2) they are worried about future
+# incompatibilities, so they write their version constraint like this:
+#
+# gem 'stack', '~> 0.1'
+#
+# The <tt>depth</tt> method was introduced in version 0.1.0, so that version
+# or anything later is fine, as long as the version stays below version 1.0
+# where incompatibilities are introduced. We call Client B pessimistic
+# because they are worried about incompatible future changes (it is OK to be
+# pessimistic!).
+#
+# == Preventing Version Catastrophe:
+#
+# From: http://blog.zenspider.com/2008/10/rubygems-howto-preventing-cata.html
+#
+# Let's say you're depending on the fnord gem version 2.y.z. If you
+# specify your dependency as ">= 2.0.0" then, you're good, right? What
+# happens if fnord 3.0 comes out and it isn't backwards compatible
+# with 2.y.z? Your stuff will break as a result of using ">=". The
+# better route is to specify your dependency with an "approximate" version
+# specifier ("~>"). They're a tad confusing, so here is how the dependency
+# specifiers work:
+#
+# Specification From ... To (exclusive)
+# ">= 3.0" 3.0 ... &infin;
+# "~> 3.0" 3.0 ... 4.0
+# "~> 3.0.0" 3.0.0 ... 3.1
+# "~> 3.5" 3.5 ... 4.0
+# "~> 3.5.0" 3.5.0 ... 3.6
+# "~> 3" 3.0 ... 4.0
+#
+# For the last example, single-digit versions are automatically extended with
+# a zero to give a sensible result.
+
+class Gem::Version
+ autoload :Requirement, 'rubygems/requirement'
+
+ include Comparable
+
+ VERSION_PATTERN = '[0-9]+(?>\.[0-9a-zA-Z]+)*(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?' # :nodoc:
+ ANCHORED_VERSION_PATTERN = /\A\s*(#{VERSION_PATTERN})?\s*\z/ # :nodoc:
+
+ ##
+ # A string representation of this Version.
+
+ def version
+ @version.dup
+ end
+
+ alias to_s version
+
+ ##
+ # True if the +version+ string matches RubyGems' requirements.
+
+ def self.correct? version
+ version.to_s =~ ANCHORED_VERSION_PATTERN
+ end
+
+ ##
+ # Factory method to create a Version object. Input may be a Version
+ # or a String. Intended to simplify client code.
+ #
+ # ver1 = Version.create('1.3.17') # -> (Version object)
+ # ver2 = Version.create(ver1) # -> (ver1)
+ # ver3 = Version.create(nil) # -> nil
+
+ def self.create input
+ if self === input then # check yourself before you wreck yourself
+ input
+ elsif input.nil? then
+ nil
+ else
+ new input
+ end
+ end
+
+ @@all = {}
+
+ def self.new version # :nodoc:
+ return super unless Gem::Version == self
+
+ @@all[version] ||= super
+ end
+
+ ##
+ # Constructs a Version from the +version+ string. A version string is a
+ # series of digits or ASCII letters separated by dots.
+
+ def initialize version
+ raise ArgumentError, "Malformed version number string #{version}" unless
+ self.class.correct?(version)
+
+ @version = version.to_s.strip.gsub("-",".pre.")
+ @segments = nil
+ end
+
+ ##
+ # Return a new version object where the next to the last revision
+ # number is one greater (e.g., 5.3.1 => 5.4).
+ #
+ # Pre-release (alpha) parts, e.g, 5.3.1.b.2 => 5.4, are ignored.
+
+ def bump
+ segments = self.segments.dup
+ segments.pop while segments.any? { |s| String === s }
+ segments.pop if segments.size > 1
+
+ segments[-1] = segments[-1].succ
+ self.class.new segments.join(".")
+ end
+
+ ##
+ # A Version is only eql? to another version if it's specified to the
+ # same precision. Version "1.0" is not the same as version "1".
+
+ def eql? other
+ self.class === other and @version == other.version
+ end
+
+ def hash # :nodoc:
+ @hash ||= segments.hash
+ end
+
+ def init_with coder # :nodoc:
+ yaml_initialize coder.tag, coder.map
+ end
+
+ def inspect # :nodoc:
+ "#<#{self.class} #{version.inspect}>"
+ end
+
+ ##
+ # Dump only the raw version string, not the complete object. It's a
+ # string for backwards (RubyGems 1.3.5 and earlier) compatibility.
+
+ def marshal_dump
+ [version]
+ end
+
+ ##
+ # Load custom marshal format. It's a string for backwards (RubyGems
+ # 1.3.5 and earlier) compatibility.
+
+ def marshal_load array
+ initialize array[0]
+ end
+
+ def yaml_initialize(tag, map) # :nodoc:
+ @version = map['version']
+ @segments = nil
+ @hash = nil
+ end
+
+ def to_yaml_properties # :nodoc:
+ ["@version"]
+ end
+
+ def encode_with coder # :nodoc:
+ coder.add 'version', @version
+ end
+
+ ##
+ # A version is considered a prerelease if it contains a letter.
+
+ def prerelease?
+ @prerelease ||= !!(@version =~ /[a-zA-Z]/)
+ end
+
+ def pretty_print q # :nodoc:
+ q.text "Gem::Version.new(#{version.inspect})"
+ end
+
+ ##
+ # The release for this version (e.g. 1.2.0.a -> 1.2.0).
+ # Non-prerelease versions return themselves.
+
+ def release
+ return self unless prerelease?
+
+ segments = self.segments.dup
+ segments.pop while segments.any? { |s| String === s }
+ self.class.new segments.join('.')
+ end
+
+ def segments # :nodoc:
+
+ # segments is lazy so it can pick up version values that come from
+ # old marshaled versions, which don't go through marshal_load.
+
+ @segments ||= @version.scan(/[0-9]+|[a-z]+/i).map do |s|
+ /^\d+$/ =~ s ? s.to_i : s
+ end
+ end
+
+ ##
+ # A recommended version for use with a ~> Requirement.
+
+ def approximate_recommendation
+ segments = self.segments.dup
+
+ segments.pop while segments.any? { |s| String === s }
+ segments.pop while segments.size > 2
+ segments.push 0 while segments.size < 2
+
+ "~> #{segments.join(".")}"
+ end
+
+ ##
+ # Compares this version with +other+ returning -1, 0, or 1 if the
+ # other version is larger, the same, or smaller than this
+ # one. Attempts to compare to something that's not a
+ # <tt>Gem::Version</tt> return +nil+.
+
+ def <=> other
+ return unless Gem::Version === other
+ return 0 if @version == other.version
+
+ lhsegments = segments
+ rhsegments = other.segments
+
+ lhsize = lhsegments.size
+ rhsize = rhsegments.size
+ limit = (lhsize > rhsize ? lhsize : rhsize) - 1
+
+ i = 0
+
+ while i <= limit
+ lhs, rhs = lhsegments[i] || 0, rhsegments[i] || 0
+ i += 1
+
+ next if lhs == rhs
+ return -1 if String === lhs && Numeric === rhs
+ return 1 if Numeric === lhs && String === rhs
+
+ return lhs <=> rhs
+ end
+
+ return 0
+ end
+end