Ruby doesn’t provide a primitive version type by default so Versionaire fills this gap by providing immutable and thread-safe Strict Semantic Versioning so you can leverage versions within your applications. This new Version
type behaves and feels a lot like other primitives (i.e. String
, Array
, Hash
, Proc
, etc) and can be cast/converted from other primitives.
Features
-
Provides Strict Semantic Versioning which means
<major>.<minor>.<patch>
. -
Provides immutable, thread-safe version instances.
-
Converts (casts) from a
String
,Array
,Hash
,Proc
, orVersion
to aVersion
. -
Disallows
<major>.<minor>.<patch>-<pre-release>
usage even though Semantic Versioning suggests you may use pre-release information. -
Disallows
<major>.<minor>.<patch>+<build_metadata>
usage even though Semantic Versioning suggests you may use build metadata.
Requirements
-
Ruby.
Setup
To install with security, run:
# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install versionaire --trust-policy HighSecurity
To install without security, run:
gem install versionaire
You can also add the gem directly to your project:
bundle add versionaire
Once the gem is installed, you only need to require it:
require "versionaire"
Usage
Initialization
A new version can be initialized in a variety of ways:
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
Value (#==
)
Equality is determined by the state of the object. This means that a version is equal to another version as long as all of the values (i.e. state) are equal to each other. Example:
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
Knowing this, versions can be compared against one another too:
version_a > version_b # false
version_a < version_b # true
version_a.between? version_c, version_b # true
Hash (#eql?
)
Behaves exactly as #==
.
Case (#===
)
Behaves exactly as #==
.
Identity (#equal?
)
Works like any other standard Ruby object where an object is equal only to itself.
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
Conversions
Function
Use the Versionaire::Version
function to explicitly cast to a version:
version = Versionaire::Version[major: 1]
Versionaire::Version "1.0.0"
Versionaire::Version [1, 0, 0]
Versionaire::Version major: 1, minor: 0, patch: 0
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::Error
exception will be thrown.
Refinement
Building upon the above examples, a more elegant solution is to use a refinement:
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 to reduce the amount of
typing so you don’t pollute your entire object space, like a monkey patch, while providing an idiomatic approach to casting like any other primitive.
Implicit
Implicit conversion to a String
is supported:
"1.0.0".match Versionaire::Version[major: 1] # <MatchData "1.0.0">
Explicit
Explicit conversion to a String
, Array
, Hash
, or Proc
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_proc # #<Proc:0x000000010b015b88 (lambda)>
To elaborate on procs, this means the following is possible where you might want to collect all minor verions values or make use of version information in other useful ways:
using Versionaire::Cast
version = Version "1.2.3"
version.to_proc.call :major # 1
[version, version, version].map(&:minor) # [2, 2, 2]
Inspections
You can inspect a version which is the equivalent of an escaped string representation. Example:
using Versionaire::Cast
Version("1.2.3").inspect # "\"1.2.3\""
Comparisons
All versions are comparable which means any of the operators from the Comparable
module will
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)
Bumping
Versions can be bumped to next logical version with respect current version. Example:
version = Versionaire::Version.new # #<struct Versionaire::Version major=0, minor=0, patch=0>
version.bump :major # #<struct Versionaire::Version major=1, minor=0, patch=0>
version.bump :minor # #<struct Versionaire::Version major=0, minor=1, patch=0>
version.bump :patch # #<struct Versionaire::Version major=0, minor=0, patch=1>
Versionaire::Version[major: 1, minor: 2, patch: 3].bump :major
#<struct Versionaire::Version major=2, minor=0, patch=0>
Versionaire::Version[major: 1, minor: 2, patch: 3].bump :minor
#<struct Versionaire::Version major=1, minor=3, patch=0>
Versionaire::Version[major: 1, minor: 2, patch: 3].bump :patch
#<struct Versionaire::Version major=1, minor=2, patch=4>
You’ll notice, when bumping the major or minor versions, lower precision gets zeroed out in order to provide the next logical version.
Math
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.
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"
Subtraction
Versions can be substracted from each other as long as there isn’t a negative result.
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 = Versionaire::Version[major: 1]
version_2 = Versionaire::Version[major: 5]
version_1 - version_2 # Versionaire::Error
Up
Versions can be sequentially increased or given a specific version to jump to.
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.
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::Error
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
OptionParser is one of Ruby’s 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 theVersion
type withOptionParser
. -
act.on "--tag VERSION", Versionaire::Version
: SpecifyingVersionaire::Version
as the second argument will ensureOptionParser
properly casts command line input as aVersion
type.
Here’s an example implementation that demonstrates full usage:
require "versionaire/extensions/option_parser"
= {}
parser = OptionParser.new do |act|
act.on "--tag VERSION", Versionaire::Version, "Casts to version." do |value|
[:version] = value
end
end
parser.parse %w[--tag 1.2.3]
puts
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:
git clone https://github.com/bkuhlmann/versionaire
cd versionaire
bin/setup
You can also use the IRB console for direct access to all objects:
bin/console
Tests
To test, run:
bin/rake
Credits
-
Built with Gemsmith.
-
Engineered by Brooke Kuhlmann.