howzit 2.0.9 → 2.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e11e4e9f19c26666de0d9dbfbfd0ab1b3c1bee495575fe0962ab5157a185e613
-  data.tar.gz: 7430c1da6d45f7dc873e01a8c1e6618da2dab503659921b9b72d690ad7aff181
+  metadata.gz: 700c444e11477c62c6de0f06b81b3029b21f3363f507c5a6cab927f2365d2be5
+  data.tar.gz: be862c2c31427abae2428a024009aea0f73885a5dc9652c5d2b5f308c181ca3b
 SHA512:
-  metadata.gz: 739879dd1a53689e005511745003dd9b9d2ff5a8fa964cec3cb1754ef78e740c488d0a9040cee6b6de5e5eaf62a4a9c50dcc74a236db732e1c78ef4f9c8978cd
-  data.tar.gz: '009601634be888e709ee5709fc2bb990b5dff1a274144469621a9b23dc5108778fec2f8838fc46f03999df8c31d9872f3ad8b9de57afb6bb534035a8f8070c25'
+  metadata.gz: d07c309680eef72f5edb3b41d40354aa9cefa1b6efebd1c0dfbaa59f7cbfc95c6211433f081b6f21afa069cd5ae30f79dc42f1a4a08c96680b533b16519ca25b
+  data.tar.gz: '08ca9d51ec3793c1750d70f500bde1e68c1f327cd41d0b92839c317d6a421f96cbb8ef2f03204ab6cfe1ddb1d83a497084aa9590233d6ceb860921fdb473267e'

data/.travis.yml

@@ -10,4 +10,4 @@ install:
   - gem uninstall bundler
   - gem install bundler --version '2.2.29'
   - bundle install
-script: "rake"
+script: "bundle exec rspec spec --exclude-pattern 'cli*'"

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+### 2.0.12
+
+2022-08-05 11:27
+
+#### IMPROVED
+
+- Show how many tasks will be included when requesting confirmation for an include? directive
+
+### 2.0.11
+
+2022-08-05 11:21
+
+#### IMPROVED
+
+- Update fish completions with all current command line options
+
+### 2.0.10
+
+2022-08-05 08:17
+
+#### IMPROVED
+
+- Provide more helpful feedback if no content is found in build note
+- Confirm whether the user wants to create a new note when one isn't found
+
 ### 2.0.9
 
 2022-08-05 07:29

data/fish/completions/howzit.fish

@@ -1,3 +1,35 @@
 complete -xc howzit -a "(howzit -L)"
-complete -xc howzit -s r -a "(howzit -T)"
-
+complete -c howzit -l default  -d "Answer all prompts with default response"
+complete -c howzit -x -s m -l matching -a "partial exact fuzzy beginswith" -d "Topics matching type"
+complete -c howzit -x -l multiple -a "first best all choose" -d "Multiple result handling"
+complete -c howzit -s u -l no-upstream -d "Don't traverse up parent directories for additional build notes"
+complete -c howzit -s u -l upstream -d "Traverse up parent directories for additional build notes"
+complete -c howzit -s L -l list-completions -d "List topics for completion"
+complete -c howzit -s l -l list -d "List available topics"
+complete -c howzit -s R -l list-runnable -d "List topics containing @ directives (verbose)"
+complete -c howzit -s T -l task-list -d "List topics containing @ directives (completion-compatible)"
+complete -c howzit -l templates -d "List available templates"
+complete -c howzit -l title-only -d "Output title only"
+complete -c howzit -s c -l create -d "Create a skeleton build note in the current working directory"
+complete -c howzit -f -l config-get -d "Display the configuration settings or setting for a specific key"
+complete -c howzit -f -l config-set -d "Set a config value (must be a valid key)"
+complete -c howzit -l edit-config -d "Edit configuration file using editor (subl)"
+complete -c howzit -s e -l edit -d "Edit buildnotes file in current working directory using editor (subl)"
+complete -c howzit -x -l grep -d "Display sections matching a search pattern"
+complete -c howzit -s r -l run -a "(howzit -T)" -d "Execute @run, @open, and/or @copy commands for given topic"
+complete -c howzit -s s -l select -d "Select topic from menu"
+complete -c howzit -l color -d "Colorize output (default on)"
+complete -c howzit -l no-color -d "Don't colorize output (default on)"
+complete -c howzit -x -l header-format -d "Formatting style for topic titles (border, block)"
+complete -c howzit -l md-highlight -d "Highlight Markdown syntax (default on), requires mdless or mdcat"
+complete -c howzit -l no-md-highlight -d "Don't highlight Markdown syntax (default on), requires mdless or mdcat"
+complete -c howzit -l pager -d "Paginate output (default on)"
+complete -c howzit -l no-pager -d "Don't paginate output (default on)"
+complete -c howzit -l show-code -d "Display the content of fenced run blocks"
+complete -c howzit -s t -l title -d "Output title with build notes"
+complete -c howzit -x -s w -l wrap  -d "Wrap to specified width (default 80, 0 to disable)"
+complete -c howzit -s d -l debug -d "Show debug messages (and all messages)"
+complete -c howzit -s q -l quiet -d "Silence info message"
+complete -c howzit -l verbose -d "Show all messages"
+complete -c howzit -s h -l help -d "Display this screen"
+complete -c howzit -s v -l version -d "Display version number"

data/lib/howzit/buildnote.rb

@@ -7,10 +7,27 @@ module Howzit
 
     attr_reader :metadata, :title
 
+    ##
+    ## Initialize a build note
+    ##
+    ## @param      file  [String] The path to the build note file
+    ## @param      args  [Array] additional args
+    ##
     def initialize(file: nil, args: [])
       @topics = []
-      create_note if note_file.nil?
-      @metadata = Util.read_file(note_file).split(/^#/)[0].strip.get_metadata
+      if note_file.nil?
+        res = Prompt.yn('No build notes file found, create one?', default: true)
+
+        create_note if res
+        Process.exit 0
+      end
+      content = Util.read_file(note_file)
+      if content.nil? || content.empty?
+        Howzit.console.error("{br}No content found in build note (#{note_file}){x}".c)
+        Process.exit 1
+      else
+        @metadata = content.split(/^#/)[0].strip.get_metadata
+      end
 
       read_help(file)
     end
@@ -19,14 +36,25 @@ module Howzit
       puts "#<Howzit::BuildNote @topics=[#{@topics.count}]>"
     end
 
+    ##
+    ## Public method to begin processing the build note based on command line options
+    ##
     def run
       process
     end
 
+    ##
+    ## Public method to open build note in editor
+    ##
     def edit
       edit_note
     end
 
+    ##
+    ## Find a topic based on a fuzzy match
+    ##
+    ## @param      term  [String] The search term
+    ##
     def find_topic(term)
       @topics.filter do |topic|
         rx = term.to_rx
@@ -34,11 +62,19 @@ module Howzit
       end
     end
 
+    ##
+    ## Call grep on all topics, filtering out those that don't match
+    ##
+    ## @param      term  [String] The search pattern
+    ##
     def grep(term)
       @topics.filter { |topic| topic.grep(term) }
     end
 
     # Output a list of topic titles
+    #
+    # @return     [String] formatted list of topics in build note
+    #
     def list
       output = []
       output.push("{bg}Topics:{x}\n".c)
@@ -48,14 +84,32 @@ module Howzit
       output.join("\n")
     end
 
+
+    ##
+    ## Return an array of topic titles
+    ##
+    ## @return     [Array] array of topic titles
+    ##
     def list_topics
       @topics.map { |topic| topic.title }
     end
 
+    ##
+    ## Return a list of topic titles suitable for shell completion
+    ##
+    ## @return     [String] newline-separated list of topic titles
+    ##
     def list_completions
       list_topics.join("\n")
     end
 
+    ##
+    ## Return a list of topics containing @directives,
+    ## suitable for shell completion
+    ##
+    ## @return     [String] newline-separated list of topic
+    ##             titles
+    ##
     def list_runnable_completions
       output = []
       @topics.each do |topic|
@@ -64,6 +118,12 @@ module Howzit
       output.join("\n")
     end
 
+    ##
+    ## Return a formatted list of topics containing
+    ## directives suitable for console output
+    ##
+    ## @return     [String] formatted list
+    ##
     def list_runnable
       output = []
       output.push(%({bg}"Runnable" Topics:{x}\n).c)
@@ -82,6 +142,11 @@ module Howzit
       output.join("\n")
     end
 
+    ##
+    ## Read the help file contents
+    ##
+    ## @param      file  [String] The filepath
+    ##
     def read_file(file)
       read_help_file(file)
     end
@@ -210,28 +275,24 @@ module Howzit
       buildnotes.reverse
     end
 
-    def build_note?(filename)
-      return false if filename.downcase !~ /^(howzit[^.]*|build[^.]+)/
-
-      return false if Howzit.config.should_ignore(filename)
-
-      true
-    end
-
+    ##
+    ## Glob current directory for valid build note filenames
+    ## (must start with "build" or "howzit" and have
+    ## extension of "txt", "md", or "markdown")
+    ##
+    ## @return     [String] file path
+    ##
     def glob_note
-      filename = nil
-      # Check for a build note file in the current folder. Filename must start
-      # with "build" and have an extension of txt, md, or markdown.
-
-      Dir.glob('*.{txt,md,markdown}').each do |f|
-        if build_note?(f)
-          filename = f
-          break
-        end
-      end
-      filename
+      Dir.glob('*.{txt,md,markdown}').select(&:build_note?)[0]
     end
 
+    ##
+    ## Search for a valid build note, checking current
+    ## directory, git top level directory, and parent
+    ## directories
+    ##
+    ## @return     [String] filepath
+    ##
     def find_note_file
       filename = glob_note
 
@@ -253,6 +314,11 @@ module Howzit
       File.expand_path(filename)
     end
 
+    ##
+    ## Search upstream directories for build notes
+    ##
+    ## @return     [Array] array of build note paths
+    ##
     def read_upstream
       buildnotes = glob_upstream
 
@@ -263,6 +329,13 @@ module Howzit
       topics_dict
     end
 
+    ##
+    ## Test to ensure that any `required` metadata in a
+    ## template is fulfilled by the build note
+    ##
+    ## @param      template  [String] The template to read
+    ##                       from
+    ##
     def ensure_requirements(template)
       t_leader = Util.read_file(template).split(/^#/)[0].strip
       if t_leader.length > 0
@@ -271,8 +344,8 @@ module Howzit
           required = t_meta['required'].strip.split(/\s*,\s*/)
           required.each do |req|
             unless @metadata.keys.include?(req.downcase)
-              Howzit.console.error %({xr}ERROR: Missing required metadata key from template '{bw}#{File.basename(template, '.md')}{xr}'{x}).c
-              Howzit.console.error %({xr}Please define {by}#{req.downcase}{xr} in build notes{x}).c
+              Howzit.console.error %({bRw}ERROR:{xbr} Missing required metadata key from template '{bw}#{File.basename(template, '.md')}{xr}'{x}).c
+              Howzit.console.error %({br}Please define {by}#{req.downcase}{xr} in build notes{x}).c
               Process.exit 1
             end
           end
@@ -280,6 +353,11 @@ module Howzit
       end
     end
 
+    ##
+    ## Read a list of topics from an included template
+    ##
+    ## @param      content  [String] The template contents
+    ##
     def get_template_topics(content)
       leader = content.split(/^#/)[0].strip
 
@@ -327,10 +405,16 @@ module Howzit
       template_topics
     end
 
-    def include_file(m)
-      file = File.expand_path(m[1])
+    ##
+    ## Import the contents of a filename as new topics
+    ##
+    ## @param      mtch  [MatchData] the filename match from
+    ##                   the include directive
+    ##
+    def include_file(mtch)
+      file = File.expand_path(mtch[1])
 
-      return m[0] unless File.exist?(file)
+      return mtch[0] unless File.exist?(file)
 
       content = Util.read_file(file)
       home = ENV['HOME']
@@ -345,6 +429,11 @@ module Howzit
       end
     end
 
+    ##
+    ## Get the title of the build note (top level header)
+    ##
+    ## @param      truncate  [Integer] Truncate to width
+    ##
     def note_title(truncate = 0)
       help = Util.read_file(note_file)
       title = help.match(/(?:^(\S.*?)(?=\n==)|^# ?(.*?)$)/)
@@ -357,7 +446,13 @@ module Howzit
       title && truncate.positive? ? title.trunc(truncate) : title
     end
 
-    # Read in the build notes file and output a hash of "Title" => contents
+    # Read in the build notes file and output a hash of
+    # "Title" => contents
+    #
+    # @param      path  [String] The build note path
+    #
+    # @return     [Array] array of Topics
+    #
     def read_help_file(path = nil)
       topics = []
 
@@ -365,6 +460,11 @@ module Howzit
 
       help = Util.read_file(filename)
 
+      if help.nil? || help.empty?
+        Howzit.console.error("{br}No content found in #{filename}{x}".c)
+        Process.exit 1
+      end
+
       @title = note_title
 
       help.gsub!(/@include\((.*?)\)/) do
@@ -403,6 +503,11 @@ module Howzit
       topics
     end
 
+    ##
+    ## Read build note and include upstream topics
+    ##
+    ## @param      path  [String] The build note path
+    ##
     def read_help(path = nil)
       @topics = read_help_file(path)
       return unless path.nil? && Howzit.options[:include_upstream]
@@ -412,8 +517,17 @@ module Howzit
       upstream_topics.each do |topic|
         @topics.push(topic) unless find_topic(title.sub(/^.+:/, '')).count.positive?
       end
+
+      if note_file && @topics.empty?
+        Howzit.console.error("{br}Note file found but no topics detected in #{note_file}{x}".c)
+        Process.exit 1
+      end
+
     end
 
+    ##
+    ## Open build note in editor
+    ##
     def edit_note
       editor = Howzit.options.fetch(:editor, ENV['EDITOR'])
 
@@ -431,7 +545,16 @@ module Howzit
       end
     end
 
-    def process_topic(topic, run, single = false)
+    ##
+    ## Run or print a topic
+    ##
+    ## @param      topic   [Topic] The topic
+    ## @param      run     [Boolean] execute directives if
+    ##                     true
+    ## @param      single  [Boolean] is being output as a
+    ##                     single topic
+    ##
+    def process_topic(topic, run, single: false)
       new_topic = topic.dup
 
       # Handle variable replacement
@@ -445,6 +568,9 @@ module Howzit
       output.nil? ? '' : output.join("\n")
     end
 
+    ##
+    ## Search and process the build note
+    ##
     def process
       output = []
 
@@ -537,10 +663,10 @@ module Howzit
 
       if !topic_matches.empty?
         # If we found a match
-        topic_matches.each { |topic_match| output.push(process_topic(topic_match, Howzit.options[:run], true)) }
+        topic_matches.each { |topic_match| output.push(process_topic(topic_match, Howzit.options[:run], single: true)) }
       else
         # If there's no argument or no match found, output all
-        topics.each { |k| output.push(process_topic(k, false, false)) }
+        topics.each { |k| output.push(process_topic(k, false, single: false)) }
       end
       Howzit.options[:paginate] = false if Howzit.options[:run]
       Util.show(output.join("\n").strip, Howzit.options)

data/lib/howzit/colors.rb

@@ -4,7 +4,9 @@
 module Howzit
   # Terminal output color functions.
   module Color
+    # Regexp to match excape sequences
     ESCAPE_REGEX = /(?<=\[)(?:(?:(?:[349]|10)[0-9]|[0-9])?;?)+(?=m)/.freeze
+
     # All available color names. Available as methods and string extensions.
     #
     # @example Use a color as a method. Color reset will be added to end of string.
@@ -79,6 +81,7 @@ module Howzit
       [:default, '0;39']
     ].map(&:freeze).freeze
 
+    # Array of attribute keys only
     ATTRIBUTE_NAMES = ATTRIBUTES.transpose.first
 
     # Returns true if Howzit::Color supports the +feature+.

data/lib/howzit/console_logger.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Available log levels
 LOG_LEVELS = {
   debug: 0,
   info: 1,

data/lib/howzit/hash.rb

@@ -5,7 +5,7 @@ class ::Hash
   ##
   ## Freeze all values in a hash
   ##
-  ## @return     Hash with all values frozen
+  ## @return     [Hash] Hash with all values frozen
   ##
   def deep_freeze
     chilled = {}
@@ -16,10 +16,18 @@ class ::Hash
     chilled.freeze
   end
 
+  ##
+  ## Deep freeze a hash in place (destructive)
+  ##
   def deep_freeze!
     replace deep_thaw.deep_freeze
   end
 
+  ##
+  ## Unfreeze nested hash values
+  ##
+  ## @return     [Hash] Hash with all values unfrozen
+  ##
   def deep_thaw
     chilled = {}
     each do |k, v|
@@ -29,27 +37,40 @@ class ::Hash
     chilled.dup
   end
 
+  ##
+  ## Unfreeze nested hash values in place (destructive)
+  ##
   def deep_thaw!
     replace deep_thaw
   end
 
   # Turn all keys into string
   #
-  # Return a copy of the hash where all its keys are strings
+  # @return     [Hash] hash with all keys as strings
+  #
   def stringify_keys
     each_with_object({}) { |(k, v), hsh| hsh[k.to_s] = v.is_a?(Hash) ? v.stringify_keys : v }
   end
 
+  ##
+  ## Turn all keys into strings in place (destructive)
+  ##
   def stringify_keys!
-  	replace stringify_keys
+    replace stringify_keys
   end
 
   # Turn all keys into symbols
+  #
+  # @return     [Hash] hash with all keys as symbols
+  #
   def symbolize_keys
     each_with_object({}) { |(k, v), hsh| hsh[k.to_sym] = v.is_a?(Hash) ? v.symbolize_keys : v }
   end
 
+  ##
+  ## Turn all keys into symbols in place (destructive)
+  ##
   def symbolize_keys!
-  	replace symbolize_keys
+    replace symbolize_keys
   end
 end

data/lib/howzit/prompt.rb

@@ -4,10 +4,22 @@ module Howzit
   # Command line prompt utils
   module Prompt
     class << self
-    	def yn(prompt, default: true)
+
+      ##
+      ## Display and read a Yes/No prompt
+      ##
+      ## @param      prompt   [String] The prompt string
+      ## @param      default  [Boolean] default value if
+      ##                      return is pressed or prompt is
+      ##                      skipped
+      ##
+      ## @return     [Boolean] result
+      ##
+      def yn(prompt, default: true)
         return default unless $stdout.isatty
 
         return default if Howzit.options[:default]
+
         tty_state = `stty -g`
         system 'stty raw -echo cbreak isig'
         yn = color_single_options(default ? %w[Y n] : %w[y N])
@@ -20,6 +32,14 @@ module Howzit
         res.empty? ? default : res =~ /y/i
       end
 
+      ##
+      ## Helper function to colorize the Y/N prompt
+      ##
+      ## @param      choices  [Array] The choices with
+      ##                      default capitalized
+      ##
+      ## @return     [String] colorized string
+      ##
       def color_single_options(choices = %w[y n])
         out = []
         choices.each do |choice|
@@ -33,6 +53,12 @@ module Howzit
         Color.template("{xg}[#{out.join('/')}{xg}]{x}")
       end
 
+      ##
+      ## Create a numbered list of options. Outputs directly
+      ## to console, returns nothing
+      ##
+      ## @param      matches  [Array] The list items
+      ##
       def options_list(matches)
         counter = 1
         puts
@@ -43,6 +69,15 @@ module Howzit
         puts
       end
 
+      ##
+      ## Choose from a list of items. If fzf is available,
+      ## uses that, otherwise generates its own list of
+      ## options and accepts a numeric response
+      ##
+      ## @param      matches  [Array] The options list
+      ##
+      ## @return     [Array] the selected results
+      ##
       def choose(matches)
         if Util.command_exist?('fzf')
           settings = [
@@ -80,7 +115,7 @@ module Howzit
             end
             line = line == '' ? 1 : line.to_i
 
-            return matches[line - 1] if line.positive? && line <= matches.length
+            return [matches[line - 1]] if line.positive? && line <= matches.length
 
             puts 'Out of range'
             options_list(matches)