versionaire 8.4.0 → 9.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1776d9481fa83da0c743faa221bda1a9c65634994ef1033e31eaaa4e0cb19633
-  data.tar.gz: 2167d8631a24e61763400cecb8bf33842f66753a0098a5c3e1610331288d295a
+  metadata.gz: 7dd4a85312295a2cc1e5aa13d6252156a095da2718fe8bff2afaa6d4a5ca0689
+  data.tar.gz: 6eadfe1ca935a2e35681a189562ee9fd5a6e49c9c757774ec977ee2e21820399
 SHA512:
-  metadata.gz: 0cacf3c8a5927747a88ca9dd679a1dd685a1aec06ead8d2d0bc349b2534434eda31d6c7d3cb1a42c44a9cca581a1e07c3c9530575d8edffda18094e8699725ae
-  data.tar.gz: 398494d23393c467d3f18361fc87574d86e2b299fce75b007326b5de45b8a0c3218ff7edb6268ff6b8796da27e84429ac47d602f2743e5bc30c465dc2d4b4705
+  metadata.gz: 21b92646e48340c1fdde455bf0d45aed944e3d63440e304c86ed7d3b66877cfd1d66e9c7e49468a7e340d96015ecc8e995f64878755764f8bda5e98df4df6daa
+  data.tar.gz: 7a5d2418831d0c11f0802bc5f3a554b610a39a21736fef4b08b1130963b594c074c4127871288eb05446b053ccebe4e6fbfbf68cd5cf74c8d16a564349d161b8

checksums.yaml.gz.sig

@@ -1,3 +1,2 @@
-P0��n4{Zωh����+�F~�����y�� Fu�Nekb��Gh%h�V^�U�����.������x7�7	�憡�[q�9>\��j��&sy�Rf�z����-0�pܒX�&A�Mx�F�?����tXX���X��ޔ]�vq�Px�~Aɨ%�{��ẓ�H�?���-P�3�:���i�d��h���_�"�L�v)wśEaM�㼩�
-K:�$�LyԄ�h�]h���W��[Y
-dq�
+��tN�
+��V=�Βk?!*V��ϖ�

data/README.adoc

@@ -55,10 +55,10 @@ A new version can be initialized in a variety of ways:
 
 [source,ruby]
 ----
-Versionaire::Version.new                                    # "0.0.0"
-Versionaire::Version[major: 1]                              # "1.0.0"
-Versionaire::Version[major: 1, minor: 2]                    # "1.2.0"
-Versionaire::Version[major: 1, minor: 2, patch: 3]          # "1.2.3"
+Versionaire::Version.new                            # "0.0.0"
+Versionaire::Version[major: 1]                      # "1.0.0"
+Versionaire::Version[major: 1, minor: 2]            # "1.2.0"
+Versionaire::Version[major: 1, minor: 2, patch: 3]  # "1.2.3"
 ----
 
 === Equality
@@ -74,18 +74,18 @@ version_a = Versionaire::Version[major: 1]
 version_b = Versionaire::Version[major: 2]
 version_c = Versionaire::Version[major: 1]
 
-version_a == version_a # true
-version_a == version_b # false
-version_a == version_c # true
+version_a == version_a  # true
+version_a == version_b  # false
+version_a == version_c  # true
 ----
 
 Knowning this, versions can be compared against one another too:
 
 [source,ruby]
 ----
-version_a > version_b                   # false
-version_a < version_b                   # true
-version_a.between? version_c, version_b # true
+version_a > version_b                    # false
+version_a < version_b                    # true
+version_a.between? version_c, version_b  # true
 ----
 
 ==== Hash (`#eql?`)
@@ -106,16 +106,16 @@ version_a = Versionaire::Version[major: 1]
 version_b = Versionaire::Version[major: 2]
 version_c = Versionaire::Version[major: 1]
 
-version_a.equal? version_a # true
-version_a.equal? version_b # false
-version_a.equal? version_c # false
+version_a.equal? version_a  # true
+version_a.equal? version_b  # false
+version_a.equal? version_c  # false
 ----
 
 === Conversions
 
-==== Function (Casting)
+==== Function
 
-The `Versionaire::Version` function is provided for explicit casting to a version:
+Use the `Versionaire::Version` function to explicitly cast to a version:
 
 [source,ruby]
 ----
@@ -128,7 +128,30 @@ Versionaire::Version version
 ----
 
 Each of these conversions will result in a version object that represents "`1.0.0`". When attempting
-to convert an unsupported type, a `+Versionaire::Errors::Conversion+` exception will be thrown.
+to convert an unsupported type, a `+Versionaire::Errors::Cast+` exception will be thrown.
+
+==== Refinement
+
+Building upon the examples shown above, there is an even more elegant solution where you can use
+this gem's built-in link:https://www.alchemists.io/articles/ruby_refinements[refinement] support:
+
+[source,ruby]
+----
+using Versionaire::Cast
+
+version = Versionaire::Version[major: 1]
+
+Version "1.0.0"
+Version [1, 0, 0]
+Version major: 1, minor: 0, patch: 0
+Version version
+----
+
+By adding `using Versionaire::Cast` to your implementation, this allows Versionaire to refine
+`Kernel` so you have a top-level `Version` conversion function much like Kernel's native support for
+`Integer`, `String`, `Array`, `Hash`, etc. The benefit to this approach is it reduces the amount of
+typing, doesn't polute your entire object space like a monkey patch would, and provides a idiomatic
+approach to casting like any other primitive.
 
 ==== Implicit
 
@@ -136,7 +159,7 @@ Implicit conversion to a `+String+` is supported:
 
 [source,ruby]
 ----
-"1.0.0".match Versionaire::Version[major: 1] # <MatchData "1.0.0">
+"1.0.0".match Versionaire::Version[major: 1]  # <MatchData "1.0.0">
 ----
 
 ==== Explicit
@@ -147,9 +170,9 @@ Explicit conversion to a `String`, `Array`, or `Hash` is supported:
 ----
 version = Versionaire::Version.new
 
-version.to_s # "0.0.0"
-version.to_a # [0, 0, 0]
-version.to_h # {major: 0, minor: 0, patch: 0}
+version.to_s  # "0.0.0"
+version.to_a  # [0, 0, 0]
+version.to_h  # {major: 0, minor: 0, patch: 0}
 ----
 
 === Comparisons
@@ -162,39 +185,76 @@ work. Example:
 version_1 = Versionaire::Version "1.0.0"
 version_2 = Versionaire::Version "2.0.0"
 
-version_1 < version_2 # true
-version_1 <= version_2 # true
-version_1 == version_2 # false (see Equality section above for details)
-version_1 > version_2 # false
-version_1 >= version_2 # false
-version_1.between? version_1, version_2 # true
-version_1.clamp version_1, version_2 # version_1 (added in Ruby 2.4.0)
+version_1 < version_2                    # true
+version_1 <= version_2                   # true
+version_1 == version_2                   # false (see Equality section above for details)
+version_1 > version_2                    # false
+version_1 >= version_2                   # false
+version_1.between? version_1, version_2  # true
+version_1.clamp version_1, version_2     # version_1 (added in Ruby 2.4.0)
 ----
 
 === Math
 
-Versions can be added and subtracted from each other.
+Versions can be added, subtracted, sequentially increased, or sequentially decreased from each
+other.
 
 ==== Addition
 
+Versions can be added together to produce a resulting version sum.
+
 [source,ruby]
 ----
 version_1 = Versionaire::Version[major: 1, minor: 2, patch: 3]
 version_2 = Versionaire::Version[major: 2, minor: 5, patch: 7]
-version_1 + version_2 # "3.7.10"
+version_1 + version_2  # "3.7.10"
 ----
 
 ==== Subtraction
 
+Versions can be substracted from each other as long as there isn't a negative result.
+
 [source,ruby]
 ----
 version_1 = Versionaire::Version[major: 1, minor: 2, patch: 3]
 version_2 = Versionaire::Version[major: 1, minor: 1, patch: 1]
-version_1 - version_2 # "0.1.2"
+version_1 - version_2  # "0.1.2"
 
 version_1 = Versionaire::Version[major: 1]
 version_2 = Versionaire::Version[major: 5]
-version_1 - version_2 # Fails with a Versionaire::Errors::NegativeNumber
+version_1 - version_2  # Versionaire::Errors::NegativeNumber
+----
+
+==== Up
+
+Versions can be sequentially increased or given a specific version to jump to.
+
+[source,ruby]
+----
+version = Versionaire::Version[major: 1, minor: 1, patch: 1]
+version.up :major     # => "2.1.1"
+version.up :major, 3  # => "4.1.1"
+version.up :minor     # => "1.2.1"
+version.up :minor, 3  # => "1.4.1"
+version.up :patch     # => "1.1.2"
+version.up :patch, 3  # => "1.1.4"
+----
+
+==== Down
+
+Versions can be sequentially decreased or given a specific version to jump to as long as the result
+is not negative.
+
+[source,ruby]
+----
+version = Versionaire::Version[major: 5, minor: 5, patch: 5]
+version.down :major     # => "4.5.5"
+version.down :major, 3  # => "2.5.5"
+version.down :minor     # => "5.4.5"
+version.down :minor, 3  # => "5.2.5"
+version.down :patch     # => "5.5.4"
+version.down :patch, 3  # => "5.5.2"
+version.down :major, 6  # => Versionaire::Errors::NegativeNumber
 ----
 
 == Development

data/lib/versionaire.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
+require "versionaire/identity"
 require "versionaire/errors/base"
-require "versionaire/errors/conversion"
+require "versionaire/errors/cast"
 require "versionaire/errors/invalid_number"
 require "versionaire/errors/negative_number"
-require "versionaire/filler"
-require "versionaire/conversion"
-require "versionaire/identity"
 require "versionaire/version"
+require "versionaire/function"
+require "versionaire/cast"

data/lib/versionaire/cast.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Versionaire
+  # Refines Kernel in order to provide a top-level Version conversion function.
+  module Cast
+    refine Kernel do
+      def Version object
+        Versionaire::Version object
+      end
+    end
+  end
+end

data/lib/versionaire/errors/cast.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Versionaire
+  module Errors
+    # Thrown when attempting to cast an invalid primitive to a version.
+    class Cast < Base
+    end
+  end
+end

data/lib/versionaire/{conversion.rb → function.rb}

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "refinements/arrays"
+require "refinements/structs"
+
 # The gem namespace.
 module Versionaire
   module_function
@@ -20,50 +23,48 @@ module Versionaire
 
   # Aids with converting objects into valid versions.
   class Converter
-    def initialize object, filler: Filler.new
+    using Refinements::Arrays
+    using Refinements::Structs
+
+    def initialize object
       @object = object
-      @filler = filler
     end
 
     def from_string
       body = "Use: <major>.<minor>.<patch>, <major>.<minor>, <major>, or empty string."
-      fail Errors::Conversion, error_message(object, body) unless Version.regex.match? object
+      fail Errors::Cast, error_message(object, body) unless Version.pattern.match? object
 
-      Version[**string_to_arguments]
+      string_to_version
     end
 
     def from_array
       body = "Use: [<major>, <minor>, <patch>], [<major>, <minor>], [<major>], or []."
-      fail Errors::Conversion, error_message(object, body) unless (0..3).cover? object.size
+      fail Errors::Cast, error_message(object, body) unless (0..3).cover? object.size
 
-      Version[**array_to_arguments]
+      Version.with_positions(*object.pad(0, max: 3))
     end
 
     def from_hash
       body = "Use: {major: <major>, minor: <minor>, patch: <patch>}, " \
              "{major: <major>, minor: <minor>}, {major: <major>}, or {}."
-      fail Errors::Conversion, error_message(object, body) unless required_keys?
+      fail Errors::Cast, error_message(object, body) unless required_keys?
 
       Version[**object]
     end
 
     def from_object
-      fail Errors::Conversion, error_message(object, "Use: String, Array, Hash, or Version.")
+      fail Errors::Cast, error_message(object, "Use: String, Array, Hash, or Version.")
     end
 
     private
 
     attr_reader :object, :filler
 
-    def string_to_arguments
-      object.split(DELIMITER)
+    def string_to_version
+      object.split(Version.delimiter)
             .map(&:to_i)
-            .then { |numbers| filler.call numbers }
-            .then { |arguments| Version.arguments(*arguments) }
-    end
-
-    def array_to_arguments
-      Version.arguments(*filler.call(object))
+            .then { |numbers| numbers.pad 0, max: 3 }
+            .then { |arguments| Version.with_positions(*arguments) }
     end
 
     def required_keys?

data/lib/versionaire/identity.rb

@@ -5,7 +5,7 @@ module Versionaire
   module Identity
     NAME = "versionaire"
     LABEL = "Versionaire"
-    VERSION = "8.4.0"
+    VERSION = "9.1.0"
     VERSION_LABEL = "#{LABEL} #{VERSION}"
   end
 end

data/lib/versionaire/version.rb

@@ -1,41 +1,47 @@
 # frozen_string_literal: true
 
-module Versionaire
-  DELIMITER = "."
+require "refinements/structs"
 
+module Versionaire
   # An immutable, semantic version value object.
   Version = Struct.new :major, :minor, :patch, keyword_init: true do
     include Comparable
 
-    def self.regex
+    using Refinements::Structs
+
+    def self.delimiter
+      "."
+    end
+
+    def self.pattern
       /
         \A(                  # Start of string and OR.
         \d*                  # Major only.
         |                    # OR pipe.
         \d+                  # Major.
-        #{DELIMITER}?        # Delimiter.
+        #{delimiter}?        # Delimiter.
         \d*                  # Minor.
-        (?:#{DELIMITER}\d+)  # Passive delimiter and patch.
+        (?:#{delimiter}\d+)  # Passive delimiter and patch.
         )\z                  # End of OR and string.
       /x
     end
 
-    def self.arguments major, minor, patch
-      Hash[members.zip [major, minor, patch]]
-    end
-
     def initialize major: 0, minor: 0, patch: 0
       super
       validate
       freeze
     end
 
+    def []= key, value
+      super(key, value).tap { validate }
+    end
+
     def + other
-      self.class.then { |klass| klass.new(**klass.arguments(*reduce(other, :+))) }
+      revalue(other.to_h) { |previous, current| previous + current }
     end
 
     def - other
-      self.class.then { |klass| klass.new(**klass.arguments(*reduce(other, :-))) }
+      revalue(other.to_h) { |previous, current| previous - current }
     end
 
     def == other
@@ -48,25 +54,26 @@ module Versionaire
       to_s <=> other.to_s
     end
 
-    def to_s
-      to_a.join DELIMITER
+    def down key, value = 1
+      revalue(key => value) { |previous, current| previous - current }
     end
 
-    alias_method :to_str, :to_s
+    def up key, value = 1
+      revalue(key => value) { |previous, current| previous + current }
+    end
 
-    def to_a
-      [major, minor, patch]
+    def to_s
+      to_a.join self.class.delimiter
     end
 
+    alias_method :to_str, :to_s
+    alias_method :values, :to_a
+
     private
 
     def validate
       fail Errors::InvalidNumber if to_a.any? { |number| !number.is_a? Integer }
       fail Errors::NegativeNumber if to_a.any?(&:negative?)
     end
-
-    def reduce other, action
-      to_a.zip(other.to_a).map { |pair| pair.reduce action }
-    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: versionaire
 version: !ruby/object:Gem::Version
-  version: 8.4.0
+  version: 9.1.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,190 +28,22 @@ cert_chain:
   2XV8FRa7/JimI07sPLC13eLY3xd/aYTi85Z782KIA4j0G8XEEWAX0ouBhlXPocZv
   QWc=
   -----END CERTIFICATE-----
-date: 2020-11-14 00:00:00.000000000 Z
+date: 2021-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler-audit
+  name: refinements
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :development
+        version: '8.0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
-- !ruby/object:Gem::Dependency
-  name: bundler-leak
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-- !ruby/object:Gem::Dependency
-  name: guard-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.7'
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.13'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.13'
-- !ruby/object:Gem::Dependency
-  name: pry-byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: reek
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '6.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.10'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.10'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.8'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.5'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.19'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.19'
+        version: '8.0'
 description:
 email:
 - brooke@alchemists.io
@@ -224,12 +56,12 @@ files:
 - LICENSE.adoc
 - README.adoc
 - lib/versionaire.rb
-- lib/versionaire/conversion.rb
+- lib/versionaire/cast.rb
 - lib/versionaire/errors/base.rb
-- lib/versionaire/errors/conversion.rb
+- lib/versionaire/errors/cast.rb
 - lib/versionaire/errors/invalid_number.rb
 - lib/versionaire/errors/negative_number.rb
-- lib/versionaire/filler.rb
+- lib/versionaire/function.rb
 - lib/versionaire/identity.rb
 - lib/versionaire/version.rb
 homepage: https://www.alchemists.io/projects/versionaire
@@ -248,14 +80,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.5
 signing_key:
 specification_version: 4
 summary: Provides an immutable, thread-safe, and semantic version type.

data/lib/versionaire/errors/conversion.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Versionaire
-  module Errors
-    # Thrown when attempting to convert (cast) an invalid primitive to a version.
-    class Conversion < Base
-    end
-  end
-end

data/lib/versionaire/filler.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Versionaire
-  class Filler
-    def initialize pad = 0, max: 2
-      @pad = pad
-      @max = max
-    end
-
-    def call array
-      array.dup.fill pad, array.size..max
-    end
-
-    private
-
-    attr_reader :pad, :max
-  end
-end