qb 0.3.14 → 0.3.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b5043907ea8b17d2fd4f2a4d5ad146e4a3c13a3a
-  data.tar.gz: ddec830eccaae82a55107bae595e81ad93948deb
+  metadata.gz: 003b446aa520075c83fc445695b0babad54437b3
+  data.tar.gz: c994400156228766aeec6ea26103e7ee6217ad3c
 SHA512:
-  metadata.gz: a609942e5b5ef542c8a48d8911defea06a1b33b95d4d2bf1c84d89e8a8871b9416647f03bcef1363bc7d67aac0a22dc696acb2493de9abcbf7c2127c8ad985ae
-  data.tar.gz: 5636e6d6a03a0410c2b8233165b39f934fd63b8ff1e86c7aa897aead9220dcaadd437aba7b682bec83cae73a20754a95900288bb669cdb7f7c74d62b5619988d
+  metadata.gz: 2e379e64f336af6be769dc44e14654e598c01aa21b03e2148f5e82c51c23f8ece9808c0943459eb39158515b5b6e3c0f4c8ce6e27785ee2b30846543c8f6ba58
+  data.tar.gz: '0813dfb291517540ac560d6dabf4aafb4bb328b1abf54cd61dab3b858aea28833e3060be8c6ac057a505f78371a970ebcbe1b7656abe5e678191147d6da346e2'

data/.yardopts

@@ -2,6 +2,9 @@
 --markup=markdown
 lib/**/*.rb
 dev/packages/gems/nrser/lib/**/*.rb
+dev/packages/gems/cmds/lib/**/*.rb
 -
 README.md
 doc/**/*.md
+dev/packages/gems/nrser/README.md
+dev/packages/gems/cmds/README.md

data/lib/qb/options.rb

@@ -19,6 +19,10 @@ module QB
     # Constants
     # =======================================================================
     
+    # Default initial values for {#qb}.
+    # 
+    # @return [Hash]
+    # 
     QB_DEFAULTS = {
       'hosts' => ['localhost'].freeze,
       'facts' => true,
@@ -28,15 +32,19 @@ module QB
       'ask' => false,
     }.freeze
     
-    # appended on the end of an `opts.on` call to create a newline after
+    
+    # Appended on the end of an `opts.on` call to create a newline after
     # the option (making the help output a bit easier to read)
     # 
-    # you might think the empty string would be reasonable, but OptionParser
+    # You might think the empty string would be reasonable, but OptionParser
     # blows up if you do that.
     # 
+    # @return [String]
+    # 
     SPACER = ' '
     
-    # attributes
+    
+    # Attributes
     # =======================================================================
     
     # @!attribute [r] ansible
@@ -319,7 +327,7 @@ module QB
     def initialize role, argv
       @role = role
       @argv = argv
-      @qb = QB_DEFAULTS.clone
+      @qb = QB_DEFAULTS.dup
       
       parse!
     end
@@ -356,7 +364,7 @@ module QB
       
       opt_parser = OptionParser.new do |opts|
         opts.accept(QB::Package::Version) do |string|
-          QB::Package::Version.from_string(string).to_h
+          QB::Package::Version.from( string ).to_h
         end
         
         opts.banner = @role.banner

data/lib/qb/package/gem.rb

@@ -78,7 +78,7 @@ class QB::Package::Gem < QB::Package
       # 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 
+      # Cast to {Pathname} if it's not already and expand it to create the
       # root path
       values[:root_path] = path.to_pn.expand_path
       
@@ -98,8 +98,7 @@ class QB::Package::Gem < QB::Package
       values[:name] = values[:spec].name
       
       # Get the version from the spec
-      values[:version] = QB::Package::Version.from_gem_version \
-        values[:spec].version
+      values[:version] = QB::Package::Version.from values[:spec].version
       
       # Construct the resource instance and return it.
       new **values

data/lib/qb/package/version.rb

@@ -34,7 +34,7 @@ class QB::Package < QB::Util::Resource; end
 # Definitions
 # =======================================================================
 
-# An attempt to unify NPM and Gem version schemes to a reasonable extend, 
+# 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.
@@ -56,7 +56,7 @@ class QB::Package::Version < QB::Util::Resource
   MIXED_SEGMENT = t.union NUMBER_SEGMENT, NAME_SEGMENT
   
   
-  # Reasonably simple regular expression to extract things that might be 
+  # Reasonably simple regular expression to extract things that might be
   # versions from strings.
   # 
   # Intended for use on reasonably short strings like `git tag` output or
@@ -76,8 +76,8 @@ class QB::Package::Version < QB::Util::Resource
   #     `0-9`.
   # 
   # This will match *many* strings that are not versions, but it should not
-  # miss any that are. It cold obviously be refined and improve to reduce 
-  # false positives at the cost of additional complexity, but I wanted to 
+  # miss any that are. It cold obviously be refined and improve to reduce
+  # false positives at the cost of additional complexity, but I wanted to
   # start simple and complicate it as needed.
   # 
   # @return [Regexp]
@@ -97,13 +97,9 @@ class QB::Package::Version < QB::Util::Resource
   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
@@ -113,8 +109,7 @@ class QB::Package::Version < QB::Util::Resource
   # Attributes
   # =====================================================================
 
-  attr_reader :release,
-              :level
+  attr_reader :release
   
   
   # Class Methods
@@ -123,110 +118,31 @@ class QB::Package::Version < QB::Util::Resource
   # Utilities
   # ---------------------------------------------------------------------
   
-  # Time formatted to be stuck in a version segment per [Semver][] spec.
-  # We also strip out '-' to avoid possible parsing weirdness.
-  # 
-  # [Semver]: https://semver.org/
-  # 
-  # @return [String]
-  # 
-  def self.to_time_segment time
-    time.utc.iso8601.gsub /[^0-9A-Za-z]/, ''
+  def self.from object
+    QB::Package::Version::From.object object
   end
   
   
-  # Instance Builders
-  # ---------------------------------------------------------------------
-  
-  # Create a Version instance from a {Gem::Version}.
-  # 
-  # @param [Gem::Version] version
+  # @depreciated Use {.from} instead.
   # 
-  # @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']
+  def self.from_string string
+    QB::Package::Version::From.string string
   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
+  singleton_class.send :alias_method, :from_s, :from_string
   
   
-  # Parse string version into an instance. Accept Semver, Ruby Gem and 
-  # Docker image tag formats.
+  # Time formatted to be stuck in a version segment per [Semver][] spec.
+  # We also strip out '-' to avoid possible parsing weirdness.
   # 
-  # @param [String]
-  #   String version to parse.
+  # [Semver]: https://semver.org/
   # 
-  # @return [QB::Package::Version]
+  # @return [String]
   # 
-  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
+  def self.to_time_segment time
+    time.utc.iso8601.gsub /[^0-9A-Za-z]/, ''
   end
   
-  singleton_class.send :alias_method, :from_s, :from_string
-  
   
   # Extract version number from a string.
   # 
@@ -239,7 +155,7 @@ class QB::Package::Version < QB::Util::Resource
   def self.extract string
     string.scan( POSSIBLE_VERSION_RE ).map { |possible_version_string|
       begin
-        from_string possible_version_string
+        from possible_version_string
       rescue
         nil
       end
@@ -247,29 +163,6 @@ class QB::Package::Version < QB::Util::Resource
   end # .extract
   
   
-  # 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
   # =====================================================================
   
@@ -285,7 +178,7 @@ class QB::Package::Version < QB::Util::Resource
   
   
   # @return [Boolean]
-  #   True if any prerelease segments are present (stuff after '-' in 
+  #   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.
@@ -299,8 +192,8 @@ class QB::Package::Version < QB::Util::Resource
   #   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 
+  #   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?
@@ -323,36 +216,14 @@ class QB::Package::Version < QB::Util::Resource
   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
-  
+  # Derived Properties
+  # ---------------------------------------------------------------------
   
-  # @return [Boolean]
-  #   True if this version is a release candidate (first prerelease element
-  #   is 'rc').
-  # 
-  def rc?
-    level == 'rc'
+  def release
+    [major, minor, patch].join '.'
   end
   
   
-  # Derived Properties
-  # ---------------------------------------------------------------------
-  
   # @return [String]
   #   The Semver version string
   #   (`Major.minor.patch-prerelease+build` format).
@@ -403,7 +274,7 @@ class QB::Package::Version < QB::Util::Resource
   # Related Versions
   # ---------------------------------------------------------------------
   # 
-  # Functions that construct new version instances based on the current 
+  # Functions that construct new version instances based on the current
   # one as well as additional information provided.
   # 
   
@@ -412,7 +283,7 @@ class QB::Package::Version < QB::Util::Resource
   #   *is* a release version already, still returns a new instance.
   # 
   def release_version
-    self.class.from_string release
+    self.class.from release
   end # #release_version
   
   
@@ -448,115 +319,6 @@ class QB::Package::Version < QB::Util::Resource
   end # #prerelease_version
   
   
-  # Bumping
-  # ---------------------------------------------------------------------
-  
-  
-  # @todo Document bump_dev method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
-  def bump_to_dev
-    props = { prerelease: ['dev'] }
-    
-    case self.level
-    when 'release'
-      merge patch: patch.succ, **props
-    when 'rc'
-      merge **props
-    when 'dev'
-      self
-    end
-  end # #bump_dev
-  
-  
-  # Bump to next release-candidate version.
-  # 
-  # This is a little tricky because we need to know what the *last* rc
-  # version was, which is not in the version in most cases.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
-  def bump_to_rc existing_versions: nil
-    case self.level
-    when 'release'
-      merge patch: patch.succ, prerelease: ['rc', 0]
-    when 'rc'
-      merge prerelease: ['rc', prerelease[1].succ]
-    when 'dev'
-      if existing_versions.nil?
-        raise ArgumentError.squished <<-END
-          Can't bump to next rc version without knowing what rc versions have
-          already been used.
-        END
-      elsif existing_versions.is_a? String
-        existing_versions = self.class.extract existing_versions
-      end
-      
-      last_existing_rc = existing_versions.
-        select { |version|
-          version.rc? && version.release == release
-        }.
-        sort.
-        last
-      
-      rc_number = if last_existing_rc.nil?
-        0
-      else
-        last_existing_rc.prerelease[1].succ
-      end
-      
-      merge prerelease: ['rc', rc_number]
-    end
-  end # #bump_rc
-  
-  
-  # @todo Document bump_to_release method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
-  def bump_to_release
-    case self.level
-    when 'release'
-      # bump forward to next release, M.m.p -> M.m.(p+1)
-      merge patch: patch.succ
-    when 'rc', 'dev'
-      # bump forward to release version for rc or dev
-      release
-    end
-  end # #bump_to_release
-  
-  
-  # @todo Document bump method.
-  # 
-  # @param [type] arg_name
-  #   @todo Add name param description.
-  # 
-  # @return [return_type]
-  #   @todo Document return value.
-  # 
-  def bump level:, **options
-    method_name = "bump_to_#{ level }"
-    if options.empty?
-      public_send method_name
-    else
-      public_send method_name, **options
-    end
-  end # #bump
-  
-  
   # Language Interface
   # =====================================================================
   
@@ -572,7 +334,7 @@ class QB::Package::Version < QB::Util::Resource
   # 
   def == other
     other.class == self.class &&
-    other.to_a == self.to_a 
+    other.to_a == self.to_a
   end # #==
   
   
@@ -585,19 +347,17 @@ class QB::Package::Version < QB::Util::Resource
   # precedence.
   # 
   # This is considered the representative structure for the object's data,
-  # from which all other values are dependently derived, and is used in 
+  # 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 = QB::Package::Version.from "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
+  #   QB::Package::Version.from( '1' ).to_a
   #   # => [1, nil, nil, [], []]
   # 
   # @return [Array]
@@ -628,3 +388,10 @@ class QB::Package::Version < QB::Util::Resource
   end
   
 end # class QB::Package::Version
+
+
+# Post-Processing
+# =======================================================================
+
+require 'qb/package/version/leveled'
+require 'qb/package/version/from'

data/lib/qb/package/version/from.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+# Module of factory methods to create {QB::Package::Version} instances from
+# other objects (strings, {Gem::Version}, etc.)
+# 
+module QB::Package::Version::From
+  
+  # Get class to instantiate for prop values - either {QB::Package::Version}
+  # or a specialized subclass like {QB::Package::Version::Leveled}.
+  # 
+  # @param [Hash<Symbol, Object>] **values
+  #   Prop values.
+  # 
+  # @return [Class<QB::Package::Version>]
+  # 
+  def self.class_for **values
+    if QB::Package::Version::Leveled.level_for **values
+      QB::Package::Version::Leveled
+    else
+      QB::Package::Version
+    end
+  end # .class_for
+  
+  
+  # Instantiate an instance from prop values, using {.class_for} to choose
+  # the possible specialized class.
+  # 
+  # @param [Hash<Symbol, Object>] **values
+  #   Prop values.
+  # 
+  # @return [QB::Package::Version]
+  # 
+  def self.prop_values **values
+    class_for( **values ).new **values
+  end # .values
+  
+  
+  # Create an instance from a Gem-style version.
+  # 
+  # @param [String | Gem::Version] version
+  # 
+  # @return [QB::Package::Version]
+  # 
+  def self.gemver version
+    version = Gem::Version.new( version ) if version.is_a?( String )
+    
+    # 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]
+    
+    prop_values \
+      raw: version.to_s,
+      major: release_segments[0] || 0,
+      minor: release_segments[1] || 0,
+      patch: release_segments[2] || 0,
+      prerelease: prerelease_segments,
+      build: []
+  end
+  
+  singleton_class.send :alias_method, :gem_version, :gemver
+
+
+  def self.semver 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!
+    
+    prop_values \
+      raw: version,
+      major: parse['major'],
+      minor: parse['minor'],
+      patch: parse['patch'],
+      prerelease: parse['prerelease'],
+      build: parse['build']
+  end
+  
+  singleton_class.send :alias_method, :npm_version, :semver
+
+
+  # Parse Docker image tag version and create an instance.
+  # 
+  # @param [String] version
+  #   String version to parse.
+  # 
+  # @return [QB::Package::Version]
+  # 
+  def self.docker_tag version
+    string( version.gsub( '_', '+' ) ).merge raw: version
+  end # .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.string string
+    if string.include? '_'
+      docker_tag string
+    elsif string.include?( '-' ) || string.include?( '+' )
+      semver string
+    else
+      gem_version string
+    end
+  end
+
+  singleton_class.send :alias_method, :s, :string
+  
+  
+  def self.object object
+    case object
+    when String
+      string object
+    when Hash
+      prop_values **object
+    when Gem::Version
+      gem_version object
+    else
+      raise TypeError.new binding.erb <<-END
+        `object` must be String, Hash or Gem::Version
+        
+        Found:
+        
+            <%= object.pretty_inspect %>
+        
+      END
+    end
+  end
+  
+end # module QB::Package::Version::From

data/lib/qb/package/version/leveled.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+require 'qb/package/version'
+
+
+# Refinements
+# =======================================================================
+
+using NRSER
+using NRSER::Types
+
+
+# Definitions
+# =======================================================================
+
+# 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::Leveled < QB::Package::Version
+  DEV = 'dev'
+  RC = 'rc'
+  RELEASE = 'release'
+  
+  LEVELS = Set[ DEV, RC, RELEASE ].freeze
+  
+  module Types
+    LEVEL = t.in LEVELS, name: 'LevelType'
+    
+    def self.level
+      LEVEL
+    end
+  end
+  
+  
+  # Props
+  # ==========================================================================
+  
+  prop :level,          type: Types.level,      source: :level
+  prop :is_dev,         type: t.bool,           source: :dev?
+  prop :is_rc,          type: t.bool,           source: :rc?
+  
+  
+  # Class Methods
+  # ==========================================================================
+  
+  # Get the level for version prop values. Returns `nil` if they are not
+  # "leveled".
+  # 
+  # @param [Array<String | Integer>] prerelease:
+  #   The prerelease segments of the version.
+  # 
+  # @param [Array<String | Integer>] build:
+  #   The build segments of the version.
+  # 
+  # @param [Hash<Symbol, Object>] **etc
+  #   Really, anything, but meant to allow you to just pass all
+  #   {QB::Package::Version} prop values to the method.
+  # 
+  # @return [nil]
+  #   If the prop values don't have a level.
+  # 
+  # @return ['dev' | 'rc' | 'release']
+  #   If the values do have a level.
+  # 
+  def self.level_for prerelease: [], build: [], **etc
+    return RELEASE if prerelease.empty? && build.empty?
+    
+    return DEV if prerelease[0] == DEV
+    
+    if  prerelease[0] == RC &&
+        prerelease.length == 2 &&
+        t.non_neg_int.test( prerelease[1] )
+      return RC
+    end
+    
+    nil
+  end # .level_for
+  
+  
+  # Just like {.level_for} but raises if the props don't represent a valid
+  # level.
+  # 
+  # @param (see .level_for)
+  # @return (see .level_for)
+  # 
+  # @raise [ArgumentError]
+  #   If the prop values don't represent a version level.
+  # 
+  def self.level_for! **values
+    level_for( **values ).tap { |response|
+      if response.nil?
+        raise ArgumentError.new binding.erb <<-END
+          Prop values not valid for a leveled version:
+          
+              <%= values.pretty_inspect %>
+          
+        END
+      end
+    }
+  end
+  
+  
+  # Constructor
+  # ==========================================================================
+  
+  # Construct a new Version
+  def initialize **values
+    # Just to do the type check...
+    self.class.level_for! **values
+    super **values
+  end
+  
+  
+  # Instance Methods
+  # ============================================================================
+  
+  def level
+    self.class.level_for \
+      prerelease: prerelease,
+      build: build
+  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
+  
+  
+  # Transitions
+  # ---------------------------------------------------------------------
+  # 
+  # Methods for transitioning from one level to another that abide by rules
+  # for cycling between them.
+  # 
+
+  # @todo Document bump_dev method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def transition_to_dev inc: :patch
+    props = { prerelease: ['dev'] }
+    
+    t.match level,
+      'release', ->(_) {
+        succ = public_send( inc ).succ
+        
+        merge inc => succ, **props
+      },
+      
+      'rc', ->(_) {
+        merge **props
+      },
+      
+      'dev',  ->(_) {
+        raise QB::VersionError,
+          "Version #{ self } is already at `dev` level"
+      }
+  end # #transition_to_dev
+
+
+  # Transition to next release-candidate version.
+  # 
+  # This is a little tricky because we need to know what the *last* rc
+  # version was, which is not in the version in most cases.
+  # 
+  # @param [nil | String | Array] existing_versions:
+  #   Required when transitioning *from* `dev` level; ignored from `rc` and
+  #   `release` levels.
+  #   
+  #   > When transitioning from `dev` to `rc` we need to know what `rc.X`
+  #   versions have already been used in order to figure out the correct
+  #   next one.
+  #   
+  #   Value details:
+  #   
+  #   -   `nil` - Default value; fine when {#level} is `release` or `rc`. An
+  #       {ArgumentError} will be raised if {#level} is `dev`.
+  #   
+  #   -   `String` -
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def transition_to_rc existing_versions: nil
+    t.match level,
+      'release', ->(_) {
+        raise QB::VersionError,
+          "Can not transition from `release` to `rc` levels (for #{ self })"
+      },
+      
+      'rc', ->(_) {
+        merge prerelease: ['rc', prerelease[1].succ]
+      },
+      
+      'dev', ->(_) {
+        if existing_versions.nil?
+          raise ArgumentError.squished <<-END
+            Can't bump to next rc version without knowing what rc versions have
+            already been used.
+          END
+        elsif existing_versions.is_a? String
+          existing_versions = self.class.extract existing_versions
+        end
+        
+        last_existing_rc = existing_versions.
+          select { |version|
+            version.rc? && version.release == release
+          }.
+          sort.
+          last
+        
+        rc_number = if last_existing_rc.nil?
+          0
+        else
+          last_existing_rc.prerelease[1].succ
+        end
+        
+        merge prerelease: ['rc', rc_number]
+      }
+  end # #transition_to_rc
+
+
+  # @todo Document transition_to_release method.
+  # 
+  # @return [QB::Package::Version]
+  # 
+  def transition_to_release
+    t.match level,
+      'release', ->(_) {
+        raise QB::VersionError,
+          "Version #{ self } is already at `release` level"
+      },
+      
+      'dev', ->(_) {
+        raise QB::VersionError,
+          "Can not transition from `dev` to `release` levels (for #{ self })"
+      },
+      
+      'rc', ->(_) {
+        release_version
+      }
+  end # #transition_to_release
+
+
+  # @todo Document bump method.
+  # 
+  # @param [type] arg_name
+  #   @todo Add name param description.
+  # 
+  # @return [return_type]
+  #   @todo Document return value.
+  # 
+  def transition_to level, **options
+    Types.level.check level.to_s
+    
+    method_name = "transition_to_#{ level }"
+    if options.empty?
+      public_send method_name
+    else
+      public_send method_name, **options
+    end
+  end # #transition
+  
+  
+end

data/lib/qb/version.rb

@@ -4,7 +4,7 @@ module QB
   
   GEM_NAME = 'qb'
   
-  VERSION = "0.3.14"
+  VERSION = "0.3.15"
   
   MIN_ANSIBLE_VERSION = Gem::Version.new '2.1.2'
   

data/library/path_facts

@@ -169,7 +169,7 @@ class PathFacts < QB::Ansible::Module
   end
   
   
-  # If `path` is a directory containing the source for a Ruby Gem, add 
+  # If `path` is a directory containing the source for a Ruby Gem, add
   # useful information about it.
   def add_gem_facts
     unless @path.directory?
@@ -193,7 +193,7 @@ class PathFacts < QB::Ansible::Module
     
     spec = Gem::Specification::load(gemspec_path.to_s)
     gem.name = spec.name
-    gem.version = QB::Package::Version.from_gem_version spec.version
+    gem.version = QB::Package::Version.from spec.version
   end
   
   
@@ -218,9 +218,7 @@ class PathFacts < QB::Ansible::Module
     npm.name = npm.package_json['name']
     
     if npm.package_json['version']
-      npm.version = QB::Package::Version.from_npm_version(
-        npm.package_json['version']
-      )
+      npm.version = QB::Package::Version.from npm.package_json['version']
     end
   end
   
@@ -234,7 +232,7 @@ class PathFacts < QB::Ansible::Module
   #         -   True if `@path/VERSION` exists and was successfully parsed.
   # 
   # -   If `has_version_file` is `true`:
-  #     -   
+  #     -
   # 
   def add_version_file_facts
     unless @path.directory?
@@ -250,7 +248,7 @@ class PathFacts < QB::Ansible::Module
     end
     
     version = begin
-      QB::Package::Version.from_string version_file_path.read
+      QB::Package::Version.from version_file_path.read
     rescue Exception => e
       warn "Unable to parse version from #{ version_file_path.to_s }; #{ e }"
       @result.has_version_file = false
@@ -316,7 +314,7 @@ class PathFacts < QB::Ansible::Module
     # Add version/package facts from a @path/VERSION file if present
     add_version_file_facts
     
-    # If we only have one type of package present, we set it's type and 
+    # If we only have one type of package present, we set it's type and
     # version as `package.type` and `package.version`, which makes it easy for
     # code to 'auto-detect' the info.
     # 

data/library/stream

@@ -2,10 +2,18 @@
 # WANT_JSON
 
 # init bundler in dev env
+
+# HACK  Keep track of the ENV vars we overwrite so we can swap them back in
+#       later when we need to run the command.
+#       
+$replaced_env_vars = {}
+
 if ENV['QB_DEV_ENV']
   ENV.each {|k, v|
     if k.start_with? 'QB_DEV_ENV_'
-      ENV[k.sub('QB_DEV_ENV_', '')] = v
+      key = k.sub('QB_DEV_ENV_', '')
+      $replaced_env_vars[key] = [ENV[key], v]
+      ENV[key] = v
     end
   }
   require 'bundler/setup'
@@ -14,6 +22,8 @@ end
 require 'qb'
 require 'cmds'
 
+using NRSER
+
 class Stream < QB::Ansible::Module
   def main
     template = @args['template'] || @args['cmd']
@@ -41,9 +51,31 @@ class Stream < QB::Ansible::Module
     cmd = Cmds.new(template, **opts)
     
     if @args['log']
-      info "STREAMING\n\n#{ cmd.prepare }\n\n"
+      info binding.erb <<-END
+        
+        STREAMING
+        ========================================================================
+        
+        Template:
+        
+            <%= template %>
+        
+        Options:
+        
+            <%= opts.pretty_inspect %>
+        
+        Prepared command:
+        
+          <%= cmd.prepare %>
+        
+      END
     end
     
+    # HACK  Swap any ENV vars we replaced at the top back in
+    $replaced_env_vars.each do |key, (original, replacement)|
+      ENV[key] = original
+    end
+      
     cmd.stream!
     
     changed!

data/plugins/filter_plugins/version_plugins.py

@@ -4,26 +4,36 @@ __metaclass__ = type
 import subprocess
 import os
 import json
+import sys
 
 from ansible.errors import AnsibleError
 
 
-QB_ROOT = os.path.realpath(
+HERE = os.path.dirname(os.path.realpath(__file__))
+
+PROJECT_ROOT = os.path.realpath(
     os.path.join(
-        os.path.dirname(os.path.realpath(__file__)), # /plugins/filter_plugins
-        '..', # /plugins
-        '..', # /
+        HERE, # //plugins/filter_plugins
+        '..', # //plugins
+        '..', # //
     )
 )
 
+LIB_PYTHON_DIR = os.path.join( PROJECT_ROOT, 'lib', 'python' )
+
+if not (LIB_PYTHON_DIR in sys.path):
+    sys.path.insert(0, LIB_PYTHON_DIR)
+
+import qb.interop
+
 
 def get_semver_path():
-    bin_path = os.path.join(QB_ROOT, 'node_modules', 'semver', 'bin', 'semver')
+    bin_path = os.path.join(PROJECT_ROOT, 'node_modules', 'semver', 'bin', 'semver')
     
     if not os.path.isfile(bin_path):
         raise Exception("can't find semver at %s" % bin_path)
     
-    return bin_path 
+    return bin_path
 # get_semver_path()
 
 
@@ -83,7 +93,7 @@ def semver_parse(version):
     
     out = subprocess.check_output(
         cmd,
-        cwd = QB_ROOT
+        cwd = PROJECT_ROOT
     )
     
     version = json.loads(out)
@@ -118,23 +128,9 @@ def qb_version_parse(version_string):
     '''Parse version into QB::Package::Version
     '''
     
-    ruby_code = (
-        '''
-        require 'qb'
-        
-        puts JSON.dump(
-            QB::Package::Version.from_string %s
-        )
-        ''' % json.dumps(version_string)
+    return qb.interop.send_const(
+        'QB::Package::Version', 'from', version_string
     )
-    
-    cmd = ['/usr/bin/env', 'ruby', '-e', ruby_code]
-    
-    out = subprocess.check_output(cmd)
-    
-    version = json.loads(out)
-    
-    return version
 
 
 def qb_read_version(file_path):
@@ -163,4 +159,4 @@ class FilterModule(object):
 if __name__ == '__main__':
     import doctest
     doctest.testmod()
-    
+    

data/qb.gemspec

@@ -194,8 +194,8 @@ Gem::Specification.new do |spec|
   # Runtime Dependencies
   # ----------------------------------------------------------------------------
   
-  spec.add_dependency "cmds",             '~> 0.0', ">= 0.2.4"
-  spec.add_dependency "nrser",            '~> 0.1', ">= 0.1.0"
+  spec.add_dependency "cmds",             '~> 0.0', ">= 0.2.5"
+  spec.add_dependency "nrser",            '~> 0.1', ">= 0.1.1"
   spec.add_dependency "nrser-extras",     '~> 0.0', ">= 0.0.3"
   spec.add_dependency "state_mate",       '~> 0.0', ">= 0.1.0"
   

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qb
 version: !ruby/object:Gem::Version
-  version: 0.3.14
+  version: 0.3.15
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-10 00:00:00.000000000 Z
+date: 2018-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -123,7 +123,7 @@ dependencies:
         version: '0.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.2.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -133,7 +133,7 @@ dependencies:
         version: '0.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.2.5
 - !ruby/object:Gem::Dependency
   name: nrser
   requirement: !ruby/object:Gem::Requirement
@@ -143,7 +143,7 @@ dependencies:
         version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -153,7 +153,7 @@ dependencies:
         version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.1
 - !ruby/object:Gem::Dependency
   name: nrser-extras
   requirement: !ruby/object:Gem::Requirement
@@ -320,6 +320,8 @@ files:
 - lib/qb/package.rb
 - lib/qb/package/gem.rb
 - lib/qb/package/version.rb
+- lib/qb/package/version/from.rb
+- lib/qb/package/version/leveled.rb
 - lib/qb/path.rb
 - lib/qb/repo.rb
 - lib/qb/repo/git.rb