qb 0.3.7 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a666712edbad3cabb581a2f91202b3d25448d9df
-  data.tar.gz: 0f396ef64b4ec6986705ba766ec8274e8c73c43f
+  metadata.gz: fbc3b61137b1ac315d4a59b946216ffc49a698c5
+  data.tar.gz: 382fa7a1f0d99d90adfef8421811464811ecb855
 SHA512:
-  metadata.gz: cd24c18f6efb9a5725062494fc7d50336380a6bd9f17808db5dfe12c8b2d9ac1dfb03e9ba1a114509a3c3f6846d8549129a1d8b7bb54dc14981ab31bc5d59b0d
-  data.tar.gz: 0d1b2fd63fa86988cb3aff0deed0103a18b328f1f39c4906775b98443d1e9adb0028c8586c052cab90a4b168fd0ecced313cbc822e7955f0f7a1812fae8c6572
+  metadata.gz: 2399c2e4af9def73a5589e91a005aff11085663fe388d16010f2eb1684b36073faed4c778958056a4b63f84e107e810b43141723b01c18980e97805a301f8808
+  data.tar.gz: ef7ef9dd5b12cd9c8aab404a5ede52e5afdb642b1a4205c8f1a5fdc0ea45aa60aee2f9ef7c3bcbdb11177a37739804635aeb550a13b74da2a18ae455481449bf

data/lib/qb.rb

@@ -3,7 +3,7 @@ require 'nrser/extras'
 require_relative './qb/errors'
 require_relative './qb/version'
 require_relative './qb/util'
-require_relative './qb/ansible_module'
+require_relative './qb/path'
 
 module QB
   ROOT = (Pathname.new(__FILE__).dirname + '..').expand_path
@@ -38,6 +38,12 @@ end
 # needs QB::*_ROLES_DIR
 require 'qb/role'
 require 'qb/options'
-require_relative './qb/repo'
-require_relative './qb/cli'
-require_relative './qb/ansible'
+require 'qb/repo'
+require 'qb/cli'
+
+require 'qb/ansible'
+# Depreciated namespace:
+require 'qb/ansible_module'
+
+require 'qb/package'
+

data/lib/qb/package.rb

@@ -0,0 +1,102 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'qb/util/resource'
+
+require_relative './package/version'
+
+
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements'
+using NRSER
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+
+# Declarations
+# =======================================================================
+
+module QB; end
+
+
+# Definitions
+# =======================================================================
+
+# Common properties and methods of package resources, aimed at packages
+# represented as directories in projects.
+# 
+class QB::Package < QB::Util::Resource
+  
+  # Constants
+  # ======================================================================
+  
+  
+  # Class Methods
+  # ======================================================================
+  
+  
+  # Properties
+  # ======================================================================
+  
+  # @!attribute [r] ref_path
+  #   User-provided path value used to construct the resource instance, if any.
+  #   
+  #   This may not be the same as a root path for the resource, such as with
+  #   resource classes that can be constructed from any path *inside* the 
+  #   directory, like a {QB::Repo::Git}.
+  #   
+  #   @return [String | Pathname]
+  #     If the resource instance was constructed based on a path argument.
+  #   
+  #   @return [nil]
+  #     If the resource instance was *not* constructed based on a path 
+  #     argument.
+  #   
+  prop  :ref_path, type: t.maybe( t.dir_path )
+  
+  
+  # @!attribute [r] root_path
+  #   Absolute path to the gem's root directory.
+  #   
+  #   @return [Pathname]
+  #   
+  prop  :root_path, type: t.dir_path
+  
+  
+  # @!attribute [r] version
+  #   Version of the package.
+  # 
+  #   @return [QB::Package::Version]
+  # 
+  prop  :version, type: QB::Package::Version
+  
+  
+  # @!attribute [r] name
+  #   The string name the package goes by.
+  # 
+  #   @return [String]
+  #     Non-empty string.
+  # 
+  prop  :name, type: t.non_empty_str
+  
+  
+end # class QB::Package
+
+
+# Post-Processing
+# =======================================================================
+
+require_relative './package/gem'
+

data/lib/qb/package/gem.rb

@@ -0,0 +1,153 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'qb/package'
+
+
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements'
+using NRSER
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+# Package resource for a Ruby Gem.
+# 
+class QB::Package::Gem < QB::Package
+  
+  # Constants
+  # ======================================================================
+  
+  
+  # Eigenclass (Singleton Class)
+  # ========================================================================
+  # 
+  class << self
+    
+    # Find the only `*.gemspec` path in the `root_path` Gem directory.
+    # 
+    # @param [String | Pathname] root_path
+    #   Path to the gem's root directory.
+    # 
+    def gemspec_path root_path
+      paths = Pathname.glob( root_path.to_pn / '*.gemspec' )
+      
+      case paths.length
+      when 0
+        nil
+      when 1
+        paths[0]
+      else
+        nil
+      end
+    end # #gemspec_path
+    
+    
+    # @todo Document from_path method.
+    # 
+    # @param [String | Pathname] path
+    #   Path to gem root directory.
+    # 
+    # @return [QB::Package::Gem]
+    #   If `path` is the root directory of a Ruby gem.
+    # 
+    # @return [nil]
+    #   If `path` is not the root directory of a Ruby gem.
+    # 
+    # @raise [QB::FSStateError]
+    #   If `path` is not a directory.
+    #     
+    def from_root_path path
+      # Values we will use to construct the resource instance.
+      values = {}
+      
+      # Whatever we were passes is the reference path
+      values[:ref_path] = path
+      
+      # Cast to {Pathname} if it's not already and expand it to create the 
+      # root path
+      values[:root_path] = path.to_pn.expand_path
+      
+      # Check that we're working with a directory, returning `nil` if we're not
+      return nil unless values[:root_path].directory?
+      
+      # Get the path to the (single) Gemspec file.
+      values[:gemspec_path] = self.gemspec_path values[:root_path]
+      
+      # Check that we got it, returning `nil` if we don't
+      return nil if values[:gemspec_path].nil?
+      
+      # Load up the gemspec ad version
+      values[:spec] = ::Gem::Specification::load values[:gemspec_path].to_s
+      
+      # Get the name from the spec
+      values[:name] = values[:spec].name
+      
+      # Get the version from the spec
+      values[:version] = QB::Package::Version.from_gem_version \
+        values[:spec].version
+      
+      # Construct the resource instance and return it.
+      new **values
+    end # #from_root_path
+    
+    
+    # Like {.from_root_path} but raises an error if the path is not a gem
+    # root directory.
+    # 
+    # @param path see .from_root_path
+    # 
+    # @return [QB::Package::Gem]
+    # 
+    # @raise [QB::FSStateError]
+    #   -   If `path` is not a directory.
+    #       
+    #   -   If `path` is not a Gem directory.
+    # 
+    def from_root_path! path
+      from_root_path( path ).tap { |gem|
+        if gem.nil?
+          raise QB::FSStateError.squished <<-END
+            Path #{ path.inspect } does not appear to be the root directory
+            of a Ruby gem.
+          END
+        end
+      }
+    end # #from_root_path!
+    
+    
+    
+  end # class << self (Eigenclass)
+  
+  
+  # Properties
+  # =====================================================================
+  
+  # Principle Properties
+  # ---------------------------------------------------------------------
+  
+  prop  :gemspec_path,
+        type: t.file_path
+        
+  prop  :spec,
+        type: ::Gem::Specification
+  
+  
+  # Instance Methods
+  # ======================================================================
+  
+end # class QB::Package::Gem

data/lib/qb/package/version.rb

@@ -1,434 +1,457 @@
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
 require 'time'
 
-require 'nrser/refinements/types'
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'qb/util/docker_mixin'
+require 'qb/util/resource'
+
+
+# Refinements
+# =======================================================================
 
+require 'nrser/refinements/types'
 using NRSER::Types
 
-require 'qb/util/docker_mixin'
 
-module QB
-  module Package
-    # An attempt to unify NPM and Gem version schemes to a reasonable extend, 
-    # and hopefully cover whatever else the cat may drag in.
-    # 
-    # Intended to be immutable for practical purposes.
-    # 
-    class Version < NRSER::Meta::Props::Base
-      
-      # Mixins
-      # =====================================================================
-      
-      include QB::Util::DockerMixin
-      
-      
-      # Constants
-      # =====================================================================
-      
-      NUMBER_SEGMENT = t.non_neg_int
-      NAME_SEGMENT = t.str
-      MIXED_SEGMENT = t.union NUMBER_SEGMENT, NAME_SEGMENT
-      
-      
-      # Props
-      # =====================================================================
+# Declarations
+# =======================================================================
 
-      prop :raw,            type: t.maybe(t.str),         default: nil
-      prop :major,          type: NUMBER_SEGMENT
-      prop :minor,          type: NUMBER_SEGMENT,         default: 0
-      prop :patch,          type: NUMBER_SEGMENT,         default: 0
-      prop :prerelease,     type: t.array(MIXED_SEGMENT), default: []
-      prop :build,          type: t.array(MIXED_SEGMENT), default: []
+module QB; end
+class QB::Package < QB::Util::Resource; end
 
-      prop :release,        type: t.str,            source: :@release
-      prop :level,          type: t.str,            source: :@level
-      prop :is_release,     type: t.bool,           source: :release?
-      prop :is_prerelease,  type: t.bool,           source: :prerelease?
-      prop :is_build,       type: t.bool,           source: :build?
-      prop :is_dev,         type: t.bool,           source: :dev?
-      prop :is_rc,          type: t.bool,           source: :rc?
-      prop :has_level,      type: t.bool,           source: :level?
-      prop :semver,         type: t.str,            source: :semver
-      prop :docker_tag,     type: t.str,            source: :docker_tag
-      prop :build_commit,   type: t.maybe(t.str),   source: :build_commit
-      prop :is_build_dirty, type: t.maybe(t.bool),  source: :build_dirty?
 
+# Definitions
+# =======================================================================
 
-      # Attributes
-      # =====================================================================
+# An attempt to unify NPM and Gem version schemes to a reasonable extend, 
+# and hopefully cover whatever else the cat may drag in.
+# 
+# Intended to be immutable for practical purposes.
+# 
+class QB::Package::Version < QB::Util::Resource
+  
+  # Mixins
+  # =====================================================================
+  
+  include QB::Util::DockerMixin
+  
+  
+  # Constants
+  # =====================================================================
+  
+  NUMBER_SEGMENT = t.non_neg_int
+  NAME_SEGMENT = t.str
+  MIXED_SEGMENT = t.union NUMBER_SEGMENT, NAME_SEGMENT
+  
+  
+  # Props
+  # =====================================================================
 
-      attr_reader :release,
-                  :level
-      
-      
-      # Class Methods
-      # =====================================================================
-      
-      # Utilities
-      # ---------------------------------------------------------------------
-      
-      # @return [String]
-      #   Time formatted to be stuck in a version segment per Semver spec.
-      #   We also strip out '-' to avoid possible parsing weirdness.
-      def self.to_time_segment time
-        time.utc.iso8601.gsub /[^0-9A-Za-z]/, ''
-      end
-      
-      
-      # Instance Builders
-      # ---------------------------------------------------------------------
-      
-      # Create a Version instance from a Gem::Version
-      def self.from_gem_version version
-        # release segments are everything before a string
-        release_segments = version.segments.take_while { |seg|
-          !seg.is_a?(String)
-        }
-        
-        # We don't support > 3 release segments to make life somewhat
-        # reasonable. Yeah, I think I've seen projects do it. We'll cross that
-        # bridge if and when we get to it.
-        if release_segments.length > 3
-          raise ArgumentError,
-                "We don't handle releases with more than 3 segments " +
-                "(found #{ release_segments.inspect } in #{ version })"
-        end
-        
-        prerelease_segments = version.segments[release_segments.length..-1]
-        
-        new raw: version.to_s,
-            major: release_segments[0] || 0,
-            minor: release_segments[1] || 0,
-            patch: release_segments[2] || 0,
-            prerelease: prerelease_segments,
-            build: []
-      end
-      
-      def self.from_npm_version version
-        stmt = NRSER.squish <<-END
-          var Semver = require('semver');
-          
-          console.log(
-            JSON.stringify(
-              Semver(#{ JSON.dump version })
-            )
-          );
-        END
-        
-        parse = JSON.load Cmds.new(
-          "node --eval %s", args: [stmt], chdir: QB::ROOT
-        ).out!
-        
-        new raw: version,
-            major: parse['major'],
-            minor: parse['minor'],
-            patch: parse['patch'],
-            prerelease: parse['prerelease'],
-            build: parse['build']
-      end
-      
-      
-      # Parse Docker image tag version into a string. Reverse of 
-      # {QB::Package::Version#docker_tag}.
-      # 
-      # @param [String] version
-      #   String version to parse.
-      # 
-      # @return [QB::Package::Version]
-      # 
-      def self.from_docker_tag version
-        from_string(version.gsub('_', '+')).merge raw: version
-      end # .from_docker_tag
-      
-      
-      
-      # Parse string version into an instance. Accept Semver, Ruby Gem and 
-      # Docker image tag formats.
-      # 
-      # @param [String]
-      #   String version to parse.
-      # 
-      # @return [QB::Package::Version]
-      # 
-      def self.from_string string
-        if string.include? '_'
-          self.from_docker_tag string
-        elsif string.include?( '-' ) || string.include?( '+' )
-          self.from_npm_version string
-        else
-          self.from_gem_version Gem::Version.new(string)
-        end
-      end
-      
-      
-      # Constructor
-      # =====================================================================
-      
-      # Construct a new Version
-      def initialize **values
-        super **values
-        
-        @release = [major, minor, patch].join '.'
-        
-        @level = t.match prerelease[0], {
-          t.is(nil) => ->(_) {
-            if build.empty?
-              'release'
-            end
-          },
-          
-          NAME_SEGMENT => ->(str) { str },
-          
-          NUMBER_SEGMENT => ->(int) { nil },
-        }
-      end
-      
-      
-      # Instance Methods
-      # =====================================================================
-      
-      # Tests
-      # ---------------------------------------------------------------------
-      
-      # @return [Boolean]
-      #   True if this version is a release (no prerelease or build values).
-      # 
-      def release?
-        prerelease.empty? && build.empty?
-      end
-      
-      
-      # @return [Boolean]
-      #   True if any prerelease segments are present (stuff after '-' in 
-      #   SemVer / "NPM" format, or the first string segment and anything
-      #   following it in "Gem" format). Tests if {@prerelease} is not
-      #   empty.
-      # 
-      def prerelease?
-        !prerelease.empty?
-      end
-      
-      
-      # @return [Boolean]
-      #   True if any build segments are present (stuff after '+' character
-      #   in SemVer / "NPM" format). Tests if {@build} is empty.
-      #   
-      #   As of writing, we don't have a way to convey build segments in 
-      #  "Gem" version format, so this will always be false when loading a 
-      #   Gem version.
-      # 
-      def build?
-        !build.empty?
-      end
-      
-      
-      
-      # @todo Document build_dirty? method.
-      # 
-      # @param [type] arg_name
-      #   @todo Add name param description.
-      # 
-      # @return [return_type]
-      #   @todo Document return value.
-      # 
-      def build_dirty?
-        if build?
-          build.include? 'dirty'
-        end
-      end # #build_dirty?
-      
-      
-      
-      # @return [Boolean]
-      #   True if self is a prerelease version that starts with a string that
-      #   we consider the 'level'.
-      #   
-      def level?
-        !level.nil?
-      end
-      
-      
-      # @return [Boolean]
-      #   True if this version is a dev prerelease (first prerelease element 
-      #   is 'dev').
-      # 
-      def dev?
-        level == 'dev'
-      end
-      
-      
-      # @return [Boolean]
-      #   True if this version is a release candidate (first prerelease element
-      #   is 'rc').
-      # 
-      def rc?
-        level == 'rc'
-      end
-      
-      
-      # Derived Properties
-      # ---------------------------------------------------------------------
-      
-      # @return [String]
-      #   The Semver version string
-      #   (`Major.minor.patch-prerelease+build` format).
-      # 
-      def semver
-        result = release
-        
-        unless prerelease.empty?
-          result += "-#{ prerelease.join '.' }"
-        end
-        
-        unless build.empty?
-          result += "+#{ build.join '.' }"
-        end
-        
-        result
-      end # #semver
-      
-      alias_method :normalized, :semver
-      
-      
-      # @todo Document commit method.
-      # 
-      # @param [type] arg_name
-      #   @todo Add name param description.
-      # 
-      # @return [return_type]
-      #   @todo Document return value.
-      # 
-      def build_commit
-        if build?
-          build.find { |seg| seg =~ /[0-9a-f]{7}/ }
-        end
-      end # #commit
-      
-      
-      # Docker image tag for the version.
-      # 
-      # See {QB::Util::DockerMixin::ClassMethods#to_docker_tag}.
-      # 
-      # @return [String]
-      #   
-      def docker_tag
-        self.class.to_docker_tag semver
-      end # #docker_tag
-      
-      
-      # Related Versions
-      # ---------------------------------------------------------------------
-      # 
-      # Functions that construct new version instances based on the current 
-      # one as well as additional information provided.
-      # 
-      
-      # @return [QB::Package::Version]
-      #   A new {QB::Package::Version} created from {#release}. Even if `self`
-      #   *is* a release version already, still returns a new instance.
-      # 
-      def release_version
-        self.class.from_string release
-      end # #release_version
-      
-      
-      # Return a new {QB::Package::Version} with build information added.
-      # 
-      # @return [QB::Package::Version]
-      # 
-      def build_version branch: nil, ref: nil, time: nil, dirty: nil
-        time = self.class.to_time_segment(time) unless time.nil?
-        
-        segments = [
-          branch,
-          ref,
-          ('dirty' if dirty),
-          time,
-        ].reject &:nil?
-        
-        if segments.empty?
-          raise ArgumentError,
-                "Need to provide at least one of branch, ref, time."
+  prop :raw,            type: t.maybe(t.str),         default: nil
+  prop :major,          type: NUMBER_SEGMENT
+  prop :minor,          type: NUMBER_SEGMENT,         default: 0
+  prop :patch,          type: NUMBER_SEGMENT,         default: 0
+  prop :prerelease,     type: t.array(MIXED_SEGMENT), default: []
+  prop :build,          type: t.array(MIXED_SEGMENT), default: []
+
+  prop :release,        type: t.str,            source: :@release
+  prop :level,          type: t.str,            source: :@level
+  prop :is_release,     type: t.bool,           source: :release?
+  prop :is_prerelease,  type: t.bool,           source: :prerelease?
+  prop :is_build,       type: t.bool,           source: :build?
+  prop :is_dev,         type: t.bool,           source: :dev?
+  prop :is_rc,          type: t.bool,           source: :rc?
+  prop :has_level,      type: t.bool,           source: :level?
+  prop :semver,         type: t.str,            source: :semver
+  prop :docker_tag,     type: t.str,            source: :docker_tag
+  prop :build_commit,   type: t.maybe(t.str),   source: :build_commit
+  prop :is_build_dirty, type: t.maybe(t.bool),  source: :build_dirty?
+
+
+  # Attributes
+  # =====================================================================
+
+  attr_reader :release,
+              :level
+  
+  
+  # Class Methods
+  # =====================================================================
+  
+  # Utilities
+  # ---------------------------------------------------------------------
+  
+  # @return [String]
+  #   Time formatted to be stuck in a version segment per Semver spec.
+  #   We also strip out '-' to avoid possible parsing weirdness.
+  def self.to_time_segment time
+    time.utc.iso8601.gsub /[^0-9A-Za-z]/, ''
+  end
+  
+  
+  # Instance Builders
+  # ---------------------------------------------------------------------
+  
+  # Create a Version instance from a {Gem::Version}.
+  # 
+  # @param [Gem::Version] version
+  # 
+  # @return [QB::Package::Version]
+  # 
+  def self.from_gem_version version
+    # release segments are everything before a string
+    release_segments = version.segments.take_while { |seg|
+      !seg.is_a?(String)
+    }
+    
+    # We don't support > 3 release segments to make life somewhat
+    # reasonable. Yeah, I think I've seen projects do it. We'll cross that
+    # bridge if and when we get to it.
+    if release_segments.length > 3
+      raise ArgumentError,
+            "We don't handle releases with more than 3 segments " +
+            "(found #{ release_segments.inspect } in #{ version })"
+    end
+    
+    prerelease_segments = version.segments[release_segments.length..-1]
+    
+    new raw: version.to_s,
+        major: release_segments[0] || 0,
+        minor: release_segments[1] || 0,
+        patch: release_segments[2] || 0,
+        prerelease: prerelease_segments,
+        build: []
+  end
+  
+  def self.from_npm_version version
+    stmt = NRSER.squish <<-END
+      var Semver = require('semver');
+      
+      console.log(
+        JSON.stringify(
+          Semver(#{ JSON.dump version })
+        )
+      );
+    END
+    
+    parse = JSON.load Cmds.new(
+      "node --eval %s", args: [stmt], chdir: QB::ROOT
+    ).out!
+    
+    new raw: version,
+        major: parse['major'],
+        minor: parse['minor'],
+        patch: parse['patch'],
+        prerelease: parse['prerelease'],
+        build: parse['build']
+  end
+  
+  
+  # Parse Docker image tag version into a string. Reverse of 
+  # {QB::Package::Version#docker_tag}.
+  # 
+  # @param [String] version
+  #   String version to parse.
+  # 
+  # @return [QB::Package::Version]
+  # 
+  def self.from_docker_tag version
+    from_string(version.gsub('_', '+')).merge raw: version
+  end # .from_docker_tag
+  
+  
+  # Parse string version into an instance. Accept Semver, Ruby Gem and 
+  # Docker image tag formats.
+  # 
+  # @param [String]
+  #   String version to parse.
+  # 
+  # @return [QB::Package::Version]
+  # 
+  def self.from_string string
+    if string.include? '_'
+      self.from_docker_tag string
+    elsif string.include?( '-' ) || string.include?( '+' )
+      self.from_npm_version string
+    else
+      self.from_gem_version Gem::Version.new(string)
+    end
+  end
+  
+  
+  # Constructor
+  # =====================================================================
+  
+  # Construct a new Version
+  def initialize **values
+    super **values
+    
+    @release = [major, minor, patch].join '.'
+    
+    @level = t.match prerelease[0], {
+      t.is(nil) => ->(_) {
+        if build.empty?
+          'release'
         end
-        
-        merge raw: nil, build: segments
-      end
-      
-      
-      # @return [QB::Package::Version]
-      #   A new {QB::Package::Version} created from {#release} and
-      #   {#prerelease} data, but without any build information.
-      # 
-      def prerelease_version
-        merge raw: nil, build: []
-      end # #prerelease_version
-      
-      
-      
-      # Language Interface
-      # =====================================================================
-      
-      # Test for equality.
-      # 
-      # Compares classes then {QB::Package::Version#to_a} results.
-      # 
-      # @param [Object] other
-      #   Object to compare to self.
-      # 
-      # @return [Boolean]
-      #   True if self and other are considered equal.
-      # 
-      def == other
-        other.class == self.class &&
-        other.to_a == self.to_a 
-      end # #==
-      
-      
-      # Return array of the version elements in order from greatest to least
-      # precedence.
-      # 
-      # This is considered the representative structure for the object's data,
-      # from which all other values are dependently derived, and is used in 
-      # {#==}, {#hash} and {#eql?}.
-      # 
-      # @example
-      #   
-      #   version = QB::Package::Version.from_string(
-      #     "0.1.2-rc.10+master.0ab1c3d"
-      #   )
-      #   
-      #   version.to_a
-      #   # => [0, 1, 2, ['rc', 10], ['master', '0ab1c3d']]
-      #   
-      #   QB::Package::Version.from_string('1').to_a
-      #   # => [1, nil, nil, [], []]
-      # 
-      # @return [Array]
-      # 
-      def to_a
-        [
-          major,
-          minor,
-          patch,
-          prerelease,
-          build,
-        ]
-      end # #to_a
-      
-      
-      def hash
-        to_a.hash
-      end
-      
-      
-      def eql? other
-        self == other && self.hash == other.hash
-      end
-      
-      
-      def to_s
-        "#<QB::Package::Version #{ @raw }>"
-      end
-      
-    end # class Version
-  end # Package
-end # QB
+      },
+      
+      NAME_SEGMENT => ->(str) { str },
+      
+      NUMBER_SEGMENT => ->(int) { nil },
+    }
+  end
+  
+  
+  # Instance Methods
+  # =====================================================================
+  
+  # Tests
+  # ---------------------------------------------------------------------
+  
+  # @return [Boolean]
+  #   True if this version is a release (no prerelease or build values).
+  # 
+  def release?
+    prerelease.empty? && build.empty?
+  end
+  
+  
+  # @return [Boolean]
+  #   True if any prerelease segments are present (stuff after '-' in 
+  #   SemVer / "NPM" format, or the first string segment and anything
+  #   following it in "Gem" format). Tests if {@prerelease} is not
+  #   empty.
+  # 
+  def prerelease?
+    !prerelease.empty?
+  end
+  
+  
+  # @return [Boolean]
+  #   True if any build segments are present (stuff after '+' character
+  #   in SemVer / "NPM" format). Tests if {@build} is empty.
+  #   
+  #   As of writing, we don't have a way to convey build segments in 
+  #  "Gem" version format, so this will always be false when loading a 
+  #   Gem version.
+  # 
+  def build?
+    !build.empty?
+  end
+  
+  
+  # @todo Document build_dirty? method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def build_dirty?
+    if build?
+      build.include? 'dirty'
+    end
+  end # #build_dirty?
+  
+  
+  # @return [Boolean]
+  #   True if self is a prerelease version that starts with a string that
+  #   we consider the 'level'.
+  #   
+  def level?
+    !level.nil?
+  end
+  
+  
+  # @return [Boolean]
+  #   True if this version is a dev prerelease (first prerelease element 
+  #   is 'dev').
+  # 
+  def dev?
+    level == 'dev'
+  end
+  
+  
+  # @return [Boolean]
+  #   True if this version is a release candidate (first prerelease element
+  #   is 'rc').
+  # 
+  def rc?
+    level == 'rc'
+  end
+  
+  
+  # Derived Properties
+  # ---------------------------------------------------------------------
+  
+  # @return [String]
+  #   The Semver version string
+  #   (`Major.minor.patch-prerelease+build` format).
+  # 
+  def semver
+    result = release
+    
+    unless prerelease.empty?
+      result += "-#{ prerelease.join '.' }"
+    end
+    
+    unless build.empty?
+      result += "+#{ build.join '.' }"
+    end
+    
+    result
+  end # #semver
+  
+  alias_method :normalized, :semver
+  
+  
+  # @todo Document commit method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def build_commit
+    if build?
+      build.find { |seg| seg =~ /[0-9a-f]{7}/ }
+    end
+  end # #commit
+  
+  
+  # Docker image tag for the version.
+  # 
+  # See {QB::Util::DockerMixin::ClassMethods#to_docker_tag}.
+  # 
+  # @return [String]
+  #   
+  def docker_tag
+    self.class.to_docker_tag semver
+  end # #docker_tag
+  
+  
+  # Related Versions
+  # ---------------------------------------------------------------------
+  # 
+  # Functions that construct new version instances based on the current 
+  # one as well as additional information provided.
+  # 
+  
+  # @return [QB::Package::Version]
+  #   A new {QB::Package::Version} created from {#release}. Even if `self`
+  #   *is* a release version already, still returns a new instance.
+  # 
+  def release_version
+    self.class.from_string release
+  end # #release_version
+  
+  
+  # Return a new {QB::Package::Version} with build information added.
+  # 
+  # @return [QB::Package::Version]
+  # 
+  def build_version branch: nil, ref: nil, time: nil, dirty: nil
+    time = self.class.to_time_segment(time) unless time.nil?
+    
+    segments = [
+      branch,
+      ref,
+      ('dirty' if dirty),
+      time,
+    ].reject &:nil?
+    
+    if segments.empty?
+      raise ArgumentError,
+            "Need to provide at least one of branch, ref, time."
+    end
+    
+    merge raw: nil, build: segments
+  end
+  
+  
+  # @return [QB::Package::Version]
+  #   A new {QB::Package::Version} created from {#release} and
+  #   {#prerelease} data, but without any build information.
+  # 
+  def prerelease_version
+    merge raw: nil, build: []
+  end # #prerelease_version
+  
+  
+  
+  # Language Interface
+  # =====================================================================
+  
+  # Test for equality.
+  # 
+  # Compares classes then {QB::Package::Version#to_a} results.
+  # 
+  # @param [Object] other
+  #   Object to compare to self.
+  # 
+  # @return [Boolean]
+  #   True if self and other are considered equal.
+  # 
+  def == other
+    other.class == self.class &&
+    other.to_a == self.to_a 
+  end # #==
+  
+  
+  # Return array of the version elements in order from greatest to least
+  # precedence.
+  # 
+  # This is considered the representative structure for the object's data,
+  # from which all other values are dependently derived, and is used in 
+  # {#==}, {#hash} and {#eql?}.
+  # 
+  # @example
+  #   
+  #   version = QB::Package::Version.from_string(
+  #     "0.1.2-rc.10+master.0ab1c3d"
+  #   )
+  #   
+  #   version.to_a
+  #   # => [0, 1, 2, ['rc', 10], ['master', '0ab1c3d']]
+  #   
+  #   QB::Package::Version.from_string('1').to_a
+  #   # => [1, nil, nil, [], []]
+  # 
+  # @return [Array]
+  # 
+  def to_a
+    [
+      major,
+      minor,
+      patch,
+      prerelease,
+      build,
+    ]
+  end # #to_a
+  
+  
+  def hash
+    to_a.hash
+  end
+  
+  
+  def eql? other
+    self == other && self.hash == other.hash
+  end
+  
+  
+  def to_s
+    "#<QB::Package::Version #{ @raw }>"
+  end
+  
+end # class QB::Package::Version