versionaire 8.6.0 → 9.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '086f0f72812f1c6dd5ae1597a8098c53513642ba6b642009dc7d33309dc87b84'
-  data.tar.gz: daad3d46b8ccd0528fe9def4a0b4bd83b6b99810b909076150edce0fe6e8efcd
+  metadata.gz: d1e1e12933915ebaa8ce2769bac22f1ead28d07902b32bcdb4801f70b724b016
+  data.tar.gz: 4c454f8f399df43ebc649010c50d9ee95f321435c96468162ab21b9abd849abb
 SHA512:
-  metadata.gz: 7958a758fc0d40c359f26a21c3f6eb9bbaf778b8dbfe82b9f798f15b5bfd5333ca1275554ea908a76a35539408578a8c9025386b14379983788e8d1ebdd47222
-  data.tar.gz: 8646bfa7633a29cf08a75231df02eb55fc04f8d0ef8fc7b7c1e77b2361b8967f508ea2caa1444367e0d3fd683537babf14d2338773965a3a17c1d5ea272fffd2
+  metadata.gz: facb53e495986112920ca938387be6448eb5bd6e6b94d1a8d5a5e3f3a9c34bbed72da9b6d2f0476b052796d61bedbbb1f27553c536792d2b72a9f81e961d4f70
+  data.tar.gz: 32ad27fbdd19b4c6d253009c025b9409ee29766f2eb0c7e158f5d2e231052b8efa661886a534c719cc0baef9b74758698831c81e49c1f7fd93d264ae7e3ffa33

data/README.adoc

@@ -128,7 +128,7 @@ 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
 
@@ -159,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
@@ -170,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
@@ -185,41 +185,118 @@ 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
 ----
 
+=== Extensions
+
+This project supports libraries which might desire native `Version` types. Each extension _must be
+explicitly required_ in order to be used since they are _optional_ by default. See below for
+details.
+
+==== OptionParser
+
+link:https://github.com/ruby/optparse[OptionParser] is one of Ruby's
+link:https://stdgems.org[default gems] which can accept additional types not native to Ruby by
+default. To extend `OptionParser` with the `Version` type, all you need to do is add these two lines
+to your implementation:
+
+. `require "versionaire/extensions/option_parser"` - This will load dependencies and register the
+  `Version` type with `OptionParser`.
+. `instance.on "--tag VERSION", Versionaire::Version` - Specifying `Versionaire::Version` as the
+  second argument will ensure `OptionParser` properly casts command line input as a `Version` type.
+
+Here's an example implementation that demonstrates full usage:
+
+[source,ruby]
+----
+require "versionaire/extensions/option_parser"
+
+options = {}
+
+parser = OptionParser.new do |instance|
+  instance.on "--tag VERSION", Versionaire::Version, "Casts to version." do |value|
+    options[:version] = value
+  end
+end
+
+parser.parse! %w[--tag 1.2.3]
+puts options
+----
+
+The above will ensure `--tag 1.2.3` is parsed as `{:version=>#<struct Versionaire::Version major=1,
+minor=2, patch=3>}` within your `options` variable. Should `OptionParser` parse an invalid version,
+you'll get a `OptionParser::InvalidArgument` instead.
+
 == Development
 
 To contribute, run:

data/lib/versionaire.rb

@@ -1,11 +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

@@ -4,9 +4,7 @@ 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
+      def Version(object) = Versionaire::Version(object)
     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/errors/invalid_number.rb

@@ -4,9 +4,7 @@ module Versionaire
   module Errors
     # Thrown when not using numbers.
     class InvalidNumber < Base
-      def initialize message = "Major, minor, and patch must be a number."
-        super message
-      end
+      def initialize(message = "Major, minor, and patch must be a number.") = super(message)
     end
   end
 end

data/lib/versionaire/extensions/option_parser.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "versionaire"
+
+OptionParser.accept Versionaire::Version do |value|
+  Versionaire::Version value
+rescue Versionaire::Errors::Base
+  raise OptionParser::InvalidArgument, value
+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,59 +23,53 @@ 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?
-      object.keys.all? { |key| Version.members.include? key }
-    end
+    def required_keys? = object.keys.all? { |key| Version.members.include? key }
 
-    def error_message object, body
-      "Invalid version conversion: #{object}. #{body}"
-    end
+    def error_message(object, body) = "Invalid version conversion: #{object}. #{body}"
   end
 
   private_constant :Converter

data/lib/versionaire/identity.rb

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

data/lib/versionaire/version.rb

@@ -1,41 +1,45 @@
 # 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 = "."
+
+    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,15 +52,14 @@ module Versionaire
       to_s <=> other.to_s
     end
 
-    def to_s
-      to_a.join DELIMITER
-    end
+    def down(key, value = 1) = revalue(key => value) { |previous, current| previous - current }
 
-    alias_method :to_str, :to_s
+    def up(key, value = 1) = revalue(key => value) { |previous, current| previous + current }
 
-    def to_a
-      [major, minor, patch]
-    end
+    def to_s = to_a.join(self.class.delimiter)
+
+    alias_method :to_str, :to_s
+    alias_method :values, :to_a
 
     private
 
@@ -64,9 +67,5 @@ module Versionaire
       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.6.0
+  version: 9.2.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -10,9 +10,9 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIIC/jCCAeagAwIBAgIBAzANBgkqhkiG9w0BAQsFADAlMSMwIQYDVQQDDBpicm9v
-  a2UvREM9YWxjaGVtaXN0cy9EQz1pbzAeFw0yMDAzMTUxNDQ1MzJaFw0yMTAzMTUx
-  NDQ1MzJaMCUxIzAhBgNVBAMMGmJyb29rZS9EQz1hbGNoZW1pc3RzL0RDPWlvMIIB
+  MIIC/jCCAeagAwIBAgIBBDANBgkqhkiG9w0BAQsFADAlMSMwIQYDVQQDDBpicm9v
+  a2UvREM9YWxjaGVtaXN0cy9EQz1pbzAeFw0yMTAzMTkxMjQ4MDZaFw0yMjAzMTkx
+  MjQ4MDZaMCUxIzAhBgNVBAMMGmJyb29rZS9EQz1hbGNoZW1pc3RzL0RDPWlvMIIB
   IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6l1qpXTiomH1RfMRloyw7MiE
   xyVx/x8Yc3EupdH7uhNaTXQGyORN6aOY//1QXXMHIZ9tW74nZLhesWMSUMYy0XhB
   brs+KkurHnc9FnEJAbG7ebGvl/ncqZt72nQvaxpDxvuCBHgJAz+8i5wl6FhLw+oT
@@ -20,16 +20,30 @@ cert_chain:
   D5vkU0YlAm1r98BymuJlcQ1qdkVEI1d48ph4kcS0S0nv1RiuyVb6TCAR3Nu3VaVq
   3fPzZKJLZBx67UvXdbdicWPiUR75elI4PXpLIic3xytaF52ZJYyKZCNZJhNwfQID
   AQABozkwNzAJBgNVHRMEAjAAMAsGA1UdDwQEAwIEsDAdBgNVHQ4EFgQU0nzow9vc
-  2CdikiiE3fJhP/gY4ggwDQYJKoZIhvcNAQELBQADggEBAIHhAlD3po4sTYqacXaQ
-  XI9jIhrfMy//2PgbHWcETtlJPBeNUbbSNBABcllUHKqYsVDlSvSmss034KSWNR8F
-  bF1GcloicyvcCC4y6IoW4it0COAcdeaaxkxiBSgKdQFpff9REnDlIKK4uQ9lLxIo
-  Y2G5xubiziKZkyfWFuSr67PIjW3Bu673D1JVBArhA1qbgQmYQcy1CkGOjo+iO8Nf
-  7u/QSfBHb+r/bXhKscDgPpnKwbUmvgO2+94zJG9KsrmIydlzYfsD09aXKx0t6Xy4
-  2XV8FRa7/JimI07sPLC13eLY3xd/aYTi85Z782KIA4j0G8XEEWAX0ouBhlXPocZv
-  QWc=
+  2CdikiiE3fJhP/gY4ggwDQYJKoZIhvcNAQELBQADggEBAEjpaOXHHp8s/7GL2qCb
+  YAs7urOLv9VHSPfQWAwaTMVnSsIf3Sw4xzISOP/mmfEPBPXtz61K5esrE/uTFtgb
+  FyjxQk2H0sEWgrRXGGNHBWQRhhEs7LP/TByoC15A0br++xLxRz4r7HBLGAWQQDpg
+  66BJ2TBVjxS6K64tKbq7+ACyrOZGgTfNHACh4M076y0x0oRf/rwBrU39/KRfuhbb
+  cm+nNCEtO35gTmZ2bVDHLGvWazi3gJt6+huQjfXTCUUG2YYBxwhu+GPdAGQPxpf9
+  lkHilIrX69jq8wMPpBhlaw2mRmeSL50Wv5u6xVBvOHhXFSP1crXM95vfLhLyRYod
+  W2A=
   -----END CERTIFICATE-----
-date: 2020-12-13 00:00:00.000000000 Z
-dependencies: []
+date: 2021-05-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: refinements
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 description:
 email:
 - brooke@alchemists.io
@@ -43,12 +57,12 @@ files:
 - README.adoc
 - lib/versionaire.rb
 - lib/versionaire/cast.rb
-- lib/versionaire/conversion.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/extensions/option_parser.rb
+- lib/versionaire/function.rb
 - lib/versionaire/identity.rb
 - lib/versionaire/version.rb
 homepage: https://www.alchemists.io/projects/versionaire
@@ -67,14 +81,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.2.0
+rubygems_version: 3.2.16
 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,19 +0,0 @@
-# frozen_string_literal: true
-
-module Versionaire
-  # Ensures an array can be filled to a certain size with default elements.
-  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