howzit 2.0.10 → 2.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd8307dc1bdbf51c7a78333c5880990b0bf82acb3fb2401d9e9969fe312ce125
-  data.tar.gz: 72ef1a744da1debcd5faf9ff9ee170eae3389b04e585cd652450eb65ba177c30
+  metadata.gz: e269532605e044c35e2a0ebe322fe51ba5199d690a57385a358a3bad4fc2921f
+  data.tar.gz: 4ca045a0c3c2d1627b04a47363beb8e2de6718f5c708e1f4bf96285af96e09d4
 SHA512:
-  metadata.gz: affa665e5f83a8b836f5fe0a3d3c8e178d6fc880bcf3cecfe13afe44e61f4392831a45ff57f1a412a6ae7878f5cd7c00cd541aea1d780eb2b61aa01247268855
-  data.tar.gz: 85449c9184c5927d56acbd00e4086f11a9f4ee85085bfe07c12eb3e7b27e71c00eccee203fd73bda94919dfef000ead8f99f61e275b4d73700b442e25caa38c9
+  metadata.gz: 803b06d4a85632357eb1e61a898f88c39971df388107a62f67479e34788346f1824f78a3b3473cf5ee45dc445a494e7a144590d5df33ffd1b73d2114ba19049d
+  data.tar.gz: 51c6ec7213c4b7c531e53c32140dc485d897f40ee79d242ee8ec446804ad0edac8a9bac61d3b68189bf60884a3dbee28fe6d5f5f3040dae23ec8cb7ddb24903c

data/.rubocop.yml

@@ -6,6 +6,7 @@ AllCops:
 
 Metrics/BlockLength:
   Exclude:
+    - Rakefile
     - bin/howzit
     - lib/*.rb
 

data/.travis.yml

@@ -4,10 +4,10 @@ sudo: required
 dist: trusty
 cache: bundler
 rvm:
+  - ruby-2.6.4
   - ruby-2.7.0
   - ruby-3.0.1
 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,27 @@
+### 2.0.13
+
+2022-08-05 13:19
+
+#### IMPROVED
+
+- Add tests for more ruby versions via Docker
+
+### 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

data/Rakefile

@@ -5,6 +5,7 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
 require 'yard'
+require 'tty-spinner'
 
 task default: %i[test yard]
 
@@ -34,3 +35,43 @@ desc 'Changelog version check'
 task :cver do
   puts IO.read(File.join(File.dirname(__FILE__), 'CHANGELOG.md')).match(/^#+ (\d+\.\d+\.\d+(\w+)?)/)[1]
 end
+
+desc 'Run tests in Docker'
+task :dockertest, :version, :login do |_, args|
+  args.with_defaults(version: 'all', login: false)
+  case args[:version]
+  when /^a/
+    %w[6 7 3].each do |v|
+      Rake::Task['dockertest'].reenable
+      Rake::Task['dockertest'].invoke(v, false)
+    end
+    Process.exit 0
+  when /^3/
+    img = 'howzittest3'
+    file = 'docker/Dockerfile-3.0'
+  when /6$/
+    img = 'howzittest26'
+    file = 'docker/Dockerfile-2.6'
+  when /(^2|7$)/
+    img = 'howzittest27'
+    file = 'docker/Dockerfile-2.7'
+  else
+    img = 'howzittest'
+    file = 'docker/Dockerfile'
+  end
+
+  puts `docker build . --file #{file} -t #{img}`
+
+  exec "docker run -v #{File.dirname(__FILE__)}:/howzit -it #{img} /bin/bash -l" if args[:login]
+
+  spinner = TTY::Spinner.new('[:spinner] Running tests ...', hide_cursor: true)
+
+  spinner.auto_spin
+  res = `docker run --rm -v #{File.dirname(__FILE__)}:/howzit -it #{img}`
+  # commit = puts `bash -c "docker commit $(docker ps -a|grep #{img}|awk '{print $1}'|head -n 1) #{img}"`.strip
+  spinner.success
+  spinner.stop
+
+  puts res
+  # puts commit&.empty? ? "Error commiting Docker tag #{img}" : "Committed Docker tag #{img}"
+end

data/bin/howzit

@@ -1,4 +1,4 @@
-#!/usr/bin/env ruby -W1
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift File.join(__dir__, '..', 'lib')

data/docker/Dockerfile

@@ -0,0 +1,11 @@
+FROM ruby:3.0.1
+# RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
+RUN mkdir /howzit
+WORKDIR /howzit
+# COPY ./ /howzit/
+RUN gem install bundler:2.2.17
+RUN apt-get update -y
+RUN apt-get install -y less vim
+COPY ./docker/inputrc /root/.inputrc
+COPY ./docker/bash_profile /root/.bash_profile
+CMD ["scripts/runtests.sh"]

data/docker/Dockerfile-2.6

@@ -0,0 +1,11 @@
+FROM ruby:2.6
+# RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
+RUN mkdir /howzit
+WORKDIR /howzit
+# COPY ./ /howzit/
+RUN gem install bundler:2.2.17
+RUN apt-get update -y
+RUN apt-get install -y less vim
+COPY ./docker/inputrc /root/.inputrc
+COPY ./docker/bash_profile /root/.bash_profile
+CMD ["scripts/runtests.sh"]

data/docker/Dockerfile-2.7

@@ -0,0 +1,11 @@
+FROM ruby:2.7
+# RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
+RUN mkdir /howzit
+WORKDIR /howzit
+# COPY ./ /howzit/
+RUN gem install bundler:2.2.17
+RUN apt-get update -y
+RUN apt-get install -y less vim
+COPY ./docker/inputrc /root/.inputrc
+COPY ./docker/bash_profile /root/.bash_profile
+CMD ["scripts/runtests.sh"]

data/docker/Dockerfile-3.0

@@ -0,0 +1,11 @@
+FROM ruby:3.0.0
+# RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
+RUN mkdir /howzit
+WORKDIR /howzit
+# COPY ./ /howzit/
+RUN gem install bundler:2.2.17
+RUN apt-get update -y
+RUN apt-get install -y less vim
+COPY ./docker/inputrc /root/.inputrc
+COPY ./docker/bash_profile /root/.bash_profile
+CMD ["scripts/runtests.sh"]

data/docker/bash_profile

@@ -0,0 +1,13 @@
+#!/bin/bash
+export GLI_DEBUG=true
+export EDITOR="/usr/bin/vim"
+alias b="bundle exec bin/howzit"
+
+shopt -s nocaseglob
+shopt -s histappend
+shopt -s histreedit
+shopt -s histverify
+shopt -s cmdhist
+
+cd /howzit
+bundle install

data/docker/inputrc

@@ -0,0 +1,57 @@
+"\e[3~": delete-char
+"\ex": 'cd !$ \015ls\015'
+"\ez": 'cd -\015'
+"\e\C-m": '\C-a "$(\C-e|fzf)"\C-a'
+"\e/": '"$(!!|fzf)"\C-a \C-m\C-m'
+# these allow you to use alt+left/right arrow keys
+# to jump the cursor over words
+"\e[1;5C": forward-word
+"\e[1;5D": backward-word
+# "\e[D": backward-word
+# "\e[C": forward-word
+"\ea": menu-complete
+# TAB: menu-complete
+# "\e[Z": "\e-1\C-i"
+
+"\e\C-l": history-and-alias-expand-line
+
+# these allow you to start typing a command and
+# use the up/down arrow to auto complete from
+# commands in your history
+"\e[B": history-search-forward
+"\e[A": history-search-backward
+"\ew": history-search-backward
+"\es": history-search-forward
+# this lets you hit tab to auto-complete a file or
+# directory name ignoring case
+set completion-ignore-case On
+set mark-symlinked-directories On
+set completion-prefix-display-length 2
+set bell-style none
+# set bell-style visible
+set meta-flag on
+set convert-meta off
+set input-meta on
+set output-meta on
+set show-all-if-ambiguous on
+set show-all-if-unmodified on
+set completion-map-case on
+set visible-stats on
+
+# Do history expansion when space entered?
+$if bash
+	Space: magic-space
+$endif
+
+# Show extra file information when completing, like `ls -F` does
+set visible-stats on
+
+# Be more intelligent when autocompleting by also looking at the text after
+# the cursor. For example, when the current line is "cd ~/src/mozil", and
+# the cursor is on the "z", pressing Tab will not autocomplete it to "cd
+# ~/src/mozillail", but to "cd ~/src/mozilla". (This is supported by the
+# Readline used by Bash 4.)
+set skip-completed-text on
+
+# Use Alt/Meta + Delete to delete the preceding word
+"\e[3;3~": kill-word

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

@@ -38,6 +38,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'yard', '~> 0.9.5'
   spec.add_development_dependency 'redcarpet', '~> 3.2'
   spec.add_development_dependency 'github-markup', '~> 1.3'
+  spec.add_development_dependency 'tty-spinner', '~> 0.9'
 
   spec.add_runtime_dependency 'mdless', '~> 1.0', '>= 1.0.28'
   spec.add_runtime_dependency 'tty-screen', '~> 0.8'

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

@@ -52,7 +52,13 @@ module Howzit
 
         @tasks.each do |task|
           if task.optional
-            q = %({bg}#{task.type.to_s.capitalize} {xw}"{bw}#{task.title}{xw}"{x}).c
+            note = if task.type == :include
+                     task_count = Howzit.buildnote.find_topic(task.action)[0].tasks.count
+                     " (#{task_count} tasks)"
+                   else
+                     ""
+                   end
+            q = %({bg}#{task.type.to_s.capitalize} {xw}"{bw}#{task.title}{xw}"#{note}{x}).c
             res = Prompt.yn(q, default: task.default)
             next unless res
 
@@ -81,7 +87,7 @@ module Howzit
 
               $stderr.puts "{by}Running tasks from {bw}#{matches[0].title}{x}".c if Howzit.options[:log_level] < 2
               output.push(matches[0].run(nested: true))
-              $stderr.puts "{by}End include: #{matches[0].tasks.count} tasks".c if Howzit.options[:log_level] < 2
+              $stderr.puts "{by}End include: #{matches[0].tasks.count} tasks{x}".c if Howzit.options[:log_level] < 2
               tasks += matches[0].tasks.count
             when :run
               $stderr.puts "{bg}Running {bw}#{title}{x}".c if Howzit.options[:log_level] < 2
@@ -107,6 +113,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 +142,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 +169,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 +244,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 +277,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 +301,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 +325,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.13'
 end

data/scripts/runtests.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+bundle install
+rake test

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.13
 platform: ruby
 authors:
 - Brett Terpstra
@@ -220,6 +220,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: tty-spinner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: mdless
   requirement: !ruby/object:Gem::Requirement
@@ -289,6 +303,12 @@ files:
 - README.md
 - Rakefile
 - bin/howzit
+- docker/Dockerfile
+- docker/Dockerfile-2.6
+- docker/Dockerfile-2.7
+- docker/Dockerfile-3.0
+- docker/bash_profile
+- docker/inputrc
 - fish/completions/bld.fish
 - fish/completions/fisher.fish
 - fish/completions/howzit.fish
@@ -307,9 +327,9 @@ files:
 - lib/howzit/topic.rb
 - lib/howzit/util.rb
 - lib/howzit/version.rb
+- scripts/runtests.sh
 - 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 +363,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...
-