Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
bin
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.adoc

Versionaire

Features

  • Provides Semantic Versioning.

  • Provides immutable, thread-safe version instances.

  • Converts (casts) from a String, Array, Hash, or Version to a Version.

Screencasts

Screencast

Requirements

  1. Ruby.

Setup

Production

To install, run:

gem install versionaire

Add the following to your Gemfile:

gem "versionaire"

Development

To contribute, run:

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:

bin/console

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 deterimined 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

Knowning 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 (Casting)

The Versionaire::Version function is provided for explicit casting 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::Errors::Conversion exception will be thrown.

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, 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}

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)

Math

Versions can be added and subtracted from each other.

Addition

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

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 # Fails with a Versionaire::Errors::NegativeNumber

Tests

To test, run:

bundle exec rake

Versioning

Read Semantic Versioning for details. Briefly, it means:

  • Major (X.y.z) - Incremented for any backwards incompatible public API changes.

  • Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.

  • Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.

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

Read LICENSE for details.

History

Read CHANGES for details.

Credits

Engineered by Brooke Kuhlmann.

About

Provides an immutable, thread-safe, and semantic version type.

Topics

Resources

License

You can’t perform that action at this time.