vmlib 1.0.0

data/lib/vmlib/errors.rb

@@ -0,0 +1,55 @@
+###############################################################################
+# VMLib exceptions
+###############################################################################
+# Copyright (C) 2013 Nirenjan Krishnan
+# All rights reserved.
+###############################################################################
+
+;
+
+module VMLib
+
+
+  # This is a namespace for errors that can be thrown by VMLib
+  module Errors
+
+    # Base class for all VMLib exceptions
+    class VMLibError < ::RuntimeError
+    end
+
+    # Thrown if release type doesn't match with requested parameter
+    class NoVersionError < VMLibError
+    end
+
+    # Thrown if bump operation cannot be performed
+    class BumpError < VMLibError
+    end
+
+    # Thrown if initialization fails
+    class InitError < VMLibError
+    end
+
+    # Thrown if parsing fails
+    class ParseError < VMLibError
+    end
+
+    # Thrown if assigning an invalid value
+    class AssignError < VMLibError
+    end
+
+    # Thrown if the API receives invalid parameters
+    class ParameterError < VMLibError
+    end
+
+    # Thrown if there's an issue with the path for the version file
+    class PathError < VMLibError
+    end
+
+    # Thrown if there's an issue with the version file itself
+    class VersionFileError < VMLibError
+    end
+  end
+
+
+end
+

data/lib/vmlib/file.rb

@@ -0,0 +1,106 @@
+###############################################################################
+# VMLib file manager
+###############################################################################
+# Copyright (C) 2013 Nirenjan Krishnan
+# All rights reserved.
+###############################################################################
+
+;
+
+module VMLib
+
+  # This is the file class for handling VMLib version files
+  class File
+
+    # Default file name of 'Version'
+    FILE_NAME = 'Version'
+
+    # Create a new file object with the specified filename. If the filename
+    # is not specified, it reverts to the default
+    def initialize(filename = nil)
+      @filename ||= FILE_NAME
+      @dir = nil
+    end
+
+    # Search the current and all parent folders for a version file
+    # Raises an error if it cannot find any up to the root.
+    def find_file(dir = nil)
+      dir ||= ::Dir.pwd
+      raise Errors::PathError unless ::File.directory?(dir)
+      path = ::File.join(dir, @filename)
+
+      ::Dir.chdir(dir) do
+        while !::File.exists?(path) do
+          if (::File.dirname(path).match(/^(\w:\/|\/)$/i))
+            raise Errors::NoVersionError, "#{dir} is not versioned"
+          end
+
+          path = ::File.join(::File.dirname(path), '..')
+          path = ::File.expand_path(path)
+          #puts "vmlib: looking at path #{path}"
+          path = ::File.join(path, @filename)
+        end
+        @dir = path
+        return path
+      end
+    end
+
+    # Read the version file and return the parsed version data
+    def read(dir = nil)
+      path = find_file(dir)
+
+      if ::File.readable?(path)
+        # Read
+        verdata = Version.new
+        verdata.parse ::File.read(path)
+      else
+        raise Errors::VersionFileError, "unable to read #{path}"
+      end
+
+      return verdata
+    end
+
+    # Write the specfied version into the version file
+    def write(version, dir = nil)
+      path = find_file(dir)
+
+      unless version.is_a? Version
+        raise Errors::ParameterError, "invalid version #{version}"
+      end
+
+      if ::File.writable?(path)
+        # Write
+        ::File.write(path, version.to_s + "\n")
+      else
+        raise Errors::VersionFileError, "unable to write #{path}"
+      end
+    end
+
+    # Create a new version file for the current (or specified) folder.
+    # If it already exists, then throw an error
+    def create(name = '', dir = nil)
+      # Make sure that the directory isn't versioned already
+      begin
+        path = find_file(dir)
+      rescue Errors::NoVersionError
+        # We are good to go
+      else
+        # Raise error that it's already versioned
+        raise Errors::VersionFileError, "version already exists at #{path}"
+      end
+
+      dir ||= ::Dir.pwd
+      raise Errors::PathError unless ::File.directory?(dir)
+      path = ::File.join(dir, @filename)
+
+      ::File.open(path, "w") do |file|
+        version = Version.new(name)
+        file.write version.to_s + "\n"
+      end
+
+    end
+
+  end
+
+
+end

data/lib/vmlib/format.rb

@@ -0,0 +1,94 @@
+###############################################################################
+# VMLib formatter
+###############################################################################
+# Copyright (C) 2013 Nirenjan Krishnan
+# All rights reserved.
+###############################################################################
+
+;
+
+module VMLib
+
+  class Version
+
+    # Default tag format for version control systems
+    TAG_FORMAT = 'v%M.%m.%p%r%b'
+
+    # Display the version in the specified format
+    # Input: Format string
+    #        %n - name
+    #        %M - major version number
+    #        %m - minor version number
+    #        %p - patch number
+    #        %r - prerelease
+    #        %b - build number
+    def format(fstr)
+      if @name.empty?
+        fstr = fstr.gsub('%n', '')
+      else
+        fstr = fstr.gsub('%n', @name.to_s + ' ')
+      end
+
+      # Match the major version
+      match = /%(\d*)M/.match(fstr)
+      fstr = fstr.gsub(/%(\d*)M/, "%0#{$1}d" % @major)
+
+      # Match the minor version
+      match = /%(\d*)m/.match(fstr)
+      fstr = fstr.gsub(/%(\d*)m/, "%0#{$1}d" % @minor)
+
+      # Match the patch version
+      match = /%(\d*)p/.match(fstr)
+      fstr = fstr.gsub(/%(\d*)p/, "%0#{$1}d" % @patch)
+
+      if (@reltype == :rel_type_final) or
+         (@reltype == :rel_type_custom and @relcustom.length == 0)
+        fstr = fstr.gsub('%r', '')
+      else
+        fstr = case @reltype
+          when :rel_type_dev
+            fstr.gsub('%r', "-#{@devnum}")
+          when :rel_type_alpha
+            fstr.gsub('%r', "-a.#{@alphanum}")
+          when :rel_type_beta
+            fstr.gsub('%r', "-b.#{@betanum}")
+          when :rel_type_rc
+            fstr.gsub('%r', "-rc.#{@rcnum}")
+          when :rel_type_custom
+            fstr.gsub('%r', '-' + @relcustom.join('.'))
+          else
+            fstr.gsub('%r', '')
+          end
+      end
+
+      if (@buildtype == :bld_type_final) or
+         (@buildtype == :bld_type_custom and @buildcustom.length == 0)
+        fstr = fstr.gsub('%b', '')
+      else
+        fstr = case @buildtype
+          when :bld_type_custom
+            fstr.gsub('%b', '+' + @buildcustom.join('.'))
+          else
+            fstr.gsub('%b', '')
+          end
+      end
+
+      fstr
+    end
+
+    # Display a version tag suitable for use in tagging releases
+    # in the user's version control system
+    def tag
+      format TAG_FORMAT
+    end
+
+    # Display the version information as a string
+    def to_s
+      format "%n%M.%m.%p%r%b"
+    end
+
+
+  end
+
+
+end

data/lib/vmlib/issue.txt

@@ -0,0 +1,13 @@
+In paragraphs 10 and 11, the following text is present.
+
+> Identifiers MUST be comprised of only ASCII alphanumerics and dash [0-9A-Za-z-].
+
+However, it is unclear if an identifier can begin or end with a dash, or have multiple dashes in sequence. If that is allowed, then in theory, we could have identifiers like the following.
+
+    1.0.0--+-
+    1.0.0-----+----
+    1.0.0--alpha--.-1-
+    1.0.0--beta-.-2-+--build-256--
+    1.0.0+-256
+
+My understanding of the text indicates that this is not disallowed, but in my opinion, we should have the text

data/lib/vmlib/parse.rb

@@ -0,0 +1,216 @@
+###############################################################################
+# VMLib parser
+###############################################################################
+# Copyright (C) 2013 Nirenjan Krishnan
+# All rights reserved.
+###############################################################################
+
+;
+
+module VMLib
+
+  class Version
+
+    # The parse functions are all marked as private
+    private
+
+    # Regular expression format to understand the release and build formats.
+    #
+    # Acceptable formats:
+    #     alpha.1.4
+    #     beta.1.4
+    #     6.2.8
+    #     1
+    #     build-256.2013-01-04T16-40Z
+    #
+    # These fields consist of dot-separated identifiers, and these identifiers
+    # may contain only alphanumeric characters and hyphens.
+    #
+    # Fields consisting of only digits will be interpreted as numeric and
+    # leading zeroes will be stripped.
+    SPECIAL_REGEX = /^[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*/
+
+    # Regular expression to understand the version format.
+    #
+    # Acceptable formats:
+    #     1.078.2
+    #     v1.30.4908
+    #     version 2.4.875
+    #
+    # Leading zeroes will be stripped in any numeric field, therefore, the
+    # version 1.078.2 would be treated the same as 1.78.2
+    VER_REGEX = /^(?:v|version )?(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)/
+
+    # Regular expression format to retrieve the name. Names may consist of
+    # any combination of any alphanumeric character, underscores and hyphens.
+    NAME_REGEX = /^(?<name>[0-9A-Za-z_-]+)\s+/
+
+    def convert_to_integer(array)
+      array.kind_of? Array or
+        raise Errors::VMLibError, "not an array: #{array}"
+
+      for i in (0...array.length)
+        array[i].to_s.match(/^\d+$/) and array[i] = array[i].to_i
+      end
+    end
+
+    def parse_release(str)
+      match = SPECIAL_REGEX.match(str)
+      if match
+        # OK, we have a prerelease match, now parse it to determine
+        # the release type
+        @relcustom = match[0].split '.'
+        rel = @relcustom[0]
+        case rel
+
+        # Development version 1.0.0-0, 1.0.0-1, 1.0.0-2, etc.
+        when /^\d+$/
+          if @relcustom.length == 1
+            @reltype = :rel_type_dev
+            @devnum = rel.to_i
+          else
+            @reltype = :rel_type_custom
+          end
+
+        # Alpha version 1.0.0-a.1, 1.0.0-alpha.2, etc.
+        when /^(a|alpha)$/
+          if @relcustom.length == 2 && @relcustom[1].match(/^\d+$/)
+            @reltype = :rel_type_alpha
+            @alphanum = @relcustom[1].to_i
+          else
+            @reltype = :rel_type_custom
+          end
+
+        # Beta version 1.0.0-b.1, 1.0.0-beta.2, etc.
+        when /^(b|beta)$/
+          if @relcustom.length == 2 && @relcustom[1].match(/^\d+$/)
+            @reltype = :rel_type_beta
+            @betanum = @relcustom[1].to_i
+          else
+            @reltype = :rel_type_custom
+          end
+
+        # Release Candidate version 1.0.0-rc.1, 1.0.0-rc.2, etc.
+        when /^rc$/
+          if @relcustom.length == 2 && @relcustom[1].match(/^\d+$/)
+            @reltype = :rel_type_rc
+            @rcnum = @relcustom[1].to_i
+          else
+            @reltype = :rel_type_custom
+          end
+
+        else
+          @reltype = :rel_type_custom
+        end
+
+        # Done parsing, clear the relcustom array if it's not a custom type
+        @relcustom = [] unless @reltype == :rel_type_custom
+        convert_to_integer(@relcustom)
+      else # if !match
+        # It may be an empty string, so set the reltype to final in that case
+        if str.empty?
+          match = nil
+          @reltype = :rel_type_final
+        else
+          raise Errors::ParseError, "unrecognized prerelease '#{str}'"
+        end
+      end
+
+      return match
+    end
+
+    def parse_build(str)
+      match = SPECIAL_REGEX.match(str)
+      if match
+        # OK, we have a build match, now parse it to determine
+        # the release type
+        # Currently, only supports :bld_type_custom
+        @buildcustom = match[0].split '.'
+        @buildtype = :bld_type_custom
+
+        # Done parsing, clear the array if it's not a custom type
+        @buildcustom = [] unless @buildtype == :bld_type_custom
+        convert_to_integer(@buildcustom)
+      else # if !match
+        # It may be an empty string, so set the buildtype to final in that case
+        if str.empty?
+          match = nil
+          @buildtype = :bld_type_final
+        else
+          raise Errors::ParseError, "unrecognized build '#{str}'"
+        end
+      end
+
+      return match
+    end
+
+    # With the exception of the root parse function
+    public
+
+    def parse(ver)
+      unless ver.kind_of? String
+        raise Errors::ParameterError, "expected a string to be parsed"
+      end
+
+      # Chop off any trailing newlines
+      ver.chomp!
+
+      # Match the name
+      match = NAME_REGEX.match(ver)
+      if match
+        @name = match[:name]
+        ver = ver.sub(NAME_REGEX, '')
+      #else
+      # Sometimes we may not get a name to be parsed. If that's the case
+      # then simply ignore it.
+      end
+
+      # Match the major, minor and patch versions
+      match = VER_REGEX.match(ver)
+      if match
+        @major = match[:major].to_i
+        @minor = match[:minor].to_i
+        @patch = match[:patch].to_i
+        ver = ver.sub(VER_REGEX, '')
+      else
+        raise Errors::ParseError, "unrecognized version format '#{ver}'"
+      end
+
+      # See if we have a prerelease version (begins with a -)
+      if ver =~ /^-/
+        ver = ver.sub(/^-/, '')
+
+        match = parse_release(ver)
+        if match
+          # Delete the matched data
+          ver = ver.sub(SPECIAL_REGEX, '')
+        end
+      else # if ver !~ /^-/
+        @reltype = :rel_type_final
+      end
+
+      # See if we have a build version (begins with a +)
+      if ver =~ /^\+/
+        ver = ver.sub(/^\+/, '')
+
+        match = parse_build(ver)
+        if match
+          # Delete the matched data
+          ver = ver.sub(SPECIAL_REGEX, '')
+        end
+      else # if ver !~ /^\+/
+        @buildtype = :bld_type_final
+      end
+
+      # By now, ver should be empty. Raise an error if this is not the case
+      unless ver.empty?
+        raise Errors::ParseError, "unrecognized version format '#{ver}'"
+      end
+
+      true
+    end
+
+  end
+
+
+end

data/lib/vmlib/source.rb

@@ -0,0 +1,65 @@
+###############################################################################
+# VMLib source editor
+###############################################################################
+# Copyright (C) 2013 Nirenjan Krishnan
+# All rights reserved.
+###############################################################################
+
+;
+
+module VMLib
+
+  # This is the class for updating source files with the new version
+  class Source
+
+    # Set up the tree to find the root of the source repository
+    def initialize(dir = nil)
+      # Find the primary version file and get the root path
+      version = File.new.find_file(dir)
+      root = ::File.dirname(version)
+
+      # Find all files below the root which have the filename
+      # beginning with 'version'
+      @files = ::Dir.glob("#{root}/**/version*")
+      @files.delete_if {|f| ! ::File.file? f }
+
+      # Read the primary version file and get the version string from it
+      verdata = ::File.read(version)
+      v = Version.new
+      v.parse verdata
+      @verstring = v.format '"%M.%m.%p%r%b"'
+    end
+
+    # Update the specified file
+    def update_file (f)
+      fdata = ::File.read(f).split("\n")
+      
+      for i in (0...fdata.length)
+        # Check for a version string
+        # VERSION ... "<version string>"
+        line = fdata[i]
+        
+        if (line =~ /VERSION.*"\d+\.\d+\.\d+[^"]*"/)
+          puts "updating line #{i} in #{f}..."
+          puts "    old: #{line}"
+          fdata[i] = line.gsub(/"\d+\.\d+\.\d+[^"]*"/, @verstring)
+          puts "    new: #{fdata[i]}"
+        end
+      end
+
+      # For whatever reason, the split deletes the last entry and leaves
+      # us without a newline at the end of the file. Make sure that we 
+      # do insert a newline at the end of the file.
+      ::File.write(f, fdata.join("\n") + "\n")
+    end
+    private :update_file
+
+    # Update all the source files containing the version
+    def update
+      @files.each {|f| update_file(f) }
+    end
+
+  end
+
+
+end

data/lib/vmlib/version.rb

@@ -0,0 +1,12 @@
+###############################################################################
+# VMLib version information
+###############################################################################
+# Copyright (C) 2013 Nirenjan Krishnan
+# All rights reserved.
+###############################################################################
+
+module VMLib
+
+  VERSION = "1.0.0" #:nodoc:
+
+end

data/lib/vmlib.rb

@@ -0,0 +1,23 @@
+###############################################################################
+# VMLib library file
+###############################################################################
+# Copyright (C) 2013 Nirenjan Krishnan
+# All rights reserved.
+###############################################################################
+
+# Version processing
+require 'vmlib/base'
+require 'vmlib/bump'
+require 'vmlib/errors'
+require 'vmlib/compare'
+require 'vmlib/parse'
+require 'vmlib/format'
+
+# File processing
+require 'vmlib/file'
+
+# Gem version
+require 'vmlib/version'
+
+# Source file processing
+require 'vmlib/source'

data/test/test_version_basic.rb

@@ -0,0 +1,113 @@
+###############################################################################
+# VMLib basic version test cases
+###############################################################################
+# Copyright (C) 2013 Nirenjan Krishnan
+# All rights reserved.
+###############################################################################
+
+require 'test/unit'
+require 'vmlib'
+
+module VMLib
+
+  module Tests #:nodoc:
+
+    class TestBasicVersion < ::Test::Unit::TestCase   #:nodoc:
+
+      # Test the default value when a new version is created
+      def test_default_value
+        version = VMLib::Version.new
+
+        assert_equal '0.0.0-0', version.to_s
+      end
+
+
+      # Test the version with a different version number
+      def test_custom_version
+        version = VMLib::Version.new('SomeProject', 1, 1, 0, 'a.1', 'b.20')
+        assert_equal 'SomeProject 1.1.0-a.1+b.20', version.to_s
+      end
+
+
+      # Test setting the version record fields individually
+      def test_version_fields
+        version = VMLib::Version.new
+        assert_equal '0.0.0-0', version.to_s
+
+        version.major = 1
+        assert_equal '1.0.0-0', version.to_s
+
+        version.minor = 2
+        assert_equal '1.2.0-0', version.to_s
+
+        version.patch = 3
+        assert_equal '1.2.3-0', version.to_s
+
+        version.name = 'FooBar'
+        assert_equal 'FooBar 1.2.3-0', version.to_s
+
+        version.prerelease = ''
+        assert_equal 'FooBar 1.2.3', version.to_s
+
+        version.build = 'build.20'
+        assert_equal 'FooBar 1.2.3+build.20', version.to_s
+
+        version.prerelease = 'alpha.1'
+        assert_equal 'FooBar 1.2.3-a.1+build.20', version.to_s
+
+      end
+
+
+      # Test the prerelease parser and formatter
+      def test_prerelease
+        version = VMLib::Version.new
+        version.prerelease = '1'
+        assert_equal '0.0.0-1', version.to_s
+
+        version.prerelease = 'a.2'
+        assert_equal '0.0.0-a.2', version.to_s
+
+        # Test that the string alpha gets interpreted as 'a'
+        version.prerelease = 'alpha.3'
+        assert_equal '0.0.0-a.3', version.to_s
+
+        # Test that a non-standard alpha gets treated as a custom field
+        version.prerelease = 'alpha.1.2'
+        assert_equal '0.0.0-alpha.1.2', version.to_s
+
+        version.prerelease = 'alpha.a1'
+        assert_equal '0.0.0-alpha.a1', version.to_s
+
+        version.prerelease = 'b.4'
+        assert_equal '0.0.0-b.4', version.to_s
+
+        # Test that the string beta gets interpreted as 'b'
+        version.prerelease = 'beta.3'
+        assert_equal '0.0.0-b.3', version.to_s
+
+        # Test that a non-standard beta gets treated as a custom field
+        version.prerelease = 'beta.a2'
+        assert_equal '0.0.0-beta.a2', version.to_s
+
+        version.prerelease = 'beta.1.2'
+        assert_equal '0.0.0-beta.1.2', version.to_s
+
+        version.prerelease = 'rc.1'
+        assert_equal '0.0.0-rc.1', version.to_s
+
+        # Test that an unrecognized format still gets stored
+        version.prerelease = 'foo.bar.baz'
+        assert_equal '0.0.0-foo.bar.baz', version.to_s
+
+        # Verify that an empty pre-release gets treated as a final release
+        version.prerelease = ''
+        assert_equal '0.0.0', version.to_s
+      end
+
+    end
+
+
+  end
+
+
+end