howzit 2.0.10 → 2.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd8307dc1bdbf51c7a78333c5880990b0bf82acb3fb2401d9e9969fe312ce125
-  data.tar.gz: 72ef1a744da1debcd5faf9ff9ee170eae3389b04e585cd652450eb65ba177c30
+  metadata.gz: 700ee2e9d73bdfcfeea142ed992c442119513428c7f4ceca415df2c3c792c844
+  data.tar.gz: c13005486bfac3f5add20bc1076a89f5b9cfad43288c9d5661d059d35271f1d7
 SHA512:
-  metadata.gz: affa665e5f83a8b836f5fe0a3d3c8e178d6fc880bcf3cecfe13afe44e61f4392831a45ff57f1a412a6ae7878f5cd7c00cd541aea1d780eb2b61aa01247268855
-  data.tar.gz: 85449c9184c5927d56acbd00e4086f11a9f4ee85085bfe07c12eb3e7b27e71c00eccee203fd73bda94919dfef000ead8f99f61e275b4d73700b442e25caa38c9
+  metadata.gz: dd6f68ba71489fcc87a9cc833ba7ab1c28fa0e680d12f92f09cf59e82bb1e289390a75631a69437c9f1f64e3f0dad470f7c783f5200affdad78e96cec14e35bc
+  data.tar.gz: 9eec9ae3a192de290026b129c81d97ec2a76940e14ea3f958b60e899bbb8a2951923cbf0186a9cecf4a0dae471a46cdc144157aa85df8d764026af70911bbdd2

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,11 @@
+### 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

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

@@ -120,7 +120,7 @@ module Howzit
 
     ##
     ## Return a formatted list of topics containing
-    ## @directives suitable for console output
+    ## directives suitable for console output
     ##
     ## @return     [String] formatted list
     ##
@@ -275,38 +275,15 @@ module Howzit
       buildnotes.reverse
     end
 
-    ##
-    ## Test if the filename matches the conditions to be a build note
-    ##
-    ## @param      filename  [String] The filename to test
-    ##
-    ## @return     [Boolean] true if filename passes test
-    ##
-    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
 
     ##

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,26 +37,39 @@ 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
   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
   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)

data/lib/howzit/stringutils.rb

@@ -3,7 +3,37 @@
 module Howzit
   # String Extensions
   module StringUtils
+    ##
+    ## Test if the filename matches the conditions to be a build note
+    ##
+    ## @return     [Boolean] true if filename passes test
+    ##
+    def build_note?
+      return false if downcase !~ /^(howzit[^.]*|build[^.]+)/
+
+      return false if Howzit.config.should_ignore(self)
+
+      true
+    end
+
+    ##
+    ## Replace slash escaped characters in a string with a
+    ## zero-width space that will prevent a shell from
+    ## interpreting them when output to console
+    ##
+    ## @return     [String] new string
+    ##
+    def preserve_escapes
+      gsub(/\\([a-z])/, '\​\1')
+    end
+
     # Convert a string to a valid YAML value
+    #
+    # @param      orig_value  The original value from which
+    #                         type will be determined
+    #
+    # @return     coerced value
+    #
     def to_config_value(orig_value = nil)
       if orig_value
         case orig_value.class.to_s
@@ -28,10 +58,21 @@ module Howzit
       end
     end
 
+    ##
+    ## Shortcut for calling Color.template
+    ##
+    ## @return     [String] colorized string
+    ##
     def c
       Color.template(self)
     end
 
+
+    ##
+    ## Convert a string to a regex object based on matching settings
+    ##
+    ## @return     [Regexp] Receive regex representation of the object.
+    ##
     def to_rx
       case Howzit.options[:matching]
       when 'exact'
@@ -50,9 +91,17 @@ module Howzit
       gsub(/\e\[[\d;]+m/, '').gsub(/\e\]1337;SetMark/,'')
     end
 
+    # Wrap text at a specified width.
+    #
     # Adapted from https://github.com/pazdera/word_wrap/,
-    # copyright (c) 2014, 2015  Radek Pazdera
-    # Distributed under the MIT License
+    # copyright (c) 2014, 2015  Radek Pazdera Distributed
+    # under the MIT License
+    #
+    # @param      width  [Integer] The width at which to
+    #                    wrap lines
+    #
+    # @return     [String] wrapped string
+    #
     def wrap(width)
       width ||= 80
       output = []
@@ -84,12 +133,19 @@ module Howzit
       output.join("\n")
     end
 
+    ##
+    ## Wrap string in place (destructive)
+    ##
+    ## @param      width  [Integer] The width at which to wrap
+    ##
     def wrap!(width)
       replace(wrap(width))
     end
 
     # Truncate string to nearest word
-    # @param len <number> max length of string
+    #
+    # @param      len   [Integer] max length of string
+    #
     def trunc(len)
       split(/ /).each_with_object([]) do |x, ob|
         break ob unless ob.join(' ').length + ' '.length + x.length <= len
@@ -98,10 +154,21 @@ module Howzit
       end.join(' ').strip
     end
 
+    ##
+    ## Truncate string in place (destructive)
+    ##
+    ## @param      len   [Integer] The length to truncate at
+    ##
     def trunc!(len)
       replace trunc(len)
     end
 
+    ##
+    ## Splits a line at nearest word break
+    ##
+    ## @param      width   [Integer] The width of the first segment
+    ## @param      indent  [String] The indent string
+    ##
     def split_line(width, indent = '')
       line = dup
       at = line.index(/\s/)
@@ -119,10 +186,23 @@ module Howzit
       end
     end
 
+    ##
+    ## Test if an executable is available on the system
+    ##
+    ## @return     [Boolean] executable is available
+    ##
     def available?
       Util.valid_command?(self)
     end
 
+    ##
+    ## Render [%variable] placeholders in a templated string
+    ##
+    ## @param      vars  [Hash] Key/value pairs of variable
+    ##                   values
+    ##
+    ## @return     [String] Rendered string
+    ##
     def render_template(vars)
       vars.each do |k, v|
         gsub!(/\[%#{k}(:.*?)?\]/, v)
@@ -131,10 +211,20 @@ module Howzit
       gsub(/\[%(.*?):(.*?)\]/, '\2')
     end
 
+    ##
+    ## Render [%variable] placeholders in place
+    ##
+    ## @param      vars  [Hash] Key/value pairs of variable values
+    ##
     def render_template!(vars)
       replace render_template(vars)
     end
 
+    ##
+    ## Render $X placeholders based on positional arguments
+    ##
+    ## @return     [String] rendered string
+    ##
     def render_arguments
       return self if Howzit.arguments.nil? || Howzit.arguments.empty?
 
@@ -145,6 +235,13 @@ module Howzit
       gsub(/\$[@*]/, Shellwords.join(Howzit.arguments))
     end
 
+    ##
+    ## Split the content at the first top-level header and
+    ## assume everything before it is metadata. Passes to
+    ## #get_metadata for processing
+    ##
+    ## @return     [Hash] key/value pairs
+    ##
     def extract_metadata
       if File.exist?(self)
         leader = Util.read_file(self).split(/^#/)[0].strip
@@ -154,6 +251,11 @@ module Howzit
       end
     end
 
+    ##
+    ## Examine text for multimarkdown-style metadata and return key/value pairs
+    ##
+    ## @return     [Hash] The metadata as key/value pairs
+    ##
     def get_metadata
       data = {}
       scan(/(?mi)^(\S[\s\S]+?): ([\s\S]*?)(?=\n\S[\s\S]*?:|\Z)/).each do |m|
@@ -162,6 +264,13 @@ module Howzit
       normalize_metadata(data)
     end
 
+    ##
+    ## Autocorrect some keys
+    ##
+    ## @param      meta  [Hash] The metadata
+    ##
+    ## @return     [Hash] corrected metadata
+    ##
     def normalize_metadata(meta)
       data = {}
       meta.each do |k, v|
@@ -177,15 +286,33 @@ module Howzit
       data
     end
 
+    ##
+    ## Test if iTerm markers should be output. Requires that
+    ## the $TERM_PROGRAM be iTerm and howzit is not running
+    ## directives or paginating output
+    ##
+    ## @return     [Boolean] should mark?
+    ##
     def should_mark_iterm?
       ENV['TERM_PROGRAM'] =~ /^iTerm/ && !Howzit.options[:run] && !Howzit.options[:paginate]
     end
 
+    ##
+    ## Output an iTerm marker
+    ##
+    ## @return     [String] ANSI escape sequence for iTerm
+    ##             marker
+    ##
     def iterm_marker
       "\e]1337;SetMark\a" if should_mark_iterm?
     end
 
     # Make a fancy title line for the topic
+    #
+    # @param      opts  [Hash] options
+    #
+    # @return     [String] formatted string
+    #
     def format_header(opts = {})
       title = dup
       options = {

data/lib/howzit/task.rb

@@ -5,11 +5,14 @@ module Howzit
   class Task
     attr_reader :type, :title, :action, :parent, :optional, :default
 
-    def initialize(type, title, action, parent = nil, optional: false, default: true)
-      @type = type
-      @title = title
-      @action = action.render_arguments
-      @parent = parent
+    ##
+    ## Initialize a Task object
+    ##
+    def initialize(params, optional: false, default: true)
+      @type = params[:type]
+      @title = params[:title]
+      @action = params[:action].render_arguments
+      @parent = params[:parent] || nil
       @optional = optional
       @default = default
     end
@@ -23,7 +26,7 @@ module Howzit
     end
 
     def to_list
-      "    * #{@type}: #{@title.gsub(/\\n/, '\​n')}"
+      "    * #{@type}: #{@title.preserve_escapes}"
     end
   end
 end

data/lib/howzit/topic.rb

@@ -107,6 +107,11 @@ module Howzit
       output
     end
 
+    ##
+    ## Platform-agnostic copy-to-clipboard
+    ##
+    ## @param      string  [String] The string to copy
+    ##
     def os_copy(string)
       os = RbConfig::CONFIG['target_os']
       out = "{bg}Copying {bw}#{string}".c
@@ -131,6 +136,11 @@ module Howzit
       end
     end
 
+    ##
+    ## Platform-agnostic open command
+    ##
+    ## @param      command  [String] The command
+    ##
     def os_open(command)
       os = RbConfig::CONFIG['target_os']
       out = "{bg}Opening {bw}#{command}".c
@@ -153,6 +163,11 @@ module Howzit
     end
 
     # Output a topic with fancy title and bright white text.
+    #
+    # @param      options  [Hash] The options
+    #
+    # @return     [Array] array of formatted lines
+    #
     def print_out(options = {})
       defaults = { single: false, header: true }
       opt = defaults.merge(options)
@@ -223,7 +238,7 @@ module Howzit
                    "\u{279A}"
                  end
 
-          output.push("{bmK}#{icon} {bwK}#{title.gsub(/\\n/, '\​n')}{x}#{option}".c)
+          output.push("{bmK}#{icon} {bwK}#{title.preserve_escapes}{x}#{option}".c)
         when /(?<fence>`{3,})run(?<optional>[!?]{1,2})? *(?<title>.*?)$/i
           m = Regexp.last_match.named_captures.symbolize_keys
           optional = m[:optional] =~ /[?!]+/ ? true : false
@@ -256,6 +271,11 @@ module Howzit
 
     private
 
+    ##
+    ## Collect all directives in the topic content
+    ##
+    ## @return     [Array] array of Task objects
+    ##
     def gather_tasks
       runnable = []
       @prereqs = @content.scan(/(?<=@before\n).*?(?=\n@end)/im).map(&:strip)
@@ -275,7 +295,12 @@ module Howzit
           default = c[:optional2] =~ /!/ ? false : true
           title = c[:title2].nil? ? '' : c[:title2].strip
           block = c[:block]&.strip
-          runnable << Howzit::Task.new(:block, title, block, optional: optional, default: default)
+          runnable << Howzit::Task.new({ type: :block,
+                                         title: title,
+                                         action: block,
+                                         parent: nil },
+                                       optional: optional,
+                                       default: default)
         else
           cmd = c[:cmd]
           optional = c[:optional] =~ /[?!]{1,2}/ ? true : false
@@ -294,15 +319,35 @@ module Howzit
             #   end
             #   runnable.concat(tasks)
             # end
-            runnable << Howzit::Task.new(:include, title, obj, optional: optional, default: default)
+            runnable << Howzit::Task.new({ type: :include,
+                                           title: title,
+                                           action: obj,
+                                           parent: nil },
+                                         optional: optional,
+                                         default: default)
           when /run/i
             # warn "{bg}Running {bw}#{obj}{x}".c if Howzit.options[:log_level] < 2
-            runnable << Howzit::Task.new(:run, title, obj, optional: optional, default: default)
+            runnable << Howzit::Task.new({ type: :run,
+                                           title: title,
+                                           action: obj,
+                                           parent: nil },
+                                         optional: optional,
+                                         default: default)
           when /copy/i
             # warn "{bg}Copied {bw}#{obj}{bg} to clipboard{x}".c if Howzit.options[:log_level] < 2
-            runnable << Howzit::Task.new(:copy, title, Shellwords.escape(obj), optional: optional, default: default)
+            runnable << Howzit::Task.new({ type: :copy,
+                                           title: title,
+                                           action: Shellwords.escape(obj),
+                                           parent: nil },
+                                         optional: optional,
+                                         default: default)
           when /open|url/i
-            runnable << Howzit::Task.new(:open, title, obj, optional: optional, default: default)
+            runnable << Howzit::Task.new({ type: :open,
+                                           title: title,
+                                           action: obj,
+                                           parent: nil },
+                                         optional: optional,
+                                         default: default)
           end
         end
       end

data/lib/howzit/util.rb

@@ -4,15 +4,40 @@ module Howzit
   # Util class
   module Util
     class << self
+
+      ##
+      ## Read a file with UTF-8 encoding and
+      ## leading/trailing whitespace removed
+      ##
+      ## @param      path  [String] The path to read
+      ##
+      ## @return     [String] UTF-8 encoded string
+      ##
       def read_file(path)
         IO.read(path).force_encoding('utf-8').strip
       end
 
+      ##
+      ## Test if an external command exists and is
+      ## executable. Removes additional arguments and passes
+      ## just the executable to #command_exist?
+      ##
+      ## @param      command  [String] The command
+      ##
+      ## @return     [Boolean] command is valid
+      ##
       def valid_command?(command)
         cmd = command.split(' ')[0]
         command_exist?(cmd)
       end
 
+      ##
+      ## Test if external command exists
+      ##
+      ## @param      command  [String] The command
+      ##
+      ## @return     [Boolean] command exists
+      ##
       def command_exist?(command)
         exts = ENV.fetch('PATHEXT', '').split(::File::PATH_SEPARATOR)
         if Pathname.new(command).absolute?

data/lib/howzit/version.rb

@@ -3,5 +3,5 @@
 # Primary module for this gem.
 module Howzit
   # Current Howzit version.
-  VERSION = '2.0.10'
+  VERSION = '2.0.11'
 end

data/spec/task_spec.rb

@@ -3,7 +3,12 @@
 require 'spec_helper'
 
 describe Howzit::Task do
-  subject(:task) { Howzit::Task.new(:run, 'List Directory', 'ls') }
+  subject(:task) do
+    Howzit::Task.new({ type: :run,
+                       title: 'List Directory',
+                       action: 'ls',
+                       parent: nil })
+  end
 
   describe ".new" do
     it "makes a new task instance" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.0.10
+  version: 2.0.11
 platform: ruby
 authors:
 - Brett Terpstra
@@ -309,7 +309,6 @@ files:
 - lib/howzit/version.rb
 - spec/.rubocop.yml
 - spec/buildnote_spec.rb
-- spec/buildnotes.md.bak
 - spec/cli_spec.rb
 - spec/ruby_gem_spec.rb
 - spec/spec_helper.rb
@@ -343,7 +342,6 @@ summary: Provides a way to access Markdown project notes by topic with query cap
 test_files:
 - spec/.rubocop.yml
 - spec/buildnote_spec.rb
-- spec/buildnotes.md.bak
 - spec/cli_spec.rb
 - spec/ruby_gem_spec.rb
 - spec/spec_helper.rb

data/spec/buildnotes.md.bak

@@ -1,22 +0,0 @@
-# spec
-
-
-
-## File Structure
-
-Where are the main editable files? Is there a dist/build folder that should be ignored?
-
-## Build
-
-What build system/parameters does this use?
-
-@run(./build command)
-
-## Deploy
-
-What are the procedures/commands to deploy this project?
-
-## Other
-
-Version control notes, additional gulp/rake/make/etc tasks...
-