mixlib-versioning 1.0.0

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+YARD::Rake::YardocTask.new

data/lib/mixlib/versioning.rb

@@ -0,0 +1,194 @@
+#
+# Author:: Seth Chisamore (<schisamo@opscode.com>)
+# Author:: Christopher Maier (<cm@opscode.com>)
+# Copyright:: Copyright (c) 2013 Opscode, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'mixlib/versioning/exceptions'
+require 'mixlib/versioning/format'
+
+module Mixlib
+  # @author Seth Chisamore (<schisamo@opscode.com>)
+  # @author Christopher Maier (<cm@opscode.com>)
+  class Versioning
+
+    # Create a new {Format} instance given a version string to parse, and an
+    # optional format type.
+    #
+    # @example
+    #   Mixlib::Versioning.parse("11.0.0")
+    #   Mixlib::Versioning.parse("11.0.0", :semver)
+    #   Mixlib::Versioning.parse("11.0.0", 'semver')
+    #   Mixlib::Versioning.parse("11.0.0", Mixlib::Versioning::Format::SemVer)
+    #
+    # @param version_string [String] String representatin of the version to
+    #   parse
+    # @param format_type [String, Symbol, Mixlib::Versioning::Format] Optional
+    #   format type to parse the version string as. If this is exluded all
+    #   version types will be attempted from most specific to most specific
+    #   with a preference for SemVer formats
+    #
+    # @raise [Mixlib::Versioning::ParseError] if the parse fails.
+    # @raise [Mixlib::Versioning::UnknownFormatError] if the given format type
+    #   doesn't exist.
+    #
+    # @return
+    #
+    def self.parse(version_string, format_type=nil)
+      if version_string.kind_of?(Mixlib::Versioning::Format)
+        return version_string
+      elsif format_type
+        return Mixlib::Versioning::Format.for(format_type).new(version_string)
+      else
+        # Attempt to parse from the most specific formats first.
+        parsed_version = nil
+        [
+          Mixlib::Versioning::Format::GitDescribe,
+          Mixlib::Versioning::Format::OpscodeSemVer,
+          Mixlib::Versioning::Format::SemVer,
+          Mixlib::Versioning::Format::Rubygems
+        ].each do |version|
+          begin
+            break parsed_version = version.new(version_string)
+          rescue Mixlib::Versioning::ParseError
+            next
+          end
+        end
+        return parsed_version
+      end
+    end
+
+    # Selects the most recent version from `all_versions` that satisfies the
+    # filtering constraints provided by `filter_version`,
+    # `use_prerelease_versions`, and `use_build_versions`.
+    #
+    # If `filter_version` specifies a release (e.g. 1.0.0), then the target
+    # version that is returned will be in the same "release line" (it will have
+    # the same major, minor, and patch versions), subject to filtering by
+    # `use_prerelease_versions` and `use_build_versions`.
+    #
+    # If `filter_version` specifies a pre-release (e.g., 1.0.0-alpha.1), the
+    # returned target version will be in the same "pre-release line", and will
+    # only be subject to further filtering by `use_build_versions`; that is,
+    # `use_prerelease_versions` is completely ignored.
+    #
+    # If `filter_version` specifies a build version (whether it is a
+    # pre-release or not), no filtering is performed at all, and
+    # `filter_version` *is* the target version; `use_prerelease_versions` and
+    # `use_build_versions` are both ignored.
+    #
+    # If `filter_version` is `nil`, then only `use_prerelease_versions` and
+    # `use_build_versions` are used for filtering.
+    #
+    # In all cases, the returned {Format} is the most recent one in
+    # `all_versions` that satisfies the given constraints.
+    #
+    # @example
+    #   all = %w{ 11.0.0-beta.1
+    #             11.0.0-rc.1
+    #             11.0.0
+    #             11.0.1 }
+    #
+    #   Mixlib::Versioning.find_target_version(all,
+    #                                          "11.0.1",
+    #                                          true,
+    #                                          true)
+    #
+    #
+    # @param all_versions [Array<String, Mixlib::Versioning::Format>] An array
+    #   of {Format} objects. This is the "world" of versions we will be
+    #   filtering to produce the final target version. Any strings in the array
+    #   will automatically be converted into instances of {Format} using
+    #   {Versioning.parse}.
+    # @param filter_version [String, Mixlib::Versioning::Format] A version that
+    #   is used to perform more fine-grained filtering. If a string is passed,
+    #   {Versioning.parse} will be used to instantiate a version.
+    # @param use_prerelease_versions [Boolean] If true, keep versions with
+    #   pre-release specifiers. When false, versions in `all_versions` that
+    #   have a pre-release specifier will be filtered out.
+    # @param use_build_versions [Boolean] If true, keep versions with build
+    #   version specifiers. When false, versions in `all_versions` that have a
+    #   build version specifier will be filtered out.
+    #
+    def self.find_target_version(all_versions,
+                                 filter_version=nil,
+                                 use_prerelease_versions=false,
+                                 use_build_versions=false)
+
+      # attempt to parse a `Mixlib::Versioning::Format` instance if we were
+      # passed a string
+      unless filter_version.nil? ||
+             filter_version.kind_of?(Mixlib::Versioning::Format)
+        filter_version = Mixlib::Versioning.parse(filter_version)
+      end
+
+      all_versions.map! do |v|
+        if v.kind_of?(Mixlib::Versioning::Format)
+          v
+        else
+          Mixlib::Versioning.parse(v)
+        end
+      end
+
+      if filter_version && filter_version.build
+        # If we've requested a build (whether for a pre-release or release),
+        # there's no sense doing any other filtering; just return that version
+        filter_version
+      elsif filter_version && filter_version.prerelease
+        # If we've requested a prerelease version, we only need to see if we
+        # want a build version or not.  If so, keep only the build version for
+        # that prerelease, and then take the most recent. Otherwise, just
+        # return the specified prerelease version
+        if use_build_versions
+          all_versions.select{|v| v.in_same_prerelease_line?(filter_version)}.max
+        else
+          filter_version
+        end
+      else
+        # If we've gotten this far, we're either just interested in
+        # variations on a specific release, or the latest of all versions
+        # (depending on various combinations of prerelease and build status)
+        all_versions.select do |v|
+          # If we're given a version to filter by, then we're only
+          # interested in other versions that share the same major, minor,
+          # and patch versions.
+          #
+          # If we weren't given a version to filter by, then we don't
+          # care, and we'll take everything
+          in_release_line = if filter_version
+                              filter_version.in_same_release_line?(v)
+                            else
+                              true
+                            end
+
+          in_release_line && if use_prerelease_versions && use_build_versions
+                               v.prerelease_build?
+                             elsif !use_prerelease_versions &&
+                                   use_build_versions
+                               v.release_build?
+                             elsif use_prerelease_versions &&
+                                   !use_build_versions
+                               v.prerelease?
+                             elsif !use_prerelease_versions &&
+                                   !use_build_versions
+                               v.release?
+                             end
+        end.max # select the most recent version
+      end # if
+    end # self.find_target_version
+
+  end # Versioning
+end # Mixlib

data/lib/mixlib/versioning/exceptions.rb

@@ -0,0 +1,28 @@
+#
+# Author:: Seth Chisamore (<schisamo@opscode.com>)
+# Copyright:: Copyright (c) 2013 Opscode, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module Mixlib
+  class Versioning
+    # Base class for all Mixlib::Versioning Errors
+    class Error < RuntimeError; end
+    # Exception raised if parsing fails
+    class ParseError < Error; end
+    # Exception raised if version format cannot be identified
+    class UnknownFormatError < Error; end
+  end
+end

data/lib/mixlib/versioning/format.rb

@@ -0,0 +1,351 @@
+#
+# Author:: Seth Chisamore (<schisamo@opscode.com>)
+# Copyright:: Copyright (c) 2013 Opscode, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'mixlib/versioning/format/git_describe'
+require 'mixlib/versioning/format/opscode_semver'
+require 'mixlib/versioning/format/rubygems'
+require 'mixlib/versioning/format/semver'
+
+module Mixlib
+  class Versioning
+
+    # @author Seth Chisamore (<schisamo@opscode.com>)
+    #
+    # @!attribute [r] major
+    #   @return [Integer] major identifier
+    # @!attribute [r] minor
+    #   @return [Integer] minor identifier
+    # @!attribute [r] patch
+    #   @return [Integer] patch identifier
+    # @!attribute [r] prerelease
+    #   @return [String] pre-release identifier
+    # @!attribute [r] build
+    #   @return [String] build identifier
+    # @!attribute [r] iteration
+    #   @return [String] build interation
+    # @!attribute [r] input
+    #   @return [String] original input version string that was parsed
+    class Format
+      include Comparable
+
+      # Returns the {Mixlib::Versioning::Format} class that maps to the given
+      # format type.
+      #
+      # @example
+      #   Mixlib::Versioning::Format.for(:semver)
+      #   Mixlib::Versioning::Format.for('semver')
+      #   Mixlib::Versioning::Format.for(Mixlib::Versioning::Format::SemVer)
+      #
+      # @param format_type [String, Symbol, Mixlib::Versioning::Format] Name of
+      #   a valid +Mixlib::Versioning::Format+ in Class or snake-case form.
+      #
+      # @raise [Mixlib::Versioning::UnknownFormatError] if the given format
+      #   type doesn't exist
+      #
+      # @return [Class] the {Mixlib::Versioning::Format} class
+      #
+      def self.for(format_type)
+        if format_type.kind_of?(Class) &&
+           format_type.ancestors.include?(Mixlib::Versioning::Format)
+          format_type
+        else
+          case format_type.to_s
+          when 'semver'; Mixlib::Versioning::Format::SemVer
+          when 'opscode_semver'; Mixlib::Versioning::Format::OpscodeSemVer
+          when 'git_describe'; Mixlib::Versioning::Format::GitDescribe
+          when 'rubygems'; Mixlib::Versioning::Format::Rubygems
+          else
+            msg = "'#{format_type.to_s}' is not a supported Mixlib::Versioning format"
+            raise Mixlib::Versioning::UnknownFormatError, msg
+          end
+        end
+      end
+
+      attr_reader :major, :minor, :patch, :prerelease, :build, :iteration, :input
+
+      # @param version_string [String] string representation of the version
+      def initialize(version_string)
+        parse(version_string)
+        @input = version_string
+      end
+
+      # Parses the version string splitting it into it's component version
+      # identifiers for easy comparison and sorting of versions. This method
+      # **MUST** be overriden by all descendants of this class.
+      #
+      # @param version_string [String] string representation of the version
+      # @raise [Mixlib::Versioning::ParseError] raised if parsing fails
+      def parse(version_string)
+        raise Error, "You must override the #parse"
+      end
+
+      # @return [Boolean] Whether or not this is a release version
+      def release?
+        @prerelease.nil? && @build.nil?
+      end
+
+      # @return [Boolean] Whether or not this is a pre-release version
+      def prerelease?
+        !!(@prerelease && @build.nil?)
+      end
+
+      # @return [Boolean] Whether or not this is a release build version
+      def release_build?
+        !!(@prerelease.nil? && @build)
+      end
+
+      # @return [Boolean] Whether or not this is a pre-release build version
+      def prerelease_build?
+        !!(@prerelease && @build)
+      end
+
+      # @return [Boolean] Whether or not this is a build version
+      def build?
+        !!@build
+      end
+
+      # Returns `true` if `other` and this {Format} share the same `major`,
+      # `minor`, and `patch` values. Pre-release and build specifiers are not
+      # taken into consideration.
+      #
+      # @return [Boolean]
+      def in_same_release_line?(other)
+        @major == other.major &&
+        @minor == other.minor &&
+        @patch == other.patch
+      end
+
+      # Returns `true` if `other` an share the same
+      # `major`, `minor`, and `patch` values. Pre-release and build specifiers
+      # are not taken into consideration.
+      #
+      # @return [Boolean]
+      def in_same_prerelease_line?(other)
+        @major == other.major &&
+        @minor == other.minor &&
+        @patch == other.patch &&
+        @prerelease == other.prerelease
+      end
+
+      # @return [String] String representation of this {Format} instance
+      def to_s
+        @input
+      end
+
+      # Since the default implementation of `Object#inspect` uses `Object#to_s`
+      # under the covers (which we override) we need to also override `#inspect`
+      # to ensure useful debug information.
+      def inspect
+        vars = instance_variables.map do |n|
+          "#{n}=#{instance_variable_get(n).inspect}"
+        end
+        "#<%s:0x%x %s>" % [self.class,object_id,vars.join(', ')]
+      end
+
+      # Returns SemVer compliant string representation of this {Format}
+      # instance. The string returned will take on the form:
+      #
+      # ```text
+      # MAJOR.MINOR.PATCH-PRERELEASE+BUILD
+      # ```
+      #
+      # @return [String] SemVer compliant string representation of this
+      #   {Format} instance
+      # @todo create a proper serialization abstraction
+      def to_semver_string
+        s = [@major, @minor, @patch].join(".")
+        s += "-#{@prerelease}" if @prerelease
+        s += "+#{@build}" if @build
+        s
+      end
+
+      # Returns Rubygems compliant string representation of this {Format}
+      # instance. The string returned will take on the form:
+      #
+      # ```text
+      # MAJOR.MINOR.PATCH.PRERELEASE
+      # ```
+      #
+      # @return [String] Rubygems compliant string representation of this
+      #   {Format} instance
+      # @todo create a proper serialization abstraction
+      def to_rubygems_string
+        s = [@major, @minor, @patch].join(".")
+        s += ".#{@prerelease}" if @prerelease
+        s
+      end
+
+      # Compare this version number with the given version number, following
+      # Semantic Versioning 2.0.0-rc.1 semantics.
+      #
+      # @param other [Mixlib::Versioning::Format]
+      # @return [Integer] -1, 0, or 1 depending on whether the this version is
+      #   less than, equal to, or greater than the other version
+      def <=>(other)
+
+        # First, perform comparisons based on major, minor, and patch
+        # versions.  These are always presnt and always non-nil
+        maj = @major <=> other.major
+        return maj unless maj == 0
+
+        min = @minor <=> other.minor
+        return min unless min == 0
+
+        pat = @patch <=> other.patch
+        return pat unless pat == 0
+
+        # Next compare pre-release specifiers.  A pre-release sorts
+        # before a release (e.g. 1.0.0-alpha.1 comes before 1.0.0), so
+        # we need to take nil into account in our comparison.
+        #
+        # If both have pre-release specifiers, we need to compare both
+        # on the basis of each component of the specifiers.
+        if @prerelease && other.prerelease.nil?
+          return -1
+        elsif @prerelease.nil? && other.prerelease
+          return 1
+        elsif @prerelease && other.prerelease
+          pre = compare_dot_components(@prerelease, other.prerelease)
+          return pre unless pre == 0
+        end
+
+        # Build specifiers are compared like pre-release specifiers,
+        # except that builds sort *after* everything else
+        # (e.g. 1.0.0+build.123 comes after 1.0.0, and
+        # 1.0.0-alpha.1+build.123 comes after 1.0.0-alpha.1)
+        if @build.nil? && other.build
+          return -1
+        elsif @build && other.build.nil?
+          return 1
+        elsif @build && other.build
+          build_ver = compare_dot_components(@build, other.build)
+          return build_ver unless build_ver == 0
+        end
+
+        # Some older version formats improperly include a package iteration in
+        # the version string. This is different than a build specifier and
+        # valid release versions may include an iteration. We'll transparently
+        # handle this case and compare iterations if it was parsed by the
+        # implementation class.
+        if @iteration.nil? && other.iteration
+          return -1
+        elsif @iteration && other.iteration.nil?
+          return 1
+        elsif @iteration && other.iteration
+          return @iteration <=> other.iteration
+        end
+
+        # If we get down here, they're both equal
+        return 0
+      end
+
+      # @param other [Mixlib::Versioning::Format]
+      # @return [Boolean] returns true if the versions are equal, false
+      #   otherwise.
+      def eql?(other)
+        @major == other.major &&
+          @minor == other.minor &&
+          @patch == other.patch &&
+          @prerelease == other.prerelease &&
+          @build == other.build
+      end
+
+      def hash
+        [@major, @minor, @patch, @prerelease, @build].compact.join(".").hash
+      end
+
+      #########################################################################
+
+      private
+
+      # If a String `n` can be parsed as an Integer do so; otherwise, do
+      # nothing.
+      #
+      # @param n [String, nil]
+      # @return [Integer] the parsed {Integer}
+      def maybe_int(n)
+        Integer(n)
+      rescue
+        n
+      end
+
+      # Compares prerelease and build version component strings
+      # according to SemVer 2.0.0-rc.1 semantics.
+      #
+      # Returns -1, 0, or 1, just like the spaceship operator (`<=>`),
+      # and is used in the implemntation of `<=>` for this class.
+      #
+      # Pre-release and build specifiers are dot-separated strings.
+      # Numeric components are sorted numerically; otherwise, sorting is
+      # standard ASCII order.  Numerical components have a lower
+      # precedence than string components.
+      #
+      # See http://www.semver.org for more.
+      #
+      # Both `a_item` and `b_item` should be Strings; `nil` is not a
+      # valid input.
+      def compare_dot_components(a_item, b_item)
+        a_components = a_item.split(".")
+        b_components = b_item.split(".")
+
+        max_length = [a_components.length, b_components.length].max
+
+        (0..(max_length-1)).each do |i|
+          # Convert the ith component into a number if possible
+          a = maybe_int(a_components[i])
+          b = maybe_int(b_components[i])
+
+          # Since the components may be of differing lengths, the
+          # shorter one will yield +nil+ at some point as we iterate.
+          if a.nil? && !b.nil?
+            # a_item was shorter
+            return -1
+          elsif !a.nil? && b.nil?
+            # b_item was shorter
+            return 1
+          end
+
+          # Now we need to compare appropriately based on type.
+          #
+          # Numbers have lower precedence than strings; therefore, if
+          # the components are of differnt types (String vs. Integer),
+          # we just return -1 for the numeric one and we're done.
+          #
+          # If both are the same type (Integer vs. Integer, or String
+          # vs. String), we can just use the native comparison.
+          #
+          if a.is_a?(Integer) && b.is_a?(String)
+            # a_item was "smaller"
+            return -1
+          elsif a.is_a?(String) && b.is_a?(Integer)
+            # b_item was "smaller"
+            return 1
+          else
+            comp = a <=> b
+            return comp unless comp == 0
+          end
+        end # each
+
+        # We've compared all components of both strings; if we've gotten
+        # down here, they're totally the same
+        return 0
+      end
+
+    end # Format
+  end # Versioning
+end # Mixlib