Versionaire

Provides immutable, semantic versioning.

Table of Contents

• Features
• Screencasts
• Requirements
• Setup
• Usage
  • Basic
  • Math
  • Add
  • Subtract
  • Comparisons
  • Equality
  • Identity
  • Implicit Conversions
  • Explicit Conversions
  • Conversions (Casting)
• Tests
• Versioning
• Code of Conduct
• Contributions
• License
• History
• Credits

Features

• Provides Semantic Versioning.
• Provides immutable version instances.
• Provides conversions (casts) from a String, Array, Hash, or Version to a new Version.
• Provides impicit conversion to a String.
• Provides explicit conversions to a String, Array, and a Hash.

Screencasts

TBD

Requirements

1. MRI 2.3.0

Setup

For a secure install, type the following (recommended):

gem cert --add <(curl --location --silent https://www.alchemists.io/gem-public.pem)
gem install versionaire --trust-policy MediumSecurity

NOTE: A HighSecurity trust policy would be best but MediumSecurity enables signed gem verification while allowing the installation of unsigned dependencies since they are beyond the scope of this gem.

For an insecure install, type the following (not recommended):

gem install versionaire

Add the following to your Gemfile:

gem "versionaire"

Usage

Basic

A new version can be initialized in a variety of ways:

Versionaire::Version.new                                    # "0.0.0"
Versionaire::Version.new major: 1                           # "1.0.0"
Versionaire::Version.new major: 1, minor: 2                 # "1.2.0"
Versionaire::Version.new major: 1, minor: 2, maintenance: 3 # "1.2.3"

Math

Versions can be added and subtracted from each other.

Add

version_1 = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
version_2 = Versionaire::Version.new major: 2, minor: 5, maintenance: 7
version_1 + version_2 # "3.7.10"

Subtract

version_1 = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
version_2 = Versionaire::Version.new major: 1, minor: 1, maintenance: 1
version_1 - version_2 # "0.1.2"

version_1 = Versionaire::Version.new major: 1
version_2 = Versionaire::Version.new major: 5
version_1 - version_2 # Fails with a Versionaire::Errors::NegativeNumber

Comparisons

Versions can be compared against other versions:

version_1 = Versionaire::Version.new major: 1
version_2 = Versionaire::Version.new major: 5

version_1 > version_2  # false
version_1 == version_2 # false
version_1 < version_2  # true

Versions can't be compared to similar objects:

version = Versionaire::Version.new major: 1

version == "1.0.0"                              # false
version == [1, 0, 0]                            # false
version == {major: 1, minor: 0, maintenance: 0} # false

Equality

Equality is based on the values that make up the version, not identity.

version = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
identical = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
different = Versionaire::Version.new major: 3

version == version   # true
version == identical # true
version == different # false

This is the same behavior for #eql? method too.

Identity

Identity is composed of the values that make up the version plus the class:

version = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
identical = Versionaire::Version.new major: 1, minor: 2, maintenance: 3
different = Versionaire::Version.new major: 3

version.hash   # -4162833121614102126
identical.hash # -4162833121614102126
different.hash # -2082793513660996236

Implicit Conversions

Implicit conversion to a String is supported:

"1.0.0".match Versionaire::Version.new(major: 1) # <MatchData "1.0.0">

Explicit Conversions

Explicit converting 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, maintenance: 0}

Conversions (Casting)

The Versionaire::Version function is provided for explicit conversion (casting) to a new version:

version = Versionaire::Version.new major: 1

Versionaire::Version "1.0.0"
Versionaire::Version [1, 0, 0]
Versionaire::Version major: 1, minor: 0, maintenance: 0
Versionaire::Version version

Each of these conversions will result in a new version object that is equal to "1.0.0". When attempting to convert an unsupported type, a Versionaire::Errors::Conversion exception will be thrown.

Tests

To test, run:

bundle exec rake

Versioning

Read Semantic Versioning for details. Briefly, it means:

• Patch (x.y.Z) - Incremented for small, backwards compatible bug fixes.
• Minor (x.Y.z) - Incremented for new, backwards compatible public API enhancements and/or bug fixes.
• Major (X.y.z) - Incremented for any backwards incompatible public API changes.

Code of Conduct

Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.

Contributions

Read CONTRIBUTING for details.

License

Copyright (c) 2016 Alchemists. Read the LICENSE for details.

History

Read the CHANGELOG for details. Built with Gemsmith.

Credits

Developed by Brooke Kuhlmann at Alchemists.