qb 0.1.47 → 0.1.48

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 63ae54569cf29beff79d801d32e28d243c959d3c
-  data.tar.gz: c9d99ed1389b6b5fc370ac81b10fcca184e175cd
+  metadata.gz: 0eb9c603416537655809bf3a2147a55cd35e1833
+  data.tar.gz: f6c6ae61026428b672ee0dd61a01dddfddd492bc
 SHA512:
-  metadata.gz: 366267848f33fecb1a8a8aa39119870db2d78dc91f009933f790b98bb13abbd0fd1e9a50b2b23d8478115ab4893553fd53b931d38b1d33eb5258a668552e297b
-  data.tar.gz: d6a819e756d023cb6c0f6da18b1b5603419e650c856da23da124b86185afc41bd09ee375690153b81282f7b57b6982f9ca820646e27ea3be13253c4da7c4e193
+  metadata.gz: 65c50309bd1d3501a14228cced913d84351d8192df54b13f777d9e99c50fbabefd757d384c6bfdecfbe8b9725f60fc48b0d85a44660af08851a459cdd60a9b24
+  data.tar.gz: c719eb898d4fc602559396028dcd7fb6b98534b96645d718ccad76d40cbcd388dc11ddff24669ac385778c8db164f53b15be3f2f71a828c679eb1b5d54927cff

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/lib/qb.rb

@@ -43,24 +43,40 @@ module QB
                               options: options
     
     key = 'default_dir'
-    case role.meta[key]
-    when nil, false
+    value = role.meta[key]
+    case value
+    when nil
       # there is no get_dir info in meta/qb.yml, can't get the dir
       raise "unable to infer default directory: no '#{ key }' key in meta/qb.yml"
-      
+    
+    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 "role does not use default directory (meta/qb.yml:default_dir = false)"
+    
     when 'git_root'
       debug "returning the git root relative to cwd"
       NRSER.git_root cwd
     
     when 'cwd'
-      debug "returing current working directory"
+      debug "returning current working directory"
       cwd
       
     when Hash
       debug "qb meta option is a Hash"
       
-      if role.meta[key].key? 'exe'
-        exe_path = role.meta[key]['exe']
+      unless value.length == 1
+        raise "#{ role.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]
@@ -78,8 +94,21 @@ module QB
         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
+        
+        debug "found 'find_up', looking for file named #{ filename }"
+        
+        Util.find_up filename
+        
       else
-        raise "not sure to process '#{ key }' in metea/qb.yml"
+        raise "bad key: #{ hash_key } in #{ role.meta_path.to_s }:default_dir"
+        
       end
     end
   end # get_default_dir

data/lib/qb/options.rb

@@ -250,6 +250,9 @@ module QB
         
         opts.on_tail("-h", "--help", "Show this message") do
           puts opts
+          
+          role.puts_examples
+          
           exit
         end
       end

data/lib/qb/role.rb

@@ -3,9 +3,20 @@ require 'cmds'
 require 'parseconfig'
 
 module QB
+  # contains info on a QB role.
+  # 
+  # 
   class Role
+    # attrs
+    # =====
+    
     attr_accessor :path, :name, :rel_path
     
+    # @!attribute [r] meta_path
+    #   @return [String, nil] the path qb metadata was load from. `nil` if it's
+    #     never been loaded or doesn't exist.
+    attr_accessor :meta_path
+    
     # errors
     # ======
     
@@ -273,6 +284,9 @@ module QB
       end
       
       @name = path.to_s.split(File::SEPARATOR).last
+      
+      # gets filled in when {#meta_load}
+      @meta_path = nil
     end
     
     def to_s
@@ -300,13 +314,18 @@ module QB
     #
     # if `cache` is true caches it as `@meta`
     # 
-    def load_meta cache = true
+    def load_meta cache = true      
       meta = if (@path + 'meta' + 'qb').exist?
-        YAML.load(Cmds.out!((@path + 'meta' + 'qb').realpath.to_s)) || {}
+        @meta_path = @path + 'meta' + 'qb'
+        YAML.load(Cmds.out!(@meta_path.realpath.to_s)) || {}
+        
       elsif (@path + 'meta' + 'qb.yml').exist?
-        YAML.load((@path + 'meta' + 'qb.yml').read) || {}
+        @meta_path = @path + 'meta' + 'qb.yml'
+        YAML.load(@meta_path.read) || {}
+        
       else
         {}
+        
       end
       
       if cache
@@ -422,6 +441,46 @@ module QB
       lines.join("\n")
     end
     
+    def examples
+      @meta['examples']
+    end
+    
+    # format the `meta.examples` hash into a string suitable for cli
+    # output.
+    # 
+    # @return [String]
+    #   the CLI-formatted examples.
+    # 
+    def format_examples
+      examples.
+        map {|title, body|
+          [
+            "#{ title }:",
+            body.lines.map {|l|
+              # only indent non-empty lines
+              # makes compacting newline sequences easier (see below)
+              if l.match(/^\s*$/)
+                l
+              else
+                '  ' + l
+              end
+            },
+            ''
+          ]
+        }.
+        flatten.
+        join("\n").
+        # compact newline sequences
+        gsub(/\n\n+/, "\n\n")
+    end
+    
+    # examples text
+    def puts_examples
+      return unless examples
+      
+      puts "\n" + format_examples + "\n"
+    end
+    
     private
     
     # get the value at the first found of the keys or the default.

data/lib/qb/util.rb

@@ -50,5 +50,33 @@ module QB
       # shouldn't ever happen
       raise "resolution failed: #{ segments.inspect }"
     end
+    
+    # find `filename` in `from` or closest parent directory.
+    # 
+    # @param [String] filename
+    #   name of file to search for.
+    # 
+    # @param [Pathname] from (Pathname.pwd)
+    #   directory to start from.
+    # 
+    # @return [Pathname]
+    #   Pathname of found file.
+    # 
+    # @raise
+    #   if file is not found in `from` or any of it's parent directories.
+    # 
+    def self.find_up filename, from = Pathname.pwd
+      path = from + filename
+      
+      return from if path.exist?
+      
+      parent = from.parent
+      
+      if from == parent
+        raise "not found in current or any parent directories: #{ filename }"
+      end
+      
+      return find_up filename, parent
+    end # .find_up
   end # Util
 end # QB

data/lib/qb/version.rb

@@ -1,7 +1,7 @@
 module QB
   GEM_NAME = 'qb'
   
-  VERSION = "0.1.47"
+  VERSION = "0.1.48"
   
   def self.gemspec
     Gem.loaded_specs[GEM_NAME]

data/qb.gemspec

@@ -91,6 +91,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "yard"
   
   spec.add_dependency "cmds",'~> 0.0', ">= 0.0.9"
   spec.add_dependency "nrser-extras", '~> 0.0', ">= 0.0.3"

data/roles/qb.gitignore/meta/qb

@@ -14,6 +14,10 @@ end
 puts JSON.pretty_generate({
   save_options: false,
   
+  default_dir: {
+    find_up: '.gitignore',
+  },
+  
   vars: [
     {
       name: "name",

data/roles/qb.install/meta/qb.yml

@@ -38,6 +38,13 @@ default_user: null
 # set to false to not save options in .qb-options.yml files
 save_options: false
 
+examples:
+  create a new role backed by a GitHub repo: >
+    
+    qb install --create --name=nrser.blah
+    
+    (`name` needs to have the namespace attached if one is desired)
+
 options:
 # - name: example
 #   description: an example of a variable.
@@ -46,7 +53,9 @@ options:
 #   short: e
 
 - name: name
-  description: name of role to install.
+  description: >
+    name of role to install.
+    include namespace if desired (nrser.blah vs blah).
   required: true
   type: string
   short: n
@@ -64,7 +73,7 @@ options:
   short: v
 
 - name: path
-  description: path to isntall roles at.
+  description: path to install roles at.
   required: false
   type: string
   short: p

data/roles/qb.qb_role/templates/qb.yml.j2

@@ -30,6 +30,10 @@ var_prefix: null
 #     -   invoke an execuable, passing a JSON serialization of the options 
 #         mapping their CLI names to values. path can be relative to role
 #         directory.
+# -   {find_up: FILENAME}
+#     -   starting at the current direcotry and climbing up to parent 
+#         directories, use the first one that contains FILENAME. error
+#         if none is found.
 default_dir: null
 
 # default user to become for play

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qb
 version: !ruby/object:Gem::Version
-  version: 0.1.47
+  version: 0.1.48
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-06 00:00:00.000000000 Z
+date: 2017-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: cmds
   requirement: !ruby/object:Gem::Requirement
@@ -140,6 +154,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - LICENSE.txt
 - README.md
 - ansible.cfg