sem_version 1.2.0 → 1.3.0

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (C) 2012 Antony Male
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,146 @@
+SemVersion
+==========
+
+SemVersion is a gem to help parse, validate, modify, and compare [Semantic Versions](http://semver.org).
+
+Parsing
+-------
+
+Parsing is easy:
+
+```ruby
+v = SemVersion.new('1.2.3-pre.4+build.5')
+
+v.major         # => 1
+v.minor         # => 2
+v.patch         # => 3
+
+v.pre           # => 'pre.4'
+v.prerelease    # => 'pre.4'
+v.build         # => 'build.5'
+
+v.to_s          # => '1.2.3-pre.4+build.5'
+```
+
+You can pass any valid semantic version string, as specified by [Semantic Versions](http://semver.org).
+Invalid versions will raise an ArgumentError.
+
+You can also create a new SemVersion from an array or a hash, and serialise back to arrays and hashes.
+
+```ruby
+v1 = SemVersion.new([1, 2, 3, 'pre.4', 'build.5'])
+v1.to_s          # => '1.2.3-pre.4+build.5'
+v1.to_a          # => [1, 2, 3, 'pre.4', 'build.5']
+
+v2 = SemVersion.new(1, 2, 3, nil, 'build.5')
+v2.to_s          # => '1.2.3+build.5'
+v2.to_a          # => [1, 2, 3, nil, 'build.5']
+
+v3 = SemVersion.new(:major => 1, :minor => 2, :patch => 3, :pre => 'pre.4', :build => 'build.5')
+v.to_s           # => '1.2.3-pre.4+build.5'
+v.to_h           # => {:major => 1, :minor => 2, :patch => 3, :pre => 'pre.4', :build => 'build.5'}
+
+v4 = SemVersion.new(:major => 1, :minor => 2, :patch => 3, :build => 'build.6')
+v4.to_h          # => {:major => 1, :minor => 2, :patch => 3, :build => 'build.6'}
+```
+
+You can also use `SemVersion()` as an alias for `SemVersion.new()`.
+
+
+Validating
+----------
+
+Validating is easier:
+
+```ruby
+SemVersion.valid?('1.2.3')          # => true
+SemVersion.valid?('1.2')            # => false
+SemVersion.valid?('1.2.3-pre.1')    # => true
+SemVersion.valid?('1.2.3-pre.!')    # => false
+```
+
+And so on...
+
+Modifying
+---------
+
+You can modify any part of a parsed version.
+Invalid new values will raise an ArgumentError
+
+```ruby
+v = SemVersion.new('1.2.3')
+v.major = 3
+v.minor = 5
+v.pre = 'pre.2'
+v.build = 'build.x.7'
+
+v.to_s                           # => '3.5.1-pre.2+build.x.7'
+
+v.major = -1                     # => ArgumentError
+v.major = 'a'                    # => ArgumentError
+v.pre = 'a.!'                    # => ArgumentError
+v.pre = '.a'                     # => ArgumentError
+```
+
+Comparing
+---------
+
+You can compare semantic versions using `<`, `>`, `<=`, `>=`, `==`, and `<=>`
+
+```ruby
+SemVersion.new('1.2.3') < SemVersion.new('1.2.2')                  # => true
+SemVersion.new('1.2.3-pre.1') <= SemVersion.new('1.2.3-pre')       # => false
+SemVersion.new('1.2.3+build.11') > SemVersion.new('1.2.3+build.2') # => true
+```
+
+Satisfying constraints
+----------------------
+
+You can see whether a semantic version satisfies a particular constraint.
+Constraints are in the form `"<comparison> <version>"`, e.g. ">= 1.2.2", "= 1.3", or "~> 1.2".
+
+When using the pessimistic operation, `~>`, versions may be specified in the form `"x.y"` or `"x.y.z"` (with `"~> x.y"` meaning `">= x.y.0" && "< x+1.0.0"`, and `"~> x.y.z"` meaning `">= x.y.z" && "< x.y+1.0"`).
+
+When using the other operations, versions may be in the form `"x"`, `"x.y"`, or a full semantic version (including optional pre-release and build).
+In the former two cases, the missing versions out of minor and patch will be filled in with 0's, and the pre-release and build ignored.
+
+```ruby
+SemVersion.new('1.2.3').satisfies?('>= 1.2')         # => true
+SemVersion.new('1.2.3-pre.1').satisfies?('>= 1.2.3') # => false
+SemVersion.new('0.1.0').satisfies?('> 0')            # => true
+SemVersion.new('2.3.0').satisfies?('~> 2.2')         # => true
+```
+
+You can also see whether a given constraint is 'open' (allows a range of versions), or 'closed' (allows only one version).
+
+For example:
+
+```ruby
+SemVersion.open_constraint?('1.2.3')      # => false
+SemVersion.open_constraint?('= 1.2.3')    # => false
+SemVersion.open_constraint?('== 1.2.3')   # => false
+SemVersion.open_constraint?('<= 1.2.3')   # => true
+SemVersion.open_constraint?('~> 1.2.3')   # => true
+```
+
+It's also possible to split a constraint into its comparison and version.
+If the comparison is not given, or is '==', it is normalised to '='.
+
+```ruby
+SemVersion.split_constraint('1.2.3')     # => ['=', '1.2.3']
+SemVersion.split_constraint('= 1.2.3')   # => ['=', '1.2.3']
+SemVersion.split_constraint('== 1.2.3')  # => ['=', '1.2.3']
+SemVersion.split_constraint('> 1.2.3')   # => ['>', '1.2.3']
+```
+
+Core Extensions
+===============
+
+You can also load a set of core extensions using an optional require.
+
+```ruby
+require 'sem_version'
+require 'sem_version/core_ext'
+
+"1.2.3+pre.4-build.5".to_version
+```

data/lib/sem_version/core_ext.rb

@@ -0,0 +1,8 @@
+# Just make sure sem_version has been required
+require 'sem_version'
+
+class String
+  def to_version
+    SemVersion.new(self)
+  end
+end

data/lib/sem_version.rb

@@ -1,19 +1,32 @@
 class SemVersion
   include Comparable
 
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
+
   # Pattern allows min and patch to be skipped. We have to do extra checking if we want them
   SEMVER_REGEX = /^(\d+)(?:\.(\d+)(?:\.(\d+)(?:-([\dA-Za-z\-]+(?:\.[\dA-Za-z\-]+)*))?(?:\+([\dA-Za-z\-]+(?:\.[\dA-Za-z\-]+)*))?)?)?$/
+  PRE_BUILD_REGEX = /^[\dA-Za-z\-]+(\.[\dA-Za-z\-]+)*$/
 
   attr_reader :major, :minor, :patch, :pre, :build
   alias_method :prerelease, :pre
 
   # Format were raw bits are passed in is undocumented, and not validity checked
-  def initialize(string, *args)
-    if args.empty?
-      @major, @minor, @patch, @pre, @build = self.class.parse(string)
+  def initialize(*args)
+    if args.first.is_a?(String)
+      @major, @minor, @patch, @pre, @build = self.class.parse(args.first)
+      # Validation should be handled at a string level by self.parse, but validate anyway
+      validate
+    elsif args.first.is_a?(Hash)
+      @major, @minor, @patch, @pre, @build = args.first.values_at(:major, :minor, :patch, :pre, :build)
+      # Allow :prerelease as well
+      @pre ||= args.first[:prerelease]
+      validate
+    elsif args.first.is_a?(Array)
+      @major, @minor, @patch, @pre, @build = *args.first
+      validate
     else
-      @major, @minor, @patch, @pre, @build = [string, *args]
+      @major, @minor, @patch, @pre, @build = *args
+      validate
     end
   end
 
@@ -59,7 +72,7 @@ class SemVersion
   end
 
   def satisfies?(constraint)
-    comparison, version = constraint.strip.split(' ', 2)
+    comparison, version = self.class.split_constraint(constraint)
     # Allow pessimistic operator
     if comparison == '~>'
       match = version.match(/^(\d+)\.(\d+)\.?(\d*)$/)
@@ -73,22 +86,17 @@ class SemVersion
         upper = "#{maj}.#{min.to_i+1}.0"
       end
 
-      send('>=', SemVersion.new(lower)) && send('<', SemVersion.new(upper)) 
+      send('>=', SemVersion.new(lower)) && send('<', SemVersion.new(upper))
     else
-      # Allow '1.0.2' as '== 1.0.2'
-      version, comparison = comparison, '==' if version.nil?
-      # Allow '= 1.0.2' as '== 1.0.2'
       comparison = '==' if comparison == '='
-
       semversion = self.class.from_loose_version(version)
-
       send(comparison, semversion)
     end
   end
 
   def self.open_constraint?(constraint)
-    comparison, version = constraint.strip.split(' ', 2)
-    !['=', '=='].include?(comparison) && !version.nil?
+    comparison, _ = self.split_constraint(constraint)
+    comparison != '='
   end
 
   def self.split_constraint(constraint)
@@ -114,30 +122,42 @@ class SemVersion
   end
 
   def pre=(val)
-    if !val.is_a?(String) || val !~ /^[\dA-Za-z\-]+(\.[\dA-Za-z\-]+)*$/
-      raise ArgumentError, "#{val} is not a valid pre-release version (must be a string following http://semver.org constraints)"
+    unless val.nil? || (val.is_a?(String) && val =~ PRE_BUILD_REGEX)
+      raise ArgumentError, "#{val} is not a valid pre-release version (must be nil, or a string following http://semver.org constraints)"
     end
     @pre = val
   end
   alias_method :prerelease=, :pre=
 
   def build=(val)
-    if !val.is_a?(String) || val !~ /^[\dA-Za-z\-]+(\.[\dA-Za-z\-]+)*$/
-      raise ArgumentError, "#{val} is not a valid pbuild version (must be a string following http://semver.org constraints)"
+    unless val.nil? || (val.is_a?(String) && val =~ PRE_BUILD_REGEX)
+      raise ArgumentError, "#{val} is not a valid build version (must be nil, or a string following http://semver.org constraints)"
     end
     @build = val
   end
 
-
   def to_s
-    r = "#{@major}.#{@minor}.#{patch}"
+    r = "#{@major}.#{@minor}.#{@patch}"
     r << "-#{@pre}" if @pre
     r << "+#{@build}" if @build
     r
   end
 
+  def to_a
+    [@major, @minor, @patch, @pre, @build]
+  end
+
+  def to_h
+    h = [:major, :minor, :patch, :pre, :build].zip(to_a)
+    Hash[h.reject{ |k,v| v.nil? }]
+  end
+
+  def inspect
+    "#<SemVersion: #{to_s}>"
+  end
+
   private
-  
+
   def compare_sep(ours, theirs, nil_wins)
     # Both nil? They're equal
     return 0 if ours.nil? && theirs.nil?
@@ -162,6 +182,19 @@ class SemVersion
     # If we got this far, either they're equal (same length) or they won
     return (our_parts.length == their_parts.length) ? 0 : -1
   end
+
+  def validate
+    # Validates the instance variables. Different approach to validating a raw string
+    raise ArgumentError, "Invalid version (major is not an int >= 0)" unless @major.is_a?(Fixnum) && @major >= 0
+    raise ArgumentError, "Invalid version (minor is not an int >= 0)" unless @minor.is_a?(Fixnum) && @minor >= 0
+    raise ArgumentError, "Invalid version (patch is not an int >= 0)" unless @patch.is_a?(Fixnum) && @patch >= 0
+    unless @pre.nil? || (@pre.is_a?(String) && @pre =~ PRE_BUILD_REGEX)
+      raise ArgumentError, "Invalid version (pre must be nil, or a string following http://semver.org contraints)"
+    end
+    unless @build.nil? || (@build.is_a?(String) && @build =~ PRE_BUILD_REGEX)
+      raise ArgumentError, "Invalid version (build must be nil, or a string following http://semver.org contraints)"
+    end
+  end
 end
 
 def SemVersion(*args)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sem_version
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,18 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-12 00:00:00.000000000 Z
+date: 2012-12-16 00:00:00.000000000 Z
 dependencies: []
-description: Allows you to parse and compare semantic versions, as specified by http://semver.org/.
-  Allows constraint checking e.g. >=, <, ~>
+description: Semantic Version parsing, comparison, and constraint checking utility
+  (e.g. ~> 1.2), as specified by http://semver.org/
 email: antony dot mail at gmail
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/sem_version/core_ext.rb
 - lib/sem_version.rb
+- README.md
+- LICENSE
 homepage: https://github.com/canton7/sem_version
-licenses: []
+licenses:
+- MIT
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -42,5 +46,6 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: ! 'SemVersion: Semantic version parsing and comparison. See http://semver.org/'
+summary: ! 'SemVersion: Semantic version parsing and comparison, and constraint checking.
+  See http://semver.org/'
 test_files: []