qb 0.3.12 → 0.3.13

data/lib/qb/cli/setup.rb

@@ -1,10 +1,20 @@
 # Requirements
 # =====================================================================
 
+# StdLib
+require 'pathname'
+
 # package
 require 'qb/ansible/cmds/playbook'
 
 
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements'
+using NRSER
+
+
 # Declarations
 # =======================================================================
 
@@ -25,8 +35,31 @@ module QB::CLI
   #   The `ansible-playbook` command exit code.
   # 
   def self.setup args = []
-    project_root = NRSER.git_root '.'
-    playbook_path = project_root / 'dev' / 'setup.qb.yml'
+    # Figure out project root and setup playbook path
+    case args[0]
+    when String, Pathname
+      # The playbook path has been provided, use that to find the project root
+      playbook_path = QB::Util.resolve args[0]
+      project_root = NRSER.git_root playbook_path
+      
+    when nil
+      # Figure the project root out from the current directory, then
+      # form the playbook path from that
+      project_root = NRSER.git_root '.'
+      playbook_path = project_root / 'dev' / 'setup.qb.yml'
+    
+    else
+      raise TypeError.new binding.erb <<-END
+        First entry of `args` must be nil, String or Pathname, found:
+        
+            <%= args[0].pretty_inspect %>
+        
+        args:
+        
+            <%= args.pretty_inspect %>
+        
+      END
+    end
     
     unless playbook_path.file?
       raise "Can't find QB setup playbook at `#{ playbook_path.to_s }`"

data/lib/qb/options.rb

@@ -10,7 +10,13 @@ using NRSER
 
 module QB
   class Options
-    # constants
+    # Mixins
+    # ========================================================================
+    
+    include SemanticLogger::Loggable
+    
+    
+    # Constants
     # =======================================================================
     
     QB_DEFAULTS = {
@@ -103,6 +109,8 @@ module QB
       
       QB.debug "including #{ role.name } as #{ new_include_path.join('-') }"
       
+      opts.separator "Options for included #{ role.name } role:"
+      
       add opts, options, role, new_include_path
     end
     
@@ -353,6 +361,8 @@ module QB
         
         opts.banner = @role.banner
         
+        opts.separator "Common options:"
+        
         opts.on(
           '-H',
           '--HOSTS=HOSTS',
@@ -457,6 +467,8 @@ module QB
           @qb['ask'] = value
         end
         
+        opts.separator "Role options:"
+        
         self.class.add opts, @role_options, @role
         
         opts.on_tail("-h", "--help", "Show this message") do
@@ -471,37 +483,52 @@ module QB
       opt_parser.parse! @argv
     end # parse!
     
-    # pull options that start with
-    #
-    # 1.  `--ANSIBLE_`
-    # 1.  `--ANSIBLE-`
-    # 2.  `---`
-    # 
-    # out of `@argv` and stick them in `@ansible`.
-    def parse_ansible!
-      @ansible = @role.default_ansible_options.clone
-      
-      reg_exs = [
-        /\A\-\-ANSIBLE[\-\_]/,
-        /\A\-\-\-/,
-      ]
+    
+    protected
+    # ========================================================================
       
-      @argv.reject! {|shellword|
-        if re = reg_exs.find {|re| re =~ shellword}
-          name = shellword.sub re, ''
-          
-          value = true
-          
-          if name.include? '='
-            name, value = name.split('=', 2)
+      # Pull options that start with
+      #
+      # 1.  `--ANSIBLE_`
+      # 1.  `--ANSIBLE-`
+      # 2.  `---`
+      # 
+      # out of `@argv` and stick them in `@ansible`.
+      # 
+      # @return [nil]
+      #   **Mutates** `@argv`.
+      # 
+      def parse_ansible!
+        logger.debug "Parsing Ansible options...",
+          argv: @argv.dup
+        
+        @ansible = @role.default_ansible_options.clone
+        
+        reg_exs = [
+          /\A\-\-ANSIBLE[\-\_]/,
+          /\A\-\-\-/,
+        ]
+        
+        @argv.reject! {|shellword|
+          if re = reg_exs.find {|re| re =~ shellword}
+            name = shellword.sub re, ''
+            
+            value = true
+            
+            if name.include? '='
+              name, value = name.split('=', 2)
+            end
+            
+            @ansible[name] = value
+            
+            true
           end
-          
-          @ansible[name] = value
-          
-          true
-        end
-      }
-    end # #parse_ansible!
+        }
+        
+        nil
+      end # #parse_ansible!
+      
+    # end protected
     
   end # Options
 end # QB

data/lib/qb/role.rb

@@ -1,15 +1,24 @@
-
 # Requirements
 # =======================================================================
 
 # stdlib
+# ----------------------------------------------------------------------------
+
 require 'yaml'
 require 'cmds'
 
+
 # deps
+# ----------------------------------------------------------------------------
+
 
 # package
-require_relative './role/errors'
+# ----------------------------------------------------------------------------
+
+# Breakouts
+require 'qb/role/errors'
+require 'qb/role/name'
+require 'qb/role/default_dir'
 
 
 # Refinements
@@ -29,6 +38,12 @@ module QB; end
 # 
 class QB::Role
   
+  # Mixins
+  # ============================================================================
+  
+  include SemanticLogger::Loggable
+  
+  
   # Constants
   # =====================================================================
   
@@ -219,10 +234,12 @@ class QB::Role
         search_dir.directory?
       }.
       map {|search_dir|
-        Pathname.glob(search_dir.join '**', 'meta', 'qb.yml').
-          map {|meta_path|
-            [meta_path.dirname.dirname, search_dir: search_dir] 
-          }
+        ['', '.yml', '.yaml'].flat_map { |ext|
+          Pathname.glob(search_dir.join '**', 'meta', "qb#{ ext }").
+            map {|meta_path|
+              [meta_path.dirname.dirname, search_dir: search_dir] 
+            }
+        }
       }.
       flatten(1).
       map {|args|
@@ -403,58 +420,6 @@ class QB::Role
   end
   
   
-  # Do our best to figure out a role name from a path (that might not exist).
-  # 
-  # We needs this for when we're creating a role.
-  # 
-  # @param [String | Pathname] path
-  #   
-  # 
-  # @return [String]
-  # 
-  def self.default_role_name path
-    resolved_path = QB::Util.resolve path
-    
-    # Find the first directory in the search path that contains the path,
-    # if any do.
-    # 
-    # It *could* be in more than one in funky situations like overlapping 
-    # search paths or link silliness, but that doesn't matter - we consider 
-    # the first place we find it to be the relevant once, since the search
-    # path is most-important-first.
-    # 
-    search_dir = search_path.find { |pathname|
-      resolved_path.fnmatch? ( pathname / '**' ).to_s
-    }
-    
-    if search_dir.nil?
-      # It's not in any of the search directories
-      # 
-      # If it has 'roles' as a segment than use what's after the last occurrence
-      # of that (unless there isn't anything).
-      # 
-      segments = resolved_path.to_s.split File::SEPARATOR
-      
-      if index = segments.rindex( 'roles' )
-        name_segs = segments[( index + 1 )..( -1 )]
-        
-        unless name_segs.empty?
-          return File.join name_segs
-        end
-      end
-      
-      # Ok, that didn't work... just return the basename I guess...
-      return File.basename resolved_path
-      
-    end
-    
-    # it's in the search path, return the relative path from the containing
-    # search dir to the resolved path (string version of it).
-    resolved_path.relative_path_from( search_dir ).to_s
-
-  end # #default_role_name
-  
-  
   # Instance Attributes
   # =======================================================================
   
@@ -534,22 +499,6 @@ class QB::Role
   # Instance Methods
   # =====================================================================
   
-  def namespace
-    *namespace_segments, last = @name.split File::Separator
-    
-    namespace_segments << last.split('.').first if last.include?('.')
-     
-    if namespace_segments.empty?
-      nil
-    else
-      File.join *namespace_segments
-    end
-  end
-  
-  def namespaceless
-    File.basename(@name).split('.', 2).last
-  end
-  
   def options_key
     @display_path.to_s
   end
@@ -695,7 +644,7 @@ class QB::Role
       parts << '[OPTIONS]'
     end
     
-    if uses_default_dir?
+    if has_dir_arg?
       parts << 'DIRECTORY'
     end
     
@@ -715,10 +664,11 @@ class QB::Role
       lines << meta['description']
       lines << ''
     end
-    lines << 'usage:'
+    lines << 'Usage:'
+    lines << ''
     lines << "  #{ usage }"
     lines << ''
-    lines << 'options:'
+    lines << ''
     
     lines.join("\n")
   end
@@ -776,102 +726,14 @@ class QB::Role
   end
   
   
+  # Test if the {QB::Role} uses a directory argument (that gets assigned to
+  # the `qb_dir` variable in Ansible).
+  # 
   # @return [Boolean]
-  #   @todo Document return value.
   # 
-  def uses_default_dir?
+  def has_dir_arg?
     meta['default_dir'] != false
-  end # #uses_default_dir?
-  
-  
-  # gets the default `qb_dir` value, raising an error if the role doesn't
-  # define how to get one or there is a problem getting it.
-  # 
-  # 
-  def default_dir cwd, options
-    QB.debug "get_default_dir",
-      role: self,
-      meta: self.meta,
-      cwd: cwd,
-      options: options
-    
-    key = 'default_dir'
-    value = self.meta[key]
-    case value
-    when nil
-      # there is no get_dir info in meta/qb.yml, can't get the dir
-      raise QB::UserInputError.dedented <<-END
-        unable to infer default directory: no '#{ key }' key in 'meta/qb.yml'
-        for role #{ self }
-      END
-    
-    when false
-      # this method should not get called when the value is false (an entire
-      # section is skipped in exe/qb when `default_dir = false`)
-      raise QB::StateError.squished <<-END
-        role does not use default directory (meta/qb.yml:default_dir = false)
-      END
-    
-    when 'git_root'
-      QB.debug "returning the git root relative to cwd"
-      NRSER.git_root cwd
-    
-    when 'cwd'
-      QB.debug "returning current working directory"
-      cwd
-      
-    when Hash
-      QB.debug "qb meta option is a Hash"
-      
-      unless value.length == 1
-        raise "#{ meta_path.to_s }:default_dir invalid: #{ value.inspect }"
-      end
-      
-      hash_key, hash_value = value.first
-      
-      case hash_key
-      when 'exe'
-        exe_path = hash_value
-        
-        # supply the options to the exe so it can make work off those values
-        # if it wants.
-        exe_input_data = Hash[
-          options.map {|option|
-            [option.cli_option_name, option.value]
-          }
-        ]
-        
-        unless exe_path.start_with?('~') || exe_path.start_with?('/')
-          exe_path = File.join(self.path, exe_path)
-          debug 'exe path is relative, basing off role dir', exe_path: exe_path
-        end
-        
-        debug "found 'exe' key, calling", exe_path: exe_path,
-                                          exe_input_data: exe_input_data
-        
-        Cmds.chomp! exe_path do
-          JSON.dump exe_input_data
-        end
-        
-      when 'find_up'
-        filename = hash_value
-        
-        unless filename.is_a? String
-          raise "find_up filename must be string, found #{ filename.inspect }"
-        end
-        
-        QB.debug "found 'find_up', looking for file named #{ filename }"
-        
-        QB::Util.find_up filename
-        
-      else
-        raise QB::Role::MetadataError.squised <<-END
-          bad key: #{ hash_key } in #{ self.meta_path.to_s }:default_dir
-        END
-        
-      end
-    end
-  end # default_dir
+  end # #has_dir_arg?
   
   
   # @return [Hash<String, *>]

data/lib/qb/role/default_dir.rb

@@ -0,0 +1,231 @@
+##
+# {QB::Role} methods for finding the default directory for 
+# running a role when one is not provided in the CLI.
+# 
+# Broken out from the main `//lib/qb/role.rb` file because it was starting to 
+# get long and unwieldy.
+# 
+##
+
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+require 'pathname'
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements'
+using NRSER
+
+
+# Declarations
+# =======================================================================
+
+module QB; end
+
+
+# Definitions
+# =======================================================================
+
+class QB::Role
+  
+  # Instance Methods
+  # ======================================================================
+  
+  # Gets the default `qb_dir` value, raising an error if the role doesn't
+  # define how to get one or there is a problem getting it.
+  # 
+  # It uses a "strategy" value found at the 'default_dir' key in the role's 
+  # QB metadata (in `<role_path>/meta/qb.yml` or returned by a 
+  # `<role_path>/meta/qb` executable).
+  # 
+  # See the {file:doc/qb_roles/metadata/default_dir.md default_dir} 
+  # documentation for details on the accepted strategy values.
+  # 
+  # @param [String | Pathname] cwd:
+  #   The working directory the CLI command was run in.
+  # 
+  # @param [Hash<String, QB::Options::Option>] options:
+  #   The role options (from {QB::Options#role_options}).
+  #   
+  #   TODO rename this.
+  # 
+  # @return [Pathname]
+  #   The directory to target.
+  # 
+  # @raise
+  #   When we can't determine a directory due to role meta settings or target 
+  #   system state.
+  # 
+  def default_dir cwd, options
+    logger.debug "CALLING default_dir",
+      role: self.instance_variables.map_values { |k, v|
+        self.instance_variable_get k
+      },
+      cwd: cwd,
+      options: options
+    
+    default_dir_for(
+      value: self.meta['default_dir'],
+      cwd: cwd,
+      options: options
+    ).to_pn
+  end # default_dir
+  
+  
+  protected
+  # ========================================================================
+    
+    # Internal, possibly recursive method that actually does the work of
+    # figuring out the directory value.
+    # 
+    # Recurs when the meta value is an array, trying each of the entries in
+    # sequence, returning the first to succeed, and raising if they all fail.
+    # 
+    # @param [nil | false | String | Hash | Array] strategy
+    #   Instruction for how to determine the directory value.
+    #   
+    #   See the {file:doc/qb_roles.md#default_dir default_dir} for a details
+    #   on recognized values.
+    # 
+    # @return [return_type]
+    #   @todo Document return value.
+    # 
+    def default_dir_for value:, cwd:, options:
+      case value
+      when nil
+        # there is no get_dir info in meta/qb.yml, can't get the dir
+        raise QB::UserInputError.new binding.erb <<-END
+          No default directory for role <%= self.name %>
+          
+          Role <%= self.name %> does not provide a default target directory
+          (used to populate the `qb_dir` Ansible variable).
+          
+          You must provide one via the CLI like
+          
+              qb run <%= self.name %> DIRECTORY
+          
+          or, if you are the developer of the <%= self.name %> role, set a 
+          non-null value for the 'default_dir' key in
+          
+              <%= self.meta_path %>
+          
+        END
+      
+      when false
+        # this method should not get called when the value is false (an entire
+        # section is skipped in exe/qb when `default_dir = false`)
+        raise QB::StateError.squished <<-END
+          role does not use default directory (meta/qb.yml:default_dir = false)
+        END
+      
+      when 'git_root'
+        logger.debug "returning the git root relative to cwd"
+        NRSER.git_root cwd
+      
+      when 'cwd'
+        logger.debug "returning current working directory"
+        cwd
+        
+      when Hash
+        logger.debug "qb meta option is a Hash"
+        
+        unless value.length == 1
+          raise "#{ meta_path.to_s }:default_dir invalid: #{ value.inspect }"
+        end
+        
+        hash_key, hash_value = value.first
+        
+        case hash_key
+        when 'exe'
+          exe_path = hash_value
+          
+          # supply the options to the exe so it can make work off those values
+          # if it wants.
+          exe_input_data = Hash[
+            options.map {|option|
+              [option.cli_option_name, option.value]
+            }
+          ]
+          
+          unless exe_path.start_with?('~') || exe_path.start_with?('/')
+            exe_path = File.join(self.path, exe_path)
+            debug 'exe path is relative, basing off role dir', exe_path: exe_path
+          end
+          
+          debug "found 'exe' key, calling", exe_path: exe_path,
+                                            exe_input_data: exe_input_data
+          
+          Cmds.chomp! exe_path do
+            JSON.dump exe_input_data
+          end
+          
+        when 'find_up'
+          filename = hash_value
+          
+          unless filename.is_a? String
+            raise "find_up filename must be string, found #{ filename.inspect }"
+          end
+          
+          QB.debug "found 'find_up', looking for file named #{ filename }"
+          
+          QB::Util.find_up filename
+        
+        when 'from_role'
+          # Get the value from another role, presumably one this role includes
+          
+          default_dir_for \
+            value: QB::Role.require( hash_value ).meta['default_dir'],
+            cwd: cwd,
+            options: options
+          
+        else
+          raise QB::Role::MetadataError.new binding.erb <<-END
+            Bad key <%= hash_key.inspect %> in 'default_dir' value
+            
+            Metadata for role <%= name %> read from
+            
+                <%= self.meta_path.to_s %>
+            
+            contains an invalid default directory strategy
+            
+                <%= value.pretty_inspect %>
+            
+            The key <%= hash_key.inspect %> does not correspond to a recognized 
+            form.
+            
+            Valid forms are:
+            
+            1.  {exe:         FILEPATH}
+            2.  {file_up:     FILEPATH}
+            3.  {from_role:   ROLE}
+            
+          END
+        end
+      
+      when Array
+        value.try_find do |candidate|
+          default_dir_for value: candidate, cwd: cwd, options: options
+        end
+      
+      else
+        raise QB::Role::MetadataError.new binding.erb <<-END
+          bad default_dir value: <%= value %>
+        END
+      end # case value
+    end # .default_dir_for
+    
+  # end protected
+  
+end # class QB::Role