versionaire 8.2.0 → 8.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7856bdc9290014c751c767f1534b7f492ebeb33aed4838f2dc84277428f3796
-  data.tar.gz: 23d02f9d4a7fb583762ba481492f5681f2111b560c57659537aa1630412ad4b6
+  metadata.gz: b41a84e38c6e7d73b9ecc460bb8bbecc5d763aa11a05cac1021d16d8b3e17235
+  data.tar.gz: 10e14aeb64f4ca5c92eb559a594627bef37d03abb05d1029d417ce32c7b71ea0
 SHA512:
-  metadata.gz: bbd73613229106b44da7f64103b86baf799d2e3f32cc8c4e5f93bc73fae66bf52ed71e0ef52f858d60cb2e92c2da6c2b541c3b02d97d5e23319905194199bb47
-  data.tar.gz: cb202da5b41d341454c5adeea9bf7070270ad39db9ad900661285e2121191bbb7b98655650bfdfd576cacb546249e270c73b791e66672d53e5544510ee05a31f
+  metadata.gz: 5673376e2e87acee93d11e1ef4283d18bd89fea650c9fd77018263ad3a7a1e9f9041139f38d69c881540a4810eb0035dd307c5343a2dfc114d564d47c7825af1
+  data.tar.gz: 88cc980f9c39af47d3443d3348894e8189487c378a402c537e6565d53cb1f18f753892fcec26c7f41274d6bc1a4ea2b1d902708e12c6b68eed029b8f0c6caa96

data/LICENSE.adoc

@@ -150,7 +150,7 @@ additional liability.
 
 END OF TERMS AND CONDITIONS
 
-Copyright link:https://www.alchemists.io[Alchemists].
+Copyright 2016 link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
 
 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 link:https://www.apache.org/licenses/LICENSE-2.0[copy]

data/README.adoc

@@ -6,6 +6,8 @@
 
 [link=http://badge.fury.io/rb/versionaire]
 image::https://badge.fury.io/rb/versionaire.svg[Gem Version]
+[link=https://www.alchemists.io/projects/code_quality]
+image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
 [link=https://circleci.com/gh/bkuhlmann/versionaire]
 image::https://circleci.com/gh/bkuhlmann/versionaire.svg?style=svg[Circle CI Status]
 
@@ -31,8 +33,6 @@ image::https://www.alchemists.io/images/screencasts/versionaire/cover.svg[Screen
 
 == Setup
 
-=== Production
-
 To install, run:
 
 [source,bash]
@@ -47,24 +47,6 @@ Add the following to your Gemfile:
 gem "versionaire"
 ----
 
-=== Development
-
-To contribute, run:
-
-[source,bash]
-----
-git clone https://github.com/bkuhlmann/versionaire.git
-cd versionaire
-bin/setup
-----
-
-You can also use the IRB console for direct access to all objects:
-
-[source,bash]
-----
-bin/console
-----
-
 == Usage
 
 === Initialization
@@ -73,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
@@ -92,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?`)
@@ -124,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]
 ----
@@ -148,13 +130,36 @@ 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.
 
+==== 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
 
 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
@@ -165,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
@@ -180,39 +185,94 @@ 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
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/versionaire.git
+cd versionaire
+bin/setup
+----
+
+You can also use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
 ----
 
 == Tests

data/lib/versionaire.rb

@@ -8,3 +8,4 @@ require "versionaire/filler"
 require "versionaire/conversion"
 require "versionaire/identity"
 require "versionaire/version"
+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/conversion.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "refinements/arrays"
+require "refinements/structs"
+
 # The gem namespace.
 module Versionaire
   module_function
@@ -20,23 +23,25 @@ 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
 
-      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
 
-      Version[**array_to_arguments]
+      Version.with_positions(*object.pad(0, max: 3))
     end
 
     def from_hash
@@ -55,15 +60,11 @@ module Versionaire
 
     attr_reader :object, :filler
 
-    def string_to_arguments
+    def string_to_version
       object.split(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/errors/invalid_number.rb

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

data/lib/versionaire/errors/negative_number.rb

@@ -5,7 +5,7 @@ module Versionaire
     # Thrown when numbers are negative.
     class NegativeNumber < Base
       def initialize message = "Major, minor, and patch must be a positive number."
-        super
+        super message
       end
     end
   end

data/lib/versionaire/filler.rb

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

data/lib/versionaire/identity.rb

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

data/lib/versionaire/version.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
+require "refinements/structs"
+
 module Versionaire
   DELIMITER = "."
 
   # An immutable, semantic version value object.
-  # rubocop:disable Metrics/BlockLength
   Version = Struct.new :major, :minor, :patch, keyword_init: true do
     include Comparable
 
+    using Refinements::Structs
+
     def self.regex
       /
         \A(                  # Start of string and OR.
@@ -31,12 +34,16 @@ module Versionaire
       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
@@ -49,15 +56,20 @@ module Versionaire
       to_s <=> other.to_s
     end
 
+    def down key, value = 1
+      revalue(key => value) { |previous, current| previous - current }
+    end
+
+    def up key, value = 1
+      revalue(key => value) { |previous, current| previous + current }
+    end
+
     def to_s
       to_a.join DELIMITER
     end
 
     alias_method :to_str, :to_s
-
-    def to_a
-      [major, minor, patch]
-    end
+    alias_method :values, :to_a
 
     private
 
@@ -65,10 +77,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
-  # rubocop:enable Metrics/BlockLength
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: versionaire
 version: !ruby/object:Gem::Version
-  version: 8.2.0
+  version: 8.7.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,204 +28,22 @@ cert_chain:
   2XV8FRa7/JimI07sPLC13eLY3xd/aYTi85Z782KIA4j0G8XEEWAX0ouBhlXPocZv
   QWc=
   -----END CERTIFICATE-----
-date: 2020-07-23 00:00:00.000000000 Z
+date: 2020-12-21 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.6'
-  type: :development
+        version: '7.18'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
-- !ruby/object:Gem::Dependency
-  name: gemsmith
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '14.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '14.2'
-- !ruby/object:Gem::Dependency
-  name: git-lint
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !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.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.9'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.83'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.83'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-- !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: '1.39'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.39'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.18'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '7.18'
 description:
 email:
 - brooke@alchemists.io
@@ -238,6 +56,7 @@ files:
 - LICENSE.adoc
 - README.adoc
 - lib/versionaire.rb
+- lib/versionaire/cast.rb
 - lib/versionaire/conversion.rb
 - lib/versionaire/errors/base.rb
 - lib/versionaire/errors/conversion.rb
@@ -269,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.2
 signing_key:
 specification_version: 4
 summary: Provides an immutable, thread-safe, and semantic version type.