howzit 2.0.8 → 2.0.11

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/howzit.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'rubocop', '~> 0.28'
   spec.add_development_dependency 'rspec', '~> 3.1'
+  spec.add_development_dependency 'cli-test', '~> 1.0'
   spec.add_development_dependency 'simplecov', '~> 0.9'
   # spec.add_development_dependency 'codecov', '~> 0.1'
   spec.add_development_dependency 'fuubar', '~> 2.0'
@@ -40,5 +41,6 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'mdless', '~> 1.0', '>= 1.0.28'
   spec.add_runtime_dependency 'tty-screen', '~> 0.8'
+  spec.add_runtime_dependency 'tty-box', '~> 0.7'
   # spec.add_runtime_dependency 'tty-prompt', '~> 0.23'
 end

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 = IO.read(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
@@ -89,7 +154,7 @@ module Howzit
     # Create a buildnotes skeleton
     def create_note
       trap('SIGINT') do
-        Howzit.console.info "\nCanceled"
+        Howzit.console.info "\nCancelled"
         exit!
       end
       default = !$stdout.isatty || Howzit.options[:default]
@@ -210,26 +275,24 @@ module Howzit
       buildnotes.reverse
     end
 
-    def is_build_notes(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 is_build_notes(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
 
@@ -251,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
 
@@ -261,16 +329,23 @@ 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 = IO.read(template).split(/^#/)[0].strip
+      t_leader = Util.read_file(template).split(/^#/)[0].strip
       if t_leader.length > 0
         t_meta = t_leader.get_metadata
         if t_meta.key?('required')
           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
@@ -278,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
 
@@ -325,12 +405,18 @@ 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 = IO.read(file)
+      content = Util.read_file(file)
       home = ENV['HOME']
       short_path = File.dirname(file.sub(/^#{home}/, '~'))
       prefix = "#{short_path}/#{File.basename(file)}:"
@@ -343,8 +429,13 @@ 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 = IO.read(note_file).strip
+      help = Util.read_file(note_file)
       title = help.match(/(?:^(\S.*?)(?=\n==)|^# ?(.*?)$)/)
       title = if title
                 title[1].nil? ? title[2] : title[1]
@@ -355,13 +446,24 @@ 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 = []
 
       filename = path.nil? ? note_file : path
 
-      help = IO.read(filename)
+      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
 
@@ -401,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]
@@ -410,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'])
 
@@ -429,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
@@ -443,6 +568,9 @@ module Howzit
       output.nil? ? '' : output.join("\n")
     end
 
+    ##
+    ## Search and process the build note
+    ##
     def process
       output = []
 
@@ -535,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/config.rb

@@ -3,6 +3,7 @@ module Howzit
   class Config
     attr_reader :options
 
+    # Configuration defaults
     DEFAULTS = {
       color: true,
       config_editor: ENV['EDITOR'] || nil,
@@ -46,7 +47,7 @@ module Howzit
     def should_ignore(filename)
       return false unless File.exist?(ignore_file)
 
-      @ignore_patterns ||= YAML.safe_load(IO.read(ignore_file))
+      @ignore_patterns ||= YAML.safe_load(Util.read_file(ignore_file))
 
       ignore = false
 
@@ -78,6 +79,11 @@ module Howzit
 
     private
 
+    ##
+    ## Load command line options
+    ##
+    ## @return     [Hash] options with command line flags merged in
+    ##
     def load_options
       Color.coloring = $stdout.isatty
       flags = {
@@ -98,19 +104,39 @@ module Howzit
       @options = flags.merge(config)
     end
 
+    ##
+    ## Get the config directory
+    ##
+    ## @return     [String] path to config directory
+    ##
     def config_dir
       File.expand_path(CONFIG_DIR)
     end
 
+    ##
+    ## Get the config file
+    ##
+    ## @return     [String] path to config file
+    ##
     def config_file
       File.join(config_dir, CONFIG_FILE)
     end
 
+    ##
+    ## Get the ignore config file
+    ##
+    ## @return     [String] path to ignore config file
+    ##
     def ignore_file
       File.join(config_dir, IGNORE_FILE)
     end
 
-    def create_config(d)
+    ##
+    ## Create a new config file (and directory if needed)
+    ##
+    ## @param      default     [Hash] default configuration to write
+    ##
+    def create_config(default)
       unless File.directory?(config_dir)
         Howzit::ConsoleLogger.new(1).info "Creating config directory at #{config_dir}"
         FileUtils.mkdir_p(config_dir)
@@ -118,20 +144,28 @@ module Howzit
 
       unless File.exist?(config_file)
         Howzit::ConsoleLogger.new(1).info "Writing fresh config file to #{config_file}"
-        write_config(d)
+        write_config(default)
       end
       config_file
     end
 
+    ##
+    ## Load the config file
+    ##
+    ## @return     [Hash] configuration object
+    ##
     def load_config
       file = create_config(DEFAULTS)
-      config = YAML.load(IO.read(file))
+      config = YAML.load(Util.read_file(file))
       newconfig = config ? DEFAULTS.merge(config) : DEFAULTS
       write_config(newconfig)
       newconfig.dup
     end
 
-    def edit_config(d)
+    ##
+    ## Open the config in an editor
+    ##
+    def edit_config
       editor = Howzit.options.fetch(:config_editor, ENV['EDITOR'])
 
       raise 'No config_editor defined' if editor.nil?

data/lib/howzit/console_logger.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Available log levels
 LOG_LEVELS = {
   debug: 0,
   info: 1,
@@ -12,30 +13,67 @@ module Howzit
   class ConsoleLogger
     attr_accessor :log_level
 
+    ##
+    ## Init the console logging object
+    ##
+    ## @param      level  [Integer] log level
+    ##
     def initialize(level = nil)
       @log_level = level.to_i || Howzit.options[:log_level]
     end
 
+    ##
+    ## Get the log level from options
+    ##
+    ## @return     [Integer] log level
+    ##
     def reset_level
       @log_level = Howzit.options[:log_level]
     end
 
+    ##
+    ## Write a message to the console based on the urgency
+    ## level and user's log level setting
+    ##
+    ## @param      msg    [String] The message
+    ## @param      level  [Symbol] The level
+    ##
     def write(msg, level = :info)
       $stderr.puts msg if LOG_LEVELS[level] >= @log_level
     end
 
+    ##
+    ## Write a message at debug level
+    ##
+    ## @param      msg   The message
+    ##
     def debug(msg)
       write msg, :debug
     end
 
+    ##
+    ## Write a message at info level
+    ##
+    ## @param      msg   The message
+    ##
     def info(msg)
       write msg, :info
     end
 
+    ##
+    ## Write a message at warn level
+    ##
+    ## @param      msg   The message
+    ##
     def warn(msg)
       write msg, :warn
     end
 
+    ##
+    ## Write a message at error level
+    ##
+    ## @param      msg   The message
+    ##
     def error(msg)
       write msg, :error
     end

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